API Docs MCP

API Docs MCP

API ドキュメントとやり取りするためのツールを提供する Model Context Protocol（MCP）サーバーです。GraphQL、OpenAPI/Swagger、gRPC の仕様に対応し、さまざまなソース（ローカルファイルまたはリモート URL）からスキーマ定義を取得してキャッシュし、一連のツールを通じて公開します。

目次

• API Docs MCP
  • 目次
  • MCP プラットフォーム
  • 機能
  • ユースケースの例
    • OpenAPI Petstore ドキュメントの取得
    • GraphQL ドキュメントの取得
    • 複数ソースからのドキュメント取得
  • アーキテクチャ
  • インストール
  • 設定
    • FileSource の例
    • UrlSource の例
    • API_SOURCES 環境変数の設定
  • 使い方
    • API ドキュメントツール
    • API 検索ツール
  • 開発
    • サーバーをローカルで実行する
    • プロジェクト構成
  • コントリビューション
  • ライセンス

MCP プラットフォーム

機能

• ツールの動的登録：指定されたディレクトリからツールを自動的に検出して登録します。
• API ドキュメントの取得：利用可能な API メソッドの一覧表示（api_docs）と、特定のメソッドの詳細なドキュメント取得（api_search）を行うツールを提供します。
• スキーマのキャッシュ：API スキーマ情報をキャッシュし、重複した取得を減らしてパフォーマンスを向上させます。
• 複数ソースへの対応：
  • GraphQL：graphql / gql ファイル、または json のイントロスペクション結果から GraphQL スキーマを読み込めます（ローカルファイルまたはリモート URL）。
  • OpenAPI/Swagger：ローカルファイルまたはリモート URL から OpenAPI/Swagger の yaml / yml / json スキーマを読み込めます。
  • gRPC：proto ファイル、またはリモート URL からの gRPC リフレクションを通じて gRPC スキーマを読み込めます。
• 環境変数による設定：API_SOURCES 環境変数を使って API ソースを設定でき、柔軟なデプロイと管理が可能です。
• キャッシュの自動更新：スキーマデータのキャッシュを定期的に更新し、ドキュメントを最新の状態に保ちます。

ユースケースの例

OpenAPI Petstore ドキュメントの取得

GraphQL ドキュメントの取得

複数ソースからのドキュメント取得

アーキテクチャ

api-docs-mcp プロジェクトは、さまざまな API ドキュメントソースと連携する MCP サーバーとして設計されています。

graph TD
    mcpServer[MCP Server] e1@--> tools(Tools:<br/>api_docs / api_search);
    tools e2@--> cacheManager{Cache Manager};
    cacheManager e3@--> configuration[Configuration:<br/>API_SOURCES env var];
    configuration e4@--> schemaSources{Schema Sources};
    schemaSources e5@-- FileSource--> localFiles(Local Files:<br/>.graphql, .json, .yaml, .proto);
    schemaSources e6@-- UrlSource--> remoteUrls(Remote URLs:<br/>GraphQL Endpoints, OpenAPI/Swagger Endpoints, gRPC Endpoints);
    localFiles e7@--> processor[Schema Processors];
    remoteUrls e8@--> processor;
    processor e9@--> cacheManager;
    processor e10@--> openAPIProcessor(OpenAPI Processor:<br/>OpenAPI/Swagger);
    processor e11@--> graphQLProcessor(GraphQL Processor);
    processor e12@--> grpcProcessor(gRPC Processor)
    cacheManager e13@--Cached Data--> tools;

    subgraph Core Components
        mcpServer
        tools
        cacheManager
        configuration
    end

    subgraph Data Flow
        schemaSources
        localFiles
        remoteUrls
        processor
        openAPIProcessor
        graphQLProcessor
        grpcProcessor
    end

    e1@{ animate: true }
    e2@{ animate: true }
    e3@{ animate: true }
    e4@{ animate: true }
    e5@{ animate: true }
    e6@{ animate: true }
    e7@{ animate: true }
    e8@{ animate: true }
    e9@{ animate: true }
    e10@{ animate: true }
    e11@{ animate: true }
    e12@{ animate: true }
    e13@{ animate: true }

処理の流れ：

