fix: install the plugin into Cursor's local plugins folder and register the MCP server

The docs told users to open this repository as their Cursor workspace, so
rules and the MCP server never reached their Unity project, and the
symlink instructions pointed at a folder Cursor does not load.

- Register the MCP server through mcp.json at the plugin root using
  ${CURSOR_PLUGIN_ROOT}, referenced from plugin.json, and drop the
  workspace-relative .cursor/mcp.json
- Getting Started and README: clone into ~/.cursor/plugins/local/
  unity-developer-tools, then open your Unity project; add Verify,
  Updating, and Troubleshooting sections
- Release notes and CLAUDE.md use the same local plugins path
- CI checks that the registered server path exists in the repo

Fixes #23

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01MpEiWjv38TrdFcgqU8ER5L

Author: TMHSDigital

.cursor-plugin/plugin.json

@@ -49,5 +49,6 @@
     "rules/shader-conventions.mdc",
     "rules/visual-scripting-conventions.mdc",
     "rules/security-and-builds.mdc"
-  ]
+  ],
+  "mcpServers": "mcp.json"
 }

.github/workflows/release.yml

@@ -168,7 +168,7 @@ jobs:
 
             echo "---"
             echo ""
-            echo "**Install:** Extract \`unity-developer-tools-v${{ steps.new.outputs.version }}.zip\` into \`~/.cursor/plugins/unity-developer-tools\` (Windows: \`%USERPROFILE%\.cursor\plugins\unity-developer-tools\`), restart Cursor, then open your Unity project. Do not extract it into a Unity project: the snippets and templates are references, and Unity would compile them. See [Getting Started](https://github.com/${{ github.repository }}/blob/main/docs/GETTING-STARTED.md)."
+            echo "**Install:** Extract \`unity-developer-tools-v${{ steps.new.outputs.version }}.zip\` into \`~/.cursor/plugins/local/unity-developer-tools\` (Windows: \`%USERPROFILE%\.cursor\plugins\local\unity-developer-tools\`), restart Cursor, then open your Unity project. Do not extract it into a Unity project: the snippets and templates are references, and Unity would compile them. See [Getting Started](https://github.com/${{ github.repository }}/blob/main/docs/GETTING-STARTED.md)."
             echo ""
             echo "**Full Changelog**: https://github.com/${{ github.repository }}/compare/${last_tag:-initial}...v${{ steps.new.outputs.version }}"
             echo "RELEASE_EOF"
@@ -179,8 +179,8 @@ jobs:
         run: |
           zip -r "unity-developer-tools-v${{ steps.new.outputs.version }}.zip" \
             .cursor-plugin/ \
-            .cursor/ \
             .cursorrules \
+            mcp.json \
             AGENTS.md \
             skills/ \
             rules/ \

.github/workflows/validate.yml

@@ -20,7 +20,7 @@ jobs:
         run: python3 -c "import json; json.load(open('.cursor-plugin/plugin.json'))"
 
       - name: Validate mcp.json
-        run: python3 -c "import json; json.load(open('.cursor/mcp.json'))"
+        run: python3 -c "import json; json.load(open('mcp.json'))"
 
       - name: Validate MCP data file schemas
         run: |
@@ -133,6 +133,24 @@ jobs:
           print(f'All {len(m["rules"])} rule files exist')
           PYEOF
 
+      - name: Check MCP server registration
+        run: |
+          python3 << 'PYEOF'
+          import json, os
+          m = json.load(open('.cursor-plugin/plugin.json'))
+          config = m.get('mcpServers')
+          assert isinstance(config, str) and os.path.exists(config), f'mcpServers must point to an existing file, got {config!r}'
+          servers = json.load(open(config))['mcpServers']
+          assert servers, 'No MCP servers registered'
+          for name, server in servers.items():
+              for arg in server.get('args', []):
+                  if arg.startswith('${CURSOR_PLUGIN_ROOT}/'):
+                      path = arg[len('${CURSOR_PLUGIN_ROOT}/'):]
+                      assert os.path.exists(path), f'{name}: {path} not found'
+                  assert not os.path.isabs(arg), f'{name}: absolute path {arg} breaks other installs'
+          print(f'MCP servers registered: {", ".join(servers)}')
+          PYEOF
+
   validate-skills:
     name: Validate skill files
     runs-on: ubuntu-latest

AGENTS.md

@@ -143,7 +143,7 @@ Marks issues/PRs as stale after inactivity and closes them after further inactiv
 - Data: `mcp-server/data/` (JSON reference databases)
 - Dependencies: `mcp-server/requirements.txt`
 
-The MCP server is configured in `.cursor/mcp.json` and starts automatically when Cursor invokes a tool.
+The MCP server is registered by the plugin in `mcp.json` (referenced from `.cursor-plugin/plugin.json`) and starts automatically when Cursor invokes a tool.
 
 ## Key technical facts
 

