McpDocServer

Um servidor baseado em MCP para pesquisar e recuperar documentação de frameworks de desenvolvimento, com suporte a crawling e carregamento de arquivos locais.

GitHub
48
Experimente este MCPPatrocinado

Documentação

McpDocServer

Documentação em Inglês

Um servidor de documentação de desenvolvimento baseado no protocolo MCP, projetado para documentação de diversos frameworks de desenvolvimento. Oferece funcionalidades de rastreamento multithread de documentação, carregamento de documentação local, busca por palavras-chave e obtenção de detalhes de documentos.

Demonstração das Funcionalidades Principais

1. Demonstração de Rastreamento de Documentação

文档爬取演示

Processo completo de rastreamento de documentação, da configuração à execuçãonpm run crawl

2. Demonstração de Chamada ao Servidor MCP

MCP调用演示

Processo de consulta à API no Cursor e obtenção de resultados precisos de documentação

Resolvendo o Problema de Alucinação do Cursor

Ao usar o Cursor para desenvolvimento com diversos frameworks, é comum encontrar problemas de "alucinação" causados pela compreensão imprecisa das APIs dos frameworks pela IA:

  • Problemas de precisão: A IA pode recomendar APIs e componentes de frameworks inexistentes ou desatualizados
  • Confusão de versões: Mistura de documentação de APIs de versões diferentes, resultando em código que não executa corretamente
  • Erros de parâmetros: Compreensão imprecisa dos parâmetros de métodos, especialmente para funcionalidades específicas de frameworks
  • Avaliação incorreta de compatibilidade: Incapacidade de avaliar com precisão a compatibilidade de uma API em diferentes ambientes ou plataformas

Este servidor MCP resolve efetivamente os problemas acima ao fornecer recursos precisos de recuperação de documentação:

  • Consulta precisa em tempo real: Obtém informações de API atualizadas e precisas diretamente das fontes oficiais de documentação
  • Associação contextual: Exibe documentação de APIs e componentes relacionados em conjunto, fornecendo referência completa
  • Correspondência precisa de parâmetros: Fornece assinaturas de métodos e listas de parâmetros completas, eliminando erros de parâmetros
  • Marcadores de compatibilidade entre plataformas: Identifica claramente a compatibilidade de APIs em diferentes plataformas
  • Código de exemplo: Fornece código de exemplo oficial para garantir o uso correto

Ao integrar este servidor MCP, você pode melhorar significativamente a precisão e a eficiência do Cursor no desenvolvimento com diversos frameworks, evitando obstáculos de desenvolvimento causados por "alucinações".

Recursos

  • Suporte para carregar dados de documentação de frameworks a partir de arquivos JSON locais
  • Fornece recursos poderosos de busca de documentação
  • Fornece consulta de detalhes de documentação
  • Detecta automaticamente fontes de documentação disponíveis
  • Suporte para consultas direcionadas a fontes de documentação específicas
  • Suporte para rastrear documentação externa, convertendo-a automaticamente para um formato local utilizável
  • Suporte para recarregar documentação (acionado ao buscar por "reload")

Estrutura de Diretórios

/
├── server.js              # 服务器入口文件
├── docs/                  # 文档数据目录
│   ├── taro-docs.json     # Taro框架文档
│   └── taroify-docs.json  # Taroify组件库文档
├── scripts/               # 脚本目录
│   └── crawl.js           # 文档爬取脚本
├── tests/                 # 测试目录
│   └── mcp.test.js        # MCP测试脚本
├── config/                # 配置文件目录
│   └── doc-sources.js     # 文档源配置
└── package.json           # 项目配置

Instalação e Execução

Se você já tiver o Chrome instalado localmente e quiser que o puppeteer use sua versão existente, você pode definir a variável de ambiente PUPPETEER_SKIP_DOWNLOAD:

macOS/Linux:

export PUPPETEER_SKIP_DOWNLOAD=true
npm install

Windows (Prompt de Comando):

set PUPPETEER_SKIP_DOWNLOAD=true
npm install

Windows (PowerShell):

$env:PUPPETEER_SKIP_DOWNLOAD = $true
npm install
  1. Rastrear dados de documentação

