Skip to main content
Glama
moma1992

Yaizu Smart City MCP Server

by moma1992
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote
README.md
# 焼津市スマートシティ MCP サーバー

焼津市のオープンデータを活用した Model Context Protocol (MCP) サーバー。Claude Desktop / Claude Code から焼津市スマートシティAPIへのアクセスを提供します。

## 機能一覧

### ツール (8個)

| ツール名 | 説明 |
|---------|------|
| `scrape_api_docs` | APIカタログから最新ドキュメントをスクレイピング |
| `generate_api_command` | エンティティタイプに対するAPI実行コマンドを生成 |
| `search_api_docs` | 保存済みAPIドキュメントをキーワード検索 |
| `get_api_details` | 特定APIの詳細情報を取得 |
| `execute_yaizu_api` | FIWARE NGSIv2 APIからエンティティデータを取得 |
| `get_sample_endpoints` | 主要エンドポイント例を表示 |
| `list_saved_apis` | 保存済みAPIドキュメント一覧を表示 |
| `execute_api_endpoint` | (非推奨) 汎用エンドポイント実行 |

### リソース (4個)

| URI | 説明 |
|-----|------|
| `yaizu://api-docs` | 全APIドキュメントのサマリー |
| `yaizu://disaster-apis` | 防災関連APIの一覧 |
| `yaizu://info` | 焼津市・スマートシティの基本情報 |
| `yaizu://status` | サーバーステータスとデータ状態 |

### プロンプト (1個)

| プロンプト名 | 説明 |
|-------------|------|
| `analyze_disaster_apis` | 防災APIの分析手順ガイド |

## クイックスタート

### 必要要件

