MTA:SA 문서화 MCP 서버

AI 어시스턴트에게 Multi Theft Auto: San Andreas 문서에 대한 신뢰할 수 있고 구조화된 액세스를 제공하는 MCP(Model Context Protocol) 서버입니다.

빠른 키워드 검색, 의미론적 매칭, 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. CHANGELOG.md의 Unreleased에서 버전이 지정된 섹션으로 릴리스 노트를 이동합니다 (## [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를 사용하여 MCP 레지스트리에 server.json 게시

• CHANGELOG.md에서 GitHub 릴리스 생성/업데이트

• 게시된 패키지의 설치 가능 여부 확인 및 스모크 테스트 실행

npm 신뢰할 수 있는 게시를 위한 관리자 설정

npm 패키지 설정에서 이 저장소 및 워크플로우에 대한 신뢰할 수 있는 게시자를 구성하세요:

• 저장소: Luminaire1337/mtasa-docs-mcp

• 워크플로우 파일: .github/workflows/release.yml

• 환경(사용하는 경우): GitHub Actions 구성과 일치시킵니다.

MCP 레지스트리 게시를 위한 관리자 설정

• 저장소 루트에 server.json이 존재하고 다음 패키지 이름을 사용하는지 확인하세요: mtasa-docs-mcp

• io.github.Luminaire1337/mtasa-docs-mcp에 대한 MCP 레지스트리 소유권을 구성하세요.

• 릴리스 워크플로우는 mcp-publisher login github-oidc를 사용하며 npm 게시 게이트를 통과할 때만 게시합니다.

CI 워크플로우

• .github/workflows/ci.yml - master로 푸시/PR 시 검증 (Ubuntu + macOS) 및 레이블이 지정된 PR에 대한 선택적 라이브 위키 통합 테스트

• .github/workflows/release.yml - 릴리스 태그(v*.*.*) 시 자동 게시 및 GitHub 릴리스

프로젝트 문서

• AGENTS.md - 아키텍처 및 기여자 가이드

• FEATURES.md - 로드맵 및 아이디어

• CHANGELOG.md - 릴리스 기록

• SECURITY.md - 취약점 공개 정책

라이선스

GNU General Public License v3.0. LICENSE를 참조하세요.