CLAUDE.md

@@ -90,18 +90,22 @@ The companion MCP server is Python-based (FastMCP). It exposes Unity-aware tools
 
 ## Development Workflow
 
-### Plugin development (symlink)
+### Plugin development (local plugin folder)
+
+Cursor loads local plugins from `~/.cursor/plugins/local/<name>` and skips symlinks that point outside that folder, so clone the repo there and work in that clone:
 
 **macOS / Linux:**
 ```bash
-ln -s "$(pwd)" ~/.cursor/plugins/unity-developer-tools
+git clone https://github.com/TMHSDigital/Unity-Developer-Tools.git ~/.cursor/plugins/local/unity-developer-tools
 ```
 
-**Windows (PowerShell as Admin):**
+**Windows (PowerShell):**
 ```powershell
-New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.cursor\plugins\unity-developer-tools" -Target (Get-Location)
+git clone https://github.com/TMHSDigital/Unity-Developer-Tools.git "$env:USERPROFILE\.cursor\plugins\local\unity-developer-tools"
 ```
 
+Run **Developer: Reload Window** after changing the manifest, rules, skills, or `mcp.json`.
+
 ### MCP server development
 
 ```bash

README.md

@@ -57,15 +57,14 @@ flowchart LR
 
 ## Quick Start
 
-Already have Git, Python 3.10+, and Cursor installed? Here's the short version:
+Already have Git, Python 3.10+, and Cursor installed? Here's the short version (macOS / Linux; see the guide for Windows):
 
 ```bash
-git clone https://github.com/TMHSDigital/Unity-Developer-Tools.git
-# Open Unity-Developer-Tools folder in Cursor (File > Open Folder)
-cd mcp-server && pip install -r requirements.txt
+git clone https://github.com/TMHSDigital/Unity-Developer-Tools.git ~/.cursor/plugins/local/unity-developer-tools
+python -m pip install -r ~/.cursor/plugins/local/unity-developer-tools/mcp-server/requirements.txt
 ```
 
-Then ask the AI agent to scaffold a MonoBehaviour, look up an API, or generate a shader effect.
+Restart Cursor, then open **your Unity project** (not this repository) and ask the agent to scaffold a MonoBehaviour, look up an API, or generate a shader effect.
 
 > **Need more detail?** The **[Getting Started guide](docs/GETTING-STARTED.md)** covers installing prerequisites, troubleshooting, and building your first project step by step.
 
@@ -225,16 +224,15 @@ Then ask the AI agent to scaffold a MonoBehaviour, look up an API, or generate a
 
 ## MCP Server
 
-The companion MCP server provides programmatic tools that Cursor's AI agent can call directly. Configuration lives in `.cursor/mcp.json`.
+The companion MCP server provides programmatic tools that Cursor's AI agent can call directly. The plugin registers it through `mcp.json` at the plugin root, so it is available in any workspace once the plugin is installed.
 
-**Prerequisites:** Python 3.10+
+**Prerequisites:** Python 3.10+ available as `python`
 
 ```bash
-cd mcp-server
-pip install -r requirements.txt
+python -m pip install -r ~/.cursor/plugins/local/unity-developer-tools/mcp-server/requirements.txt
 ```
 
-The server starts automatically when Cursor invokes an MCP tool.
+Cursor starts the server automatically. Other MCP clients can run `python <plugin folder>/mcp-server/server.py` over stdio.
 
 <details>
 <summary><strong>Available Tools (4)</strong></summary>
@@ -282,7 +280,7 @@ What are the WebGL limitations and recommended settings?
 ```
 Unity-Developer-Tools/
   .cursor-plugin/      Plugin manifest
-  .cursor/             MCP server configuration
+  mcp.json             MCP server registration for the plugin
   skills/              AI skill files (18 skills)
   rules/               Coding convention rules (8 rules)
   snippets/            Code snippets -- C#, shaders (20 files)

docs/ARCHITECTURE.md

@@ -6,7 +6,7 @@ This is a single Cursor IDE plugin following the standard plugin specification.
 
 ```
 .cursor-plugin/plugin.json    <- Plugin manifest (name, version, skills, rules)
-.cursor/mcp.json              <- MCP server configuration
+mcp.json                      <- MCP server registration (uses ${CURSOR_PLUGIN_ROOT})
 skills/                       <- AI context files (SKILL.md with YAML frontmatter)
 rules/                        <- Convention enforcement (.mdc with frontmatter)
 snippets/                     <- Production-ready code patterns

docs/GETTING-STARTED.md

@@ -8,19 +8,41 @@
 
 ## Installation
 
-1. Clone this repository:
+The plugin is installed once into Cursor's local plugins folder. You then open **your own Unity project** in Cursor, not this repository.
+
+1. Clone the plugin into Cursor's local plugins folder:
+
+   **macOS / Linux:**
    ```bash