O rastreador é usado para obter documentação de frameworks e é uma etapa importante antes de usar o servidor. Você precisa primeiro criar o arquivo de configuração do rastreador e, em seguida, executar o script do rastreador.

Criando a Configuração do Rastreador

Crie o arquivo doc-sources.js no diretório config, seguindo o formato abaixo:

// config/doc-sources.js

// 文档源配置
export const docSources = [
    {
        // 文档源名称 - 会用作搜索时的source参数
        name: "taro",
        // 文档网站基础URL
        url: "https://docs.taro.zone/docs",
        // 包含模式 - 指定要爬取的URL路径（空数组表示所有页面）
        includePatterns: [
        ],
        // 排除模式 - 指定不爬取的URL路径（支持正则表达式）
        excludePatterns: [
            /\d\.x/,   // 排除版本号页面
            /apis/     // 排除API页面
        ]
    },
    {
        name: "taroify",
        url: "https://taroify.github.io/taroify.com/introduce/",
        includePatterns: [
            "/components/",          // 所有组件页面
            "/components/*/",        // 组件子页面
            "/components/*/*/"       // 组件子子页面
        ],
        excludePatterns: []
    },
    {
        name: "jquery",
        url: "https://www.jquery123.com/",
        includePatterns: [],         // 空数组表示爬取所有页面
        excludePatterns: [
            /version/               // 排除版本相关页面
        ]
    }
];

// 爬虫全局配置
export const crawlerConfig = {
    // 并行抓取的线程数
    maxConcurrency: 40,
    // 页面加载超时时间(毫秒)
    pageLoadTimeout: 30000,
    // 内容加载超时时间(毫秒)
    contentLoadTimeout: 5000,
    // 是否显示浏览器窗口（false为无界面模式）
    headless: false,
    // 重试次数
    maxRetries: 3,
    // 重试间隔(毫秒)
    retryDelay: 2000,
    // 请求间隔(毫秒)
    requestDelay: 1000
};

Executando o Rastreador

Após a configuração, execute o seguinte comando para iniciar o rastreador:

npm run crawl

O rastreador rastreará automaticamente os sites de documentação especificados de acordo com a configuração e salvará os resultados no formato JSON exigido pelo servidor MCP.

Exemplo de Saída do Rastreador

Após a conclusão do rastreamento, um arquivo JSON no seguinte formato será gerado no diretório docs:

{
  "source": {
    "name": "taro",
    "url": "https://docs.taro.zone/docs"
  },
  "lastUpdated": "2024-05-20T12:00:00.000Z",
  "pages": {
    "https://docs.taro.zone/docs/components-desc": {
      "title": "组件库说明 | Taro 文档",
      "content": "页面内容...",
      "lastCrawled": "2024-05-20T12:00:00.000Z"
    },
    "https://docs.taro.zone/docs/components/viewcontainer/view": {
      "title": "View | Taro 文档",
      "content": "View 组件是一个容器组件...",
      "lastCrawled": "2024-05-20T12:00:00.000Z"
    }
    // ... 更多页面
  }
}

Rastreador Personalizado

Se precisar personalizar o comportamento do rastreador, você pode modificar o arquivo scripts/crawl.js. Você pode adicionar lógica de análise para sites específicos, personalizar o processamento de conteúdo ou aprimorar os recursos de rastreamento.

  1. Iniciar o servidor MCP
npm start

Após a inicialização, o servidor detectará e carregará os arquivos de documentação no diretório docs e fornecerá serviços de interface por meio do protocolo MCP. O servidor exibirá as informações das fontes de documentação carregadas e o número de páginas.

  1. Executar testes
npm test

Execute o script de teste para verificar se as funcionalidades básicas e as interfaces do servidor MCP estão funcionando corretamente.

Formato da Documentação

O arquivo de documentação deve ser um arquivo JSON contendo a seguinte estrutura:

{
  "source": {
    "name": "taro",
    "url": "https://docs.taro.zone/docs"
  },
  "lastUpdated": "2024-03-27T12:00:00.000Z",
  "pages": {
    "https://docs.taro.zone/docs/components-desc": {
      "title": "组件库说明 | Taro 文档",
      "content": "页面内容..."
    },
    // 更多页面...
  }
}

