Yaizu Smart City MCP Server

Instructions

Implementation Reference

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

  The main handler function for the 'generate_api_command' MCP tool. Decorated with @mcp.tool(), it generates markdown-formatted API command examples and documentation for a given entity_type by loading and analyzing API specification documents.

  @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)}"