MTA:SA Documentation MCP Server

An MCP (Model Context Protocol) server that gives AI assistants reliable,
structured access to Multi Theft Auto: San Andreas documentation.

It combines fast keyword search, semantic matching, and SQLite-backed caching so
agents can discover the right APIs and fetch authoritative docs without manual
wiki scraping.

Highlights

• 11 MCP tools for discovery, docs retrieval, cache operations, and workflow
  guidance
• Event-first discovery (search_events, find_events_for_task)
• Semantic task matching with SQLite vector search
• Smart keyword expansion (for example, database -> db* APIs)
• Built-in deprecation detection and warnings
• Local SQLite cache with configurable lifetime
• CI verification gates, smoke tests, and release automation

Installation

Requirements:

• Node.js 24+
• pnpm 10+ (for local development)

Launcher note:

• You can launch/install via npx, pnpx, bunx, or yarn dlx-style flows,
  but this package still runs on the Node.js runtime.

From npm (recommended)

npm install -g mtasa-docs-mcp

or:

pnpm add -g mtasa-docs-mcp

Quick install

From source

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

If your environment skips optional native dependencies, run:

pnpm install --force
pnpm rebuild better-sqlite3 --config.ignore-scripts=false

MCP Client Setup

Cursor (manual)

Global: ~/.cursor/mcp.json

Project: .cursor/mcp.json

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

VS Code (manual)

Workspace: .vscode/mcp.json

User: Command Palette -> MCP: Open User Configuration

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

Or add it from 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)

Global config file: ~/.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)

Config file: ~/.gemini/antigravity/mcp_config.json

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

Generic MCP clients (manual)

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

If mtasa-docs-mcp is already published, replace the command with:

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

Development

pnpm build
pnpm test
pnpm smoke
pnpm verify
pnpm verify:full

Useful checks:

• pnpm check:versions - keep package.json and MCP server version aligned
• pnpm check:changelog - ensure CHANGELOG.md has current release heading
• pnpm check:tool-names - prevent legacy tool naming regressions

Scripts are located in scripts/ (build, smoke, release guards).

Release Flow

Release automation is handled by .github/workflows/release.yml.

1. Bump version in package.json and src/index.ts.
2. Move release notes from Unreleased into a versioned section in
   CHANGELOG.md using ## [x.y.z] - YYYY-MM-DD.
3. Create and push a release tag: git tag v<version> && git push origin v<version>.

Branching policy:

• Before v1.0.0: direct pushes to master are allowed.
• Starting at v1.0.0: use PR-based development for all changes to master.

On release tag pushes (v*.*.*), the release workflow:

• checks whether the version already exists on npm
• runs pnpm verify:full
• publishes to npm with provenance using trusted publishing (OIDC)
• creates/updates the GitHub Release from CHANGELOG.md
• verifies installability of the published package and runs smoke tests

Maintainer setup for npm trusted publishing

In npm package settings, configure a trusted publisher for this repository and
workflow:

• Repository: Luminaire1337/mtasa-docs-mcp
• Workflow file: .github/workflows/release.yml
• Environment (if used): match your GitHub Actions configuration

CI Workflows

• .github/workflows/ci.yml - verification on push/PR to master (Ubuntu +
  macOS) and optional live wiki integration tests on labeled PRs
• .github/workflows/release.yml - automated publish and GitHub release on
  release tags (v*.*.*)

Project Docs

• AGENTS.md - architecture and contributor guidance
• FEATURES.md - roadmap and ideas
• CHANGELOG.md - release history
• SECURITY.md - vulnerability disclosure policy

License

GNU General Public License v3.0. See LICENSE.