mcp-server

English | 日本語

<!-- When the content is updated, remember to sync README.ja.md as well. -->

Overview

A server implementation conforming to the Model Context Protocol (MCP). It exposes tools that MCP clients can call to retrieve information from external APIs. Continuous integration is not yet configured.

The server is built in two stages. The first stage (stdio) is complete and preserved as tag v1.0.0. Work is now under way on the second stage: remote access over Streamable HTTP.

Key Features

Provides a tool (get_current_weather) that retrieves the current weather from Open-Meteo. It takes a place name and returns the current conditions, temperature, humidity, and wind speed in Japanese.

Tech Stack

Category	Technology	Version
Language	TypeScript	6
Runtime	Node.js	24
Framework	Hono	- (introduced in stage 2)
MCP SDK	@modelcontextprotocol/sdk	1
Schema Validation	Zod	4
Testing	Vitest	4
Package Manager	pnpm	11
Authorization	WorkOS AuthKit	- (introduced in stage 2)
Hosting	Vercel	- (introduced in stage 2)

Architecture

Stage 1 (stdio) — complete

The server runs on the user's own machine, so no authentication or authorization is required.

MCP client (e.g. Claude Desktop)
       ↓ stdio (launched as a child process)
MCP server (this repository)
       ↓
Open-Meteo API

Stage 2 (Streamable HTTP) — in progress

The server accepts requests from MCP clients over Streamable HTTP. Connections require authentication and authorization. Because general-purpose MCP clients connect to it, the server acts as an OAuth 2.1 resource server. The authorization server is not implemented here — it is delegated to an external identity provider (WorkOS AuthKit).

MCP client (e.g. Claude Desktop)
       ↓ Streamable HTTP (authentication & authorization required)
MCP server (this repository)
       ↓
Open-Meteo API

Tool definitions and external API calls are implemented independently of the transport. Server construction (server.ts) is separated from the stdio wiring (index.ts), so the second stage is confined to the connection layer and to authentication and authorization.

Setup

Prerequisites: Node.js 24 or later. The pnpm version is enforced by devEngines in package.json.

pnpm install
pnpm build

Registering with Claude Desktop

Add the following to Claude Desktop's claude_desktop_config.json, then restart.

{
  "mcpServers": {
    "mcp-server": {
      "command": "node",
      "args": ["<absolute path to this repository>\\dist\\index.js"]
    }
  }
}

If mcp-server appears under Settings → Developer, the server is connected.

You can also run the server as of tag v1.0.0 alongside the main branch under development. Running the following from the repository root creates a working tree pinned to v1.0.0 in the parent directory.

git worktree add ../mcp-server-v1.0.0 v1.0.0
cd ../mcp-server-v1.0.0
pnpm install
pnpm build

Register the generated dist/index.js in Claude Desktop under a different name (e.g. mcp-server-v1). When it is no longer needed, remove it with git worktree remove ../mcp-server-v1.0.0.

Development Commands

Command	Description
pnpm build	Build (includes type checking)
pnpm test	Run tests (requires network access — they call the real API)
pnpm lint	Lint with ESLint
pnpm format	Format with Prettier

Directory Structure

src/
  index.ts         Entry point (stdio wiring)
  server.ts        MCP server construction
  weather-api.ts   Open-Meteo client
  weather-tool.ts  Weather tool definition
  *.test.ts        Colocated tests
dist/              Build output (not under version control)

Data Attribution

Weather and geocoding data are provided by Open-Meteo under CC BY 4.0.

Weather data by Open-Meteo.com