1. サーバーの初期化：エントリーポイントの index.ts が MCP サーバーを初期化し、src/tools ディレクトリで定義されているツールを動的に登録します。
2. 設定の読み込み：CacheManager は、src/utils/config.ts を介して API_SOURCES 環境変数から API ソースの設定を読み込みます。
3. スキーマの取得とキャッシュ：
   • 設定されたソース（ファイルベースまたは URL ベース）に応じて、CacheManager が API スキーマを取得します。
   • ファイルソースの場合、ローカルファイル（graphql、gql、json、yaml、yml、proto）を読み込みます。
   • URL ソースの場合、GraphQL、OpenAPI、または gRPC エンドポイントに HTTP リクエストを送信します。
   • その後、スキーマは専用のハンドラー（OpenAPI 用の src/api/api.ts、GraphQL 用の src/gql/gql.ts、gRPC 用の src/grpc/grpc.ts）で処理されます。
   • 処理されたドキュメントは、指定された TTL（有効期間）でインメモリキャッシュ（src/utils/cache.ts）に保存されます。
   • キャッシュは定期的に更新されます。
4. ツールの使用：
   • api_docs：呼び出されると、キャッシュから利用可能なすべての API リソースの一覧を取得します。source が指定されている場合は、それで絞り込みます。
   • api_search：detailName を指定して呼び出すと、キャッシュから特定の API リソースの詳細ドキュメント（リクエスト、レスポンス、エラー構造）を返します。

インストール

api-docs-mcp サーバーをセットアップするには、次の手順に従ってください。

1. リポジトリをクローンします：

   git clone https://github.com/EliFuzz/api-docs-mcp.git
   cd api-docs-mcp
   

2. 依存関係をインストールします：

   pnpm install
   

3. プロジェクトをビルドします：

   pnpm build
   

設定

サーバーの動作は API_SOURCES 環境変数によって制御されます。この変数には、SchemaSource オブジェクトの配列を表す JSON 文字列を指定します。各 SchemaSource は、FileSource または UrlSource のいずれかです。

FileSource の例

ローカルの GraphQL スキーマの場合：

{
  "name": "MyGraphQLFile",
  "path": "/path/to/your/schema.graphql",
  "type": "gql"
}

ローカルの OpenAPI JSON スキーマの場合：

{
  "name": "MyOpenAPIFile",
  "path": "/path/to/your/openapi.json",
  "type": "api"
}

ローカルの gRPC proto ファイルの場合：

{
  "name": "MyGrpcFile",
  "path": "/path/to/your/service.proto",
  "type": "grpc"
}

UrlSource の例

リモートの GraphQL エンドポイントの場合：

{
  "name": "GitHubGraphQL",
  "method": "POST",
  "url": "https://api.github.com/graphql",
  "headers": {
    "Authorization": "Bearer YOUR_GITHUB_TOKEN"
  },
  "type": "gql"
}

リモートの OpenAPI エンドポイントの場合：

{
  "name": "PetstoreAPI",
  "method": "GET",
  "url": "https://petstore.swagger.io/v2/swagger.json",
  "type": "api"
}

リフレクションを使用するリモートの gRPC エンドポイントの場合：

{
  "name": "MyGrpcService",
  "url": "grpc://localhost:9090",
  "type": "grpc"
}

API_SOURCES 環境変数の設定

サーバーの実行前に、シェルで設定できます。

export API_SOURCES='[{"name": "MyGraphQLFile", "path": "./example/fixtures/graphql/graphql-schema.graphql", "type": "gql"}, {"name": "PetstoreAPI", "method": "GET", "url": "https://petstore.swagger.io/v2/swagger.json", "type": "api"}]'

または、MCP の実行用に mcp.json で設定できます。

"api-docs-mcp": {
    "type": "stdio",
    "command": "npx",
    "args": [ "api-docs-mcp" ],
    "env": {
        "API_SOURCES": "[{\"name\": \"MyGraphQLFile\", \"path\": \"./example/fixtures/graphql/graphql-schema.graphql\", \"type\": \"gql\"}, {\"name\": \"PetstoreAPI\", \"method\": \"GET\", \"url\": \"https://petstore.swagger.io/v2/swagger.json\", \"type\": \"api\"}]"
    }
}

