McpDocServer

Un servidor basado en MCP para buscar y recuperar documentación de marcos de desarrollo,

GitHub
47
Prueba este MCPPatrocinado

Documentación

McpDocServer

Documentación en inglés

Un servidor de documentación de desarrollo basado en el protocolo MCP, diseñado específicamente para documentación de diversos marcos de desarrollo. Proporciona funciones de rastreo de documentos multihilo, carga de documentos locales, búsqueda por palabras clave y obtención de detalles de documentos.

Demostración de funciones principales

1. Demostración de rastreo de documentos

文档爬取演示

Proceso completo de rastreo de documentos desde la configuración hasta la ejecución de npm run crawl

2. Demostración de invocación del servidor MCP

MCP调用演示

Proceso de consulta de API en Cursor y obtención de resultados de documentación precisos

Resolviendo el problema de alucinaciones de Cursor

Al utilizar Cursor para el desarrollo con diversos marcos, a menudo se encuentra el problema de "alucinaciones" causado por una comprensión insuficientemente precisa de las API del marco por parte de la IA:

  • Problemas de precisión: la IA puede recomendar API y componentes de marcos que no existen o están desactualizados
  • Confusión de versiones: mezcla documentación de API de diferentes versiones, lo que impide que el código funcione correctamente
  • Errores de parámetros: comprensión inexacta de los parámetros de los métodos, especialmente para funciones específicas del marco
  • Juicio incorrecto de compatibilidad: incapacidad de determinar con precisión la compatibilidad de una API en diferentes entornos o plataformas

Este servidor MCP resuelve eficazmente los problemas anteriores al proporcionar capacidades precisas de recuperación de documentación:

  • Consultas precisas en tiempo real: obtiene información de API actualizada y precisa directamente de las fuentes de documentación oficiales
  • Contexto relacionado: muestra documentación de API y componentes relacionados para proporcionar una referencia completa
  • Coincidencia precisa de parámetros: proporciona firmas de métodos y listas de parámetros completas, eliminando errores de parámetros
  • Marcadores de compatibilidad multiplataforma: identifica claramente la compatibilidad de las API en diferentes plataformas
  • Código de ejemplo: proporciona código de ejemplo oficial para garantizar un uso correcto

Al integrar este servidor MCP, se puede mejorar significativamente la precisión y eficiencia de Cursor en el proceso de desarrollo con diversos marcos, evitando los obstáculos de desarrollo causados por las "alucinaciones".

Características

  • Soporta la carga de datos de documentación de marcos desde archivos JSON locales
  • Proporciona potentes funciones de búsqueda de documentos
  • Proporciona consulta de detalles de documentos
  • Detecta automáticamente las fuentes de documentación disponibles
  • Soporta consultas dirigidas a fuentes de documentación específicas
  • Soporta el rastreo de documentación externa y la conversión automática a un formato utilizable localmente
  • Soporta la recarga de documentación (activada mediante la búsqueda de "reload")

Estructura de directorios

/
├── 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           # 项目配置

Instalación y ejecución

Si ya tiene Chrome instalado localmente y desea que puppeteer use su versión existente, puede configurar la variable de entorno PUPPETEER_SKIP_DOWNLOAD:

macOS/Linux:

export PUPPETEER_SKIP_DOWNLOAD=true
npm install

Windows (Símbolo del sistema):

set PUPPETEER_SKIP_DOWNLOAD=true
npm install

Windows (PowerShell):

$env:PUPPETEER_SKIP_DOWNLOAD = $true
npm install
  1. Rastreo de datos de documentación

El rastreador se utiliza para obtener documentación de marcos y es un paso importante antes de usar el servidor. Primero debe crear el archivo de configuración del rastreador y luego ejecutar el script del rastreador.

Creación de la configuración del rastreador

Cree el archivo doc-sources.js en el directorio config, siguiendo el siguiente formato:

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

Ejecución del rastreador

Una vez completada la configuración, ejecute el siguiente comando para iniciar el rastreador:

npm run crawl

El rastreador rastreará automáticamente los sitios web de documentación especificados según la configuración y guardará los resultados en formato JSON compatible con los requisitos del servidor MCP.

Ejemplo de salida del rastreador

