unity-api-mcp 1.0.0__tar.gz

unity_api_mcp-1.0.0/.env.example

@@ -0,0 +1,5 @@
+# Override Unity install path (auto-detected if not set)
+# UNITY_INSTALL_PATH=H:/Unity/6000.3.8f1
+
+# Path to a Unity project for package source parsing (Input System, Addressables)
+# UNITY_PROJECT_PATH=F:/Unity Projects/my-project

unity_api_mcp-1.0.0/.gitignore

@@ -0,0 +1,8 @@
+venv/
+__pycache__/
+*.pyc
+.env
+*.egg-info/
+dist/
+build/
+/data/

unity_api_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,9 @@
+Metadata-Version: 2.4
+Name: unity-api-mcp
+Version: 1.0.0
+Summary: MCP server providing ground-truth Unity 6 API documentation — prevents AI hallucination of signatures, namespaces, and deprecated APIs
+Requires-Python: >=3.10
+Requires-Dist: mcp[cli]>=1.8.0
+Requires-Dist: python-dotenv>=1.0
+Provides-Extra: ingest
+Requires-Dist: lxml>=5.0; extra == 'ingest'

unity_api_mcp-1.0.0/README.md

@@ -0,0 +1,233 @@
+# unity-api-mcp
+
+Local MCP server that gives AI agents accurate Unity 6 API documentation. Prevents hallucinated method signatures, wrong namespaces, and deprecated API usage.
+
+Works with Claude Code, Cursor, Windsurf, or any MCP-compatible AI tool.
+
+## What it does
+
+5 tools your AI can call:
+
+| Tool | Purpose | Example |
+|------|---------|---------|
+| `search_unity_api` | Find APIs by keyword | "Tilemap SetTile", "async load scene" |
+| `get_method_signature` | Get exact signatures with all overloads | `UnityEngine.Physics.Raycast` |
+| `get_namespace` | Resolve `using` directives | "SceneManager" → `using UnityEngine.SceneManagement;` |
+| `get_class_reference` | Full class reference card (all members) | "InputAction" → 31 methods/fields/properties |
+| `get_deprecation_warnings` | Check if an API is obsolete + get replacement | "WWW" → Use UnityWebRequest instead |
+
+**Coverage:** All UnityEngine/UnityEditor modules (~75K records), Input System, Addressables. 78K total records ship pre-built — no ingestion step required.
+
+## Requirements
+
+- Python 3.10+
+- That's it. The database ships pre-built. Unity does not need to be installed.
+
+## Setup
+
+### 1. Install
+
+```bash
+pip install unity-api-mcp
+```
+
+Or install from source:
+```bash
+git clone <repo-url> unity-api-mcp
+cd unity-api-mcp
+pip install .
+```
+
+### 2. Add to your AI tool
+
+#### Claude Code
+
+Add to `~/.claude/mcp.json` (global) or `<project>/.mcp.json` (per-project):
+
+**macOS / Linux:**
+```json
+{
+  "mcpServers": {
+    "unity-api": {
+      "command": "unity-api-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+**Windows:**
+```json
+{
+  "mcpServers": {
+    "unity-api": {
+      "command": "unity-api-mcp.exe",
+      "args": []
+    }
+  }
+}
+```
+
+If the command isn't found (not on PATH), use the full path to the script:
+
+**macOS / Linux:**
+```json
+{
+  "mcpServers": {
+    "unity-api": {
+      "command": "/path/to/venv/bin/unity-api-mcp",
+      "args": []
+    }
+  }
+}
+```
+
+**Windows:**
+```json
+{
+  "mcpServers": {
+    "unity-api": {
+      "command": "C:\\path\\to\\venv\\Scripts\\unity-api-mcp.exe",
+      "args": []
+    }
+  }
+}
+```
+
+#### Cursor / Windsurf
+
+Add the same config to your MCP settings file. The server uses stdio transport (default).
+
+### 3. Verify it's working
+
+Restart your AI tool (or run `/mcp` in Claude Code to reconnect), then ask:
+
+*"What namespace does SceneManager belong to?"*
+
+If everything is connected, it should call `get_namespace("SceneManager")` and answer `using UnityEngine.SceneManagement;`. If it guesses without calling a tool, the MCP server isn't connected — check the config paths and restart.
+
+You can also try: *"Show me all methods on the Tilemap class"* — this should call `get_class_reference` and return 60+ methods.
+
+### 4. Tell your AI to use it proactively
+
+Add the following to your project's `CLAUDE.md` (or equivalent instructions file). **This step is important** — without it, the AI has the tools but won't know when to reach for them.
+
+```markdown
+## Unity API Lookup (unity-api MCP)
+
+Use the `unity-api` MCP tools to verify Unity API usage instead of guessing. **Do not hallucinate signatures.**
+
+| When | Tool | Example |
+|------|------|---------|
+| Unsure about a method's parameters or return type | `get_method_signature` | `get_method_signature("UnityEngine.Tilemaps.Tilemap.SetTile")` |
+| Need the `using` directive for a type | `get_namespace` | `get_namespace("SceneManager")` |
+| Want to see all members on a class | `get_class_reference` | `get_class_reference("InputAction")` |
+| Searching for an API by keyword | `search_unity_api` | `search_unity_api("async load scene")` |
+| Checking if an API is deprecated | `get_deprecation_warnings` | `get_deprecation_warnings("FindObjectOfType")` |
+
+**Rules:**
+- Before writing a Unity API call you haven't used in this conversation, verify the signature with `get_method_signature`
+- Before adding a `using` directive, verify with `get_namespace` if unsure
+- Covers: all UnityEngine/UnityEditor modules, Input System, Addressables
+- Does NOT cover: DOTween, VContainer, Newtonsoft.Json (third-party — rely on project source)
+```
+
+## AI-Assisted Setup
+
+If an AI agent (Claude Code, etc.) is setting this up for you, give it these instructions:
+
+> Read the README at `<path>/unity-api-mcp/README.md` and set up the MCP server for my Unity project at `<project-path>`.
+
+The agent should:
+1. **Install** — `pip install unity-api-mcp` (or `pip install .` if cloned locally)
+2. **Find the executable** — run `which unity-api-mcp` (macOS/Linux) or `where unity-api-mcp` (Windows) to get the full path
+3. **Write MCP config** — add to `~/.claude/mcp.json` with `"command": "<full-path-to-unity-api-mcp>"`
+4. **Add CLAUDE.md instructions** — append the "Unity API Lookup" snippet from Step 4 above to the project's `CLAUDE.md`
+5. **Verify** — reconnect MCP (`/mcp` in Claude Code) and test: `get_namespace("SceneManager")` should return `using UnityEngine.SceneManagement;`
+
+## Advanced: Rebuild or extend the database
+
+The shipped database covers Unity 6 (6000.x) engine APIs + Input System + Addressables. If you need to:
+- **Update for a newer Unity version** — re-run ingestion
+- **Add more packages** (e.g. Cinemachine, TextMeshPro) — re-run with `--project`
+- **Match your exact package versions** — re-run with `--project`
+
+### Run ingestion
+
+```bash
+# Activate venv first, then:
+
+# Engine APIs only (requires Unity 6 installed)
+python -m unity_api_mcp.ingest
+
+# Engine APIs + packages from your project
+python -m unity_api_mcp.ingest --project "/path/to/your/unity/project"
+```
+
+If Unity isn't auto-detected, set the install path:
+
+```bash
+# Windows (Command Prompt)
+set UNITY_INSTALL_PATH=C:\Program Files\Unity\Hub\Editor\6000.3.8f1
+
+# Windows (PowerShell)
+$env:UNITY_INSTALL_PATH = "C:\Program Files\Unity\Hub\Editor\6000.3.8f1"
+
+# macOS/Linux
+export UNITY_INSTALL_PATH=/Applications/Unity/Hub/Editor/6000.3.8f1
+```
+
+You can also add these to the MCP config `env` block so they're always available:
+
+```json
+"env": {
+  "PYTHONPATH": "...",
+  "UNITY_INSTALL_PATH": "...",
+  "UNITY_PROJECT_PATH": "..."
+}
+```
+
+### What ingestion parses
+
+**XML IntelliSense files** — Ship with every Unity installation at `Editor/Data/Managed/`. 139 XML files covering all UnityEngine and UnityEditor modules.
+
+**C# source doc comments** — Unity packages (Input System, Addressables, etc.) ship as source code in your project's `Library/PackageCache/`. The ingestion pipeline parses `///` XML doc comments from `.cs` files.
+
+## Project structure
+
+```
+unity-api-mcp/
+├── src/unity_api_mcp/
+│   ├── server.py          # MCP server — 5 tools
+│   ├── db.py              # SQLite + FTS5 database layer
+│   ├── xml_parser.py      # Parse Unity XML IntelliSense files
+│   ├── cs_doc_parser.py   # Parse C# doc comments from package source
+│   ├── unity_paths.py     # Locate Unity install + package dirs
+│   ├── ingest.py          # CLI ingestion pipeline
+│   └── data/
+│       └── unity_docs.db  # Pre-built SQLite database (78K records, ships with package)
+├── pyproject.toml
+└── .env.example
+```
+
+## Troubleshooting
+
+**"No results found" for a query**
+- The pre-built database should be included in the package. If missing, reinstall: `pip install --force-reinstall unity-api-mcp`
+- Or re-run ingestion to rebuild (see Advanced section)
+
+**Server won't start**
+- Check Python version: `python --version` (needs 3.10+)
+- Check the command path: run `which unity-api-mcp` (macOS/Linux) or `where unity-api-mcp` (Windows)
+- If not found, use the full path in your MCP config
+
+**Third-party packages return no results**
+- DOTween, VContainer, Newtonsoft.Json are not indexed (third-party, not Unity packages)
+- Only Unity first-party packages are supported via ingestion with `--project`
+
+**Want to add more packages**
+- Run `python -m unity_api_mcp.ingest --project "/path/to/project"` to parse all Unity packages in your project's `Library/PackageCache/`
+
+## License
+
+MIT

