Yaizu Smart City MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview 焼津市のオープンデータを活用したスマートシティAIエージェント用のMCPサーバー。Claude Desktop/Code向けのModel Context Protocol実装により、焼津市の公開データにアクセスする機能を提供します。 ## Development Setup ### 必要な環境 - Python 3.13.7 (推奨最新安定版) - uv 0.8.13以上 (Rustベースの高速パッケージマネージャー) ### セットアップ手順 ```bash # uvのインストール (macOS/Linux) curl -LsSf https://astral.sh/uv/install.sh | sh # プロジェクト初期化 uv init smartcity-mcp cd smartcity-mcp # MCP Python SDK のインストール uv add "mcp[cli]" ``` ## Build and Test Commands ```bash # 開発サーバー起動とデバッグ uv run mcp dev mcp/server.py # MCPサーバーのインストール（Claude Desktop用） uv run mcp install mcp/server.py # 依存関係の更新 uv sync # Python実行 uv run python mcp/server.py # データ処理スクリプト実行 uv run python scripts/openapi_pdf_processor.py ``` ## Architecture Notes ### MCPサーバー構成 - **FastMCP**: MCP Python SDKのフレームワーク使用 - **焼津市API連携**: https://city-api-catalog-api.smartcity-pf.com/yaizu - **認証方式**: Basic Authentication - **対象クライアント**: Claude Desktop, Claude Code ### 主要コンポーネント 1. **ツール群** (`@mcp.tool()`): 焼津市データ取得機能 2. **リソース群** (`@mcp.resource()`): 構造化データ提供 3. **プロンプト群** (`@mcp.prompt()`): スマートシティ関連のプロンプトテンプレート ### Claude Desktop設定 ```json { "mcpServers": { "yaizu-smartcity": { "command": "uv", "args": [ "--directory", "/ABSOLUTE/PATH/TO/smartcity-mcp", "run", "mcp/server.py" ] } } } ``` ### 重要な実装ノート - STDIOベースサーバーではstdoutへの出力禁止（JSON-RPC通信を破損） - エラーハンドリングでログレベル適切に設定 - 非同期処理でAPI レスポンス待機時間を考慮 ## Databricks CLI Integration ### Databricks CLI セットアップ #### インストール ```bash # macOS/Linux (Homebrew) brew tap databricks/tap brew install databricks # インストール確認 databricks -v ``` #### 認証設定 1. `.env.example` を `.env` にコピー 2. Databricks認証情報を設定： - `DATABRICKS_HOST`: ワークスペースURL - `DATABRICKS_TOKEN`: パーソナルアクセストークン #### セットアップスクリプト実行 ```bash # Databricks認証設定とテスト uv run python scripts/setup_databricks.py ``` ### 基本的なDatabricks CLIコマンド ```bash # 認証設定 databricks auth token --host <workspace-url> --token <token> # ユーザー情報確認 databricks current-user me # クラスター操作 databricks clusters list databricks clusters get --cluster-id <cluster-id> # ワークスペース操作 databricks workspace ls / databricks workspace export <path> --format SOURCE databricks workspace import <file> <path> # DBFS操作 databricks fs ls dbfs:/ databricks fs cp <local-file> dbfs:/<path> # ジョブ操作 databricks jobs list databricks jobs run-now --job-id <job-id> ``` ### Python SDKの使用 ```python from databricks.sdk import WorkspaceClient from databricks.sdk.runtime import * # クライアント初期化（環境変数から自動読み込み） w = WorkspaceClient() # クラスター一覧取得 for cluster in w.clusters.list(): print(f"{cluster.cluster_name}: {cluster.state}") # ノートブック実行 w.jobs.run_now(job_id="<job-id>") ``` ### MCPツールとの連携（将来実装予定） MCPサーバーにDatabricksツールを追加することで、Claude経由でDatabricksリソースにアクセス可能： ```python @mcp.tool() async def databricks_run_query(sql: str, catalog: str = "main", schema: str = "default"): """DatabricksでSQLクエリを実行""" # 実装例 pass @mcp.tool() async def databricks_list_tables(catalog: str = "main", schema: str = "default"): """Databricksのテーブル一覧を取得""" # 実装例 pass ``` ### トラブルシューティング - **認証エラー**: トークンの有効期限とスコープを確認 - **接続タイムアウト**: ネットワーク設定とワークスペースURLを確認 - **権限エラー**: ユーザー権限とクラスターアクセス権を確認 ### 参考リンク - [Databricks CLI Documentation](https://docs.databricks.com/dev-tools/cli/index.html) - [Databricks SDK for Python](https://docs.databricks.com/dev-tools/sdk-python.html) - [Azure Databricks Documentation](https://learn.microsoft.com/azure/databricks/)