API Docs MCP

Model Context Protocol (MCP) server that provides tools for interacting with API documentation. Supports GraphQL, OpenAPI/Swagger, and gRPC specifications, fetching schema definitions from various sources (local files or remote URLs), caching them, and exposing them through a set of tools.

- API Docs MCP

- Table of Contents
- MCP Platforms
- Features
- Example Use Cases

- OpenAPI Petstore retrieval docs
- GraphQL retrieval docs
- Multiple Sources retrieval docs

- FileSourceExample
- UrlSourceExample
- Setting theAPI_SOURCESEnvironment Variable

- Running the Server Locally
- Project Structure

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 }

- Server Initialization: Theindex.tsentry point initializes the MCP server and dynamically registers tools defined in thesrc/toolsdirectory.
- Configuration Loading: TheCacheManagerloads API source configurations from theAPI_SOURCESenvironment variable viasrc/utils/config.ts.
- Schema Fetching & Caching:

- Based on the configured sources (file-based or URL-based), theCacheManagerfetches API schemas.
- For file sources, it reads local files (graphql,gql,json,yaml,yml,proto).
- For URL sources, it makes HTTP requests to GraphQL, OpenAPI, or gRPC endpoints.
- Schemas are then processed by specialized handlers (src/api/api.tsfor OpenAPI,src/gql/gql.tsfor GraphQL,src/grpc/grpc.tsfor gRPC).
- The processed documentation is stored in an in-memory cache (src/utils/cache.ts) with a specified TTL (Time-To-Live).
- The cache is periodically refreshed.

- api_docs: When invoked, this tool retrieves a list of all available API resources from the cache, filtered bysourceif provided.
- api_search: When invoked with adetailName, this tool provides detailed documentation (request, response, error structures) for a specific API resource from the cache.

To set up theapi-docs-mcpserver, follow these steps:

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

The server's behavior is controlled by theAPI_SOURCESenvironment variable. This variable should contain a JSON string representing an array ofSchemaSourceobjects. EachSchemaSourcecan be either aFileSourceor aUrlSource.

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

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

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

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

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

For a remote gRPC endpoint with reflection:

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

Setting theAPI_SOURCESEnvironment Variable

You can set this in your shell before running the server:

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"}]'

"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\"}]" } }

Once configured and running, theapi-docs-mcpserver exposes two primary tools:api_docsandapi_search.

This tool provides a list of all available API methods from the configured sources.

Name:api_docsDescription: Get a list of all available API methods.Input Schema:

{ 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" } ] } ] }

This tool provides detailed documentation for a specific API method.

Name:api_searchDescription: Search for a specific API method by name and get its full definition.Input Schema:

{ 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! }" } } ] } ] }

-

Set theAPI_SOURCESenvironment variableas described in theConfigurationsection.

. ├── 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

This project is licensed under the Apache 2.0 License. See theLICENSEfile for details.

Provides API documentation from Apifox projects as a data source for AI programming tools that support MCP.