Yaizu Smart City MCP Server

Instructions

Implementation Reference

• mcp/server.py:169-253 (handler)

  The core handler function for the 'generate_api_command' MCP tool. Decorated with @mcp.tool(), it loads API documentation for the given entity_type using doc_manager and generates a comprehensive markdown report with example execute_yaizu_api commands, attribute lists, and NGSIv2 query details.
  @mcp.tool() async def generate_api_command(entity_type: str) -> str: """ 指定したエンティティタイプに対するAPI実行コマンドを生成します。 APIカタログの情報を基に適切なパラメータを提案します。 Args: entity_type: エンティティタイプ（例: Aed, EvacuationShelter） Returns: str: 使用可能なAPIコマンド例 """ try: # APIカタログからエンティティ情報を取得 doc = doc_manager.load_api_docs(entity_type) if not doc: available_types = doc_manager.list_available_docs() return f"❌ エンティティタイプ '{entity_type}' の情報が見つかりません。\n\n利用可能なエンティティ: {', '.join(available_types)}" output = f"# {entity_type} API コマンド生成\n\n" output += f"## 基本情報\n" output += f"- **データモデル名**: {doc.get('dataModelName', 'N/A')}\n" output += f"- **Fiware-Service**: `{doc.get('fiwareService', 'smartcity_yaizu')}`\n" output += f"- **Fiware-ServicePath**: `{doc.get('fiwareServicePath', '/')}`\n\n" output += f"## 基本的な取得コマンド\n```\n" output += f"execute_yaizu_api(\"{entity_type}\", limit=10)\n```\n\n" output += f"## パラメータ付きコマンド例\n" output += f"```\n" output += f"# 件数指定\nexecute_yaizu_api(\"{entity_type}\", limit=50)\n\n" # 属性情報からクエリ例を生成 if 'attributes' in doc: attributes = doc['attributes'] # 地理的属性がある場合の例 has_location = any('Latitude' in str(attr) or 'Longitude' in str(attr) for attr in attributes.values()) if has_location: output += f"# 地理的範囲指定（焼津駅周辺1kmの例）\n" output += f"execute_yaizu_api(\"{entity_type}\", params='{{\"georel\":\"near;maxDistance:1000\",\"geometry\":\"point\",\"coords\":\"34.8675,138.3236\"}}', limit=20)\n\n" # ID指定の例 output += f"# 特定ID指定\n" output += f"execute_yaizu_api(\"{entity_type}\", params='{{\"id\":\"jp.smartcity-yaizu.{entity_type}.001\"}}', limit=1)\n\n" # 属性フィルタリングの例 text_attrs = [k for k, v in attributes.items() if v.get('type') == 'Text'] if text_attrs: first_attr = text_attrs[0] output += f"# 属性フィルタリング（例: {first_attr}に「焼津」を含む）\n" output += f"execute_yaizu_api(\"{entity_type}\", params='{{\"q\":\"{first_attr}~=.*焼津.*\"}}', limit=30)\n\n" # 複数条件の例 output += f"# 複数条件組み合わせ\n" output += f"execute_yaizu_api(\"{entity_type}\", params='{{\"limit\":\"100\",\"options\":\"count\",\"orderBy\":\"Identification\"}}', limit=100)\n\n" output += f"```\n\n" output += f"## 利用可能な主な属性\n" if 'attributes' in doc: for attr_key, attr_info in list(doc['attributes'].items())[:10]: # 最初の10個のみ表示 output += f"- **{attr_key}** ({attr_info.get('name', '')}): {attr_info.get('description', '')} [{attr_info.get('type', '')}]\n" if len(doc['attributes']) > 10: output += f"- ... 他 {len(doc['attributes']) - 10} 個の属性\n" output += f"\n## NGSIv2クエリ詳細\n" output += f"- **type**: エンティティタイプ指定\n" output += f"- **id**: 特定IDでフィルタ\n" output += f"- **q**: 属性値による条件指定\n" output += f"- **georel**: 地理的関係指定 (near, coveredBy, intersects等)\n" output += f"- **geometry**: 地理領域指定 (point, polygon等)\n" output += f"- **coords**: 座標指定\n" output += f"- **limit**: 取得件数制限 (1-1000)\n" output += f"- **offset**: オフセット指定\n" output += f"- **attrs**: 取得属性限定\n" output += f"- **orderBy**: ソート順指定\n" output += f"- **options**: 追加オプション (count, keyValues等)\n" return output except Exception as e: logger.error(f"コマンド生成エラー: {e}") return f"❌ エラーが発生しました: {str(e)}"
• mcp/server.py:65-83 (helper)

  The load_api_docs method of APIDocumentManager (instantiated as global doc_manager), which is called by generate_api_command to retrieve API documentation JSON for the specified entity_type from data/api_specs/{entity_type}.json.
  def load_api_docs(self, filename: str = "api_catalog") -> Optional[Dict[str, Any]]: """保存済みのAPIドキュメントを読み込む""" try: # data/api_specsディレクトリを確認 specs_filepath = self.data_dir / f"{filename}.json" if specs_filepath.exists(): with open(specs_filepath, 'r', encoding='utf-8') as f: return json.load(f) data_filepath = self.data_dir / f"{filename}.json" if data_filepath.exists(): with open(data_filepath, 'r', encoding='utf-8') as f: return json.load(f) logger.warning(f"APIドキュメントが見つかりません: {filename}") return None except Exception as e: logger.error(f"APIドキュメント読み込みエラー: {e}") return None
• mcp/server.py:169-169 (registration)

  The @mcp.tool() decorator registers the generate_api_command function as an MCP tool with the FastMCP server instance (mcp = FastMCP("yaizu-smartcity") at line 126).
  @mcp.tool()
• mcp/server.py:123-123 (helper)

  Global instantiation of APIDocumentManager as doc_manager, used throughout the tools including generate_api_command.
  doc_manager = APIDocumentManager()
• mcp/server.py:171-180 (schema)

  The docstring provides the input schema (entity_type: str) and output description (str containing markdown with API command examples), used by MCP for tool schema generation.
  """ 指定したエンティティタイプに対するAPI実行コマンドを生成します。 APIカタログの情報を基に適切なパラメータを提案します。 Args: entity_type: エンティティタイプ（例: Aed, EvacuationShelter） Returns: str: 使用可能なAPIコマンド例 """