unity-mcp-server 1.0.0

package/PURPOSE.md

@@ -0,0 +1,37 @@
+# Why This MCP Server Exists and When It Makes Sense
+
+## What it does
+
+This server exposes **tools** that an MCP client (e.g. Cursor) can call when you’re working on **any Unity project**. Each tool does one thing:
+
+- **get_project_info** – Unity version, project path, how many scenes are in the build.
+- **list_build_scenes** – Full list of build scenes in order (from `EditorBuildSettings`).
+- **read_agent_docs** – Contents of `.agents/AGENT.md` (and optionally `REPO_UNDERSTANDING.md`).
+
+So the agent (or you, via the agent) can ask “what’s the build order?” or “what’s in the agent guide?” without you opening files by hand. The client starts this process and calls these tools over stdio. **No Unity Editor is required** — it reads only from the project filesystem.
+
+## Does it make sense to have it?
+
+**Yes, if:**
+
+- You use an **MCP-aware IDE** (Cursor, Claude Desktop, Windsurf, etc.) and want the AI to have structured access to project metadata and agent docs.
+- You want the **Unity project repo to stay clean** (no Node/tooling inside it), and the **tooling to live in a separate repo** that you clone once and point at any Unity project via `UNITY_PROJECT_PATH`.
+- You’re building toward **more agent-facing tools** later (e.g. “list Addressables,” “run Unity CLI build,” “inspect scene list”) without bloating the game repo.
+
+**Optional / nice-to-have if:**
+
+- You mostly work without MCP or without asking the AI about build order / agent docs. Then the server is optional; the game still works without it.
+- You’re fine opening `.agents/AGENT.md` and `ProjectSettings/EditorBuildSettings.asset` yourself. Then the server saves you a few clicks and gives the agent the same info in a structured way.
+
+**Probably overkill if:**
+
+- You never use MCP or an AI agent that can call tools. Then you don’t need this repo at all.
+
+## What purpose it serves
+
+1. **Structured project context for the agent** – The agent can ask “what scenes are in the build?” or “what’s the agent guide?” and get exact answers via tools instead of guessing or reading raw YAML/markdown without context.
+2. **Separation of concerns** – Game repo = Unity + game code. This repo = one small Node app that knows how to read that project. You can version and change the server without touching the Unity project.
+3. **Single place to add more tools** – When you want “trigger a build” or “list Addressables” or “validate scene refs,” you add a tool here and the consumer just points Cursor at the same server.
+4. **Reusability** – Same server works for **any** Unity project; switch projects by changing `UNITY_PROJECT_PATH` in the client config.
+
+In short: **it makes sense if you use MCP and want the AI to have reliable, structured access to project info and agent docs; it serves the purpose of a small, separate tool layer that sits next to any Unity project and exposes that context as MCP tools.**

package/README.md

