MCP-Typescribe

Responde perguntas sobre APIs TypeScript usando documentação JSON do TypeDoc.

Documentação

[!CAUTION] O desenvolvimento público está atualmente suspenso, pois nenhuma comunidade ativa se formou. Estamos trabalhando em um projeto de continuação, especificamente para a API yFiles. Você pode ler mais aqui: yFiles MCP Server. Desenvolvedores yFiles podem usar o MCP para consultar a API, guias de desenvolvimento, trechos de código-fonte e receitas usando essas ferramentas. Elas funcionam muito melhor do que a implementação neste repositório.

MCP-Typescribe - um servidor MCP que fornece informações de API para LLMs

O Problema

Grandes Modelos de Linguagem (LLMs) fizeram avanços incríveis na geração de código e na produtividade dos desenvolvedores. No entanto, eles enfrentam uma limitação fundamental: só conseguem usar de forma confiável APIs e bibliotecas que viram durante o treinamento. Isso cria um gargalo para a adoção de novas ferramentas, SDKs ou APIs internas — os LLMs simplesmente não sabem como usá-los de forma eficaz.

Embora as ferramentas possam ter acesso ao código-fonte (ao interagir com APIs cujos fontes estão disponíveis) ou acesso a arquivos de documentação (por exemplo, arquivos de definição de tipos TypeScript), isso não escala bem para APIs grandes. Os LLMs precisam de uma maneira mais eficiente de aprender mais sobre uma API. Colocar toda a documentação no contexto de cada solicitação é ineficiente, inviável e leva a resultados ruins.

Como resultado:

APIs novas ou internas maiores permanecem "invisíveis" para os LLMs.

Os desenvolvedores precisam guiar manualmente os LLMs ou fornecer exemplos de uso.

A inovação é desacelerada pela defasagem entre o lançamento de uma API e sua compreensão generalizada pelas ferramentas de IA.

A Ideia

Este projeto é uma implementação de código aberto do Model Context Protocol (MCP) — um protocolo projetado para fornecer aos LLMs acesso contextual e em tempo real a informações. Neste caso, é a documentação da API e, particularmente por enquanto, as definições TypeScript.

Nosso objetivo é:

Analisar definições TypeScript (e outras) em um formato legível por máquina.

Servir esse contexto dinamicamente aos LLMs por meio de ferramentas como Claude, Cline, Cursor, Windsurf e outras interfaces personalizadas.

Habilitar comportamento agêntico permitindo que os LLMs consultem, planejem e se adaptem a APIs desconhecidas sem retreinamento.

O Que Isso Permite

Suporte plug-and-play de API para assistentes de codificação baseados em LLM.

Onboarding mais rápido para SDKs novos ou proprietários.

Um passo em direção a agentes de codificação mais autônomos e conscientes do contexto.

Visão Geral do Projeto

Este projeto fornece uma maneira para agentes de IA explorarem e entenderem eficientemente APIs TypeScript desconhecidas. Ele carrega documentação JSON gerada pelo TypeDoc e a expõe por meio de um conjunto de endpoints de consulta que permitem aos agentes pesquisar símbolos, obter informações detalhadas sobre partes específicas da API e entender as relações entre diferentes componentes.

Recursos Atuais

Integração com TypeDoc: Carrega e indexa documentação JSON do TypeDoc para consultas eficientes
Capacidades Abrangentes de Consulta: Fornece uma ampla gama de ferramentas para explorar APIs TypeScript
Protocolo MCP: Segue o Model Context Protocol para integração perfeita com agentes de IA

Capacidades de Consulta

O servidor fornece as seguintes ferramentas para consultar a API:

search_symbols: Encontra símbolos por nome com filtragem opcional por tipo
get_symbol_details: Obtém informações detalhadas sobre um símbolo específico
list_members: Lista métodos e propriedades de uma classe ou interface
get_parameter_info: Obtém informações sobre parâmetros de funções
find_implementations: Encontra implementações de interfaces ou subclasses
search_by_return_type: Encontra funções que retornam um tipo específico
search_by_description: Pesquisa em comentários JSDoc
get_type_hierarchy: Mostra relações de herança
find_usages: Encontra onde um tipo/função é usado

Começando

Pré-requisitos

Node.js
npm

Instalação

Clone o repositório
Instale as dependências:
```
npm install
```

Uso

Gere o JSON do TypeDoc para sua API TypeScript:

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

Se você (apenas) tiver um arquivo .d.ts existente, pode criar um arquivo api json da seguinte forma:

Crie um tsconfig.docs.json separado:

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

Em seguida, execute

npx typedoc --tsconfig tsconfig.docs.json

Compile o projeto:
```
npm run build
```

Explore o servidor MCP:

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

Conecte um agente de IA ao servidor para consultar a API

Por exemplo, com o cline no VSCode, especifique o seguinte servidor MCP em cline_mcp_settings.json:

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

Habilite o servidor e provavelmente aprove automaticamente as várias ferramentas. Diga ao agente para usar a ferramenta "typescribe" para aprender sobre sua API.

Estrutura do Projeto

src/sample-api/: Uma API TypeScript de exemplo para testes - usa um dialeto estranho semelhante ao alemão para os nomes da API, para testar se o LLM não alucina a API
src/mcp-server/: A implementação do servidor MCP
- utils/: Funções utilitárias
- schemas/: Esquemas JSON para as ferramentas MCP
- core/: Funcionalidade principal
- server.ts: A implementação do servidor MCP
- index.ts: Ponto de entrada para as exportações da biblioteca
- cli.ts: o ponto de entrada para o CLI/binário
tests/: Testes para a funcionalidade da API

Desenvolvimento

Executando Testes

npm test

Compilação

npm run build

Licença

MIT