MCP-Typescribe

Responde preguntas sobre APIs de TypeScript usando documentación JSON de TypeDoc.

Documentación

[!CAUTION] El desarrollo público está actualmente suspendido ya que no se formó una comunidad activa. Estamos trabajando en un proyecto de seguimiento, específicamente para la API yFiles. Puedes leer más aquí: yFiles MCP Server. Los desarrolladores de yFiles pueden usar el MCP para consultar la API, guías de desarrollo, fragmentos de código fuente y recetas usando esas herramientas, en su lugar. Funcionan mucho mejor que la implementación en este repositorio.

MCP-Typescribe - un servidor MCP que proporciona información de API a los LLMs

El Problema

Los Modelos de Lenguaje de Gran Tamaño (LLMs) han logrado avances increíbles en la generación de código y la productividad de los desarrolladores. Sin embargo, enfrentan una limitación clave: solo pueden usar de manera confiable las APIs y bibliotecas que han visto durante el entrenamiento. Esto crea un cuello de botella para adoptar nuevas herramientas, SDKs o APIs internas — los LLMs simplemente no saben cómo usarlas de manera efectiva.

Si bien a las herramientas se les puede dar acceso al código fuente (cuando interactúan con APIs para las cuales los fuentes están disponibles) o acceso a archivos de documentación (por ejemplo, archivos de definición de tipos de TypeScript), esto no escala bien para APIs grandes. Los LLMs necesitan una forma más eficiente de aprender más sobre una API. Poner toda la documentación en contexto para cada solicitud es ineficiente, inviable y conduce a malos resultados.

Como resultado:

Las APIs nuevas o internas más grandes permanecen "invisibles" para los LLMs.

Los desarrolladores deben guiar manualmente a los LLMs o proporcionar ejemplos de uso.

La innovación se ve frenada por el desfase entre el lanzamiento de una API y su comprensión generalizada por parte de las herramientas de IA.

La Idea

Este proyecto es una implementación de código abierto del Protocolo de Contexto de Modelo (MCP), un protocolo diseñado para proporcionar a los LLMs acceso contextual y en tiempo real a la información. En este caso, se trata de la documentación de la API, y particularmente por ahora en este proyecto, las definiciones de TypeScript.

Nuestro objetivo es:

Analizar definiciones de TypeScript (y otras) en un formato legible por máquina.

Servir este contexto dinámicamente a los LLMs a través de herramientas como Claude, Cline, Cursor o Windsurf y otras interfaces personalizadas.

Habilitar el comportamiento agéntico permitiendo que los LLMs consulten, planifiquen y se adapten a APIs desconocidas sin reentrenamiento.

Lo que Esto Permite

Soporte de API plug-and-play para asistentes de codificación basados en LLM.

Incorporación más rápida para SDKs nuevos o propietarios.

Un paso hacia agentes de codificación más autónomos y conscientes del contexto.

Resumen del Proyecto

Este proyecto proporciona una forma para que los agentes de IA exploren y comprendan eficientemente APIs de TypeScript desconocidas. Carga documentación JSON generada por TypeDoc y la expone a través de un conjunto de endpoints de consulta que permiten a los agentes buscar símbolos, obtener información detallada sobre partes específicas de la API y comprender las relaciones entre diferentes componentes.

Características Actuales

Integración con TypeDoc: Carga e indexa documentación JSON de TypeDoc para consultas eficientes
Capacidades de Consulta Integrales: Proporciona una amplia gama de herramientas para explorar APIs de TypeScript
Protocolo MCP: Sigue el Protocolo de Contexto de Modelo para una integración perfecta con agentes de IA

Capacidades de Consulta

El servidor proporciona las siguientes herramientas para consultar la API:

search_symbols: Encuentra símbolos por nombre con filtrado opcional por tipo
get_symbol_details: Obtén información detallada sobre un símbolo específico
list_members: Lista métodos y propiedades de una clase o interfaz
get_parameter_info: Obtén información sobre los parámetros de una función
find_implementations: Encuentra implementaciones de interfaces o subclases
search_by_return_type: Encuentra funciones que devuelven un tipo específico
search_by_description: Busca en comentarios JSDoc
get_type_hierarchy: Muestra relaciones de herencia
find_usages: Encuentra dónde se usa un tipo/función

Comenzando

Requisitos previos

Node.js
npm

Instalación

Clona el repositorio
Instala las dependencias:
```
npm install
```

Uso

Genera JSON de TypeDoc para tu API de TypeScript:

npx typedoc --json docs/api.json --entryPointStrategy expand path/to/your/typescript/files

Si (solo) tienes un archivo existente.d.ts, puedes crear un archivo json de api de la siguiente manera:

Crea un tsconfig.docs.json separado:

{
  "extends": "./tsconfig.json",
  "files": ["existing.d.ts"],
  "typedocOptions": {
    "entryPoints": ["existing.d.ts"],
    "json": "docs/api.json",
    "pretty": false
  }
}

Luego haz

npx typedoc --tsconfig tsconfig.docs.json

Compila el proyecto:
```
npm run build
```

Explora el servidor MCP:

npx @modelcontextprotocol/inspector node ./dist/mcp-server/cli.js run-server docs/api.json

Conecta un agente de IA al servidor para consultar la API

Por ejemplo, con cline en VSCode, especifica el siguiente servidor MCP en cline_mcp_settings.json:

{
  "mcpServers": {
    "typescribe": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-typescribe@latest",
        "run-server",
        "<PATH_TO_API_DOT_JSON>"
      ],
      "env": {}
    }
  }
}

Habilita el servidor y probablemente aprueba automáticamente las diversas herramientas. Dile al agente que use la herramienta "typescribe" para aprender sobre tu API.

Estructura del Proyecto

src/sample-api/: Una API de TypeScript de muestra para pruebas - utiliza un dialecto extraño similar al alemán para los nombres de la API para probar que el LLM no alucine la API
src/mcp-server/: La implementación del servidor MCP
- utils/: Funciones de utilidad
- schemas/: Esquemas JSON para las herramientas MCP
- core/: Funcionalidad principal
- server.ts: La implementación del servidor MCP
- index.ts: Punto de entrada para las exportaciones de la biblioteca
- cli.ts: el punto de entrada para el CLI/binario
tests/: Pruebas para la funcionalidad de la API

Desarrollo

Ejecutar Pruebas

npm test

Compilar

npm run build

Licencia

MIT