Servidor MCP de documentación de MTA:SA

Un servidor MCP (Model Context Protocol) que proporciona a los asistentes de IA acceso fiable y estructurado a la documentación de Multi Theft Auto: San Andreas.

Combina búsqueda rápida por palabras clave, coincidencia semántica y almacenamiento en caché respaldado por SQLite para que los agentes puedan descubrir las API correctas y obtener documentación autorizada sin necesidad de extraer datos de la wiki manualmente.

Aspectos destacados

• 11 herramientas MCP para descubrimiento, recuperación de documentos, operaciones de caché y guía de flujo de trabajo

• Descubrimiento basado en eventos (search_events, find_events_for_task)

• Coincidencia semántica de tareas con búsqueda vectorial en SQLite

• Expansión inteligente de palabras clave (por ejemplo, database -> API db*)

• Detección y advertencias de obsolescencia integradas

• Caché local de SQLite con tiempo de vida configurable

• Puertas de verificación de CI, pruebas de humo y automatización de lanzamientos

Instalación

Requisitos:

• Node.js 24+

• Bun 1.3+ (entorno de ejecución opcional)

• pnpm 10+ (para desarrollo local)

Nota sobre el lanzador:

• Puede lanzar/instalar mediante flujos de estilo npx, pnpx, bunx o yarn dlx.

• El soporte de tiempo de ejecución es multiplataforma: Node.js (vía node:sqlite) y Bun (vía bun:sqlite).

Desde npm (recomendado)

npm install -g mtasa-docs-mcp

o:

pnpm add -g mtasa-docs-mcp

Instalación rápida

Desde el código fuente

git clone https://github.com/Luminaire1337/mtasa-docs-mcp.git
cd mtasa-docs-mcp
pnpm install
pnpm build

Si su entorno omite las dependencias nativas opcionales, ejecute:

pnpm install --force

Configuración del cliente MCP

Cursor (manual)

Global: ~/.cursor/mcp.json

Proyecto: .cursor/mcp.json

{
  "mcpServers": {
    "mtasa-docs": {
      "command": "npx",
      "args": ["-y", "mtasa-docs-mcp"]
    }
  }
}

VS Code (manual)

Espacio de trabajo: .vscode/mcp.json

Usuario: Paleta de comandos -> MCP: Open User Configuration

{
  "servers": {
    "mtasa-docs": {
      "command": "npx",
      "args": ["-y", "mtasa-docs-mcp"]
    }
  }
}

O añádalo desde la terminal:

code --add-mcp "{\"name\":\"mtasa-docs\",\"command\":\"npx\",\"args\":[\"-y\",\"mtasa-docs-mcp\"]}"

Claude Code (CLI)

claude mcp add-json mtasa-docs '{"type":"stdio","command":"npx","args":["-y","mtasa-docs-mcp"]}'

OpenCode (manual)

Archivo de configuración global: ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mtasa-docs": {
      "type": "local",
      "command": ["npx", "-y", "mtasa-docs-mcp"],
      "enabled": true
    }
  }
}

Antigravity (manual)

Archivo de configuración: ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "mtasa-docs": {
      "command": "npx",
      "args": ["-y", "mtasa-docs-mcp"]
    }
  }
}

Clientes MCP genéricos (manual)

{
  "mcpServers": {
    "mtasa-docs": {
      "command": "node",
      "args": ["/absolute/path/to/mtasa-docs-mcp/build/index.js"]
    }
  }
}

Si mtasa-docs-mcp ya está publicado, reemplace el comando por:

{
  "mcpServers": {
    "mtasa-docs": {
      "command": "npx",
      "args": ["-y", "mtasa-docs-mcp"]
    }
  }
}

Herramientas disponibles

• search_functions

• search_events

• find_functions_for_task

• find_events_for_task

• get_function_docs

• get_multiple_function_docs

• get_function_examples

• list_functions_by_category

• get_cache_stats

• recommend_doc_workflow

• clear_cache

Desarrollo

pnpm build
pnpm test
pnpm test:runtime
pnpm smoke
pnpm smoke:cross-runtime
pnpm verify
pnpm verify:full

Comprobaciones útiles:

• pnpm check:versions - mantiene alineadas las versiones de package.json y del servidor MCP

• pnpm check:changelog - asegura que CHANGELOG.md tenga el encabezado de la versión actual

• pnpm check:tool-names - evita regresiones en los nombres de herramientas heredadas

• pnpm test:runtime - ejecuta pruebas de integración en tiempo de ejecución para las rutas de humo de Node y Bun

• pnpm smoke:cross-runtime - ejecuta comprobaciones de humo en los entornos de ejecución de Node y Bun

Los scripts se encuentran en scripts/ (compilación, humo, protecciones de lanzamiento).

Flujo de lanzamiento

La automatización del lanzamiento se gestiona mediante .github/workflows/release.yml.

1. Incremente la versión en package.json y src/index.ts.

2. Mueva las notas de la versión de Unreleased a una sección versionada en CHANGELOG.md usando ## [x.y.z] - YYYY-MM-DD.

3. Cree y envíe una etiqueta de lanzamiento: git tag v<version> && git push origin v<version>.

Política de ramificación:

• Antes de v1.0.0: se permiten envíos directos a master.

• A partir de v1.0.0: utilice desarrollo basado en PR para todos los cambios en master.

En los envíos de etiquetas de lanzamiento (v*.*.*), el flujo de trabajo de lanzamiento:

• comprueba si la versión ya existe en npm

• ejecuta pnpm verify:full

• publica en npm con procedencia utilizando publicación confiable (OIDC)

• publica server.json en el Registro MCP utilizando GitHub OIDC

• crea/actualiza el lanzamiento de GitHub desde CHANGELOG.md

• verifica la instalabilidad del paquete publicado y ejecuta pruebas de humo

Configuración del mantenedor para publicación confiable en npm

En la configuración del paquete npm, configure un editor confiable para este repositorio y flujo de trabajo:

• Repositorio: Luminaire1337/mtasa-docs-mcp

• Archivo de flujo de trabajo: .github/workflows/release.yml

• Entorno (si se usa): coincida con su configuración de GitHub Actions

Configuración del mantenedor para publicación en el Registro MCP

• Asegúrese de que server.json exista en la raíz del repositorio y utilice este nombre de paquete: mtasa-docs-mcp

• Configure la propiedad del Registro MCP para io.github.Luminaire1337/mtasa-docs-mcp

• El flujo de trabajo de lanzamiento utiliza mcp-publisher login github-oidc y publica solo cuando se supera la puerta de publicación de npm

Flujos de trabajo de CI

• .github/workflows/ci.yml - verificación en push/PR a master (Ubuntu + macOS) y pruebas opcionales de integración con la wiki en vivo en PR etiquetados

• .github/workflows/release.yml - publicación automatizada y lanzamiento en GitHub en etiquetas de lanzamiento (v*.*.*)

Documentación del proyecto

• AGENTS.md - arquitectura y guía para colaboradores

• FEATURES.md - hoja de ruta e ideas

• CHANGELOG.md - historial de lanzamientos

• SECURITY.md - política de divulgación de vulnerabilidades

Licencia

GNU General Public License v3.0. Consulte LICENSE.