# mcp-server

English | [日本語](./README.ja.md)

<!-- 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. Implementation has not started yet, and continuous integration is not yet configured.

The server is built in two stages. The first stage runs locally over standard input/output (stdio); the second stage moves to remote access over Streamable HTTP.

### Key Features

Provides tools that retrieve information from a weather API.

## Tech Stack

| Category | Technology | Version |
| --- | --- | --- |
| Language | TypeScript | - |
| Runtime | Node.js | - |
| Framework | Hono | - |
| MCP SDK | `@modelcontextprotocol/sdk` | - |
| Schema Validation | Zod | - |
| Testing | Vitest | - |
| Package Manager | pnpm | - |
| Hosting | Vercel | - |

Hono and Vercel are introduced in the second stage. They are not used in the first.

## Architecture

### Stage 1 (stdio)

The MCP client launches this server as a child process and communicates over standard input/output. 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)
       ↓
Weather API
```

### Stage 2 (Streamable HTTP)

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.

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

Tool definitions and external API calls are implemented independently of the transport, so that moving between stages is confined to the connection layer and to authentication and authorization.

## Setup

To be written once the project scaffold is generated.

## Development Commands

To be written once the project scaffold is generated.

## Directory Structure

To be written once the project scaffold is generated.