From 7997fabbf860ae2bd29d516661a4a699f572afaf Mon Sep 17 00:00:00 2001
From: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Date: Thu, 8 Oct 2026 15:04:21 -0400
Subject: [PATCH 1/3] fix: make MCP server tools correct and testable

- Resolve data files next to server.py so tools work from any working
  directory, and fail at startup instead of returning empty results (#22)
- shader_helper no longer labels URP-only HLSL as HDRP or Built-in code;
  validates pipeline and lists available effects (#24)
- scaffold_script validates C# identifiers, replaces the TARGET_TYPE
  placeholder with an inferred or explicit target_type, gives each state
  machine its own state interface, and notes Editor/test assembly needs (#25)
- lookup_api: multi-word ranked search, category validation, Unity 6
  linearVelocity/linearDamping entries, and new input, ui, networking and
  editor entries so no advertised category is empty (#26)
- Add pytest suite with a stdio MCP smoke test, run it in CI on Python 3.10
  and 3.12, drop unused fastapi/uvicorn, bound mcp to <2, and add pip to
  Dependabot (#36)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MpEiWjv38TrdFcgqU8ER5L
---
 .cursor/mcp.json                         |   5 +-
 .github/dependabot.yml                   |   4 +
 .github/workflows/validate.yml           |  29 ++-
 mcp-server/data/deprecated_patterns.json |  18 ++
 mcp-server/data/shader_properties.json   |   6 +
 mcp-server/data/unity_api_common.json    | 136 ++++++++++++-
 mcp-server/requirements-dev.txt          |   2 +
 mcp-server/requirements.txt              |   4 +-
 mcp-server/server.py                     | 201 ++++++++++++++++---
 mcp-server/tests/conftest.py             |   5 +
 mcp-server/tests/test_server.py          | 233 +++++++++++++++++++++++
 11 files changed, 600 insertions(+), 43 deletions(-)
 create mode 100644 mcp-server/requirements-dev.txt
 create mode 100644 mcp-server/tests/conftest.py
 create mode 100644 mcp-server/tests/test_server.py

diff --git a/.cursor/mcp.json b/.cursor/mcp.json
index d2dc65b..931b6ff 100644
--- a/.cursor/mcp.json
+++ b/.cursor/mcp.json
@@ -2,10 +2,7 @@
   "mcpServers": {
     "unity-dev-tools": {
       "command": "python",
-      "args": ["mcp-server/server.py"],
-      "env": {
-        "UNITY_DATA_PATH": "./mcp-server/data"
-      }
+      "args": ["mcp-server/server.py"]
     }
   }
 }
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
index 5ace460..82f07b3 100644
--- a/.github/dependabot.yml
+++ b/.github/dependabot.yml
@@ -4,3 +4,7 @@ updates:
     directory: "/"
     schedule:
       interval: "weekly"
+  - package-ecosystem: "pip"
+    directory: "/mcp-server"
+    schedule:
+      interval: "weekly"
diff --git a/.github/workflows/validate.yml b/.github/workflows/validate.yml
index 8bb6da6..da6b718 100644
--- a/.github/workflows/validate.yml
+++ b/.github/workflows/validate.yml
@@ -245,6 +245,18 @@ jobs:
           fi
           echo "No em/en dashes found"
 
+      - name: Check C# stays within Unity 6 language version (C# 9)
+        run: |
+          if grep -rnP '^\s*namespace\s+[A-Za-z0-9_.]+\s*;' --include='*.cs' . 2>/dev/null; then
+            echo "::error::File-scoped namespaces are C# 10 and do not compile in Unity 6. Use block-scoped namespaces."
+            exit 1
+          fi
+          if grep -rniP '\b(use|prefer)\s+(file-scoped namespaces|primary constructors)' --include='*.md' --include='*.mdc' skills rules snippets templates 2>/dev/null; then
+            echo "::error::Guidance recommends C# 10+ features that Unity 6 cannot compile."
+            exit 1
+          fi
+          echo "No C# 10+ constructs or recommendations found"
+
       - name: Check for hardcoded credentials
         run: |
           patterns='password\s*=\s*["\x27][^"\x27]+|api_key\s*=\s*["\x27][^"\x27]+|token\s*=\s*["\x27][A-Za-z0-9]+'
@@ -367,22 +379,29 @@ jobs:
           PYEOF
 
   validate-python:
-    name: Validate MCP server
+    name: Validate MCP server (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.12"]
     steps:
       - uses: actions/checkout@v6
 
       - uses: actions/setup-python@v6
         with:
-          python-version: "3.12"
+          python-version: ${{ matrix.python-version }}
 
       - name: Install dependencies
-        run: pip install -r mcp-server/requirements.txt
+        run: pip install -r mcp-server/requirements-dev.txt
 
       - name: Check Python syntax
         run: |
-          python3 -m py_compile mcp-server/server.py
+          python -m py_compile mcp-server/server.py
           for f in mcp-server/tools/*.py; do
-            python3 -m py_compile "$f"
+            python -m py_compile "$f"
           done
           echo "All Python files pass syntax check"
+
+      - name: Run MCP server tests
+        run: python -m pytest mcp-server/tests -v
diff --git a/mcp-server/data/deprecated_patterns.json b/mcp-server/data/deprecated_patterns.json
index ad8fa1b..04316fa 100644
--- a/mcp-server/data/deprecated_patterns.json
+++ b/mcp-server/data/deprecated_patterns.json
@@ -100,5 +100,23 @@
     "replacement": "JSON serialization to Application.persistentDataPath or a save system",
     "reason": "PlayerPrefs is stored in the registry on Windows and has size limits. It is not encrypted, not portable, and not suitable for structured save data.",
     "since_version": "N/A (best practice)"
+  },
+  {
+    "legacy": "Rigidbody.velocity / Rigidbody2D.velocity",
+    "replacement": "Rigidbody.linearVelocity / Rigidbody2D.linearVelocity",
+    "reason": "Renamed in Unity 6 to distinguish linear from angular velocity. The old property is obsolete.",
+    "since_version": "6000.0"
+  },
+  {
+    "legacy": "Rigidbody.drag / Rigidbody.angularDrag",
+    "replacement": "Rigidbody.linearDamping / Rigidbody.angularDamping",
+    "reason": "Renamed in Unity 6 to match physics terminology. The old properties are obsolete.",
+    "since_version": "6000.0"
+  },
+  {
+    "legacy": "[ServerRpc] / [ClientRpc]",
+    "replacement": "[Rpc(SendTo.Server)] / [Rpc(SendTo.ClientsAndHost)]",
+    "reason": "Netcode for GameObjects universal RPCs replace the separate ServerRpc and ClientRpc attributes and support more send targets.",
+    "since_version": "NGO 1.8"
   }
 ]
diff --git a/mcp-server/data/shader_properties.json b/mcp-server/data/shader_properties.json
index 3509005..81d1850 100644
--- a/mcp-server/data/shader_properties.json
+++ b/mcp-server/data/shader_properties.json
@@ -3,6 +3,7 @@
     "effect": "Dissolve",
     "description": "Dissolves an object using a noise texture, revealing or hiding geometry along a threshold. Commonly used for death effects, teleportation, and material transitions.",
     "pipelines": ["urp", "hdrp", "builtin"],
+    "code_pipeline": "urp",
     "properties": [
       {"name": "_DissolveAmount", "type": "Range(0,1)", "description": "Controls how much of the object is dissolved. 0 = fully visible, 1 = fully dissolved."},
       {"name": "_NoiseTex", "type": "2D", "description": "Grayscale noise texture that drives the dissolve pattern."},
@@ -22,6 +23,7 @@
     "effect": "Outline",
     "description": "Renders a visible outline around objects. Used for selection highlights, toon rendering, and interactable object indication.",
     "pipelines": ["urp", "hdrp", "builtin"],
+    "code_pipeline": "urp",
     "properties": [
       {"name": "_OutlineColor", "type": "Color", "description": "Color of the outline."},
       {"name": "_OutlineWidth", "type": "Float", "description": "Thickness of the outline in clip space or world units."},
@@ -40,6 +42,7 @@
     "effect": "Fresnel",
     "description": "Brightens or colors the edges of an object based on view angle. Used for shields, holographic effects, and rim lighting.",
     "pipelines": ["urp", "hdrp", "builtin"],
+    "code_pipeline": "urp",
     "properties": [
       {"name": "_FresnelColor", "type": "Color", "description": "Color applied to the fresnel rim effect."},
       {"name": "_FresnelPower", "type": "Float", "description": "Controls the falloff of the fresnel effect. Higher values create a tighter rim."},
@@ -58,6 +61,7 @@
     "effect": "Toon",
     "description": "Cel-shading effect that quantizes lighting into discrete bands for a cartoon or anime art style.",
     "pipelines": ["urp", "hdrp", "builtin"],
+    "code_pipeline": "urp",
     "properties": [
       {"name": "_BaseColor", "type": "Color", "description": "Main tint color of the surface."},
       {"name": "_ShadowColor", "type": "Color", "description": "Color used for shadowed areas instead of darkening."},
@@ -78,6 +82,7 @@
     "effect": "Water",
     "description": "Stylized or semi-realistic water surface with scrolling normals, depth-based coloring, and vertex displacement.",
     "pipelines": ["urp", "hdrp", "builtin"],
+    "code_pipeline": "urp",
     "properties": [
       {"name": "_ShallowColor", "type": "Color", "description": "Water color in shallow areas near the shore."},
       {"name": "_DeepColor", "type": "Color", "description": "Water color in deep areas away from the shore."},
@@ -100,6 +105,7 @@
     "effect": "Hologram",
     "description": "Sci-fi holographic projection effect with scan lines, flickering, and transparent rendering.",
     "pipelines": ["urp", "hdrp", "builtin"],
+    "code_pipeline": "urp",
     "properties": [
       {"name": "_HoloColor", "type": "Color", "description": "Primary color of the hologram."},
       {"name": "_ScanLineSpeed", "type": "Float", "description": "Speed at which horizontal scan lines scroll."},
diff --git a/mcp-server/data/unity_api_common.json b/mcp-server/data/unity_api_common.json
index e1a7833..cd77b32 100644
--- a/mcp-server/data/unity_api_common.json
+++ b/mcp-server/data/unity_api_common.json
@@ -128,12 +128,20 @@
     "example": "rb.MovePosition(rb.position + velocity * Time.fixedDeltaTime);"
   },
   {
-    "name": "Rigidbody.velocity",
+    "name": "Rigidbody.linearVelocity",
     "namespace": "UnityEngine",
     "category": "physics",
-    "description": "The velocity vector of the Rigidbody in world space. Setting directly bypasses physics simulation - prefer AddForce for realistic movement.",
-    "signature": "Vector3 Rigidbody.velocity { get; set; }",
-    "example": "rb.velocity = new Vector3(rb.velocity.x, jumpSpeed, rb.velocity.z);"
+    "description": "The linear velocity vector of the Rigidbody in world space (renamed from Rigidbody.velocity in Unity 6). Setting directly bypasses physics simulation - prefer AddForce for realistic movement.",
+    "signature": "Vector3 Rigidbody.linearVelocity { get; set; }",
+    "example": "rb.linearVelocity = new Vector3(rb.linearVelocity.x, jumpSpeed, rb.linearVelocity.z);"
+  },
+  {
+    "name": "Rigidbody.linearDamping",
+    "namespace": "UnityEngine",
+    "category": "physics",
+    "description": "Linear drag applied to the Rigidbody (renamed from Rigidbody.drag in Unity 6). angularDamping replaces angularDrag.",
+    "signature": "float Rigidbody.linearDamping { get; set; }",
+    "example": "rb.linearDamping = 0.5f;"
   },
   {
     "name": "Rigidbody2D.AddForce",
@@ -470,5 +478,125 @@
     "description": "Finds the first loaded object of the given type with deterministic ordering by instance ID. Unity 2023.1+.",
     "signature": "static T Object.FindFirstObjectByType<T>(FindObjectsInactive findObjectsInactive = FindObjectsInactive.Exclude)",
     "example": "var player = FindFirstObjectByType<PlayerController>();"
+  },
+  {
+    "name": "InputSystem.actions",
+    "namespace": "UnityEngine.InputSystem",
+    "category": "input",
+    "description": "The project-wide Input Action Asset (Unity 6). Configure actions in Project Settings > Input System Package and look them up by name at runtime.",
+    "signature": "static InputActionAsset InputSystem.actions { get; set; }",
+    "example": "var move = InputSystem.actions.FindAction(\"Move\");"
+  },
+  {
+    "name": "InputActionAsset.FindAction",
+    "namespace": "UnityEngine.InputSystem",
+    "category": "input",
+    "description": "Finds an action by name, \"Map/Action\" path, or ID. Cache the result in Awake or Start instead of looking it up every frame.",
+    "signature": "InputAction InputActionAsset.FindAction(string actionNameOrId, bool throwIfNotFound = false)",
+    "example": "_jump = InputSystem.actions.FindAction(\"Player/Jump\", throwIfNotFound: true);"
+  },
+  {
+    "name": "InputAction.ReadValue",
+    "namespace": "UnityEngine.InputSystem",
+    "category": "input",
+    "description": "Reads the current value of the action, for example a Vector2 for a move stick or composite.",
+    "signature": "TValue InputAction.ReadValue<TValue>() where TValue : struct",
+    "example": "Vector2 move = _move.ReadValue<Vector2>();"
+  },
+  {
+    "name": "InputAction.WasPressedThisFrame",
+    "namespace": "UnityEngine.InputSystem",
+    "category": "input",
+    "description": "Returns true if the action was pressed during the current frame. Replaces Input.GetButtonDown polling.",
+    "signature": "bool InputAction.WasPressedThisFrame()",
+    "example": "if (_jump.WasPressedThisFrame()) Jump();"
+  },
+  {
+    "name": "UIDocument.rootVisualElement",
+    "namespace": "UnityEngine.UIElements",
+    "category": "ui",
+    "description": "The root VisualElement of a UI Toolkit document. Query it in OnEnable, since the tree is rebuilt when the UIDocument is enabled.",
+    "signature": "VisualElement UIDocument.rootVisualElement { get; }",
+    "example": "var root = GetComponent<UIDocument>().rootVisualElement;"
+  },
+  {
+    "name": "UQueryExtensions.Q",
+    "namespace": "UnityEngine.UIElements",
+    "category": "ui",
+    "description": "Returns the first descendant element matching the type, name, and/or USS class.",
+    "signature": "static T UQueryExtensions.Q<T>(this VisualElement e, string name = null, string className = null) where T : VisualElement",
+    "example": "var playButton = root.Q<Button>(\"play-button\");"
+  },
+  {
+    "name": "Button.clicked",
+    "namespace": "UnityEngine.UIElements",
+    "category": "ui",
+    "description": "Event raised when a UI Toolkit Button is clicked. Unsubscribe in OnDisable to avoid duplicate handlers.",
+    "signature": "event Action Button.clicked",
+    "example": "playButton.clicked += OnPlayClicked;"
+  },
+  {
+    "name": "VisualElement.SetBinding",
+    "namespace": "UnityEngine.UIElements",
+    "category": "ui",
+    "description": "Runtime data binding (Unity 6): binds an element property to a path on its dataSource.",
+    "signature": "void VisualElement.SetBinding(BindingId bindingId, Binding binding)",
+    "example": "label.dataSource = playerData; label.SetBinding(\"text\", new DataBinding { dataSourcePath = new PropertyPath(nameof(PlayerData.Name)) });"
+  },
+  {
+    "name": "NetworkManager.StartHost",
+    "namespace": "Unity.Netcode",
+    "category": "networking",
+    "description": "Starts a server and a local client (Netcode for GameObjects). Use StartServer or StartClient for dedicated roles.",
+    "signature": "bool NetworkManager.StartHost()",
+    "example": "NetworkManager.Singleton.StartHost();"
+  },
+  {
+    "name": "NetworkVariable",
+    "namespace": "Unity.Netcode",
+    "category": "networking",
+    "description": "A value synchronized from the server (or owner) to clients. Subscribe to OnValueChanged in OnNetworkSpawn.",
+    "signature": "NetworkVariable<T>(T value = default, NetworkVariableReadPermission readPerm = NetworkVariableReadPermission.Everyone, NetworkVariableWritePermission writePerm = NetworkVariableWritePermission.Server)",
+    "example": "private readonly NetworkVariable<int> _health = new(100);"
+  },
+  {
+    "name": "RpcAttribute",
+    "namespace": "Unity.Netcode",
+    "category": "networking",
+    "description": "Universal RPC attribute (Netcode for GameObjects 1.8+ and 2.x) that replaces [ServerRpc] and [ClientRpc]. The method name must end in Rpc.",
+    "signature": "[Rpc(SendTo target)]",
+    "example": "[Rpc(SendTo.Server)] private void FireRpc(Vector3 direction) { /* runs on server */ }"
+  },
+  {
+    "name": "EditorWindow.GetWindow",
+    "namespace": "UnityEditor",
+    "category": "editor",
+    "description": "Returns the first open EditorWindow of type T, creating and showing one if none exists.",
+    "signature": "static T EditorWindow.GetWindow<T>(string title) where T : EditorWindow",
+    "example": "[MenuItem(\"Tools/Level Builder\")] static void Open() => GetWindow<LevelBuilderWindow>(\"Level Builder\");"
+  },
+  {
+    "name": "Editor.CreateInspectorGUI",
+    "namespace": "UnityEditor",
+    "category": "editor",
+    "description": "Override to build a custom inspector with UI Toolkit. Return a VisualElement; use InspectorElement.FillDefaultInspector to include the default fields.",
+    "signature": "virtual VisualElement Editor.CreateInspectorGUI()",
+    "example": "public override VisualElement CreateInspectorGUI() { var root = new VisualElement(); InspectorElement.FillDefaultInspector(root, serializedObject, this); return root; }"
+  },
+  {
+    "name": "PrefabUtility.InstantiatePrefab",
+    "namespace": "UnityEditor",
+    "category": "editor",
+    "description": "Instantiates a prefab asset in the scene while keeping the prefab connection. Returns null if passed a scene object instead of an asset.",
+    "signature": "static Object PrefabUtility.InstantiatePrefab(Object assetComponentOrGameObject)",
+    "example": "var go = (GameObject)PrefabUtility.InstantiatePrefab(prefab); Undo.RegisterCreatedObjectUndo(go, \"Place Prefab\");"
+  },
+  {
+    "name": "Undo.RegisterCreatedObjectUndo",
+    "namespace": "UnityEditor",
+    "category": "editor",
+    "description": "Registers a newly created object so the creation can be undone with Ctrl+Z.",
+    "signature": "static void Undo.RegisterCreatedObjectUndo(Object objectToUndo, string name)",
+    "example": "Undo.RegisterCreatedObjectUndo(go, \"Create Enemy\");"
   }
 ]
diff --git a/mcp-server/requirements-dev.txt b/mcp-server/requirements-dev.txt
new file mode 100644
index 0000000..044d133
--- /dev/null
+++ b/mcp-server/requirements-dev.txt
@@ -0,0 +1,2 @@
+-r requirements.txt
+pytest>=8,<9
diff --git a/mcp-server/requirements.txt b/mcp-server/requirements.txt
index 59128d8..0c8a4f5 100644
--- a/mcp-server/requirements.txt
+++ b/mcp-server/requirements.txt
@@ -1,3 +1 @@
-mcp>=1.0.0
-fastapi>=0.100.0
-uvicorn>=0.23.0
+mcp>=1.2.0,<2
diff --git a/mcp-server/server.py b/mcp-server/server.py
index c08cefa..a4c485c 100644
--- a/mcp-server/server.py
+++ b/mcp-server/server.py
@@ -6,23 +6,45 @@
 
 import json
 import os
+import re
+import sys
 from pathlib import Path
 
 from mcp.server.fastmcp import FastMCP
 
-DATA_PATH = Path(os.environ.get("UNITY_DATA_PATH", "./data"))
+# Resolve data next to this file so the server works from any working
+# directory. UNITY_DATA_PATH remains available as an explicit override.
+DATA_PATH = Path(
+    os.environ.get("UNITY_DATA_PATH") or Path(__file__).resolve().parent / "data"
+)
+
+DATA_FILES = (
+    "unity_api_common.json",
+    "deprecated_patterns.json",
+    "shader_properties.json",
+    "platform_defines.json",
+)
 
 mcp = FastMCP("unity-dev-tools")
 
 
-def _load_json(filename: str) -> list | dict:
+def _load_json(filename: str) -> list:
     filepath = DATA_PATH / filename
     if not filepath.exists():
-        return []
+        raise FileNotFoundError(
+            f"Unity data file not found: {filepath}. "
+            "Check UNITY_DATA_PATH or reinstall the plugin."
+        )
     with open(filepath, "r", encoding="utf-8") as f:
         return json.load(f)
 
 
+def _check_data_files() -> None:
+    """Fail at startup instead of answering every query with 'not found'."""
+    for filename in DATA_FILES:
+        _load_json(filename)
+
+
 # ---------- Tool: scaffold_script ----------
 
 SCRIPT_TEMPLATES = {
@@ -105,7 +127,7 @@ def _load_json(filename: str) -> list | dict:
 
 namespace {namespace}.Editor
 {{
-    [CustomEditor(typeof(TARGET_TYPE))]
+    [CustomEditor(typeof({target_type}))]
     public class {name} : UnityEditor.Editor
     {{
         public override VisualElement CreateInspectorGUI()
@@ -121,7 +143,7 @@ def _load_json(filename: str) -> list | dict:
 
 namespace {namespace}.Editor
 {{
-    [CustomPropertyDrawer(typeof(TARGET_TYPE))]
+    [CustomPropertyDrawer(typeof({target_type}))]
     public class {name} : PropertyDrawer
     {{
         public override VisualElement CreatePropertyGUI(SerializedProperty property)
@@ -144,7 +166,7 @@ def _load_json(filename: str) -> list | dict:
 
 namespace {namespace}
 {{
-    public interface IState
+    public interface I{name}State
     {{
         void Enter();
         void Update();
@@ -154,9 +176,9 @@ def _load_json(filename: str) -> list | dict:
 
     public class {name} : MonoBehaviour
     {{
-        private IState _currentState;
+        private I{name}State _currentState;
 
-        public void ChangeState(IState newState)
+        public void ChangeState(I{name}State newState)
         {{
             _currentState?.Exit();
             _currentState = newState;
@@ -195,11 +217,46 @@ def _load_json(filename: str) -> list | dict:
 }
 
 
+CSHARP_KEYWORDS = frozenset("""
+abstract as base bool break byte case catch char checked class const continue
+decimal default delegate do double else enum event explicit extern false finally
+fixed float for foreach goto if implicit in int interface internal is lock long
+namespace new null object operator out override params private protected public
+readonly ref return sbyte sealed short sizeof stackalloc static string struct
+switch this throw true try typeof uint ulong unchecked unsafe ushort using
+virtual void volatile while
+""".split())
+
+_IDENTIFIER = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*$")
+
+# Suffixes stripped from an inspector or drawer class name to guess its target.
+_TARGET_SUFFIXES = ("PropertyDrawer", "Inspector", "Editor", "Drawer")
+
+
+def _identifier_error(value: str, label: str) -> str | None:
+    if not _IDENTIFIER.match(value):
+        return (
+            f"Invalid {label} '{value}': use letters, digits, and underscores, "
+            "starting with a letter (e.g. PlayerHealth)."
+        )
+    if value in CSHARP_KEYWORDS:
+        return f"Invalid {label} '{value}': it is a reserved C# keyword."
+    return None
+
+
+def _guess_target_type(name: str) -> str:
+    for suffix in _TARGET_SUFFIXES:
+        if name.endswith(suffix) and len(name) > len(suffix):
+            return name[: -len(suffix)]
+    return ""
+
+
 @mcp.tool()
 def scaffold_script(
     type: str,
     name: str,
     namespace: str = "MyGame",
+    target_type: str = "",
 ) -> str:
     """Generate a well-structured C# script following Unity conventions.
 
@@ -208,13 +265,39 @@ def scaffold_script(
               custom-inspector, property-drawer, interface, state-machine, test)
         name: Class name for the generated script
         namespace: C# namespace (default: MyGame)
+        target_type: Type inspected or drawn, for custom-inspector and
+                     property-drawer. Defaults to the name without an
+                     Editor/Inspector/Drawer suffix (PlayerEditor -> Player).
     """
     template = SCRIPT_TEMPLATES.get(type)
     if not template:
         valid = ", ".join(SCRIPT_TEMPLATES.keys())
         return f"Unknown script type: {type}. Valid types: {valid}"
 
-    code = template.format(name=name, namespace=namespace)
+    error = _identifier_error(name, "class name")
+    for segment in namespace.split("."):
+        error = error or _identifier_error(segment, "namespace segment")
+    if error:
+        return error
+
+    notes = []
+    if type in ("custom-inspector", "property-drawer"):
+        target_type = target_type or _guess_target_type(name)
+        if not target_type:
+            return (
+                f"Cannot infer the target type for '{name}'. Pass target_type, "
+                "or name the class <Target>Editor / <Target>Drawer."
+            )
+        error = _identifier_error(target_type, "target type")
+        if error:
+            return error
+
+    if type == "interface" and not re.match(r"^I[A-Z]", name):
+        notes.append(
+            f"// Note: interfaces use an I prefix by convention (I{name})."
+        )
+
+    code = template.format(name=name, namespace=namespace, target_type=target_type)
 
     folder_map = {
         "monobehaviour": "Assets/Scripts/Runtime",
@@ -226,9 +309,23 @@ def scaffold_script(
         "state-machine": "Assets/Scripts/Runtime",
         "test": "Assets/Tests/EditMode",
     }
-    path = f"{folder_map.get(type, 'Assets/Scripts')}/{name}.cs"
+    folder = folder_map.get(type, "Assets/Scripts")
+    path = f"{folder}/{name}.cs"
+
+    if folder.endswith("/Editor"):
+        notes.append(
+            "// Editor-only: keep this in an Editor folder or an Editor-only "
+            "assembly definition (includePlatforms: [\"Editor\"]) so player "
+            "builds do not include UnityEditor."
+        )
+    if type == "test":
+        notes.append(
+            "// Requires a test assembly: create one with Assets > Create > "
+            "Testing > Tests Assembly Folder, and reference your runtime asmdef."
+        )
 
-    return f"// Recommended path: {path}\n\n{code}"
+    header = "\n".join([f"// Recommended path: {path}", *notes])
+    return f"{header}\n\n{code}"
 
 
 # ---------- Tool: lookup_api ----------
@@ -242,29 +339,51 @@ def lookup_api(
 
     Args:
         query: Search term (class name, method name, or keyword)
-        category: Optional filter (physics, ui, animation, audio, rendering,
-                  input, networking, editor)
+        category: Optional filter (general, physics, ui, animation, audio,
+                  rendering, input, networking, editor)
     """
     api_data = _load_json("unity_api_common.json")
     deprecated = _load_json("deprecated_patterns.json")
 
-    query_lower = query.lower()
-    results = []
+    categories = sorted({e.get("category", "").lower() for e in api_data})
+    category = category.strip().lower()
+    if category and category not in categories:
+        return (
+            f"Unknown category '{category}'. "
+            f"Valid categories: {', '.join(categories)}"
+        )
+
+    query_lower = query.strip().lower()
+    terms = query_lower.split()
+    scored = []
 
     for entry in api_data:
-        name = entry.get("name", "")
-        desc = entry.get("description", "")
-        cat = entry.get("category", "")
+        name = entry.get("name", "").lower()
+        if category and entry.get("category", "").lower() != category:
+            continue
 
-        if category and cat.lower() != category.lower():
+        haystack = " ".join(
+            entry.get(field, "") for field in ("name", "namespace", "description")
+        ).lower()
+        if not terms or not all(term in haystack for term in terms):
             continue
 
-        if query_lower in name.lower() or query_lower in desc.lower():
-            results.append(entry)
+        # Exact name first, then name matches, then description-only matches.
+        if name == query_lower:
+            score = 0
+        elif all(term in name for term in terms):
+            score = 1
+        else:
+            score = 2
+        scored.append((score, entry))
+
+    scored.sort(key=lambda item: item[0])
+    results = [entry for _, entry in scored]
 
     warnings = []
     for dep in deprecated:
-        if query_lower in dep.get("legacy", "").lower():
+        legacy = dep.get("legacy", "").lower()
+        if terms and all(term in legacy for term in terms):
             warnings.append(
                 f"WARNING: '{dep['legacy']}' is deprecated. "
                 f"Use '{dep['replacement']}' instead. "
@@ -277,7 +396,11 @@ def lookup_api(
         output.append("")
 
     if not results:
-        output.append(f"No API entries found for '{query}'.")
+        output.append(
+            f"No API entries found for '{query}'. "
+            f"Try a class or member name, or filter by category: "
+            f"{', '.join(categories)}"
+        )
     else:
         for entry in results[:15]:
             output.append(f"## {entry['name']}")
@@ -308,18 +431,27 @@ def shader_helper(
     """
     shader_data = _load_json("shader_properties.json")
 
-    effect_lower = effect.lower()
+    effect_lower = effect.strip().lower()
+    pipeline = pipeline.strip().lower()
+    valid_pipelines = ("urp", "hdrp", "builtin")
+    if pipeline not in valid_pipelines:
+        return (
+            f"Unknown pipeline '{pipeline}'. "
+            f"Valid pipelines: {', '.join(valid_pipelines)}"
+        )
+
     results = []
 
     for entry in shader_data:
         if effect_lower in entry.get("effect", "").lower():
-            if pipeline.lower() in entry.get("pipelines", []):
+            if pipeline in entry.get("pipelines", []):
                 results.append(entry)
 
     if not results:
+        effects = ", ".join(e.get("effect", "").lower() for e in shader_data)
         return (
             f"No shader patterns found for effect '{effect}' "
-            f"on pipeline '{pipeline}'."
+            f"on pipeline '{pipeline}'. Available effects: {effects}"
         )
 
     output = []
@@ -334,8 +466,17 @@ def shader_helper(
                     f"- `{prop['name']}` ({prop['type']}): {prop['description']}"
                 )
 
-        if entry.get("code_snippet"):
+        # The hand-written HLSL targets a single pipeline; never present it as
+        # code for another one.
+        code_pipeline = entry.get("code_pipeline", "urp")
+        if entry.get("code_snippet") and code_pipeline == pipeline:
             output.append(f"\n**Code**:\n```hlsl\n{entry['code_snippet']}\n```")
+        elif entry.get("code_snippet"):
+            output.append(
+                f"\n**Code**: No hand-written HLSL for {pipeline.upper()} yet "
+                f"(the reference snippet targets {code_pipeline.upper()} and "
+                "will not compile here). Use the Shader Graph approach below."
+            )
 
         if entry.get("shader_graph_nodes"):
             output.append("\n**Shader Graph Approach**:")
@@ -397,4 +538,10 @@ def platform_info(
 
 
 if __name__ == "__main__":
+    try:
+        _check_data_files()
+    except (FileNotFoundError, json.JSONDecodeError) as exc:
+        # stdout carries the MCP protocol, so report on stderr.
+        print(f"unity-dev-tools: {exc}", file=sys.stderr)
+        sys.exit(1)
     mcp.run(transport="stdio")
diff --git a/mcp-server/tests/conftest.py b/mcp-server/tests/conftest.py
new file mode 100644
index 0000000..7ff4b7e
--- /dev/null
+++ b/mcp-server/tests/conftest.py
@@ -0,0 +1,5 @@
+import sys
+from pathlib import Path
+
+SERVER_DIR = Path(__file__).resolve().parent.parent
+sys.path.insert(0, str(SERVER_DIR))
diff --git a/mcp-server/tests/test_server.py b/mcp-server/tests/test_server.py
new file mode 100644
index 0000000..07f5593
--- /dev/null
+++ b/mcp-server/tests/test_server.py
@@ -0,0 +1,233 @@
+"""Tests for the Unity Developer Tools MCP server tools."""
+
+import asyncio
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+import server
+
+SERVER_DIR = Path(__file__).resolve().parent.parent
+
+
+# ---------- data loading ----------
+
+def test_tools_work_from_any_working_directory(tmp_path, monkeypatch):
+    monkeypatch.chdir(tmp_path)
+    assert "## Rigidbody.AddForce" in server.lookup_api("Rigidbody")
+    assert "UNITY_STANDALONE_WIN" in server.platform_info("windows")
+
+
+def test_missing_data_file_raises(tmp_path, monkeypatch):
+    monkeypatch.setattr(server, "DATA_PATH", tmp_path)
+    with pytest.raises(FileNotFoundError, match="unity_api_common.json"):
+        server.lookup_api("Rigidbody")
+
+
+def test_all_data_files_present():
+    server._check_data_files()
+
+
+# ---------- lookup_api ----------
+
+@pytest.mark.parametrize(
+    "category",
+    ["general", "physics", "ui", "animation", "audio", "rendering",
+     "input", "networking", "editor"],
+)
+def test_every_advertised_category_has_entries(category):
+    entries = [
+        e for e in server._load_json("unity_api_common.json")
+        if e["category"] == category
+    ]
+    assert entries, f"category '{category}' is advertised but empty"
+
+
+def test_category_filter_returns_only_that_category():
+    result = server.lookup_api("Input", "input")
+    assert "## InputAction.ReadValue" in result
+    assert "**Category**: physics" not in result
+
+
+def test_unknown_category_lists_valid_ones():
+    result = server.lookup_api("Rigidbody", "weapons")
+    assert "Unknown category" in result
+    assert "physics" in result
+
+
+def test_multi_word_query_matches_all_terms():
+    assert "## SceneManager.LoadSceneAsync" in server.lookup_api("load scene async")
+
+
+def test_results_ranked_exact_then_name_then_description(tmp_path, monkeypatch):
+    def api(name, description):
+        return {"name": name, "namespace": "UnityEngine", "category": "general",
+                "description": description, "signature": ""}
+
+    # Stored in worst-first order so the test fails if ranking is skipped.
+    (tmp_path / "unity_api_common.json").write_text(json.dumps([
+        api("Time.timeScale", "Scales Time.deltaTime."),
+        api("Time.deltaTimeScaled", "Name contains the query."),
+        api("Time.deltaTime", "Exact match."),
+    ]))
+    (tmp_path / "deprecated_patterns.json").write_text("[]")
+    monkeypatch.setattr(server, "DATA_PATH", tmp_path)
+
+    result = server.lookup_api("Time.deltaTime")
+    order = [line[3:] for line in result.splitlines() if line.startswith("## ")]
+    assert order == ["Time.deltaTime", "Time.deltaTimeScaled", "Time.timeScale"]
+
+
+def test_no_obsolete_velocity_entry():
+    names = {e["name"] for e in server._load_json("unity_api_common.json")}
+    assert "Rigidbody.velocity" not in names
+    assert "Rigidbody.linearVelocity" in names
+
+
+def test_velocity_query_warns_about_unity6_rename():
+    result = server.lookup_api("velocity")
+    assert "WARNING" in result
+    assert "linearVelocity" in result
+
+
+def test_no_results_message_suggests_categories():
+    result = server.lookup_api("zzznotanapi")
+    assert "No API entries found" in result
+    assert "networking" in result
+
+
+# ---------- shader_helper ----------
+
+def test_urp_returns_hlsl_code():
+    result = server.shader_helper("toon", "urp")
+    assert "```hlsl" in result
+    assert "GetMainLight" in result
+
+
+@pytest.mark.parametrize("pipeline", ["hdrp", "builtin"])
+def test_non_urp_pipelines_do_not_get_urp_code(pipeline):
+    for effect in ("dissolve", "outline", "fresnel", "toon", "water", "hologram"):
+        result = server.shader_helper(effect, pipeline)
+        assert "```hlsl" not in result, f"{effect} on {pipeline} returned URP code"
+        assert "Shader Graph" in result
+
+
+def test_unknown_pipeline_rejected():
+    assert "Unknown pipeline" in server.shader_helper("toon", "lwrp")
+
+
+def test_unknown_effect_lists_available_effects():
+    result = server.shader_helper("lava", "urp")
+    assert "Available effects" in result
+    assert "dissolve" in result
+
+
+# ---------- scaffold_script ----------
+
+ALL_TYPES = list(server.SCRIPT_TEMPLATES)
+
+
+@pytest.mark.parametrize("script_type", ALL_TYPES)
+def test_templates_have_no_placeholders_and_balanced_braces(script_type):
+    name = {
+        "custom-inspector": "PlayerEditor",
+        "property-drawer": "RangeDrawer",
+        "interface": "IDamageable",
+    }.get(script_type, "PlayerHealth")
+    result = server.scaffold_script(script_type, name, "Game.Core")
+    assert "TARGET_TYPE" not in result
+    assert "{" in result and result.count("{") == result.count("}")
+    assert f"class {name}" in result or f"interface {name}" in result
+
+
+@pytest.mark.parametrize("bad_name", ["My Player", "1Player", "Player-Health", "class", ""])
+def test_invalid_class_names_rejected(bad_name):
+    result = server.scaffold_script("monobehaviour", bad_name)
+    assert result.startswith("Invalid class name")
+
+
+def test_invalid_namespace_rejected():
+    result = server.scaffold_script("monobehaviour", "Player", "Game..Core")
+    assert result.startswith("Invalid namespace segment")
+
+
+def test_inspector_infers_target_type_from_name():
+    result = server.scaffold_script("custom-inspector", "PlayerEditor")
+    assert "[CustomEditor(typeof(Player))]" in result
+
+
+def test_drawer_uses_explicit_target_type():
+    result = server.scaffold_script("property-drawer", "MinMaxView", target_type="MinMaxRange")
+    assert "[CustomPropertyDrawer(typeof(MinMaxRange))]" in result
+
+
+def test_inspector_without_inferable_target_asks_for_one():
+    result = server.scaffold_script("custom-inspector", "Inspector")
+    assert "Pass target_type" in result
+
+
+def test_state_machines_do_not_share_an_interface_name():
+    first = server.scaffold_script("state-machine", "EnemyBrain")
+    second = server.scaffold_script("state-machine", "PlayerBrain")
+    assert "interface IEnemyBrainState" in first
+    assert "interface IPlayerBrainState" in second
+
+
+def test_editor_scripts_get_editor_only_note():
+    result = server.scaffold_script("editor-window", "LevelTools")
+    assert "Assets/Scripts/Editor/LevelTools.cs" in result
+    assert "Editor-only" in result
+
+
+def test_test_scripts_mention_test_assembly():
+    result = server.scaffold_script("test", "HealthTests")
+    assert "Tests Assembly Folder" in result
+
+
+def test_interface_without_prefix_gets_note():
+    assert "I prefix" in server.scaffold_script("interface", "Damageable")
+    assert "I prefix" not in server.scaffold_script("interface", "IDamageable")
+
+
+def test_unknown_type_lists_valid_types():
+    result = server.scaffold_script("ecs", "Mover")
+    assert "Unknown script type" in result
+    assert "monobehaviour" in result
+
+
+# ---------- platform_info ----------
+
+def test_platform_info_known_and_unknown():
+    assert "UNITY_WEBGL" in server.platform_info("WebGL")
+    result = server.platform_info("dreamcast")
+    assert "Unknown platform" in result
+    assert "windows" in result
+
+
+# ---------- MCP protocol smoke test ----------
+
+def test_stdio_server_lists_and_calls_tools(tmp_path):
+    """Start server.py over stdio from an unrelated directory and call a tool."""
+    from mcp import ClientSession, StdioServerParameters
+    from mcp.client.stdio import stdio_client
+
+    params = StdioServerParameters(
+        command=sys.executable,
+        args=[str(SERVER_DIR / "server.py")],
+        cwd=str(tmp_path),
+    )
+
+    async def run():
+        async with stdio_client(params) as (read, write):
+            async with ClientSession(read, write) as session:
+                await session.initialize()
+                tools = await session.list_tools()
+                names = {tool.name for tool in tools.tools}
+                result = await session.call_tool("platform_info", {"platform": "ios"})
+                return names, result.content[0].text
+
+    names, text = asyncio.run(asyncio.wait_for(run(), timeout=60))
+    assert names == {"scaffold_script", "lookup_api", "shader_helper", "platform_info"}
+    assert "UNITY_IOS" in text

From b2084017e0d37fbfc8e219a2255160c1fc37fb10 Mon Sep 17 00:00:00 2001
From: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Date: Thu, 8 Oct 2026 15:04:23 -0400
Subject: [PATCH 2/3] fix: stop recommending C# 10+ features that Unity 6
 cannot compile

The C# conventions rule told the AI to use file-scoped namespaces and
primary constructors. Unity 6 compiles C# 9, so both fail to build.
Replace them with an explicit C# 9 constraint (#30).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MpEiWjv38TrdFcgqU8ER5L
---
 rules/csharp-unity-conventions.mdc | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/rules/csharp-unity-conventions.mdc b/rules/csharp-unity-conventions.mdc
index 071a770..fc7e0e5 100644
--- a/rules/csharp-unity-conventions.mdc
+++ b/rules/csharp-unity-conventions.mdc
@@ -20,5 +20,5 @@ standards-version: 1.10.0
 - Prefer async/await with Awaitable (Unity 6+) over IEnumerator coroutines for new code
 - An Awaitable instance must never be awaited more than once (it is pooled)
 - Use `FindFirstObjectByType<T>()` instead of the deprecated `FindObjectOfType<T>()`
-- Use file-scoped namespaces to reduce nesting
-- Prefer primary constructors for simple data types
+- Unity 6 compiles C# 9: use block-scoped namespaces (`namespace MyGame { ... }`)
+- Do not use C# 10+ features: file-scoped namespaces, primary constructors on classes or structs, `required` members, raw string literals, collection expressions

From 9f1ad3013f642cee305ad1e7ffa4c65d6b760bd8 Mon Sep 17 00:00:00 2001
From: TMHSDigital <154358121+TMHSDigital@users.noreply.github.com>
Date: Thu, 8 Oct 2026 15:04:25 -0400
Subject: [PATCH 3/3] docs: align MCP tool docs with actual behavior

Remove the ECS scaffolding claim and the "200+ entries" count, and
document target_type, ranked search, URP-only HLSL, data path behavior,
and how to run the tests.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MpEiWjv38TrdFcgqU8ER5L
---
 README.md            |  4 ++--
 docs/index.md        |  4 ++--
 mcp-server/README.md | 22 +++++++++++++++++-----
 3 files changed, 21 insertions(+), 9 deletions(-)

diff --git a/README.md b/README.md
index 4e70241..e4c9c64 100644
--- a/README.md
+++ b/README.md
@@ -71,7 +71,7 @@ Then ask the AI agent to scaffold a MonoBehaviour, look up an API, or generate a
 
 ## Features
 
-- **Script scaffolding** -- Generate MonoBehaviours, ScriptableObjects, Editor windows, and ECS systems following Unity 6 conventions
+- **Script scaffolding** -- Generate MonoBehaviours, ScriptableObjects, Editor windows, inspectors, state machines, and tests following Unity 6 conventions
 - **API lookup** -- Search common Unity APIs by name, namespace, or category via MCP tools
 - **Shader patterns** -- Get HLSL code and Shader Graph node setups for common effects (dissolve, outline, hologram, etc.)
 - **Performance-aware coding rules** -- Catch deprecated APIs, allocation-heavy patterns, and common mistakes
@@ -243,7 +243,7 @@ The server starts automatically when Cursor invokes an MCP tool.
 
 | Tool | Description |
 |:-----|:------------|
-| `scaffold_script` | Generate C# scripts following Unity 6 conventions. Supports MonoBehaviour, ScriptableObject, Editor, and ECS templates. |
+| `scaffold_script` | Generate C# scripts following Unity 6 conventions. Supports MonoBehaviour, ScriptableObject, Editor window, custom inspector, property drawer, interface, state machine, and test templates. |
 | `lookup_api` | Search the Unity API reference database by name, namespace, or category. Returns signatures, descriptions, and examples. |
 | `shader_helper` | Get shader code patterns for common effects (dissolve, outline, hologram, etc.) with HLSL and Shader Graph guidance. |
 | `platform_info` | Get platform-specific defines, capabilities, limitations, and build recommendations. |
diff --git a/docs/index.md b/docs/index.md
index 0fb14ca..98ebe9c 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -10,7 +10,7 @@
 
 Unity Developer Tools is a plugin for [Cursor](https://www.cursor.com/) that teaches its AI assistant how to build Unity games and tools. Once installed, you can ask the AI to:
 
-- Scaffold MonoBehaviours, ScriptableObjects, Editor windows, and ECS systems
+- Scaffold MonoBehaviours, ScriptableObjects, Editor windows, inspectors, and tests
 - Look up Unity APIs by name, namespace, or category
 - Generate shader patterns for common effects (dissolve, outline, hologram, etc.)
 - Get platform-specific defines, capabilities, and build recommendations
@@ -29,7 +29,7 @@ For a detailed walkthrough, see the [Getting Started guide](GETTING-STARTED.md).
 
 ## Features
 
-- **Script scaffolding** -- Generate MonoBehaviours, ScriptableObjects, Editor windows, and ECS systems following Unity 6 conventions
+- **Script scaffolding** -- Generate MonoBehaviours, ScriptableObjects, Editor windows, inspectors, state machines, and tests following Unity 6 conventions
 - **API lookup** -- Search common Unity APIs by name, namespace, or category via MCP tools
 - **Shader patterns** -- Get HLSL code and Shader Graph node setups for common effects
 - **Performance-aware coding rules** -- Catch deprecated APIs, allocation-heavy patterns, and common mistakes
diff --git a/mcp-server/README.md b/mcp-server/README.md
index 7be0ece..8c64f38 100644
--- a/mcp-server/README.md
+++ b/mcp-server/README.md
@@ -7,16 +7,17 @@ A Model Context Protocol server providing Unity development tools for the Cursor
 ### scaffold_script
 Generate well-structured C# scripts following Unity conventions.
 - **type**: monobehaviour, scriptableobject, editor-window, custom-inspector, property-drawer, interface, state-machine, test
-- **name**: Class name for the generated script
+- **name**: Class name for the generated script (must be a valid C# identifier)
 - **namespace**: Optional namespace (default: MyGame)
+- **target_type**: Type inspected or drawn, for custom-inspector and property-drawer. Defaults to the name without its Editor/Inspector/Drawer suffix (`PlayerEditor` -> `Player`)
 
 ### lookup_api
-Search the Unity API reference database for classes, methods, and usage patterns.
+Search the Unity API reference database for classes, methods, and usage patterns. Multi-word queries match entries containing every word; exact name matches rank first.
 - **query**: Search term (class name, method name, or keyword)
-- **category**: Optional filter (physics, ui, animation, audio, rendering, input, networking, editor)
+- **category**: Optional filter (general, physics, ui, animation, audio, rendering, input, networking, editor)
 
 ### shader_helper
-Get shader code patterns and property setups for common effects.
+Get shader code patterns and property setups for common effects. Hand-written HLSL currently targets URP; HDRP and Built-in requests return properties and Shader Graph guidance only.
 - **effect**: Effect name (dissolve, outline, toon, water, hologram, fresnel)
 - **pipeline**: Target render pipeline (urp, hdrp, builtin)
 
@@ -34,9 +35,20 @@ pip install -r requirements.txt
 python server.py
 ```
 
+The server reads its data from `data/` next to `server.py`, so it can be started from any directory. Set `UNITY_DATA_PATH` to use a different data folder. If a data file is missing, the server exits with an error instead of returning empty results.
+
+## Testing
+
+```bash
+pip install -r requirements-dev.txt
+python -m pytest tests
+```
+
+The suite covers every tool and includes a stdio smoke test that starts the server and calls it through the MCP client.
+
 ## Data Files
 
-- `unity_api_common.json` - Common Unity API reference (200+ classes and methods)
+- `unity_api_common.json` - Curated Unity 6 API reference (75 entries across 9 categories)
 - `shader_properties.json` - Built-in shader properties and effect patterns
 - `platform_defines.json` - Platform scripting defines and capabilities
 - `lifecycle_order.json` - MonoBehaviour execution order reference