Una vez completado el rastreo, se generará un archivo JSON con el siguiente formato en el directorio 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"
    }
    // ... 更多页面
  }
}

Personalización del rastreador

Si necesita personalizar el comportamiento del rastreador, puede modificar el archivo scripts/crawl.js. Puede agregar lógica de análisis para sitios web específicos, personalizar el procesamiento de contenido o mejorar las capacidades de rastreo.

  1. Inicio del servidor MCP
npm start

Después del inicio, el servidor detectará y cargará los archivos de documentación en el directorio docs, y proporcionará servicios de interfaz a través del protocolo MCP. El servidor mostrará información sobre las fuentes de documentación cargadas y el número de páginas.

  1. Ejecución de pruebas
npm test

Ejecute el script de prueba para verificar que las funciones básicas y las interfaces del servidor MCP funcionan correctamente.

Formato de documentación

El archivo de documentación debe ser un archivo JSON que contenga la siguiente estructura:

{
  "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": "页面内容..."
    },
    // 更多页面...
  }
}

Proceso de carga de documentación:

  1. Al iniciarse, el servidor detecta y carga automáticamente los archivos JSON en el directorio docs
  2. Si no se encuentran documentos en el directorio del proyecto, intentará cargarlos desde el directorio de trabajo actual
  3. El ID de página utiliza la URL como clave de forma predeterminada, sin necesidad de especificar un campo url adicional
  4. Todos los nombres de fuentes se convierten automáticamente a minúsculas para garantizar la coherencia

Funciones del rastreador

El rastreador integrado en el sistema admite la extracción de contenido de sitios de documentación oficiales de diversos marcos y su conversión a un formato de documentación utilizable localmente. Las características del rastreador incluyen:

  1. Soporte multisitio: admite sitios de documentación de cualquier marco y biblioteca, totalmente configurable
  2. Rastreo selectivo: se pueden configurar patrones de inclusión y exclusión para controlar con precisión el contenido a rastrear
  3. Extracción inteligente de contenido: identifica automáticamente el título, el contenido del cuerpo y la estructura de las páginas de documentación
  4. Rastreo multihilo: admite rastreo de alta concurrencia para mejorar la eficiencia
  5. Conversión automática: convierte el contenido rastreado al formato JSON de documentación estándar
  6. Mecanismo de tolerancia a fallos: proporciona manejo de tiempos de espera y mecanismos de reintento para mejorar la estabilidad

Herramientas MCP

El servidor proporciona las siguientes herramientas MCP:

  1. search_docs - Búsqueda de documentos

    • Parámetros:
      • query: Palabra clave de búsqueda (cadena, obligatorio)
      • source: Nombre de la fuente de documentación (cadena, opcional)
      • limit: Número máximo de resultados (número, opcional, predeterminado 10)
    • Funciones especiales:
      • Cuando la consulta es "reload", se activa la recarga de la documentación

  2. get_doc_detail - Obtención de detalles del documento

    • Parámetros:
      • id: ID del documento (cadena, obligatorio)
      • source: Nombre de la fuente de documentación (cadena, opcional)

Ejemplo 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" 
    }
  }
};

Configuración de Cursor

Para usar este servidor en Cursor, debe agregar la siguiente configuración a mcp.json:

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

Nota: asegúrese de usar la ruta absoluta completa del archivo del servidor, no una ruta relativa. Al iniciarse, el servidor mostrará automáticamente un ejemplo de configuración adecuado para Cursor.

Pruebas

El proyecto incluye pruebas automatizadas que se pueden ejecutar con el siguiente comando:

npm test

Las pruebas verifican las funciones básicas del servidor:

  • Inicializar el servidor MCP
  • Invocar la herramienta de búsqueda
  • Invocar la herramienta de detalles de documentos

Planes futuros

El proyecto está en desarrollo continuo. Estas son las funciones que planeamos agregar:

  1. Carga de documentación local - Agregar carga y análisis directo de archivos de documentación locales, sin depender de recursos de red
  2. Soporte de internacionalización - Agregar soporte para documentación en varios idiomas

Si tiene sugerencias de funciones o encuentra problemas, no dude en enviar un Issue o Pull Request.