Fluxo de carregamento da documentação:

  1. Na inicialização, o servidor detecta e carrega automaticamente os arquivos JSON no diretório docs
  2. Se nenhuma documentação for encontrada no diretório do projeto, ele tentará carregar do diretório de trabalho atual
  3. O ID da página usa a URL como chave por padrão, sem necessidade de especificar um campo url adicional
  4. Todos os nomes de fontes são convertidos automaticamente para minúsculas para garantir consistência

Funcionalidade do Rastreador

O rastreador integrado ao sistema suporta a extração de conteúdo de sites oficiais de documentação de diversos frameworks e sua conversão para um formato de documentação local utilizável. Os recursos do rastreador incluem:

  1. Suporte a múltiplos sites: Suporta sites de documentação de qualquer framework e biblioteca, totalmente configurável
  2. Rastreamento seletivo: Permite configurar padrões de inclusão e exclusão para controlar com precisão o conteúdo a ser rastreado
  3. Extração inteligente de conteúdo: Detecta automaticamente o título, o conteúdo do corpo e a estrutura das páginas de documentação
  4. Rastreamento multithread: Suporta rastreamento de alta concorrência para melhorar a eficiência
  5. Conversão automática: Converte o conteúdo rastreado para o formato JSON padrão de documentação
  6. Mecanismo de tolerância a falhas: Fornece tratamento de tempo limite e mecanismos de repetição para maior estabilidade

Ferramentas MCP

O servidor fornece as seguintes ferramentas MCP:

  1. search_docs - Buscar documentação

    • Parâmetros:
      • query: Palavra-chave de busca (string, obrigatório)
      • source: Nome da fonte de documentação (string, opcional)
      • limit: Número máximo de resultados (número, opcional, padrão 10)
    • Funcionalidade especial:
      • Quando a consulta for "reload", o recarregamento da documentação é acionado

  2. get_doc_detail - Obter detalhes da documentação

    • Parâmetros:
      • id: ID da documentação (string, obrigatório)
      • source: Nome da fonte de documentação (string, opcional)

Exemplo de Uso

// 搜索文档
const searchRequest = {
  jsonrpc: "2.0",
  id: "search1",
  method: "tools/call",
  params: {
    name: "search_docs",
    arguments: { 
      query: "组件", 
      source: "taro", 
      limit: 5 
    }
  }
};

// 获取文档详情
const detailRequest = {
  jsonrpc: "2.0",
  id: "detail1",
  method: "tools/call",
  params: {
    name: "get_doc_detail",
    arguments: { 
      id: "https://docs.taro.zone/docs/components-desc", 
      source: "taro" 
    }
  }
};

// 重新加载文档
const reloadRequest = {
  jsonrpc: "2.0",
  id: "reload1",
  method: "tools/call",
  params: {
    name: "search_docs",
    arguments: { 
      query: "reload" 
    }
  }
};

Configurando o Cursor

Para usar o servidor no Cursor, você precisa adicionar a seguinte configuração ao mcp.json:

{
  "mcpServers": {
    "文档 MCP 服务器": {
      "command": "node",
      "args": ["/绝对路径/server.js"],
      "env": { "NODE_ENV": "development" }
    }
  }
}

Observação: Certifique-se de usar o caminho absoluto completo do arquivo do servidor, não um caminho relativo. Na inicialização, o servidor exibirá automaticamente um exemplo de configuração adequado para o Cursor.

Testes

O projeto inclui testes automatizados que podem ser executados com o seguinte comando:

npm test

Os testes verificam as funcionalidades básicas do servidor:

  • Inicializar o servidor MCP
  • Chamar a ferramenta de busca
  • Chamar a ferramenta de detalhes da documentação

Planos Futuros

O projeto está em desenvolvimento contínuo. Aqui estão os recursos que planejamos adicionar:

  1. Carregamento de documentação local - Adicionar suporte para carregar e analisar diretamente arquivos de documentação local, sem depender de recursos de rede
  2. Suporte à internacionalização - Adicionar suporte para documentação em vários idiomas

Se você tiver sugestões de recursos ou encontrar problemas, sinta-se à vontade para enviar uma Issue ou um Pull Request.