Bucketeer Docs Local MCP Server

Bucketeer Docs Local MCP Server

Descripción general

Este proyecto proporciona un servidor de Protocolo de Contexto de Modelo (MCP) para la documentación de Bucketeer. Ofrece una interfaz para buscar y recuperar contenido de la documentación de la plataforma de experimentación y feature flags de Bucketeer, lo que permite a los asistentes de IA proporcionar información precisa sobre las funciones y el uso de Bucketeer.

Configuración del entorno

Requisitos

• Node.js 18+
• npm

Pasos de instalación

1. Clona el repositorio:

git clone <repository-url>
cd bucketeer-docs-local-mcp-server

2. Instala las dependencias:

npm install

3. Compila el proyecto:

npm run build

4. Compila el índice de documentos:

npm run build:index

Iniciar el servidor

npm start

Fuentes de documentación

El servidor obtiene e indexa automáticamente la documentación del repositorio bucketeer-io/bucketeer-docs:

• Integración con el repositorio de GitHub:

  • Obtiene automáticamente los archivos .mdx del directorio docs/ y de todos los subdirectorios
  • Procesa el frontmatter y el contenido markdown para una indexación de búsqueda óptima
  • Almacena en caché el contenido obtenido mediante hashes SHA y solo se actualiza cuando los archivos se modifican
  • Admite el recorrido recursivo de directorios para capturar todos los archivos de documentación

• Indexación inteligente:

  • Extrae palabras clave de títulos, descripciones, encabezados y contenido
  • Construye un índice de búsqueda con puntuación de relevancia basada en coincidencias de palabras clave y búsqueda de texto completo
  • Optimizado para la terminología específica de Bucketeer (feature flags, experimentos, SDK, segmentación, etc.)
  • Gestiona la extracción de frontmatter (título, descripción) de archivos MDX

• Gestión de caché:

  • Los archivos se almacenan en caché localmente en el directorio files/docs/ como archivos JSON
  • El índice de documentos se almacena en files/index/document-index.json
  • La caché de GitHub se almacena en files/docs/github_cache.json con detección de cambios basada en SHA
  • Usa npm run build:index:force para forzar la reconstrucción completa del índice

Uso con npx

Configuración inicial

1. Compila el índice de documentos:

npx @bucketeer/docs-local-mcp-server build-index

2. Úsalo en tu configuración de MCP como se muestra en la siguiente sección.

Actualizar el índice

Para actualizar el índice de documentación (por ejemplo, cuando hay nueva documentación disponible):

npx @bucketeer/docs-local-mcp-server build-index --force

Configuración de Cursor y Claude Desktop

Configura el servidor MCP añadiendo lo siguiente a tu archivo mcp.json o claude_desktop_config.json, consultando la documentación de Cursor (https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers) y Claude Desktop (https://modelcontextprotocol.io/quickstart/user):

Instalación rápida con el enlace profundo de Cursor

Para los usuarios de Cursor, puedes instalar el servidor MCP con un solo clic usando el enlace profundo a continuación:

Esto configurará automáticamente el servidor MCP en tu configuración de Cursor. Después de hacer clic en el enlace, Cursor te pedirá que instales el servidor.

Opción 1: Usar npx (Recomendado)

{
  "mcpServers": {
    "bucketeer-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["@bucketeer/docs-local-mcp-server"]
    }
  }
}

Opción 2: Usar instalación local

{
  "mcpServers": {
    "bucketeer-docs": {
      "type": "stdio",
      "command": "npm",
      "args": ["start", "--prefix", "/path/to/bucketeer-docs-local-mcp-server"]
    }
  }
}

Uso

Cuando el servidor MCP está en ejecución, las siguientes herramientas están disponibles:

1. search_docs - Buscar documentación de Bucketeer

• Parámetro: query (cadena) - La consulta de búsqueda
• Parámetro: limit (número, opcional) - Número máximo de resultados a devolver (predeterminado: 5)

Ejemplo:

{
  "name": "search_docs",
  "arguments": {
    "query": "feature flags SDK integration",
    "limit": 5
  }
}

Respuesta: Devuelve una matriz de resultados de búsqueda con título, URL, ruta, descripción, extracto y puntuación de relevancia.

2. get_document - Obtener contenido específico de un documento

• Parámetro: path (cadena) - Ruta del documento obtenida de los resultados de búsqueda

Ejemplo:

{
  "name": "get_document",
  "arguments": {
    "path": "getting-started/create-feature-flag"
  }
}

Respuesta: Devuelve el contenido completo del documento, incluidos título, descripción, URL y contenido markdown completo.

Comandos de desarrollo

• npm run build - Compila archivos TypeScript al directorio dist/
• npm run build:index - Compila/actualiza el índice de documentos desde el repositorio de GitHub
• npm run build:index:force - Fuerza la reconstrucción completa del índice (ignora la caché)
• npx @bucketeer/docs-local-mcp-server build-index - Compila el índice usando npx
• npx @bucketeer/docs-local-mcp-server build-index --force - Fuerza la reconstrucción del índice usando npx
• npm run dev:index - Compila y actualiza el índice en modo de desarrollo
• npm run dev - Compila e inicia el servidor en modo de desarrollo
• npm run lint - Ejecuta el linting de Biome
• npm run lint:fix - Ejecuta el linting de Biome y corrige los errores de linting

Configuración

El servidor se configura mediante src/config/index.ts:

• siteName: "Bucketeer"
• websiteUrl: "https://docs.bucketeer.io"
• githubRepo: "https://github.com/bucketeer-io/bucketeer-docs"
• docsDirectory: "docs" (directorio en el repositorio de GitHub que contiene la documentación)
• searchLimitDefault: 5 (número predeterminado de resultados de búsqueda)
• useGithubSource: true (siempre usa GitHub como fuente)

Estructura de archivos

files/
├── docs/           # Cached JSON files from GitHub repository
├── index/          # Document search index
│   └── document-index.json
└── [created automatically when building index]

Arquitectura

El servidor consta de varios componentes clave:

1. GithubDocumentFetcher: Obtiene recursivamente los archivos .mdx del repositorio de GitHub
2. IndexManager: Compila y gestiona el índice de documentos de búsqueda
3. SearchService: Proporciona funcionalidad de búsqueda con coincidencia de palabras clave y búsqueda de texto completo
4. Servidor MCP: Expone herramientas a través del Protocolo de Contexto de Modelo

Licencia

Licencia Apache 2.0, consulta LICENSE.

Contribuciones

¡Nos encantaría ❤️ que contribuyeras a Bucketeer y nos ayudaras a mejorarlo! ¡Cualquiera puede usarlo y disfrutarlo!

Sigue nuestra guía de contribución aquí.