mcp-101 by mitchallen - MCP Server

MCP Weather Server

A Model Context Protocol (MCP) server implementation for weather data services built with TypeScript.

NOTE: This demo returns mock weather data and not real data. To return live data is an exercise for the reader.

🌤️ Overview

This project implements a weather server using the Model Context Protocol (MCP) SDK, providing standardized access to weather information through a well-defined interface.

📋 Prerequisites

Node.js (v18 or higher)
npm (v8 or higher)
TypeScript knowledge for development

🚀 Quick Start

Installation

# Clone the repository
git clone <your-repo-url>
cd mcp-101

# Install dependencies
npm install
# or using Makefile
make install

Development

# Start development server with hot reload
npm run dev
# or
make dev

# Run in watch mode
npm run watch
# or
make watch

Production

# Build the project
npm run build
# or
make build

# Start the server
npm start
# or
make start

# Build and start in one command
make start-prod

📦 Available Scripts

NPM Scripts

npm run build - Compile TypeScript to JavaScript
npm run dev - Run development server with tsx
npm start - Start the compiled application
npm run watch - Run with file watching for auto-restart
npm test - Run the test suite

Makefile Commands

Run make help to see all available commands:

Development

make dev - Start development server with hot reload
make watch - Run in watch mode
make build - Build the project
make test - Run tests
make typecheck - Run TypeScript type checking

Maintenance

make clean - Clean build artifacts
make clean-deps - Clean node_modules
make reset - Full reset (clean + reinstall + rebuild)
make verify - Full verification pipeline

Utilities

make outdated - Check for outdated packages
make update - Update dependencies
make package - Create distributable package

🏗️ Project Structure

mcp-101/
├── src/
│   ├── index.ts          # Main server entry point
│   └── test.ts           # Test suite
├── dist/                 # Compiled JavaScript output
├── node_modules/         # Dependencies
├── package.json          # Project configuration
├── tsconfig.json         # TypeScript configuration
├── Makefile             # Build and development commands
├── .gitignore           # Git ignore rules
└── README.md            # Project documentation

🔧 Configuration

TypeScript Configuration

The project uses TypeScript with ES modules. Configuration is in tsconfig.json.

Package Configuration

Type: ES Module ("type": "module")
Main Entry: dist/index.js
Binary: weather-server command available after global install

🧪 Testing

# Run tests
npm test
# or
make test

# Run tests in watch mode
make test-watch

🖥️ Testing with Claude Desktop (Mac)

Prerequisites

Claude Desktop installed on your Mac
Built MCP server: Run make build to compile your server

Configuration Steps

Build your server:
```
make build
```
Locate Claude Desktop config:

On a Mac,

Claude > Settings > Developer > Edit Config

Create or edit the config file:

In the Finder file window, right click to edit this file in your preferred editor:

claude_desktop_config.json

Add your MCP server configuration:

{
  "mcpServers": {
    "weather-server": {
      "command": "node",
      "args": ["/absolute/path/to/your/mcp-101/dist/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

Important: Replace /absolute/path/to/your/mcp-101/ with your actual project path:

# Get your current path
pwd
# Example result: /Users/username/projects/mcp/mcp-101

Alternative: Using npm global install:

# Install globally (after building)
npm install -g .

# Then use in config:
{
  "mcpServers": {
    "weather-server": {
      "command": "weather-server"
    }
  }
}

Testing Steps

Restart Claude Desktop completely:

# Quit Claude Desktop completely
# Then relaunch from Applications

Verify server connection:
- Open Claude Desktop
- Look for MCP server indicators in the interface
- Check for any error messages
Test weather functionality:
- Ask Claude about weather in various locations
- Try different weather-related queries
- Verify the responses come from your MCP server

Troubleshooting Claude Desktop Integration

Common Issues

Server not connecting:

# Check if your server runs standalone
node dist/index.js

# Verify the path in config is correct
ls -la /absolute/path/to/your/mcp-101/dist/index.js

Permission issues:

# Make sure the file is executable
chmod +x dist/index.js

Configuration file issues:

# Validate JSON syntax
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json | python3 -m json.tool

Debug Configuration

For debugging, you can add logging to your config:

{
  "mcpServers": {
    "weather-server": {
      "command": "node",
      "args": ["/absolute/path/to/your/mcp-101/dist/index.js"],
      "env": {
        "NODE_ENV": "development",
        "DEBUG": "mcp:*"
      }
    }
  }
}

Viewing Logs

Claude Desktop logs:

# Check Console app for Claude Desktop logs
# Or check system logs:
log show --predicate 'process == "Claude Desktop"' --last 1h

Your server logs:
- Add console.log statements to your src/index.ts
- Rebuild with make build
- Restart Claude Desktop

Development Workflow with Claude Desktop

Make changes to your server code
Rebuild: make build
Restart Claude Desktop to reload the server
Test the changes in Claude Desktop
Repeat as needed

Quick Setup Script

Create a setup script for easier testing:

# create setup-claude.sh
#!/bin/bash
echo "Building MCP server..."
make build

echo "Current project path:"
pwd

echo ""
echo "Add this to your Claude Desktop config:"
echo "~/Library/Application Support/Claude/claude_desktop_config.json"
echo ""
echo "{"
echo "  \"mcpServers\": {"
echo "    \"weather-server\": {"
echo "      \"command\": \"node\","
echo "      \"args\": [\"$(pwd)/dist/index.js\"]"
echo "    }"
echo "  }"
echo "}"
echo ""
echo "Then restart Claude Desktop to test!"

# Make it executable and run
chmod +x setup-claude.sh
./setup-claude.sh

🛠️ Development Workflow

Start Development: make dev
Make Changes: Edit files in src/
Test Changes: make test
Type Check: make typecheck
Build: make build
Verify: make verify (runs full pipeline)

📚 Model Context Protocol (MCP)

This server implements the Model Context Protocol, which provides:

Standardized communication between AI models and external systems
Resource discovery and access patterns
Tool invocation capabilities
Structured data exchange

Learn more about MCP at the official documentation.

🌐 Weather Server Features

This implementation provides weather-related functionality through the MCP interface, including:

Weather data retrieval
Location-based queries
Standardized response formats

🔧 Adding Features

Linting & Formatting (Optional)

To add code quality tools:

# Install ESLint
npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin

# Install Prettier
npm install --save-dev prettier

# Then use
make lint    # Lint code
make format  # Format code

📦 Building for Production

# Create production build
make build

# Create distributable package
make package

# Full verification before deployment
make verify

🔍 Troubleshooting

Common Issues

Build Errors: Run make clean then make build
Dependency Issues: Run make reset to clean and reinstall
Type Errors: Run make typecheck to see detailed type issues

Debugging

# Check project status
make git-status

# View what would be cleaned
make git-clean

# Check for outdated dependencies
make outdated

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes
Run verification: make verify
Commit your changes: git commit -am 'Add feature'
Push to the branch: git push origin feature-name
Submit a pull request

📝 License

This project is licensed under the ISC License.

🔗 Links

📧 Support

For issues and questions:

Check existing issues in the repository
Create a new issue with detailed information
Include steps to reproduce any bugs

Built with ❤️ using TypeScript and the Model Context Protocol