-   git clone https://github.com/TMHSDigital/Unity-Developer-Tools.git
+   git clone https://github.com/TMHSDigital/Unity-Developer-Tools.git ~/.cursor/plugins/local/unity-developer-tools
    ```
 
-2. Open the cloned folder in Cursor IDE
+   **Windows (PowerShell):**
+   ```powershell
+   git clone https://github.com/TMHSDigital/Unity-Developer-Tools.git "$env:USERPROFILE\.cursor\plugins\local\unity-developer-tools"
+   ```
 
-3. The plugin loads automatically. You should see skills and rules activate when editing C# or shader files.
+   Or download the zip from the [latest release](https://github.com/TMHSDigital/Unity-Developer-Tools/releases/latest) and extract it into that same folder, so that `.cursor-plugin/plugin.json` sits directly inside `unity-developer-tools/`. Do not extract it into a Unity project.
 
-4. (Optional) Install MCP server dependencies for tool access:
+2. Install the MCP server dependencies with the same Python that `python` runs:
    ```bash
-   pip install -r mcp-server/requirements.txt
+   python -m pip install -r ~/.cursor/plugins/local/unity-developer-tools/mcp-server/requirements.txt
    ```
+   On Windows, use `"$env:USERPROFILE\.cursor\plugins\local\unity-developer-tools\mcp-server\requirements.txt"`.
+
+3. Restart Cursor, or run **Developer: Reload Window** from the command palette.
+
+4. Open your Unity project folder (the one containing `Assets/` and `ProjectSettings/`) with **File > Open Folder**.
+
+### Verify it works
+
+1. Open **Customize** in the Cursor sidebar. Unity Developer Tools should be listed with its skills, rules, and the `unity-dev-tools` MCP server.
+2. Open any `.cs` file in your project. The C# rules apply to it automatically.
+3. Ask the agent: *"What are the scripting defines for WebGL?"* It should call the `platform_info` tool and answer with `UNITY_WEBGL`.
+
+### Updating
+
+Run `git pull` inside `~/.cursor/plugins/local/unity-developer-tools`, then reload Cursor. If you installed from a zip, replace the folder with the new release.
 
 ## Using Skills
 
@@ -62,6 +84,25 @@ Ask the AI to use MCP tools naturally:
 - "Show me shader properties for a dissolve effect"
 - "What are the platform limitations for WebGL?"
 
+## Troubleshooting
+
+**The plugin does not appear in Customize**
+- Check the path: `.cursor-plugin/plugin.json` must be at `~/.cursor/plugins/local/unity-developer-tools/.cursor-plugin/plugin.json`. A zip extracted into an extra nested folder will not load.
+- Symlinks are skipped when they point to a folder outside `~/.cursor/plugins/local`. Clone or copy the plugin into that folder instead.
+- On Cursor Teams or Enterprise, an admin must enable **Allow Local Plugin Imports** (Dashboard > Settings > Security & Identity > Marketplace and Plugins).
+- Reload the window after installing.
+
+**The `unity-dev-tools` MCP server shows an error or no tools**
+- `python` must be on your PATH. Run `python --version`; it must report 3.10 or newer. On macOS, if only `python3` exists, install Python from python.org or a package manager that provides `python`.
+- `ModuleNotFoundError: No module named 'mcp'`: install the requirements with the same interpreter, using `python -m pip install -r .../mcp-server/requirements.txt`.
+- `Missing data file`: the plugin folder is incomplete. Re-clone it or extract the release zip again.
+
+**Rules do not apply to my scripts**
+- Make sure the Cursor workspace is your Unity project, not the plugin repository. Rules are matched against files in the open workspace (for example, `**/*.cs`).
+
+**Unity reports compile errors after copying files**
+- Copy individual snippets or a single template folder into `Assets/`, never the whole plugin. Each template README lists the packages it needs, such as the Input System.
+
 ## Next Steps
 
 - Explore the [Architecture](ARCHITECTURE.md) to understand plugin structure

mcp-server/README.md

@@ -27,7 +27,7 @@ Get platform-specific scripting defines, capabilities, and build recommendations
 
 ## Running
 
-The server is started automatically by Cursor via the configuration in `.cursor/mcp.json`.
+The plugin registers the server in `mcp.json` at the plugin root, and Cursor starts it automatically once the plugin is installed.
 
 Manual start:
 ```bash

.cursor/mcp.json mcp.json.cursor/mcp.json renamed to mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "unity-dev-tools": {
       "command": "python",
-      "args": ["mcp-server/server.py"]
+      "args": ["${CURSOR_PLUGIN_ROOT}/mcp-server/server.py"]
     }
   }
 }