@@ -0,0 +1,101 @@
+# Unity MCP Server
+
+**MCP server for Unity** — A lightweight [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server that gives AI assistants structured access to your Unity projects. Use with Cursor, Claude Desktop, or any MCP client. Query project metadata, build settings, and agent documentation from any MCP-capable client—without running the Unity Editor.
+
+---
+
+## Overview
+
+Unity MCP Server runs as a separate process and reads your Unity project from disk. Point it at any project root via `UNITY_PROJECT_PATH`; one installation can serve multiple projects by changing the environment variable in your client config.
+
+**Key points:**
+
+- **Editor-free** — Uses only the project filesystem. No Unity process or Editor dependency.
+- **Single binary** — One Node.js server for all your Unity projects.
+- **MCP-native** — Built on the official MCP SDK; works with Cursor, Claude Desktop, Windsurf, and other MCP clients.
+
+---
+
+## Features
+
+| Tool | Description |
+|------|-------------|
+| `get_project_info` | Returns project root path, Unity version, and build scene count. |
+| `list_build_scenes` | Returns scenes in `EditorBuildSettings` in build order (JSON). |
+| `read_agent_docs` | Returns contents of `.agents/AGENT.md`; optionally includes `REPO_UNDERSTANDING.md`. |
+
+---
+
+## Prerequisites
+
+- **Node.js** 18 or later
+- **UNITY_PROJECT_PATH** — Absolute path to your Unity project root (set in your MCP client configuration)
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/YOUR_USERNAME/unity-mcp-server.git
+cd unity-mcp-server
+npm install
+npm run build
+```
+
+The server is invoked via **stdio**. Your MCP client starts it; you do not run it manually in production.
+
+---
+
+## Configuration
+
+### Cursor
+
+Add the following to your MCP settings (project or user):
+
+```json
+{
+  "mcpServers": {
+    "unity": {
+      "command": "node",
+      "args": ["/absolute/path/to/unity-mcp-server/dist/index.js"],
+      "env": {
+        "UNITY_PROJECT_PATH": "/absolute/path/to/YourUnityProject"
+      }
+    }
+  }
+}
+```
+
+Replace:
+
+1. `/absolute/path/to/unity-mcp-server/dist/index.js` with the path to this repository’s built entry point.
+2. `/absolute/path/to/YourUnityProject` with the absolute path to your Unity project root.
+
+### Other MCP clients
+
+Use the same pattern: run `node` with `dist/index.js` as the argument and set `UNITY_PROJECT_PATH` in the environment. Refer to your client’s documentation for where to configure MCP servers.
+
+---
+
+## Development
+
+- **Production:** `node dist/index.js` (after `npm run build`)
+- **Development:** `npm run dev` or `npx tsx src/index.ts`
+
+---
+
+## Security and public use
+
+This repository contains only generic tooling: no game code, assets, API keys, or secrets. The Unity project path is provided at runtime by your MCP client and is not stored in this repo. Safe to use in public or private contexts. The project is maintained anonymously; no author attribution is required.
+
+---
+
+## Further reading
+
+See [PURPOSE.md](./PURPOSE.md) for the rationale behind this server and when it is useful for your workflow.
+
+---
+
+## Discoverability
+
+Search for **Unity MCP server**, **MCP Unity**, or **Model Context Protocol Unity** to find this repo. You can also browse the [MCP Registry](https://registry.modelcontextprotocol.io/) for published servers (this server may be listed there once submitted).

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * unity-mcp-server – Lightweight MCP server for any Unity project.
+ * Exposes tools: project info, build scenes, agent docs. No Unity Editor required.
+ * Set UNITY_PROJECT_PATH to the Unity project root in your MCP client config.
+ * Run: node dist/index.js (after npm run build).
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * unity-mcp-server – Lightweight MCP server for any Unity project.
+ * Exposes tools: project info, build scenes, agent docs. No Unity Editor required.
+ * Set UNITY_PROJECT_PATH to the Unity project root in your MCP client config.
+ * Run: node dist/index.js (after npm run build).
+ */
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+function getProjectRoot() {
+    const env = process.env.UNITY_PROJECT_PATH;
+    if (env)
+        return resolve(env);
+    console.error("UNITY_PROJECT_PATH is required. Set it in your MCP client config (e.g. Cursor) to your Unity project root.");
+    process.exit(1);
+    return ""; // unreachable
+}
+function getBuildScenes(projectRoot) {
+    const path = join(projectRoot, "ProjectSettings", "EditorBuildSettings.asset");
+    if (!existsSync(path))
+        return [];
+    const content = readFileSync(path, "utf-8");
+    const scenes = [];
+    let index = 0;
+    const pathRe = /path: (Assets\/[^\n]+\.unity)/g;
+    let m;
+    while ((m = pathRe.exec(content)) !== null) {
+        const fullPath = m[1];
+        const name = fullPath.replace(/^.*\//, "").replace(/\.unity$/, "");
+        scenes.push({ index, path: fullPath, name });
+        index++;
+    }
+    return scenes;
+}
+async function main() {
+    const projectRoot = getProjectRoot();
+    const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+    const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+    const server = new McpServer({
+        name: "unity-mcp-server",
+        version: "1.0.0",
+    });
+    server.registerTool("get_project_info", {
+        description: "Get Unity project info (path, Unity version, build scene count).",
+        inputSchema: {},
+    }, async () => {
+        let unityVersion = "unknown";
+        const pvPath = join(projectRoot, "ProjectSettings", "ProjectVersion.txt");
+        if (existsSync(pvPath)) {
+            const m = readFileSync(pvPath, "utf-8").match(/m_EditorVersion:\s*(.+)/);
+            if (m)
+                unityVersion = m[1].trim();
+        }
+        const scenes = getBuildScenes(projectRoot);
+        const text = [
+            `Project root: ${projectRoot}`,
+            `Unity version: ${unityVersion}`,
+            `Build scenes: ${scenes.length}`,
+            scenes.map((s) => `  ${s.index}: ${s.name} (${s.path})`).join("\n"),
+        ].join("\n");
+        return { content: [{ type: "text", text }] };
+    });
+    server.registerTool("list_build_scenes", {
+        description: "List all scenes in Unity EditorBuildSettings (build order).",
+        inputSchema: {},
+    }, async () => {
+        const scenes = getBuildScenes(projectRoot);
+        const text = JSON.stringify(scenes, null, 2);
+        return { content: [{ type: "text", text }] };
+    });
+    server.registerTool("read_agent_docs", {
+        description: "Read the agent development guide (.agents/AGENT.md) and optionally REPO_UNDERSTANDING.md.",
+        inputSchema: {
+            include_repo_understanding: z.boolean().optional().describe("If true, also return REPO_UNDERSTANDING.md content").default(false),
+        },
+    }, async (args) => {
+        const include = args?.include_repo_understanding ?? false;
+        const agentPath = join(projectRoot, ".agents", "AGENT.md");
+        let text = "";
+        if (existsSync(agentPath)) {
+            text = readFileSync(agentPath, "utf-8");
+        }
+        else {
+            text = "(No .agents/AGENT.md found)";
+        }
+        if (include) {
+            const repPath = join(projectRoot, "REPO_UNDERSTANDING.md");
+            if (existsSync(repPath)) {
+                text += "\n\n---\n\n# REPO_UNDERSTANDING.md\n\n" + readFileSync(repPath, "utf-8");
+            }
+        }
+        return { content: [{ type: "text", text }] };
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/docs/REGISTRY.md

@@ -0,0 +1,101 @@
+# How to register this server in the MCP Registry
+
+The [MCP Registry](https://registry.modelcontextprotocol.io/) lists MCP servers so users can discover and install them. To list **Unity MCP Server** there, follow these steps.
+
+## Prerequisites
+
+- **npm account** — [Sign up](https://www.npmjs.com/signup) if needed. The registry verifies ownership via the published npm package.
+- **GitHub account** — You’ll authenticate with GitHub so the registry can verify `io.github.rachitkumarrastogi/unity-mcp-server`.
+
+## Step 1: Publish the package to npm
+
+The registry only stores metadata; the actual package must be published to npm first.
+
+```bash
+cd /path/to/unity-mcp-server
+npm install
+npm run build
+npm login          # if not already logged in
+npm publish --access public
+```
+
+If the name `unity-mcp-server` is already taken on npm, use a scoped name in `package.json` (e.g. `"name": "@rachitkumarrastogi/unity-mcp-server"`) and set the same value in `server.json` → `packages[0].identifier`. Keep `mcpName` in `package.json` as `io.github.rachitkumarrastogi/unity-mcp-server`.
+
+## Step 2: Install the MCP Publisher CLI
+
+**macOS / Linux:**
+
+```bash
+curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher && sudo mv mcp-publisher /usr/local/bin/
+```
+
+**Homebrew:**
+
+```bash
+brew install mcp-publisher
+```
+
+**Windows:** See [Registry releases](https://github.com/modelcontextprotocol/registry/releases/latest) for the Windows binary.
+
+Verify:
+
+```bash
+mcp-publisher --help
+```
+
+## Step 3: Log in to the registry (GitHub)
+
+You must authenticate as the GitHub user that owns the repo (`rachitkumarrastogi`):
+
+```bash
+mcp-publisher login github
+```
+
+Follow the prompts (open the URL, enter the code, authorize). When it says “Successfully logged in”, you’re done.
+
+## Step 4: Publish to the MCP Registry
+
+From the repo root (where `server.json` lives):
+
+```bash
+mcp-publisher publish
+```
+
+You should see something like:
+
+```text
+Publishing to https://registry.modelcontextprotocol.io...
+✓ Successfully published
+✓ Server io.github.rachitkumarrastogi/unity-mcp-server version 1.0.0
+```
+
+## Step 5: Confirm it’s listed
+
+- Browse [registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io/) and search for “Unity” or “unity-mcp-server”.
+- Or call the API:
+
+  ```bash
+  curl "https://registry.modelcontextprotocol.io/v0.1/servers?search=unity-mcp-server"
+  ```
+
+## Updating the listing later
+
+After you release a new version:
+
+1. Bump `version` in `package.json` and in `server.json` (top-level and `packages[0].version`).
+2. Run `npm run build` and `npm publish`.
+3. Run `mcp-publisher publish` again.
+
+## Troubleshooting
+
+| Issue | What to do |
+|-------|------------|
+| “Registry validation failed for package” | Ensure `package.json` has `mcpName` exactly matching `server.json` → `name` (e.g. `io.github.rachitkumarrastogi/unity-mcp-server`). |
+| “You do not have permission to publish this server” | With GitHub login, the server `name` must start with `io.github.<your-github-username>/`. Use the same GitHub account that owns the repo. |
+| “Invalid or expired Registry JWT token” | Run `mcp-publisher login github` again. |
+
+## Official docs
+
+- [Quickstart: Publish an MCP Server](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/quickstart.mdx)
+- [Package types (npm, PyPI, etc.)](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/package-types.mdx)
+- [Authentication options](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/authentication.mdx)

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "unity-mcp-server",
+  "version": "1.0.0",
+  "description": "Lightweight MCP server for any Unity project - project info, build scenes, agent docs (no Unity Editor required)",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "unity-mcp-server": "./dist/index.js"
+  },
+  "scripts": {
+    "build": "node node_modules/typescript/bin/tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "mcpName": "io.github.rachitkumarrastogi/unity-mcp-server",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/rachitkumarrastogi/unity-mcp-server.git"
+  }
+}

package/server.json

@@ -0,0 +1,28 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.rachitkumarrastogi/unity-mcp-server",
+  "title": "Unity MCP Server",
+  "description": "MCP server for Unity — project info, build scenes, agent docs. No Unity Editor required. Works with Cursor, Claude Desktop, and any MCP client.",
+  "repository": {
+    "url": "https://github.com/rachitkumarrastogi/unity-mcp-server",
+    "source": "github"
+  },
+  "version": "1.0.0",
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "unity-mcp-server",
+      "version": "1.0.0",
+      "transport": { "type": "stdio" },
+      "environmentVariables": [
+        {
+          "name": "UNITY_PROJECT_PATH",
+          "description": "Absolute path to your Unity project root (required)",
+          "isRequired": true,
+          "format": "string",
+          "isSecret": false
+        }
+      ]
+    }
+  ]
+}

package/src/index.ts

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+/**
+ * unity-mcp-server – Lightweight MCP server for any Unity project.
+ * Exposes tools: project info, build scenes, agent docs. No Unity Editor required.
+ * Set UNITY_PROJECT_PATH to the Unity project root in your MCP client config.
+ * Run: node dist/index.js (after npm run build).
+ */
+
+import { readFileSync, existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { z } from "zod";
+
+function getProjectRoot(): string {
+  const env = process.env.UNITY_PROJECT_PATH;
+  if (env) return resolve(env);
+  console.error("UNITY_PROJECT_PATH is required. Set it in your MCP client config (e.g. Cursor) to your Unity project root.");
+  process.exit(1);
+  return ""; // unreachable
+}
+
+function getBuildScenes(projectRoot: string): { index: number; path: string; name: string }[] {
+  const path = join(projectRoot, "ProjectSettings", "EditorBuildSettings.asset");
+  if (!existsSync(path)) return [];
+  const content = readFileSync(path, "utf-8");
+  const scenes: { index: number; path: string; name: string }[] = [];
+  let index = 0;
+  const pathRe = /path: (Assets\/[^\n]+\.unity)/g;
+  let m: RegExpExecArray | null;
+  while ((m = pathRe.exec(content)) !== null) {
+    const fullPath = m[1];
+    const name = fullPath.replace(/^.*\//, "").replace(/\.unity$/, "");
+    scenes.push({ index, path: fullPath, name });
+    index++;
+  }
+  return scenes;
+}
+
+async function main() {
+  const projectRoot = getProjectRoot();
+
+  const { McpServer } = await import("@modelcontextprotocol/sdk/server/mcp.js");
+  const { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js");
+
+  const server = new McpServer({
+    name: "unity-mcp-server",
+    version: "1.0.0",
+  });
+
+  server.registerTool(
+    "get_project_info",
+    {
+      description: "Get Unity project info (path, Unity version, build scene count).",
+      inputSchema: {},
+    },
+    async () => {
+      let unityVersion = "unknown";
+      const pvPath = join(projectRoot, "ProjectSettings", "ProjectVersion.txt");
+      if (existsSync(pvPath)) {
+        const m = readFileSync(pvPath, "utf-8").match(/m_EditorVersion:\s*(.+)/);
+        if (m) unityVersion = m[1].trim();
+      }
+      const scenes = getBuildScenes(projectRoot);
+      const text = [
+        `Project root: ${projectRoot}`,
+        `Unity version: ${unityVersion}`,
+        `Build scenes: ${scenes.length}`,
+        scenes.map((s) => `  ${s.index}: ${s.name} (${s.path})`).join("\n"),
+      ].join("\n");
+      return { content: [{ type: "text", text }] };
+    }
+  );
+
+  server.registerTool(
+    "list_build_scenes",
+    {
+      description: "List all scenes in Unity EditorBuildSettings (build order).",
+      inputSchema: {},
+    },
+    async () => {
+      const scenes = getBuildScenes(projectRoot);
+      const text = JSON.stringify(scenes, null, 2);
+      return { content: [{ type: "text", text }] };
+    }
+  );
+
+  server.registerTool(
+    "read_agent_docs",
+    {
+      description: "Read the agent development guide (.agents/AGENT.md) and optionally REPO_UNDERSTANDING.md.",
+      inputSchema: {
+        include_repo_understanding: z.boolean().optional().describe("If true, also return REPO_UNDERSTANDING.md content").default(false),
+      },
+    },
+    async (args: unknown) => {
+      const include = (args as { include_repo_understanding?: boolean })?.include_repo_understanding ?? false;
+      const agentPath = join(projectRoot, ".agents", "AGENT.md");
+      let text = "";
+      if (existsSync(agentPath)) {
+        text = readFileSync(agentPath, "utf-8");
+      } else {
+        text = "(No .agents/AGENT.md found)";
+      }
+      if (include) {
+        const repPath = join(projectRoot, "REPO_UNDERSTANDING.md");
+        if (existsSync(repPath)) {
+          text += "\n\n---\n\n# REPO_UNDERSTANDING.md\n\n" + readFileSync(repPath, "utf-8");
+        }
+      }
+      return { content: [{ type: "text", text }] };
+    }
+  );
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "declaration": true
+  },
+  "include": ["src/**/*"]
+}