Content
# MCP Weather Service
This repository is a simple service that provides weather information using the Model Context Protocol (MCP). It can retrieve weather information for multiple cities, including Fukuoka, Tokyo, Osaka, Moscow, and New York.
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Project Setup](#project-setup)
3. [Usage](#usage)
4. [Development Guide](#development-guide)
5. [Uploading to GitHub](#uploading-to-github)
6. [Troubleshooting](#troubleshooting)
## Prerequisites
To run this project, you need the following software:
- Node.js (version 18 or higher)
- npm (usually installed with Node.js)
- Git
### Installation Instructions
#### Installing Node.js and npm
1. Download and install the installer from the [Node.js official website](https://nodejs.org/).
2. Once the installation is complete, run the following commands in the terminal to verify:
```bash
node -v
npm -v
```
#### Installing Git
1. Download and install the installer from the [Git official website](https://git-scm.com/).
2. Once the installation is complete, run the following command in the terminal to verify:
```bash
git --version
```
## Project Setup
### Creating a New Project
1. Create a new directory and navigate into it:
```bash
mkdir my-weather-mcp
cd my-weather-mcp
```
2. Initialize an npm project:
```bash
npm init -y
```
3. Install the necessary packages:
```bash
npm install @modelcontextprotocol/sdk axios zod typescript @types/node https-proxy-agent
npm install --save-dev ts-node
```
4. Create a TypeScript configuration file:
```bash
npx tsc --init
```
5. Edit the `tsconfig.json` file as follows:
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"esModuleInterop": true,
"outDir": "./build",
"strict": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
```
6. Edit the scripts section of the `package.json` file as follows:
```json
"scripts": {
"build": "tsc && node -e \"import('fs').then(fs => fs.default.chmodSync('build/index.js', '755'))\"",
"start": "node build/index.js",
"inspect": "npx @modelcontextprotocol/inspector build/index.js",
"dev": "ts-node src/index.ts"
}
```
7. Create the project directory structure:
```bash
mkdir -p src test
```
### Cloning an Existing Project
If you want to use an existing project, clone it using the following steps:
```bash
git clone https://github.com/terisuke/my-weather-mcp.git
cd my-weather-mcp
npm install
```
## Usage
### Building and Running
To build and run the project, use the following command:
```bash
npm run build && npm run start
```
### Using the Inspector
To test the weather service using the MCP Inspector, run the following command:
```bash
npm run build && npm run inspect
```
Once the inspector is running, you can access `http://127.0.0.1:6274` in your browser to interact with the weather service.
### Retrieving Weather Information
You can retrieve weather information for the following cities using the inspector:
- Fukuoka
- Tokyo
- Osaka
- Moscow
- New York
Other cities can also be specified, but they must be recognized city names by the Open-Meteo API.
## Development Guide
### File Structure
```
my-weather-mcp/
├── build/ # Compiled JavaScript files
├── src/ # TypeScript source code
│ └── index.ts # Main application code
├── test/ # Test files
├── package.json # Project configuration
├── tsconfig.json # TypeScript configuration
└── README.md # This file
```
### Modifying Code
1. Edit the `src/index.ts` file to add or modify functionality.
2. To test the changes, run the following command:
```bash
npm run build && npm run inspect
```
3. Once you confirm that the changes work correctly, commit the changes.
## Uploading to GitHub
### Creating Your First GitHub Repository
1. Go to [GitHub](https://github.com/) and create an account or log in.
2. Click the "+" button in the upper right corner and select "New repository."
3. Enter a repository name (e.g., `my-weather-mcp`) and add a description if desired.
4. Set the repository to public or private and click "Create repository."
### Initializing and Pushing a Local Repository
1. In your local project directory, initialize a Git repository:
```bash
git init
```
2. Add changes to the staging area:
```bash
git add .
```
3. Commit the changes:
```bash
git commit -m "Initial commit: Implement MCP Weather Service"
```
4. Add the remote repository (using the GitHub repository URL):
```bash
git remote add origin https://github.com/username/my-weather-mcp.git
```
5. Push the changes to the remote repository:
```bash
git push -u origin main
```
### Pushing Changes to an Existing Repository
1. Add changes to the staging area:
```bash
git add .
```
2. Commit the changes:
```bash
git commit -m "Description of changes"
```
3. Push the changes to the remote repository:
```bash
git push
```
### Creating a Pull Request
1. Go to the repository page on GitHub.
2. Click the "Pull requests" tab and then click the "New pull request" button.
3. Select the base branch and compare branch.
4. Click the "Create pull request" button.
5. Enter a title and description for the pull request, then click the "Create pull request" button.
## Troubleshooting
### Common Issues and Solutions
#### `ERR_PACKAGE_PATH_NOT_EXPORTED` Error
This error occurs when the import path for the `@modelcontextprotocol/sdk` package is incorrect. Fix it as follows:
```typescript
// Incorrect import
import { McpServer } from "@modelcontextprotocol/sdk";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/transports";
// Correct import
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
```
#### Network Connection Errors
If you encounter network errors during API calls, check your proxy settings. You can use the following environment variables to set up a proxy:
```bash
export HTTP_PROXY=http://proxy-server:port
export HTTPS_PROXY=https://proxy-server:port
```
#### Other Issues
If the problem persists, please create an issue including the following information:
- The error message you encountered
- The versions of Node.js and npm you are using
- The commands you executed
- The expected behavior and the actual behavior
