API Docs MCP

Servidor MCP para documentación de API, compatible con GraphQL, OpenAPI/Swagger y gRPC desde archivos locales o URLs remotas

GitHub

Prueba este MCPPatrocinado

Documentación

API Docs MCP

Servidor del Model Context Protocol (MCP) que proporciona herramientas para interactuar con documentación de API. Admite especificaciones GraphQL, OpenAPI/Swagger y gRPC, obteniendo definiciones de esquemas de diversas fuentes (archivos locales o URLs remotas), almacenándolas en caché y exponiéndolas a través de un conjunto de herramientas.

Tabla de Contenidos

API Docs MCP

Plataformas MCP

Características

Registro dinámico de herramientas: Descubre y registra automáticamente herramientas desde un directorio especificado.
Recuperación de documentación de API: Proporciona herramientas para listar métodos de API disponibles (api_docs) y recuperar documentación detallada para métodos específicos (api_search).
Caché de esquemas: Almacena en caché la información de esquemas de API para reducir solicitudes redundantes y mejorar el rendimiento.
Soporte de múltiples fuentes:
- GraphQL: Admite la carga de esquemas GraphQL desde archivos graphql / gql o resultados de introspección json (archivos locales o URLs remotas).
- OpenAPI/Swagger: Admite la carga de esquemas OpenAPI/Swagger yaml / yml / json desde archivos locales o URLs remotas.
- gRPC: Admite la carga de esquemas gRPC desde archivos proto o mediante reflexión gRPC desde URLs remotas.
Configuración basada en entorno: Configura las fuentes de API mediante la variable de entorno API_SOURCES, permitiendo un despliegue y gestión flexibles.
Actualización automática de caché: Actualiza periódicamente los datos de esquemas en caché para garantizar documentación actualizada.

Ejemplos de Uso

Documentación de recuperación de OpenAPI Petstore

Documentación de recuperación de GraphQL

Documentación de recuperación de múltiples fuentes

Arquitectura

El proyecto api-docs-mcp está diseñado como un servidor MCP que se integra con diversas fuentes de documentación 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 }

Flujo de operaciones:

Inicialización del servidor: El punto de entrada index.ts inicializa el servidor MCP y registra dinámicamente las herramientas definidas en el directorio src/tools.
Carga de configuración: CacheManager carga las configuraciones de fuentes de API desde la variable de entorno API_SOURCES mediante src/utils/config.ts.
Obtención y almacenamiento en caché de esquemas:
- Según las fuentes configuradas (basadas en archivos o en URLs), CacheManager obtiene los esquemas de API.
- Para fuentes de archivos, lee archivos locales (graphql, gql, json, yaml, yml, proto).
- Para fuentes de URL, realiza solicitudes HTTP a endpoints de GraphQL, OpenAPI o gRPC.
- Los esquemas son procesados luego por manejadores especializados (src/api/api.ts para OpenAPI, src/gql/gql.ts para GraphQL, src/grpc/grpc.ts para gRPC).
- La documentación procesada se almacena en una caché en memoria (src/utils/cache.ts) con un TTL (Time-To-Live) especificado.
- La caché se actualiza periódicamente.
Uso de herramientas:
- api_docs: Cuando se invoca, esta herramienta recupera una lista de todos los recursos de API disponibles desde la caché, filtrada por source si se proporciona.
- api_search: Cuando se invoca con un detailName, esta herramienta proporciona documentación detallada (estructuras de solicitud, respuesta y errores) para un recurso de API específico desde la caché.

Instalación

Para configurar el servidor api-docs-mcp, sigue estos pasos:

Clona el repositorio:

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

Instala las dependencias:
```
pnpm install
```
Compila el proyecto:
```
pnpm build
```

Configuración

El comportamiento del servidor está controlado por la variable de entorno API_SOURCES. Esta variable debe contener una cadena JSON que represente un array de objetos SchemaSource. Cada SchemaSource puede ser un FileSource o un UrlSource.

Ejemplo de `FileSource`

Para un esquema GraphQL local:

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

Para un esquema OpenAPI JSON local:

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

Para un archivo proto gRPC local:

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

Ejemplo de `UrlSource`

Para un endpoint GraphQL remoto:

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

Para un endpoint OpenAPI remoto:

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

Para un endpoint gRPC remoto con reflexión:

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

Configuración de la variable de entorno `API_SOURCES`

Puedes configurarla en tu shell antes de ejecutar el 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"}]'

O en mcp.json para la ejecución de 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

Una vez configurado y en ejecución, el servidor api-docs-mcp expone dos herramientas principales: api_docs y api_search.

Herramienta de Documentación de API

Esta herramienta proporciona una lista de todos los métodos de API disponibles de las fuentes configuradas.

Nombre: api_docs Descripción: Obtén una lista de todos los métodos de API disponibles. 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 salida:

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

Ejemplo de salida:

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

Herramienta de Búsqueda de API

Esta herramienta proporciona documentación detallada para un método de API específico.

Nombre: api_search Descripción: Busca un método de API específico por nombre y obtén su definición 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 salida:

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

Ejemplo de salida:

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

Desarrollo

Ejecutar el servidor localmente

Configura la variable de entorno API_SOURCES como se describe en la sección Configuración.
Inicia el servidor:
```
pnpm start
```

El servidor se conectará a un StdioServerTransport, lo que significa que se comunicará a través de la entrada/salida estándar.

Estructura del proyecto

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

Contribuciones

¡Las contribuciones son bienvenidas! No dudes en abrir issues o enviar pull requests.

Licencia

Este proyecto está licenciado bajo la Licencia Apache 2.0. Consulta el archivo LICENSE para más detalles.

API Docs MCP

Documentación

API Docs MCP

Tabla de Contenidos

Plataformas MCP

Características

Ejemplos de Uso

Documentación de recuperación de OpenAPI Petstore

Documentación de recuperación de GraphQL

Documentación de recuperación de múltiples fuentes

Arquitectura

Instalación

Configuración

Ejemplo de FileSource

Ejemplo de UrlSource

Configuración de la variable de entorno API_SOURCES

Uso

Herramienta de Documentación de API

Herramienta de Búsqueda de API

Desarrollo

Ejecutar el servidor localmente

Estructura del proyecto

Contribuciones

Licencia

Ejemplo de `FileSource`

Ejemplo de `UrlSource`

Configuración de la variable de entorno `API_SOURCES`