MTA:SA Documentation MCP Server

MTA:SA 文档 MCP 服务

一个 MCP（Model Context Protocol）服务，为 AI 助手提供可靠、结构化的《Multi Theft Auto: San Andreas》文档访问能力。

它结合了快速关键词搜索、语义匹配和 SQLite 缓存，让 Agent 无需手动抓取 wiki，即可找到合适的 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 开始：对 master 的所有更改都使用基于 PR 的开发方式。

推送发布标签（v*.*.*）时，发布工作流会：

• 检查该版本是否已发布到 npm
• 运行 pnpm verify:full
• 使用可信发布（OIDC）并附带来源证明发布到 npm
• 使用 GitHub OIDC 将 server.json 发布到 MCP Registry
• 根据 CHANGELOG.md 创建或更新 GitHub Release
• 验证已发布软件包是否可安装，并运行冒烟测试

npm 可信发布的维护者设置

在 npm 软件包设置中，为此仓库和工作流配置可信发布者：

• 仓库：Luminaire1337/mtasa-docs-mcp
• 工作流文件：.github/workflows/release.yml
• 环境（如使用）：与 GitHub Actions 配置一致

MCP Registry 发布的维护者设置

• 确保仓库根目录存在 server.json，且使用此软件包名称： mtasa-docs-mcp
• 配置 MCP Registry 对 io.github.Luminaire1337/mtasa-docs-mcp 的所有权
• 发布工作流使用 mcp-publisher login github-oidc，并且仅在 npm 发布门禁通过时发布

CI 工作流

• .github/workflows/ci.yml - 在推送到 master 或向其提交 PR 时进行验证（Ubuntu + macOS），并在带标签的 PR 上运行可选的实时 wiki 集成测试
• .github/workflows/release.yml - 在发布标签（v*.*.*）上自动发布并创建 GitHub Release

项目文档

• AGENTS.md - 架构和贡献者指南
• FEATURES.md - 路线图和构想
• CHANGELOG.md - 发布历史
• SECURITY.md - 漏洞披露政策

许可证

GNU 通用公共许可证 v3.0。请参阅 LICENSE。