paulsohal1981/mcp-poc-weather

MCP Weather Demo

A Model Context Protocol (MCP) server that provides weather information and greeting resources. This is a demonstration server built with TypeScript that showcases MCP capabilities.

Features

• Weather Tool: Get weather information for any city
• Greeting Resource: Dynamic greeting generator with parameterized URLs
• TypeScript: Built with TypeScript for type safety and better development experience

Prerequisites

• Node.js (v16 or higher)
• npm or yarn

Installation

1. Clone the repository:

git clone https://github.com/paulsohal1981/mcp-poc-weather.git
cd mcp-poc-weather

2. Install dependencies:

npm install

Running the Server

Development Mode (TypeScript)

npm run dev

Production Mode (JavaScript)

npm run build
npm start

Testing with MCP Inspector

MCP Inspector is a tool that allows you to test and debug MCP servers interactively.

Installation

Install MCP Inspector globally:

npm install -g @modelcontextprotocol/inspector

Testing the Server

1. Start the MCP Inspector:

mcp-inspector

2. Connect to your server:

   • In the MCP Inspector interface, you'll see a connection form

   • Set the command to run your server. Use one of these options:

     For development (TypeScript):

     npx tsx main.ts
     

     For production (JavaScript, after running npm run build):

     node main.js
     

3. Set the working directory:

   • Set the working directory to your project path: /path/to/your/mcp-poc-weather

4. Connect: Click the "Connect" button

Available Tools and Resources

Once connected, you can test the following:

Weather Tool

• Tool Name: get-weather
• Description: Get the current weather for a specified city
• Parameters:
  • city (string): The city to get weather for
• Example: Try calling with city: "London" or city: "New York"

Greeting Resource

• Resource Template: greeting://{name}
• Description: Dynamic greeting generator
• Example URLs:
  • greeting://Alice
  • greeting://Bob
  • greeting://World

Testing Steps

1. Test the Weather Tool:

   • In MCP Inspector, navigate to the "Tools" section
   • Find the "get-weather" tool
   • Enter a city name (e.g., "Paris")
   • Click "Call Tool"
   • You should see a response with mock weather data

2. Test the Greeting Resource:

   • Navigate to the "Resources" section
   • Try accessing greeting://YourName
   • You should see a personalized greeting

Project Structure

mcp-poc-weather/
├── main.ts              # Main MCP server implementation
├── package.json         # Project dependencies and scripts
├── package-lock.json    # Locked dependency versions
├── .gitignore          # Git ignore rules
└── README.md           # This file

Development

Scripts

• npm run dev - Run in development mode with TypeScript
• npm run build - Compile TypeScript to JavaScript
• npm start - Run the compiled JavaScript version
• npm test - Run tests (placeholder)

Code Structure

The main server is implemented in main.ts and includes:

• MCP Server Setup: Creates an MCP server instance
• Weather Tool: Simulates weather API calls with mock data
• Greeting Resource: Demonstrates dynamic resource templates
• STDIO Transport: Handles communication via stdin/stdout

Troubleshooting

Common Issues

1. "spawn mcp-server-everything ENOENT" error:

   • This means the MCP client is looking for a non-existent command
   • Make sure to use the correct command: npx tsx main.ts or node main.js

2. TypeScript compilation errors:

   • Run npm install to ensure all dependencies are installed
   • Check that TypeScript is installed: npx tsc --version

3. Connection issues with MCP Inspector:

   • Ensure the working directory is set correctly
   • Verify the command path is absolute or the working directory contains your project
   • Check that all dependencies are installed

Debug Mode

For debugging, you can add console.log statements to main.ts and they will appear in the MCP Inspector's server output panel.

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes
4. Commit your changes: git commit -am 'Add feature'
5. Push to the branch: git push origin feature-name
6. Submit a pull request

License

This project is licensed under the ISC License.

Deployment and Hosting

MCP servers are designed to run locally and communicate via stdio (standard input/output), not as traditional web services. Here are the main deployment approaches:

1. Local Development/Testing

This is the most common approach for development and testing:

# Run directly with tsx (development)
npx tsx main.ts

# Or compile and run (production)
npm run build
node main.js

2. Package Distribution

NPM Package

You can publish your MCP server as an NPM package:

1. Prepare for publishing:

   # Update package.json with proper metadata
   npm version patch  # or minor/major
   

2. Publish to NPM:

   npm publish
   

3. Users can then install and run:

   npx your-package-name
   

Binary Distribution

Use tools like pkg to create standalone executables:

# Install pkg
npm install -g pkg

# Create binaries
pkg main.js --out-path dist/

3. Container Deployment

While not typical for MCP servers, you can containerize for consistent environments:

Dockerfile example:

FROM node:18-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
CMD ["node", "main.js"]

4. Integration with MCP Clients

VS Code Extension

Your .vscode/mcp.json configuration shows how to integrate with VS Code:

{
  "servers": {
    "mcp-weather": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tsx", "main.ts"]
    }
  }
}

Claude Desktop

For Claude Desktop, add to your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mcp-weather": {
      "command": "npx",
      "args": ["-y", "tsx", "/full/path/to/your/project/main.ts"]
    }
  }
}

Other MCP Clients

Most MCP clients support stdio-based servers. Provide:

• Command: npx (or full path to node)
• Arguments: ["-y", "tsx", "/path/to/main.ts"]
• Working Directory: Your project directory

5. Production Considerations

Compiled Version

For production, use the compiled JavaScript version:

npm run build
# Use: node main.js instead of npx tsx main.ts

Environment Management

• Use environment variables for configuration
• Consider using process managers like PM2 for Node.js apps if running as services
• Implement proper logging and error handling

Security

• MCP servers run with the same permissions as the calling process
• Be cautious with file system access and external API calls
• Validate all inputs thoroughly

6. Distribution Methods

1. GitHub Releases: Tag releases and provide installation instructions
2. NPM Registry: Publish as a public or private NPM package
3. Direct Git Installation: Users can install directly from Git:

   npm install -g git+https://github.com/paulsohal1981/mcp-poc-weather.git
   

Example Installation Instructions for Users

# Method 1: Clone and run locally
git clone https://github.com/paulsohal1981/mcp-poc-weather.git
cd mcp-poc-weather
npm install
npm run dev

# Method 2: Install globally (if published to NPM)
npm install -g mcp-poc-weather
mcp-poc-weather

# Method 3: Run without installing
npx mcp-poc-weather

Links

• Model Context Protocol Documentation
• MCP Inspector
• MCP SDK Documentation