API Docs MCP

Servidor MCP para documentação de API, suportando GraphQL, OpenAPI/Swagger e gRPC a partir de arquivos locais ou URLs remotas

GitHub

Experimente este MCPPatrocinado

Documentação

API Docs MCP

Servidor Model Context Protocol (MCP) que fornece ferramentas para interagir com documentação de API. Suporta especificações GraphQL, OpenAPI/Swagger e gRPC, buscando definições de esquema de várias fontes (arquivos locais ou URLs remotas), armazenando-as em cache e expondo-as por meio de um conjunto de ferramentas.

Sumário

API Docs MCP

Plataformas MCP

Recursos

Registro Dinâmico de Ferramentas: Descobre e registra automaticamente ferramentas de um diretório especificado.
Recuperação de Documentação de API: Fornece ferramentas para listar métodos de API disponíveis (api_docs) e recuperar documentação detalhada para métodos específicos (api_search).
Cache de Esquemas: Armazena em cache informações de esquema de API para reduzir buscas redundantes e melhorar o desempenho.
Suporte a Múltiplas Fontes:
- GraphQL: Suporta carregamento de esquemas GraphQL de arquivos graphql / gql ou resultados de introspecção json (arquivos locais ou URLs remotas).
- OpenAPI/Swagger: Suporta carregamento de esquemas OpenAPI/Swagger yaml / yml / json de arquivos locais ou URLs remotas.
- gRPC: Suporta carregamento de esquemas gRPC de arquivos proto ou via reflexão gRPC de URLs remotas.
Configuração Baseada em Variáveis de Ambiente: Configura fontes de API por meio da variável de ambiente API_SOURCES, permitindo implantação e gerenciamento flexíveis.
Atualização Automática do Cache: Atualiza periodicamente os dados de esquema em cache para garantir documentação atualizada.

Exemplos de Casos de Uso

Documentação de recuperação do OpenAPI Petstore

Documentação de recuperação do GraphQL

Documentação de recuperação de múltiplas fontes

Arquitetura

O projeto api-docs-mcp é projetado como um servidor MCP que se integra a várias fontes de documentação de API.

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 }

Fluxo de Operações:

Inicialização do Servidor: O ponto de entrada index.ts inicializa o servidor MCP e registra dinamicamente as ferramentas definidas no diretório src/tools.
Carregamento de Configuração: O CacheManager carrega as configurações de fonte de API da variável de ambiente API_SOURCES por meio de src/utils/config.ts.
Busca e Cache de Esquemas:
- Com base nas fontes configuradas (baseadas em arquivo ou URL), o CacheManager busca os esquemas de API.
- Para fontes de arquivo, ele lê arquivos locais (graphql, gql, json, yaml, yml, proto).
- Para fontes de URL, ele faz requisições HTTP para endpoints GraphQL, OpenAPI ou gRPC.
- Os esquemas são então processados por manipuladores especializados (src/api/api.ts para OpenAPI, src/gql/gql.ts para GraphQL, src/grpc/grpc.ts para gRPC).
- A documentação processada é armazenada em um cache em memória (src/utils/cache.ts) com um TTL (Time-To-Live) especificado.
- O cache é atualizado periodicamente.
Uso das Ferramentas:
- api_docs: Quando invocada, esta ferramenta recupera uma lista de todos os recursos de API disponíveis do cache, filtrada por source se fornecido.
- api_search: Quando invocada com um detailName, esta ferramenta fornece documentação detalhada (estruturas de requisição, resposta e erro) para um recurso de API específico do cache.

Instalação

Para configurar o servidor api-docs-mcp, siga estes passos:

Clone o repositório:

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

Instale as dependências:
```
pnpm install
```
Compile o projeto:
```
pnpm build
```

Configuração

O comportamento do servidor é controlado pela variável de ambiente API_SOURCES. Esta variável deve conter uma string JSON representando um array de objetos SchemaSource. Cada SchemaSource pode ser um FileSource ou um UrlSource.

Exemplo de `FileSource`

Para um esquema GraphQL local:

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

Para um esquema OpenAPI JSON local:

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

Para um arquivo proto gRPC local:

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

Exemplo de `UrlSource`

Para um endpoint GraphQL remoto:

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

Para um endpoint OpenAPI remoto:

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

Para um endpoint gRPC remoto com reflexão:

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

Definindo a Variável de Ambiente `API_SOURCES`

Você pode defini-la no seu shell antes de executar o servidor:

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

Ou em mcp.json para execução MCP:

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

Uso

Uma vez configurado e em execução, o servidor api-docs-mcp expõe duas ferramentas principais: api_docs e api_search.

API Docs Tool

Esta ferramenta fornece uma lista de todos os métodos de API disponíveis das fontes configuradas.

Nome: api_docs Descrição: Obtenha uma lista de todos os métodos de API disponíveis. Esquema de Entrada:

{
    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.
}

Esquema de Saída:

{
  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
    }>;
  }>;
}

Exemplo de Saída:

{
  "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 Tool

Esta ferramenta fornece documentação detalhada para um método de API específico.

Nome: api_search Descrição: Busque um método de API específico pelo nome e obtenha sua definição completa. Esquema de Entrada:

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

Esquema de Saída:

{
  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
      };
    }>;
  }>;
}

Exemplo de Saída:

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

Desenvolvimento

Executando o Servidor Localmente

Defina a variável de ambiente API_SOURCES conforme descrito na seção Configuração.
Inicie o servidor:
```
pnpm start
```

O servidor se conectará a um StdioServerTransport, o que significa que ele se comunicará por entrada/saída padrão.

Estrutura do Projeto

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

Contribuindo

Contribuições são bem-vindas! Sinta-se à vontade para abrir issues ou enviar pull requests.

Licença

Este projeto é licenciado sob a Licença Apache 2.0. Consulte o arquivo LICENSE para obter detalhes.

API Docs MCP

Documentação

API Docs MCP

Sumário

Plataformas MCP

Recursos

Exemplos de Casos de Uso

Documentação de recuperação do OpenAPI Petstore

Documentação de recuperação do GraphQL

Documentação de recuperação de múltiplas fontes

Arquitetura

Instalação

Configuração

Exemplo de FileSource

Exemplo de UrlSource

Definindo a Variável de Ambiente API_SOURCES

Uso

API Docs Tool

API Search Tool

Desenvolvimento

Executando o Servidor Localmente

Estrutura do Projeto

Contribuindo

Licença

Exemplo de `FileSource`

Exemplo de `UrlSource`

Definindo a Variável de Ambiente `API_SOURCES`