使用方法

設定して実行すると、api-docs-mcp サーバーは主要なツールとして api_docs と api_search を提供します。

API Docs ツール

このツールは、設定されたソースから利用可能なすべての API メソッドの一覧を返します。

名前：api_docs 説明：利用可能なすべての API メソッドの一覧を取得します。 入力スキーマ：

{
    sourceName?: string; // The name of the API source (e.g., "GitHub") from MCP configuration environment variables. If not provided, docs from all sources will be returned.
}

出力スキーマ：

{
  sources: Array<{
    sourceName: string; // The name of the source API
    resources: Array<{
      resourceName: string; // The name of the API resource
      resourceType: string; // The type of the API resource (e.g., "POST", "GET", "mutation", "query")
      resourceDescription: string; // A brief description of the API resource
    }>;
  }>;
}

出力例：

{
  "sources": [
    {
      "sourceName": "GitHubGraphQL",
      "resources": [
        {
          "resourceName": "getUser",
          "resourceType": "query",
          "resourceDescription": "Fetch a user by username"
        },
        {
          "resourceName": "createIssue",
          "resourceType": "mutation",
          "resourceDescription": "Create a new issue in a repository"
        }
      ]
    },
    {
      "sourceName": "PetstoreAPI",
      "resources": [
        {
          "resourceName": "getPetById",
          "resourceType": "GET",
          "resourceDescription": "Find pet by ID"
        },
        {
          "resourceName": "addPet",
          "resourceType": "POST",
          "resourceDescription": "Add a new pet to the store"
        }
      ]
    }
  ]
}

API Search ツール

このツールは、特定の API メソッドの詳細なドキュメントを返します。

名前：api_search 説明：名前で特定の API メソッドを検索し、その完全な定義を取得します。 入力スキーマ：

{
  resourceName: string; // The exact resource name of the API method to search for that was provided in `api_docs` tool's output
}

出力スキーマ：

{
  details: Array<{
    sourceName: string; // The name of the source API
    resources: Array<{
      resourceName: string; // The name of the resource
      resourceType: "query" | "mutation" | "subscription"; // The type of GraphQL resource
      resourceDescription: string; // Context or description of the resource
      details: {
        request?: string; // The request structure or input parameters for the API method
        response?: string; // The response structure or output format for the API method
        error?: string; // Error information or error handling details for the API method
      };
    }>;
  }>;
}

出力例：

{
  "details": [
    {
      "sourceName": "GitHubGraphQL",
      "resources": [
        {
          "resourceName": "getUser",
          "resourceType": "query",
          "resourceDescription": "Fetch a user by username",
          "details": {
            "request": "{ username: String! }",
            "response": "{ id: ID!, login: String!, name: String }",
            "error": "{ message: String!, code: Int! }"
          }
        }
      ]
    }
  ]
}

開発

サーバーをローカルで実行する

1. 設定のセクションで説明されているとおりに、API_SOURCES 環境変数を設定します。

2. サーバーを起動します：

   pnpm start
   

サーバーは StdioServerTransport に接続し、標準入力／出力を介して通信します。

プロジェクト構成

.
├── src/
│ ├── api/ # OpenAPI/Swagger schema processing
│ │ └── api.ts
│ ├── gql/ # GraphQL schema processing
│ │ └── gql.ts
│ ├── grpc/ # gRPC schema processing
│ │ └── grpc.ts
│ ├── tools/ # MCP tools definitions
│ │ ├── api_docs.ts
│ │ └── api_search.ts
│ ├── utils/ # Utility functions (cache, config, fetch, file, source)
│ │ ├── cache.ts
│ │ ├── config.ts
│ │ ├── fetch.ts
│ │ ├── file.ts
│ │ └── source.ts
│ ├── index.ts # Main entry point
│ └── server.ts # MCP server setup and tool registration
└── package.json # Project dependencies and scripts
└── README.md # This file

貢献

貢献を歓迎します！お気軽にイシューを作成するか、プルリクエストを送信してください。

ライセンス

このプロジェクトは Apache 2.0 ライセンスのもとでライセンスされています。詳細は LICENSE ファイルをご覧ください。