unity_api_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "unity-api-mcp"
+version = "1.0.0"
+description = "MCP server providing ground-truth Unity 6 API documentation — prevents AI hallucination of signatures, namespaces, and deprecated APIs"
+requires-python = ">=3.10"
+dependencies = [
+    "mcp[cli]>=1.8.0",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+ingest = [
+    "lxml>=5.0",
+]
+
+[project.scripts]
+unity-api-mcp = "unity_api_mcp.server:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/unity_api_mcp"]
+exclude = ["*.db-shm", "*.db-wal"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"src/unity_api_mcp/data/unity_docs.db" = "unity_api_mcp/data/unity_docs.db"

unity_api_mcp-1.0.0/src/unity_api_mcp/cs_doc_parser.py

@@ -0,0 +1,306 @@
+"""Parse C# XML doc comments (///) from source files into structured records.
+
+Used for Unity packages that ship as source code (Input System, Addressables)
+rather than pre-built DLLs with XML IntelliSense files.
+"""
+
+import re
+from pathlib import Path
+
+
+# Match /// comment blocks and the declaration that follows
+_DOC_COMMENT_LINE = re.compile(r"^\s*///\s?(.*)")
+_NAMESPACE_RE = re.compile(r"^\s*namespace\s+([\w.]+)")
+_CLASS_RE = re.compile(
+    r"^\s*(?:public|internal|private|protected)?\s*(?:static\s+)?(?:abstract\s+)?(?:sealed\s+)?(?:partial\s+)?"
+    r"(?:class|struct|interface|enum)\s+(\w+)"
+)
+_METHOD_RE = re.compile(
+    r"^\s*(?:public|internal|protected)\s+(?:static\s+)?(?:virtual\s+)?(?:override\s+)?(?:abstract\s+)?(?:new\s+)?"
+    r"(?:async\s+)?(?:[\w<>\[\],\s?]+?)\s+(\w+)\s*(?:<[^>]+>)?\s*\("
+)
+_PROPERTY_RE = re.compile(
+    r"^\s*(?:public|internal|protected)\s+(?:static\s+)?(?:virtual\s+)?(?:override\s+)?(?:abstract\s+)?(?:new\s+)?"
+    r"([\w<>\[\],\s?]+?)\s+(\w+)\s*\{"
+)
+_FIELD_RE = re.compile(
+    r"^\s*(?:public|internal|protected)\s+(?:static\s+)?(?:readonly\s+)?(?:const\s+)?"
+    r"([\w<>\[\],\s?]+?)\s+(\w+)\s*[;=]"
+)
+_EVENT_RE = re.compile(
+    r"^\s*(?:public|internal|protected)\s+(?:static\s+)?event\s+"
+    r"([\w<>\[\],\s?]+?)\s+(\w+)\s*[;{]"
+)
+_PARAM_RE = re.compile(r"<param\s+name=[\"'](\w+)[\"']>(.*?)</param>")
+_RETURNS_RE = re.compile(r"<returns>(.*?)</returns>")
+_SUMMARY_RE = re.compile(r"<summary>(.*?)</summary>", re.DOTALL)
+_SEE_CREF_RE = re.compile(r"<see\s+cref=[\"']([^\"']+)[\"']\s*/>")
+_XML_TAG_RE = re.compile(r"<[^>]+>")
+
+_DEPRECATED_PATTERNS = re.compile(
+    r"\b(obsolete|deprecated)\b|use\s+\S+\s+instead",
+    re.IGNORECASE,
+)
+
+
+def parse_cs_directory(directory: Path) -> list[dict]:
+    """Recursively parse all .cs files in a directory for XML doc comments."""
+    records = []
+    cs_files = list(directory.rglob("*.cs"))
+
+    for cs_file in cs_files:
+        # Skip test files, samples, editor-only
+        rel = str(cs_file.relative_to(directory))
+        if any(skip in rel.lower() for skip in ("test", "sample", "example", "doccode")):
+            continue
+
+        try:
+            file_records = _parse_cs_file(cs_file)
+            records.extend(file_records)
+        except Exception:
+            continue
+
+    return records
+
+
+def _parse_cs_file(path: Path) -> list[dict]:
+    """Parse a single .cs file and extract documented members."""
+    try:
+        text = path.read_text(encoding="utf-8-sig", errors="replace")
+    except (OSError, UnicodeDecodeError):
+        return []
+
+    lines = text.splitlines()
+    records = []
+    current_namespace = ""
+    class_stack = []  # Stack of class names for nesting
+
+    i = 0
+    while i < len(lines):
+        line = lines[i]
+
+        # Track namespace
+        ns_match = _NAMESPACE_RE.match(line)
+        if ns_match:
+            current_namespace = ns_match.group(1)
+            i += 1
+            continue
+
+        # Track class/struct/interface nesting
+        cls_match = _CLASS_RE.match(line)
+        if cls_match and not _is_doc_comment(line):
+            # Check if there's a doc comment block above
+            doc_block, params, returns_text = _extract_doc_block(lines, i)
+            class_name = cls_match.group(1)
+            class_stack.append(class_name)
+
+            if doc_block:
+                fqn = f"{current_namespace}.{class_name}" if current_namespace else class_name
+                summary = _clean_xml_text(doc_block)
+                deprecated = bool(_DEPRECATED_PATTERNS.search(summary))
+                records.append({
+                    "fqn": fqn,
+                    "namespace": current_namespace,
+                    "class_name": class_name,
+                    "member_name": "",
+                    "member_type": "type",
+                    "summary": summary,
+                    "params_json": [],
+                    "returns_text": "",
+                    "deprecated": deprecated,
+                    "deprecation_hint": _extract_deprecation_hint(summary) if deprecated else "",
+                })
+
+            i += 1
+            continue
+
+        # Track scope for class stack (simplified brace counting)
+        if "}" in line and not "//" in line.split("}")[0]:
+            # This is a rough heuristic — good enough for top-level classes
+            pass
+
+        # Check for doc comment block
+        if _is_doc_comment(line):
+            # Collect the full doc block
+            doc_start = i
+            while i < len(lines) and _is_doc_comment(lines[i]):
+                i += 1
+
+            # Now lines[i] should be the declaration
+            if i < len(lines):
+                decl_line = lines[i]
+                doc_text = "\n".join(
+                    _DOC_COMMENT_LINE.match(lines[j]).group(1)
+                    for j in range(doc_start, i)
+                    if _DOC_COMMENT_LINE.match(lines[j])
+                )
+
+                record = _parse_declaration(
+                    decl_line, doc_text, current_namespace,
+                    class_stack[-1] if class_stack else ""
+                )
+                if record:
+                    records.append(record)
+            continue
+
+        i += 1
+
+    return records
+
+
+def _is_doc_comment(line: str) -> bool:
+    stripped = line.strip()
+    return stripped.startswith("///")
+
+
+def _extract_doc_block(lines: list[str], decl_index: int) -> tuple[str, list[dict], str]:
+    """Look backwards from a declaration to find its doc comment block."""
+    doc_lines = []
+    i = decl_index - 1
+    while i >= 0 and _is_doc_comment(lines[i]):
+        match = _DOC_COMMENT_LINE.match(lines[i])
+        if match:
+            doc_lines.insert(0, match.group(1))
+        i -= 1
+
+    if not doc_lines:
+        return "", [], ""
+
+    doc_text = "\n".join(doc_lines)
+
+    # Extract summary
+    summary_match = _SUMMARY_RE.search(doc_text)
+    summary = summary_match.group(1).strip() if summary_match else doc_text
+
+    # Extract params
+    params = [
+        {"name": m.group(1), "description": _clean_xml_text(m.group(2))}
+        for m in _PARAM_RE.finditer(doc_text)
+    ]
+
+    # Extract returns
+    returns_match = _RETURNS_RE.search(doc_text)
+    returns_text = _clean_xml_text(returns_match.group(1)) if returns_match else ""
+
+    return summary, params, returns_text
+
+
+def _parse_declaration(decl_line: str, doc_text: str,
+                       namespace: str, class_name: str) -> dict | None:
+    """Parse a C# declaration line and combine with doc text into a record."""
+
+    # Extract summary
+    summary_match = _SUMMARY_RE.search(doc_text)
+    summary = _clean_xml_text(summary_match.group(1).strip() if summary_match else doc_text)
+
+    if not summary or len(summary) < 3:
+        return None
+
+    # Extract params
+    params = [
+        {"name": m.group(1), "description": _clean_xml_text(m.group(2))}
+        for m in _PARAM_RE.finditer(doc_text)
+    ]
+
+    # Extract returns
+    returns_match = _RETURNS_RE.search(doc_text)
+    returns_text = _clean_xml_text(returns_match.group(1)) if returns_match else ""
+
+    # Detect deprecation
+    deprecated = bool(_DEPRECATED_PATTERNS.search(summary))
+    deprecation_hint = _extract_deprecation_hint(summary) if deprecated else ""
+
+    # Try to match declaration type
+    # Check class/struct/interface first
+    cls_match = _CLASS_RE.match(decl_line)
+    if cls_match:
+        member_name_str = cls_match.group(1)
+        fqn = f"{namespace}.{member_name_str}" if namespace else member_name_str
+        return {
+            "fqn": fqn,
+            "namespace": namespace,
+            "class_name": member_name_str,
+            "member_name": "",
+            "member_type": "type",
+            "summary": summary,
+            "params_json": params,
+            "returns_text": returns_text,
+            "deprecated": deprecated,
+            "deprecation_hint": deprecation_hint,
+        }
+
+    if not class_name:
+        return None
+
+    # Event (check before property — similar syntax)
+    event_match = _EVENT_RE.match(decl_line)
+    if event_match:
+        member_name_str = event_match.group(2)
+        fqn = f"{namespace}.{class_name}.{member_name_str}" if namespace else f"{class_name}.{member_name_str}"
+        return _build_record(fqn, namespace, class_name, member_name_str, "event",
+                           summary, params, returns_text, deprecated, deprecation_hint)
+
+    # Method
+    method_match = _METHOD_RE.match(decl_line)
+    if method_match:
+        member_name_str = method_match.group(1)
+        # Skip property accessors
+        if member_name_str in ("get", "set", "add", "remove"):
+            return None
+        fqn = f"{namespace}.{class_name}.{member_name_str}" if namespace else f"{class_name}.{member_name_str}"
+        return _build_record(fqn, namespace, class_name, member_name_str, "method",
+                           summary, params, returns_text, deprecated, deprecation_hint)
+
+    # Property
+    prop_match = _PROPERTY_RE.match(decl_line)
+    if prop_match:
+        member_name_str = prop_match.group(2)
+        # Skip common false positives
+        if member_name_str in ("class", "struct", "interface", "enum", "namespace",
+                               "if", "else", "for", "while", "switch", "try", "catch"):
+            return None
+        fqn = f"{namespace}.{class_name}.{member_name_str}" if namespace else f"{class_name}.{member_name_str}"
+        return _build_record(fqn, namespace, class_name, member_name_str, "property",
+                           summary, params, returns_text, deprecated, deprecation_hint)
+
+    # Field
+    field_match = _FIELD_RE.match(decl_line)
+    if field_match:
+        member_name_str = field_match.group(2)
+        fqn = f"{namespace}.{class_name}.{member_name_str}" if namespace else f"{class_name}.{member_name_str}"
+        return _build_record(fqn, namespace, class_name, member_name_str, "field",
+                           summary, params, returns_text, deprecated, deprecation_hint)
+
+    return None
+
+
+def _build_record(fqn, namespace, class_name, member_name, member_type,
+                  summary, params, returns_text, deprecated, deprecation_hint):
+    return {
+        "fqn": fqn,
+        "namespace": namespace,
+        "class_name": class_name,
+        "member_name": member_name,
+        "member_type": member_type,
+        "summary": summary,
+        "params_json": params,
+        "returns_text": returns_text,
+        "deprecated": deprecated,
+        "deprecation_hint": deprecation_hint,
+    }
+
+
+def _clean_xml_text(text: str) -> str:
+    """Strip XML tags and normalize whitespace."""
+    # Replace <see cref="Foo"/> with Foo
+    text = _SEE_CREF_RE.sub(lambda m: m.group(1).split(".")[-1], text)
+    # Strip remaining XML tags
+    text = _XML_TAG_RE.sub("", text)
+    # Normalize whitespace
+    text = re.sub(r"\s+", " ", text).strip()
+    return text
+
+
+def _extract_deprecation_hint(summary: str) -> str:
+    match = re.search(r"(?:use|Use)\s+(\S+?)[\s.]", summary)
+    return match.group(1) if match else ""