- Python 3.13 以上
- [uv](https://docs.astral.sh/uv/) 0.8.13 以上

### セットアップ

```bash
git clone https://github.com/moma1992/smartcity-mcp.git
cd smartcity-mcp

# 依存関係のインストール
uv sync

# 環境変数の設定
cp .env.example .env
# .env ファイルを編集してAPIキーを設定
```

### Claude Desktop 設定

設定ファイルを開きます:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/Claude/claude_desktop_config.json`

以下の設定を追加:

```json
{
  "mcpServers": {
    "yaizu-smartcity": {
      "command": "/path/to/uv",
      "args": [
        "--directory",
        "/path/to/smartcity-mcp",
        "run",
        "python",
        "-m",
        "yaizu_mcp.server"
      ]
    }
  }
}
```

### 開発・デバッグ

```bash
# MCP Inspector で開発サーバー起動
uv run mcp dev yaizu_mcp/server.py

# 直接実行（STDIOモード）
uv run python yaizu_mcp/server.py

# テスト実行
uv run python tests/test_mcp_integration.py
```

## デプロイ方式

### 1. STDIO (Claude Desktop / Claude Code)

ローカル環境で直接実行。Claude DesktopまたはClaude CodeとJSON-RPC over STDIOで通信します。

### 2. Docker Streamable HTTP (exaBase / コンテナ環境)

Streamable HTTP トランスポートで HTTP サーバーとして起動します
(旧 SSE は 2026-05-19 に廃止、`mcp >= 1.27` / `fastmcp >= 3.3` 推奨)。

```bash
# ビルドと起動
docker compose -f deploy/docker/docker-compose.yml up -d

# ログ確認
docker compose -f deploy/docker/docker-compose.yml logs -f
```

エンドポイント:
- MCP: `POST http://localhost:8080/mcp`

ACR (Azure Container Registry) へのプッシュ:

```bash
# ビルド
docker build -t yaizu-mcp -f deploy/docker/Dockerfile .

# タグ付け & プッシュ
docker tag yaizu-mcp <registry>.azurecr.io/yaizu-mcp:latest
docker push <registry>.azurecr.io/yaizu-mcp:latest
```

### 3. Databricks Apps (Streamable HTTP)

Databricks Apps として Streamable HTTP トランスポートでデプロイします。
リポジトリルートに `app.py`, `app.yaml`, `requirements.txt` を配置しているため、Git Sync でそのまま利用可能です。

#### 前提条件

- Azure Databricks ワークスペース
- Databricks CLI のインストールと認証設定

```bash
# Databricks CLI インストール
brew tap databricks/tap
brew install databricks

# 認証設定
databricks auth login --host <workspace-url>
```

#### シークレット設定

環境変数は Databricks Secret Scope (`yaizu-demo`) で管理します:

```bash
# シークレットの設定
databricks secrets put-secret yaizu-demo yaizu-api-key
databricks secrets put-secret yaizu-demo yaizu-api-email
databricks secrets put-secret yaizu-demo yaizu-api-password
```

`app.yaml` の `resources` セクションでシークレットスコープを参照するため、クレデンシャルのハードコードは不要です。

#### デプロイ手順

```bash
# ワークスペースへファイルをアップロード
databricks workspace import /Workspace/Users/<email>/mcp-yaizu-demo/app.py \
  --file app.py --format AUTO --overwrite
databricks workspace import /Workspace/Users/<email>/mcp-yaizu-demo/app.yaml \
  --file app.yaml --format AUTO --overwrite
databricks workspace import /Workspace/Users/<email>/mcp-yaizu-demo/requirements.txt \
  --file requirements.txt --format AUTO --overwrite
databricks workspace import-dir yaizu_mcp \
  /Workspace/Users/<email>/mcp-yaizu-demo/yaizu_mcp --overwrite

# アプリのデプロイ
databricks apps deploy mcp-yaizu-demo \
  --source-code-path /Workspace/Users/<email>/mcp-yaizu-demo
```

#### 主要コマンド

```bash
databricks apps list                    # アプリ一覧
databricks apps get mcp-yaizu-demo      # 状態確認
databricks apps start mcp-yaizu-demo    # 開始
databricks apps stop mcp-yaizu-demo     # 停止
databricks apps logs mcp-yaizu-demo     # ログ確認
```

## プロジェクト構成

```
smartcity-mcp/                          ← Databricks Apps source-code-path
├── app.py                              - Databricks Apps エントリーポイント
├── app.yaml                            - Databricks Apps 設定（シークレット参照）
├── requirements.txt                    - pip依存関係
├── yaizu_mcp/                          # MCPサーバー本体
│   ├── server.py                       #   サーバー実装 (FastMCP)
│   └── scraper.py                      #   APIカタログスクレイパー
├── deploy/
│   └── docker/                         #   Docker / exaBase用
│       ├── Dockerfile
│       ├── docker-compose.yml
│       └── docker-entrypoint.py
├── scripts/                            # データ処理スクリプト
├── tests/                              # テスト
├── data/                               # API仕様・ドキュメント
│   ├── api_specs/                      #   48個のJSON API仕様書
│   ├── documentation/                  #   PDFドキュメント
│   └── openapi/                        #   OpenAPI仕様書 (YAML)
├── docs/                               # ドキュメント
├── config.yaml                         # API設定
├── pyproject.toml                      # プロジェクト設定
├── uv.lock                             # 依存関係ロック
├── .env.example                        # 環境変数テンプレート
├── CLAUDE.md                           # Claude Code 開発ガイド
└── README.md
```

## API 仕様

### 焼津市 FIWARE NGSIv2 API

- **エンドポイント**: `https://api.smartcity-yaizu.jp/v2/entities`
- **認証**: APIキー (`apikey` ヘッダー)
- **プロトコル**: FIWARE NGSIv2

### 対応エンティティ

| カテゴリ | エンティティタイプ |
|---------|------------------|
| 防災 | Aed, EvacuationShelter, DisasterMail, WeatherAlert, WeatherForecast |
| 防災施設 | TsunamiEvacuationBuilding, DisasterPreventionWarehouse, FirePreventionWaterTank |
| リスク | FloodRiskAreaMaxScale, LandslideVigilanceArea, DebrisFlowVigilanceArea |
| 医療 | FirstAidStation, ReliefHospital, HospitalAndClinic |
| 環境 | PrecipitationGauge, StreamGauge, DrinkingWaterTank |
| 監視 | CameraInformation |
| 観光 | Event, EventDetail, SightseeingMapStore, TouristAttraction |
| 公共施設 | PublicFacility |
| 交通 | RestrictedTrafficAreaInformation, UnderpassInformation |

## 技術スタック

- **フレームワーク**: [FastMCP](https://github.com/jlowin/fastmcp) (MCP Python SDK)
- **非同期処理**: asyncio / aiohttp
- **HTTPクライアント**: aiohttp, httpx
- **PDF処理**: PyMuPDF, PyPDF2
- **環境管理**: python-dotenv
- **パッケージ管理**: uv

## トラブルシューティング

| エラー | 対処法 |
|--------|-------|
| "No API key found" | `.env` に `YAIZU_API_KEY` を設定 |
| "Server disconnected" | Claude Desktop設定のパスを確認 |
| "Module not found" | `uv sync` で依存関係をインストール |
| Docker接続エラー | `FASTMCP_HOST=0.0.0.0` が設定されているか確認 |
| Databricks認証エラー | `databricks auth login` でトークンを更新 |

## 関連情報

- [焼津市オープンデータカタログ](https://city-api-catalog.smartcity-pf.com/yaizu)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP Documentation](https://github.com/jlowin/fastmcp)
- [Databricks Apps Documentation](https://learn.microsoft.com/en-us/azure/databricks/dev-tools/databricks-apps/)

## ライセンス

MIT License
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 8 tools

Disambiguation3/5

There is moderate overlap between tools like execute_api_endpoint and execute_yaizu_api, which both execute API calls but with different approaches, potentially causing confusion. However, other tools like scrape_api_docs and search_api_docs have distinct purposes, and descriptions help clarify the differences. Some tools, such as get_api_details and list_saved_apis, serve related but separate functions, reducing ambiguity.

Naming Consistency4/5

Most tools follow a consistent verb_noun pattern (e.g., execute_api_endpoint, generate_api_command, get_api_details), which is predictable and readable. There is a minor deviation with execute_yaizu_api, which uses a specific name instead of a generic verb, but it still fits the overall style. The naming is largely uniform, aiding in tool identification.

Tool Count5/5

With 8 tools, the count is well-scoped for a smart city API server, covering execution, documentation management, and information retrieval without being overwhelming. Each tool appears to serve a specific purpose in the domain, such as scraping, searching, and executing APIs, making the set appropriately sized for the server's functionality.

Completeness4/5

The tool set provides good coverage for interacting with Yaizu's FIWARE NGSIv2 API, including execution, documentation scraping, searching, and listing. Minor gaps exist, such as the lack of tools for updating or deleting entities, which might limit full CRUD operations, but core workflows like data retrieval and documentation management are well-supported, allowing agents to work effectively.

Maintenance

ActivityNo data
ResponsivenessSyncing

Resources