MTA:SA Dokumentations-MCP-Server

Ein MCP-Server (Model Context Protocol), der KI-Assistenten zuverlässigen, strukturierten Zugriff auf die Dokumentation von Multi Theft Auto: San Andreas bietet.

Er kombiniert schnelle Stichwortsuche, semantischen Abgleich und SQLite-basiertes Caching, sodass Agenten die richtigen APIs finden und maßgebliche Dokumentationen abrufen können, ohne manuell das Wiki durchsuchen zu müssen.

Highlights

• 11 MCP-Tools für Suche, Dokumentationsabruf, Cache-Operationen und Workflow-Anleitungen

• Ereignisbasierte Suche (search_events, find_events_for_task)

• Semantischer Aufgabenabgleich mit SQLite-Vektorsuche

• Intelligente Keyword-Erweiterung (zum Beispiel database -> db* APIs)

• Integrierte Erkennung und Warnung bei veralteten Funktionen (Deprecation)

• Lokaler SQLite-Cache mit konfigurierbarer Lebensdauer

• CI-Verifizierungsschranken, Smoke-Tests und Release-Automatisierung

Installation

Anforderungen:

• Node.js 24+

• Bun 1.3+ (optionale Laufzeitumgebung)

• pnpm 10+ (für die lokale Entwicklung)

Hinweis zum Launcher:

• Sie können den Start/die Installation über npx, pnpx, bunx oder yarn dlx-Style-Flows durchführen.

• Die Laufzeitunterstützung ist plattformübergreifend: Node.js (via node:sqlite) und Bun (via bun:sqlite).

Von npm (empfohlen)

npm install -g mtasa-docs-mcp

oder:

pnpm add -g mtasa-docs-mcp

Schnellinstallation

Aus dem Quellcode

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

Falls Ihre Umgebung optionale native Abhängigkeiten überspringt, führen Sie aus:

pnpm install --force

MCP-Client-Einrichtung

Cursor (manuell)

Global: ~/.cursor/mcp.json

Projekt: .cursor/mcp.json

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

VS Code (manuell)

Arbeitsbereich: .vscode/mcp.json

Benutzer: Befehlspalette -> MCP: Open User Configuration

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

Oder fügen Sie es über das Terminal hinzu:

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 (manuell)

Globale Konfigurationsdatei: ~/.config/opencode/opencode.json

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

Antigravity (manuell)

Konfigurationsdatei: ~/.gemini/antigravity/mcp_config.json

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

Generische MCP-Clients (manuell)

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

Falls mtasa-docs-mcp bereits veröffentlicht ist, ersetzen Sie den Befehl durch:

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

Verfügbare Tools

• 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

Entwicklung

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

Nützliche Prüfungen:

• pnpm check:versions - hält package.json und die MCP-Server-Version synchron

• pnpm check:changelog - stellt sicher, dass CHANGELOG.md die aktuelle Release-Überschrift enthält

• pnpm check:tool-names - verhindert Regressionen bei der Benennung von Legacy-Tools

• pnpm test:runtime - führt Integrations-Laufzeittests für Node- und Bun-Smoke-Pfade aus

• pnpm smoke:cross-runtime - führt Smoke-Checks für Node- und Bun-Laufzeitumgebungen aus

Skripte befinden sich in scripts/ (Build, Smoke, Release-Schutz).

Release-Ablauf

Die Release-Automatisierung wird durch .github/workflows/release.yml gehandhabt.

1. Version in package.json und src/index.ts erhöhen.

2. Release-Notizen von Unreleased in einen versionierten Abschnitt in CHANGELOG.md verschieben, unter Verwendung von ## [x.y.z] - YYYY-MM-DD.

3. Einen Release-Tag erstellen und pushen: git tag v<version> && git push origin v<version>.

Branching-Richtlinie:

• Vor v1.0.0: Direkte Pushes auf master sind erlaubt.

• Ab v1.0.0: Verwendung von PR-basierter Entwicklung für alle Änderungen an master.

Bei Release-Tag-Pushes (v*.*.*) führt der Release-Workflow:

• prüft, ob die Version bereits auf npm existiert

• führt pnpm verify:full aus

• veröffentlicht auf npm mit Provenance unter Verwendung von Trusted Publishing (OIDC)

• veröffentlicht server.json im MCP Registry unter Verwendung von GitHub OIDC

• erstellt/aktualisiert das GitHub-Release aus CHANGELOG.md

• verifiziert die Installierbarkeit des veröffentlichten Pakets und führt Smoke-Tests aus

Maintainer-Einrichtung für npm Trusted Publishing

Konfigurieren Sie in den npm-Paketeinstellungen einen Trusted Publisher für dieses Repository und diesen Workflow:

• Repository: Luminaire1337/mtasa-docs-mcp

• Workflow-Datei: .github/workflows/release.yml

• Umgebung (falls verwendet): Stimmen Sie diese mit Ihrer GitHub Actions-Konfiguration ab

Maintainer-Einrichtung für MCP Registry Publishing

• Stellen Sie sicher, dass server.json im Repository-Root existiert und diesen Paketnamen verwendet: mtasa-docs-mcp

• Konfigurieren Sie die MCP Registry-Eigentümerschaft für io.github.Luminaire1337/mtasa-docs-mcp

• Der Release-Workflow verwendet mcp-publisher login github-oidc und veröffentlicht nur, wenn die npm-Veröffentlichungsschranke passiert wurde

CI-Workflows

• .github/workflows/ci.yml - Verifizierung bei Push/PR auf master (Ubuntu + macOS) und optionale Live-Wiki-Integrationstests bei markierten PRs

• .github/workflows/release.yml - automatisierte Veröffentlichung und GitHub-Release bei Release-Tags (v*.*.*)

Projektdokumentation

• AGENTS.md - Architektur und Leitfaden für Mitwirkende

• FEATURES.md - Roadmap und Ideen

• CHANGELOG.md - Release-Historie

• SECURITY.md - Richtlinie zur Offenlegung von Sicherheitslücken

Lizenz

GNU General Public License v3.0. Siehe LICENSE.