tokyo-metro-mcp-server/README.md

MCP server for Tokyo Metro API integration

# Tokyo Metro MCP Server

An MCP (Model Context Protocol) server that provides access to Tokyo Metro's Open Data API.

## Features

- **tokyo_metro_query**: Make POST requests to any Tokyo Metro API endpoint with filtering capabilities
- **get_sample_covid_data**: Get COVID-19 data from Tokyo with date range filtering

## Installation

```bash
npm install
npm run build
```

## Usage

The server supports POST requests to Tokyo Metro API endpoints with advanced filtering:

### Tools Available

#### 1. tokyo_metro_query
Query any Tokyo Metro API endpoint with optional filtering.

**Parameters:**
- `api_url` (required): The Tokyo Metro API endpoint URL
- `columns` (optional): Array of specific columns to retrieve
- `limit` (optional): Maximum number of records (default: 100)
- `search_conditions` (optional): Object with filtering conditions

**Example:**
```json
{
  "api_url": "https://service.api.metro.tokyo.lg.jp/api/t000003d0000000093-85208d055a15cce25cc6cee785d52d75-0/json",
  "columns": ["column1", "column2"],
  "limit": 50,
  "search_conditions": {
    "condition_relationship": "and",
    "date_filters": [
      {
        "column": "公表_年月日",
        "operator": "ge", 
        "value": "2021/1/1"
      }
    ]
  }
}
```

#### 2. get_sample_covid_data
Get COVID-19 data from Tokyo Metro's dataset.

**Parameters:**
- `start_date` (optional): Start date in YYYY/M/D format
- `end_date` (optional): End date in YYYY/M/D format  
- `limit` (optional): Maximum records (default: 365)

## API Response Format

The Tokyo Metro API returns responses in this format:

```json
{
  "total": 365,
  "subtotal": 365, 
  "limit": 365,
  "offset": null,
  "metadata": {
    "apiId": "string",
    "title": "string",
    "datasetId": "string",
    "datasetTitle": "string",
    "datasetDesc": "string",
    "dataTitle": "string", 
    "dataDesc": "string",
    "sheetname": "string",
    "version": "string",
    "created": "string",
    "updated": "string"
  },
  "hits": [
    {
      "row": 1,
      "column1": "value1",
      "column2": "value2"
    }
  ]
}
```

## Filter Operators

### Date Filters
- `eq`: Equal to
- `ne`: Not equal to  
- `gt`: Greater than
- `ge`: Greater than or equal to
- `lt`: Less than
- `le`: Less than or equal to

### Text Filters  
- `eq`: Exact match
- `ne`: Not equal to
- `partial`: Partial/contains match

## Running the Server

### For Mastra Integration (HTTP Mode)

```bash
npm run build
npm run start:http
```

Or for development:

```bash  
npm run dev:http
```

Server runs on port 3001 by default (configurable via PORT env var).

### For MCP stdio mode

```bash
npm start
```

Or for development:

```bash  
npm run dev
```

## HTTP API Endpoints (Mastra Integration)

When running in HTTP mode, the following endpoints are available:

- `GET /health` - Health check
- `GET /tools` - List available MCP tools
- `POST /tools/:toolName` - Execute specific MCP tool
- `POST /tokyo-metro/query` - Direct Tokyo Metro API query
- `GET /tokyo-metro/covid` - Get COVID-19 data with query parameters

### Example HTTP Usage

```bash
# Health check
curl http://localhost:3001/health

# List tools
curl http://localhost:3001/tools

# Query Tokyo Metro API
curl -X POST http://localhost:3001/tokyo-metro/query \
  -H "Content-Type: application/json" \
  -d '{
    "api_url": "https://service.api.metro.tokyo.lg.jp/api/your-endpoint/json",
    "limit": 100
  }'

# Get COVID data
curl "http://localhost:3001/tokyo-metro/covid?start_date=2021/1/1&end_date=2021/12/31&limit=100"
```

## Environment Configuration

Copy `.env.example` to `.env` and configure:

```bash
cp .env.example .env
```

- `PORT`: HTTP server port (default: 3001)
- `MODE`: Server mode - "http" for HTTP server, "stdio" for MCP mode