MTA:SA Documentation MCP Server

MCP-сервер (Model Context Protocol), предоставляющий ИИ-ассистентам надежный структурированный доступ к документации Multi Theft Auto: San Andreas.

Он сочетает в себе быстрый поиск по ключевым словам, семантическое сопоставление и кэширование на базе SQLite, чтобы агенты могли находить нужные API и получать официальную документацию без ручного парсинга вики.

Основные возможности

• 11 инструментов MCP для поиска, получения документации, операций с кэшем и руководства по рабочим процессам

• Поиск, ориентированный на события (search_events, find_events_for_task)

• Семантическое сопоставление задач с помощью векторного поиска SQLite

• Интеллектуальное расширение ключевых слов (например, database -> db* API)

• Встроенное обнаружение устаревших функций и предупреждения

• Локальный кэш SQLite с настраиваемым временем жизни

• Проверки CI, дымовые тесты и автоматизация релизов

Установка

Требования:

• Node.js 24+

• Bun 1.3+ (опциональная среда выполнения)

• pnpm 10+ (для локальной разработки)

Примечание по запуску:

• Вы можете запускать/устанавливать через npx, pnpx, bunx или потоки в стиле yarn dlx.

• Поддержка сред выполнения: Node.js (через node:sqlite) и Bun (через bun:sqlite).

Из npm (рекомендуется)

npm install -g mtasa-docs-mcp

или:

pnpm add -g mtasa-docs-mcp

Быстрая установка

Из исходного кода

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

Если ваша среда пропускает опциональные нативные зависимости, выполните:

pnpm install --force

Настройка MCP-клиента

Cursor (вручную)

Глобально: ~/.cursor/mcp.json

Проект: .cursor/mcp.json

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

VS Code (вручную)

Рабочая область: .vscode/mcp.json

Пользователь: Палитра команд -> MCP: Open User Configuration

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

Или добавьте через терминал:

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 (вручную)

Глобальный файл конфигурации: ~/.config/opencode/opencode.json

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

Antigravity (вручную)

Файл конфигурации: ~/.gemini/antigravity/mcp_config.json

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

Универсальные MCP-клиенты (вручную)

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

Если mtasa-docs-mcp уже опубликован, замените команду на:

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

Доступные инструменты

• 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

Разработка

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

Полезные проверки:

• pnpm check:versions — синхронизация версий package.json и MCP-сервера

• pnpm check:changelog — проверка наличия заголовка текущего релиза в CHANGELOG.md

• pnpm check:tool-names — предотвращение регрессий в именовании устаревших инструментов

• pnpm test:runtime — запуск интеграционных тестов среды выполнения для Node и Bun

• pnpm smoke:cross-runtime — запуск дымовых проверок для сред Node и Bun

Скрипты расположены в scripts/ (сборка, дымовые тесты, защитные механизмы релиза).

Процесс релиза

Автоматизация релиза обрабатывается через .github/workflows/release.yml.

1. Увеличьте версию в package.json и src/index.ts.

2. Перенесите примечания к выпуску из Unreleased в версию в CHANGELOG.md, используя ## [x.y.z] - YYYY-MM-DD.

3. Создайте и отправьте тег релиза: git tag v<version> && git push origin v<version>.

Политика ветвления:

• До v1.0.0: разрешены прямые пуши в master.

• Начиная с v1.0.0: используйте разработку через PR для всех изменений в master.

При пуше тега релиза (v*.*.*) рабочий процесс релиза:

• проверяет, существует ли версия в npm

• запускает pnpm verify:full

• публикует в npm с подтверждением происхождения через доверенную публикацию (OIDC)

• публикует server.json в реестр MCP с использованием GitHub OIDC

• создает/обновляет GitHub Release из CHANGELOG.md

• проверяет возможность установки опубликованного пакета и запускает дымовые тесты

Настройка для сопровождающего (доверенная публикация npm)

В настройках пакета npm настройте доверенного издателя для этого репозитория и рабочего процесса:

• Репозиторий: Luminaire1337/mtasa-docs-mcp

• Файл рабочего процесса: .github/workflows/release.yml

• Окружение (если используется): должно соответствовать конфигурации GitHub Actions

Настройка для сопровождающего (публикация в реестре MCP)

• Убедитесь, что server.json существует в корне репозитория и использует имя пакета: mtasa-docs-mcp

• Настройте владение в реестре MCP для io.github.Luminaire1337/mtasa-docs-mcp

• Рабочий процесс релиза использует mcp-publisher login github-oidc и публикует только после прохождения проверки npm

CI-рабочие процессы

• .github/workflows/ci.yml — проверка при пуше/PR в master (Ubuntu + macOS) и опциональные тесты интеграции с живой вики для помеченных PR

• .github/workflows/release.yml — автоматическая публикация и GitHub-релиз при пуше тегов (v*.*.*)

Документация проекта

• AGENTS.md — архитектура и руководство для участников

• FEATURES.md — дорожная карта и идеи

• CHANGELOG.md — история релизов

• SECURITY.md — политика раскрытия уязвимостей

Лицензия

GNU General Public License v3.0. См. LICENSE.