Skip to content

Commit 0bc5ad4

Browse files
EliFuzzEliFuzz
committed
update README
1 parent 984ffc7 commit 0bc5ad4

1 file changed

Lines changed: 368 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 368 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,370 @@
11
# API Docs MCP
22

3-
MCP server for API and GraphQL documentation and search.
3+
Model Context Protocol (MCP) server that provides tools for interacting with API documentation. Supports both GraphQL and OpenAPI/Swagger specifications, fetching schema definitions from various sources (local files or remote URLs), caching them, and exposing them through a set of tools.
4+
5+
## Table of Contents
6+
7+
- [API Docs MCP](#api-docs-mcp)
8+
- [Table of Contents](#table-of-contents)
9+
- [Features](#features)
10+
- [Architecture](#architecture)
11+
- [Installation](#installation)
12+
- [Configuration](#configuration)
13+
- [`FileSource` Example](#filesource-example)
14+
- [`UrlSource` Example](#urlsource-example)
15+
- [Setting the `API_SOURCES` Environment Variable](#setting-the-api_sources-environment-variable)
16+
- [Usage](#usage)
17+
- [API Docs Tool](#api-docs-tool)
18+
- [API Search Tool](#api-search-tool)
19+
- [Development](#development)
20+
- [Running the Server Locally](#running-the-server-locally)
21+
- [Project Structure](#project-structure)
22+
- [Contributing](#contributing)
23+
- [License](#license)
24+
25+
## Features
26+
27+
- **Dynamic Tool Registration**: Automatically discovers and registers tools from a specified directory.
28+
- **API Documentation Retrieval**: Provides tools to list available API methods (`api_docs`) and retrieve detailed documentation for specific methods (`api_search`).
29+
- **Schema Caching**: Caches API schema information to reduce redundant fetches and improve performance.
30+
- **Multiple Source Support**:
31+
- **GraphQL**: Supports loading GraphQL schemas from `graphql` / `gql` files or `json` introspection results (local files or remote URLs).
32+
- **OpenAPI/Swagger**: Supports loading OpenAPI/Swagger `yaml` / `yml` / `json` schemas from local files or remote URLs.
33+
- **Environment-based Configuration**: Configures API sources via the `API_SOURCES` environment variable, allowing flexible deployment and management.
34+
- **Automatic Cache Refresh**: Periodically refreshes cached schema data to ensure up-to-date documentation.
35+
36+
## Architecture
37+
38+
The `api-docs-mcp` project is designed as an MCP server that integrates with various API documentation sources.
39+
40+
```mermaid
41+
graph TD
42+
mcpServer[MCP Server] e1@--> tools(Tools:<br/>api_docs / api_search);
43+
tools e2@--> cacheManager{Cache Manager};
44+
cacheManager e3@--> configuration[Configuration:<br/>API_SOURCES env var];
45+
configuration e4@--> schemaSources{Schema Sources};
46+
schemaSources e5@-- FileSource--> localFiles(Local Files:<br/>.graphql, .json, .yaml);
47+
schemaSources e6@-- UrlSource--> remoteUrls(Remote URLs:<br/>GraphQL Endpoints, OpenAPI/Swagger Endpoints);
48+
localFiles e7@--> processor[Schema Processors];
49+
remoteUrls e8@--> processor;
50+
processor e9@--> cacheManager;
51+
processor e10@--> openAPIProcessor(OpenAPI Processor:<br/>OpenAPI/Swagger);
52+
processor e11@--> graphQLProcessor(GraphQL Processor)
53+
cacheManager e12@--Cached Data--> tools;
54+
55+
subgraph Core Components
56+
mcpServer
57+
tools
58+
cacheManager
59+
configuration
60+
end
61+
62+
subgraph Data Flow
63+
schemaSources
64+
localFiles
65+
remoteUrls
66+
processor
67+
openAPIProcessor
68+
graphQLProcessor
69+
end
70+
71+
e1@{ animate: true }
72+
e2@{ animate: true }
73+
e3@{ animate: true }
74+
e4@{ animate: true }
75+
e5@{ animate: true }
76+
e6@{ animate: true }
77+
e7@{ animate: true }
78+
e8@{ animate: true }
79+
e9@{ animate: true }
80+
e10@{ animate: true }
81+
e11@{ animate: true }
82+
e12@{ animate: true }
83+
```
84+
85+
**Flow of Operations:**
86+
87+
1. **Server Initialization**: The `index.ts` entry point initializes the MCP server and dynamically registers tools defined in the `src/tools` directory.
88+
2. **Configuration Loading**: The `CacheManager` loads API source configurations from the `API_SOURCES` environment variable via `src/utils/config.ts`.
89+
3. **Schema Fetching & Caching**:
90+
- Based on the configured sources (file-based or URL-based), the `CacheManager` fetches API schemas.
91+
- For file sources, it reads local files (`graphql`, `gql`, `json`, `yaml`, `yml`).
92+
- For URL sources, it makes HTTP requests to GraphQL or OpenAPI endpoints.
93+
- Schemas are then processed by specialized handlers (`src/api/api.ts` for OpenAPI, `src/gql/gql.ts` for GraphQL).
94+
- The processed documentation is stored in an in-memory cache (`src/utils/cache.ts`) with a specified TTL (Time-To-Live).
95+
- The cache is periodically refreshed.
96+
4. **Tool Usage**:
97+
- `api_docs`: When invoked, this tool retrieves a list of all available API resources from the cache, filtered by `sourceName` if provided.
98+
- `api_search`: When invoked with a `detailName`, this tool provides detailed documentation (request, response, error structures) for a specific API resource from the cache.
99+
100+
## Installation
101+
102+
To set up the `api-docs-mcp` server, follow these steps:
103+
104+
1. **Clone the repository:**
105+
106+
```bash
107+
git clone https://github.com/EliFuzz/api-docs-mcp.git
108+
cd api-docs-mcp
109+
```
110+
111+
2. **Install dependencies:**
112+
113+
```bash
114+
pnpm install
115+
```
116+
117+
3. **Build the project:**
118+
119+
```bash
120+
pnpm build
121+
```
122+
123+
## Configuration
124+
125+
The server's behavior is controlled by the `API_SOURCES` environment variable. This variable should contain a JSON string representing an array of `SchemaSource` objects. Each `SchemaSource` can be either a `FileSource` or a `UrlSource`.
126+
127+
### `FileSource` Example
128+
129+
For a local GraphQL schema:
130+
131+
```json
132+
{
133+
"name": "MyGraphQLFile",
134+
"path": "/path/to/your/schema.graphql",
135+
"type": "gql"
136+
}
137+
```
138+
139+
For a local OpenAPI JSON schema:
140+
141+
```json
142+
{
143+
"name": "MyOpenAPIFile",
144+
"path": "/path/to/your/openapi.json",
145+
"type": "api"
146+
}
147+
```
148+
149+
### `UrlSource` Example
150+
151+
For a remote GraphQL endpoint:
152+
153+
```json
154+
{
155+
"name": "GitHubGraphQL",
156+
"method": "POST",
157+
"url": "https://api.github.com/graphql",
158+
"headers": {
159+
"Authorization": "Bearer YOUR_GITHUB_TOKEN"
160+
},
161+
"type": "gql"
162+
}
163+
```
164+
165+
For a remote OpenAPI endpoint:
166+
167+
```json
168+
{
169+
"name": "PetstoreAPI",
170+
"method": "GET",
171+
"url": "https://petstore.swagger.io/v2/swagger.json",
172+
"type": "api"
173+
}
174+
```
175+
176+
### Setting the `API_SOURCES` Environment Variable
177+
178+
You can set this in your shell before running the server:
179+
180+
```bash
181+
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"}]'
182+
```
183+
184+
Or in `mcp.json` for MCP execution:
185+
186+
```json
187+
"api-docs-mcp": {
188+
"type": "stdio",
189+
"command": "npx",
190+
"args": [ "api-docs-mcp" ],
191+
"env": {
192+
"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\"}]"
193+
}
194+
}
195+
```
196+
197+
## Usage
198+
199+
Once configured and running, the `api-docs-mcp` server exposes two primary tools: `api_docs` and `api_search`.
200+
201+
### API Docs Tool
202+
203+
This tool provides a list of all available API methods from the configured sources.
204+
205+
**Name**: `api_docs`
206+
**Description**: Get a list of all available API methods.
207+
**Input Schema**:
208+
209+
```typescript
210+
{
211+
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.
212+
}
213+
```
214+
215+
**Output Schema**:
216+
217+
```typescript
218+
{
219+
sources: Array<{
220+
name: string; // The name of the source API
221+
resources: Array<{
222+
name: string; // The name of the API resource
223+
description: string; // A brief description of the API resource
224+
resourceType: string; // The type of the API resource (e.g., "POST", "GET", "mutation", "query")
225+
}>;
226+
}>;
227+
}
228+
```
229+
230+
**Output Example**:
231+
232+
```json
233+
{
234+
"sources": [
235+
{
236+
"name": "GitHubGraphQL",
237+
"resources": [
238+
{
239+
"name": "getUser",
240+
"description": "Fetch a user by username",
241+
"resourceType": "query"
242+
},
243+
{
244+
"name": "createIssue",
245+
"description": "Create a new issue in a repository",
246+
"resourceType": "mutation"
247+
}
248+
]
249+
},
250+
{
251+
"name": "PetstoreAPI",
252+
"resources": [
253+
{
254+
"name": "getPetById",
255+
"description": "Find pet by ID",
256+
"resourceType": "GET"
257+
},
258+
{
259+
"name": "addPet",
260+
"description": "Add a new pet to the store",
261+
"resourceType": "POST"
262+
}
263+
]
264+
}
265+
]
266+
}
267+
```
268+
269+
### API Search Tool
270+
271+
This tool provides detailed documentation for a specific API method.
272+
273+
**Name**: `api_search`
274+
**Description**: Search for a specific API method by name and get its full definition.
275+
**Input Schema**:
276+
277+
```typescript
278+
{
279+
detailName: string; // The exact resource name of the API method to search for that was provided in `api_docs` tool's output
280+
}
281+
```
282+
283+
**Output Schema**:
284+
285+
```typescript
286+
{
287+
details: Array<{
288+
name: string; // The name of the cache entry
289+
resources: Array<{
290+
name: string; // The name of the resource
291+
resourceType: "query" | "mutation" | "subscription"; // The type of GraphQL resource
292+
description: string; // Context or description of the resource
293+
details: {
294+
request?: string; // The request structure or input parameters for the API method
295+
response?: string; // The response structure or output format for the API method
296+
error?: string; // Error information or error handling details for the API method
297+
};
298+
}>;
299+
}>;
300+
}
301+
```
302+
303+
**Output Example**:
304+
305+
```json
306+
{
307+
"details": [
308+
{
309+
"name": "GitHubGraphQL",
310+
"resources": [
311+
{
312+
"name": "getUser",
313+
"resourceType": "query",
314+
"description": "Fetch a user by username",
315+
"details": {
316+
"request": "{ username: String! }",
317+
"response": "{ id: ID!, login: String!, name: String }",
318+
"error": "{ message: String!, code: Int! }"
319+
}
320+
}
321+
]
322+
}
323+
]
324+
}
325+
```
326+
327+
## Development
328+
329+
### Running the Server Locally
330+
331+
1. **Set the `API_SOURCES` environment variable** as described in the [Configuration](#configuration) section.
332+
2. **Start the server:**
333+
334+
```bash
335+
pnpm start
336+
```
337+
338+
The server will connect to a `StdioServerTransport`, meaning it will communicate over standard input/output.
339+
340+
### Project Structure
341+
342+
```markdown
343+
.
344+
├── src/
345+
│ ├── api/ # OpenAPI/Swagger schema processing
346+
│ │ └── api.ts
347+
│ ├── gql/ # GraphQL schema processing
348+
│ │ └── gql.ts
349+
│ ├── tools/ # MCP tools definitions
350+
│ │ ├── api_docs.ts
351+
│ │ └── api_search.ts
352+
│ ├── utils/ # Utility functions (cache, config, fetch, file, source)
353+
│ │ ├── cache.ts
354+
│ │ ├── config.ts
355+
│ │ ├── fetch.ts
356+
│ │ ├── file.ts
357+
│ │ └── source.ts
358+
│ ├── index.ts # Main entry point
359+
│ └── server.ts # MCP server setup and tool registration
360+
└── package.json # Project dependencies and scripts
361+
└── README.md # This file
362+
```
363+
364+
## Contributing
365+
366+
Contributions are welcome! Please feel free to open issues or submit pull requests.
367+
368+
## License
369+
370+
This project is licensed under the Apache 2.0 License. See the [LICENSE](LICENSE) file for details.

0 commit comments

Comments
 (0)