Unity Manual MCP

로컬 Unity 문서 설치를 AI 어시스턴트에 제공하는 로컬 MCP 서버(stdio)입니다.

문서 폴더는 일반적으로 Unity Editors 설치 디렉터리의 Data\Documentation\en 아래에 있습니다.

• Manual/ — 방법 문서로, 챕터로 구성되어 있습니다(약 3.5k 페이지).

• ScriptReference/ — 전체 스크립팅 API 참조, 한 페이지당 클래스 / 프로퍼티 / 메서드 (약 42k 페이지)

첫 시작 시 서버는 모든 페이지의 SQLite 전문(full-text) 인덱스를 구축하고 (Mozilla-Readability 스타일로 기사 본문을 추출하고, 상용구는 제거하며, 코드 예제는 보존) OS 임시 디렉터리에 캐시합니다. 이후 시작 시에는 이를 재사용하며, 문서 파일 수가 변경되면 자동으로 다시 구축됩니다.

요구 사항

• uv

• Python 3.10+ — pyproject.toml에 선언되어 있습니다(fastmcp 3.x에서 요구). uv는 이 조건을 충족하는 이미 설치된 Python을 재사용하며, 호환되는 인터프리터가 없는 경우에만 새로 다운로드합니다.

설정

• 리포지토리 클론

• 클론한 리포지토리 안에서 터미널 열기

• 실행

  uv sync

.venv를 생성하고 pyproject.toml에서 종속성을 설치합니다.

실행

uv run server.py "C:\Program Files\Unity\Hub\Editor\<ver>\Editor\Data\Documentation\en"

...\Documentation 또는 ...\Editor\Data를 가리키면 en 폴더가 자동으로 감지됩니다.

플래그:

• --selftest — 인덱스를 구축하고 샘플 쿼리를 실행한 후 종료합니다(MCP 서버 없음, 새 설치를 확인하는 데 유용)

• --rebuild — 인덱스 재구축을 강제합니다.

• --prune — 매니페스트에서 오래된 캐시 항목(db 파일 누락)을 제거합니다.

• UNITY_DOCS_PATH 환경 변수 — 위치 인수 대신 사용할 수 있습니다.

ℹ 새로 설치한 후 수동으로 서버를 한 번 실행하여 문서를 미리 인덱싱하면 첫 사용 시 대기 시간을 피할 수 있습니다.

uv run server.py --selftest "C:\Program Files\Unity\Hub\Editor\<ver>\Editor\Data\Documentation\en"

MCP 서버 추가

이 서버는 stdio 서버이므로 로컬 프로세스를 시작할 수 있는 모든 클라이언트에서 작동합니다. 각 클라이언트는 동일한 명령을 실행합니다:

uv run --directory "<repo>" server.py "<docs path>"

<repo>는 이 리포지토리의 폴더이고 <docs path>는 Unity 문서 en 폴더입니다(...\Documentation 또는 ...\Editor\Data를 가리키면 자동으로 감지됩니다). uv run은 .venv 환경을 자동으로 생성하고 동기화하므로 클라이언트는 PATH에 uv만 있으면 됩니다.

Claude Desktop

claude_desktop_config.json(자신의 경로로 대체):

{
  "mcpServers": {
    "unity-manual": {
      "command": "uv",
      "args": ["run", "--directory", "<repo>", "server.py", "<docs path>"]
    }
  }
}

Claude Code

claude mcp add unity-manual -- uv run --directory "<repo>" server.py "<docs path>"

OpenCode

프로젝트의 opencode.json 또는 전역 구성 (~/.config/opencode/opencode.json):

{
  "mcp": {
    "unity-manual": {
      "type": "local",
      "command": ["uv", "run", "--directory", "<repo>", "server.py", "<docs path>"],
      "enabled": true
    }
  }
}

Codex

codex mcp add unity-manual -- uv run --directory "<repo>" server.py "<docs path>"

또는 ~/.codex/config.toml을 편집합니다(ChatGPT 데스크톱 앱 및 IDE 확장과 공유됨, 신뢰할 수 있는 프로젝트에서는 프로젝트 범위의 .codex/config.toml도 작동합니다):

[mcp_servers.unity-manual]
command = "uv"
args = ["run", "--directory", "<repo>", "server.py", "<docs path>"]

도구

모든 도구는 읽기 전용입니다(readOnlyHint):

인덱스 캐시

%TEMP%\unity-manual-mcp\에는 편집기당 하나의 db 파일(예: <hash>.db)이 있고, 각 문서 경로를 해당 db 파일에 매핑하는 manifest.json이 있습니다. 편집기를 전환하면 캐시된 인덱스를 재사용하며, HTML 파일 수로 검증됩니다. db 파일을 삭제하거나 (--rebuild 사용) 강제로 다시 구축할 수 있습니다. --selftest는 **오래된(stale)** 항목 (db 파일 누락)과 **고아(orphaned)** 항목(문서 폴더가 사라지고 db는 남아 있는 경우)을 보고하며, --prune은 오래된 항목을 제거합니다.

크레딧

Qwen 3.8 27b가 전적으로 작성했습니다 🙂