mtasa-docs-mcp

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+
• Bun 1.3+ (optional runtime)
• pnpm 10+ (for local development)

Launcher note:

• You can launch/install via npx, pnpx, bunx, or yarn dlx-style flows.
• Runtime support is cross-runtime: Node.js (via node:sqlite) and Bun (via bun:sqlite).

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

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"]
    }
  }
}

Available 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

Development

pnpm build
pnpm test
pnpm test:runtime
pnpm smoke
pnpm smoke:cross-runtime
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
• pnpm test:runtime - run integration runtime tests for Node and Bun smoke paths
• pnpm smoke:cross-runtime - run smoke checks against both Node and Bun runtimes

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

Release Flow

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

• Bump version in package.json and src/index.ts.
• Move release notes from Unreleased into a versioned section in CHANGELOG.md using ## [x.y.z] - YYYY-MM-DD.
• 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)
• publishes server.json to the MCP Registry using GitHub 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

Maintainer setup for MCP Registry publishing

• Ensure server.json exists at repository root and uses this package name: mtasa-docs-mcp
• Configure MCP Registry ownership for io.github.Luminaire1337/mtasa-docs-mcp
• Release workflow uses mcp-publisher login github-oidc and publishes only when the npm publish gate passes

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.