@jamius19/unity-ai-context-bridge-mcp 1.0.0

package/LICENSE.md

@@ -0,0 +1,7 @@
+Copyright 2026 Jamius Siam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,336 @@
+## Unity AI Context Bridge MCP
+
+Node MCP server that feeds AI tools Unity GameObjects, assets, and other resources that are selected by the user. Think of it like when you drag source code in Cursor, Antigravity, Github Copilot window to add that file to context, but for Unity.
+
+> [!IMPORTANT]  
+> The MCP server requires the `Unity AI Context Bridge` Unity package to be installed in the Unity project.
+
+
+> [!TIP]  
+> For the best experience, use Unity Official MCP server along with this.
+
+<br>
+
+## Installation
+
+Install the package globally:
+
+```shell
+npm install -g @jamius19/unity-ai-context-bridge-mcp
+```
+<br>
+
+## MCP Client Installation
+
+Install the NPM package globally before wiring an MCP client to it. This will enable the `uacb-mcp` command in your terminal,
+
+Choose one transport per client entry:
+
+1. Stdio: the MCP client launches this server as a subprocess.  **(Recommended)**
+2. Streamable HTTP: you start this server with `uacb-mcp --http`, then the MCP client connects to `http://127.0.0.1:3333/mcp`.
+
+<br>
+
+### GitHub Copilot (VS Code)
+
+Create or update `.vscode/mcp.json` in a project, or run `MCP: Open User Configuration` from the Command Palette for a user-wide setup.
+
+Stdio:
+
+```json
+{
+  "servers": {
+    "unity-ai-context-bridge": {
+      "type": "stdio",
+      "command": "uacb-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+HTTP with auth:
+
+```json
+{
+  "servers": {
+    "unity-ai-context-bridge": {
+      "type": "http",
+      "url": "http://127.0.0.1:3333/mcp",
+      "headers": {
+        "Authorization": "Bearer change-me"
+      }
+    }
+  }
+}
+```
+
+HTTP without auth:
+
+```json
+{
+  "servers": {
+    "unity-ai-context-bridge": {
+      "type": "http",
+      "url": "http://127.0.0.1:3333/mcp"
+    }
+  }
+}
+```
+
+After adding the server, run `MCP: List Servers` from the Command Palette and start `unity-ai-context-bridge` if VS Code does not start it automatically. Then open GitHub Copilot Chat in Agent mode and enable the server tools from the tools menu if needed.
+
+<br>
+
+### Rider/Other `mcp.json` clients
+
+Many MCP clients, including Claude Desktop-style JSON configs, accept the same `mcpServers` shape.
+
+Stdio:
+
+```json
+{
+  "mcpServers": {
+    "unity-ai-context-bridge": {
+      "command": "uacb-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+HTTP:
+
+```json
+{
+  "mcpServers": {
+    "unity-ai-context-bridge": {
+      "url": "http://127.0.0.1:3333/mcp",
+      "headers": {
+        "Authorization": "Bearer change-me"
+      }
+    }
+  }
+}
+```
+
+<br>
+
+### Claude Code
+
+Stdio:
+
+```shell
+claude mcp add --transport stdio unity-ai-context-bridge -- uacb-mcp --stdio
+```
+
+HTTP with auth:
+
+```shell
+claude mcp add --transport http --header "Authorization: Bearer change-me" unity-ai-context-bridge http://127.0.0.1:3333/mcp
+```
+
+HTTP without auth:
+
+```shell
+claude mcp add --transport http unity-ai-context-bridge http://127.0.0.1:3333/mcp
+```
+
+<br>
+
+### Codex
+
+Add one of these entries to `~/.codex/config.toml`.
+
+Stdio:
+
+```toml
+[mcp_servers.unity_ai_context_bridge]
+command = "uacb-mcp"
+args = ["--stdio"]
+enabled = true
+```
+
+HTTP with auth:
+
+```toml
+[mcp_servers.unity_ai_context_bridge]
+url = "http://127.0.0.1:3333/mcp"
+http_headers = { Authorization = "Bearer change-me" }
+enabled = true
+```
+
+HTTP without auth:
+
+```toml
+[mcp_servers.unity_ai_context_bridge]
+url = "http://127.0.0.1:3333/mcp"
+enabled = true
+```
+
+<br>
+
+### Gemini CLI
+
+Stdio:
+
+```shell
+gemini mcp add unity-ai-context-bridge uacb-mcp --stdio
+```
+
+HTTP with auth:
+
+```shell
+gemini mcp add --transport http unity-ai-context-bridge http://127.0.0.1:3333/mcp --header "Authorization: Bearer change-me"
+```
+
+HTTP without auth:
+
+```shell
+gemini mcp add --transport http unity-ai-context-bridge http://127.0.0.1:3333/mcp
+```
+
+<br>
+
+### Cursor
+
+Create or update `.cursor/mcp.json` in a project, or `~/.cursor/mcp.json` for a user-wide setup.
+
+Stdio:
+
+```json
+{
+  "mcpServers": {
+    "unity-ai-context-bridge": {
+      "type": "stdio",
+      "command": "uacb-mcp",
+      "args": ["--stdio"]
+    }
+  }
+}
+```
+
+HTTP with auth:
+
+```json
+{
+  "mcpServers": {
+    "unity-ai-context-bridge": {
+      "url": "http://127.0.0.1:3333/mcp",
+      "headers": {
+        "Authorization": "Bearer change-me"
+      }
+    }
+  }
+}
+```
+
+HTTP without auth:
+
+```json
+{
+  "mcpServers": {
+    "unity-ai-context-bridge": {
+      "url": "http://127.0.0.1:3333/mcp"
+    }
+  }
+}
+```
+
+<br>
+
+### Run over stdio
+
+```shell
+uacb-mcp --stdio
+```
+
+Use this transport from MCP clients that launch servers as subprocesses.
+
+<br>
+
+### Run over HTTP
+
+In HTTP mode it defaults to `http://127.0.0.1:3333/mcp` URL.\
+You can customize it via the following ways,
+
+PowerShell:
+
+```powershell
+$env:MCP_AUTH_TOKEN = "change-me"
+$env:PORT = "3333"
+uacb-mcp --http
+```
+
+Bash:
+
+```bash
+MCP_AUTH_TOKEN=change-me PORT=3333 uacb-mcp --http
+```
+
+If you do not want HTTP auth during local development, omit `MCP_AUTH_TOKEN`:
+
+```shell
+uacb-mcp --http
+```
+
+HTTP endpoints:
+
+- `GET /health` does not require auth.
+- `GET /context` returns the raw currently selected Unity objects/assets context JSON. It requires a `projectPath` query parameter to select a specific Unity project bridge.
+- `POST /mcp` is the SDK Streamable HTTP MCP endpoint for AI tools.
+
+Authenticated HTTP requests must include either:
+
+```text
+Authorization: Bearer change-me
+```
+
+or:
+
+```text
+x-auth-token: change-me
+```
+
+<br>
+
+## MCP surface
+
+Resource template:
+
+- `unity-context://projects/items{?projectPath}`: currently selected Unity GameObjects/assets of interest for a specific project path. Listed concrete resources percent-encode the project path in the query string, so paths with spaces are represented safely, for example `unity-context://projects/items?projectPath=C%3A%5Cexample%5Cunity%5Cunity%5Cproject` for an Unity project in the `C:\example\unity\unity\project` path.
+
+Tool:
+
+- `get_unity_context_items`: returns the current Unity selection context for AI tools. It requires a URL-encoded `projectPath`; the server reads that project's bridge file and uses its URL.
+
+Example JSON-RPC request:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "method": "tools/call",
+  "params": {
+    "name": "get_unity_context_items",
+    "arguments": {
+      "projectPath": "C%3A%5Cexample%5Cunity%5Cunity%5Cproject"
+    }
+  }
+}
+```
+
+If you have Unity Official MCP installed, this will be done automatically, otheriwse you can update your `AGENTS.md` file with the full project path.
+
+<br>
+
+## How does it work?
+It automatically discovers the live Unity selection context from the bridge file under the requested Unity project path:
+
+```text
+<projectPath>/Temp/unity-ai-context-bridge/bridge.json
+```
+
+The bridge file contains the local URL and auth key for that Unity editor instance. The MCP server reads that file for the requested `projectPath`, connects to its `url`, and sends the auth key to Unity AI Context Bridge.
+
+This bridge file is auto generated by the `Unity AI Context Bridge` Unity Editor Extension.

package/index.js

@@ -0,0 +1,321 @@
+#!/usr/bin/env node
+
+// Copyright (c) 2026 Jamius Siam
+
+'use strict';
+
+const http = require('node:http');
+const https = require('node:https');
+const fs = require('node:fs/promises');
+const path = require('node:path');
+const { z } = require('zod');
+const { McpServer, ResourceTemplate } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+const { StreamableHTTPServerTransport } = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
+const { createMcpExpressApp } = require('@modelcontextprotocol/sdk/server/express.js');
+
+const SERVER_INFO = {
+  name: 'unity-ai-context-bridge-mcp',
+  title: 'Unity AI Context Bridge MCP',
+  version: '1.0.0',
+};
+
+const RESOURCE_URI_TEMPLATE = 'unity-context://projects/items{?projectPath}';
+const DEFAULT_UPSTREAM_TIMEOUT_MS = 5000;
+
+function jsonText(value) {
+  return JSON.stringify(value, null, 2);
+}
+
+function getUnityContextResourceUri(projectPath) {
+  return `unity-context://projects/items?projectPath=${encodeURIComponent(projectPath)}`;
+}
+
+function decodeProjectPath(projectPath) {
+  if (typeof projectPath !== 'string' || projectPath.length === 0) {
+    throw new Error('projectPath is required');
+  }
+
+  try {
+    return decodeURIComponent(projectPath);
+  } catch (err) {
+    throw new Error(`projectPath must be URL encoded: ${err.message}`);
+  }
+}
+
+function getBridgeInfoPath(projectPath) {
+  return path.join(projectPath, 'Temp', 'unity-ai-context-bridge', 'bridge.json');
+}
+
+async function readBridgeInfo(projectPath) {
+  const bridgePath = getBridgeInfoPath(projectPath);
+  let bridge;
+
+  try {
+    bridge = JSON.parse(await fs.readFile(bridgePath, 'utf8'));
+  } catch (err) {
+    throw new Error(`Failed to read Unity context bridge at ${bridgePath}: ${err.message}`);
+  }
+
+  if (!bridge || typeof bridge !== 'object' || Array.isArray(bridge)) {
+    throw new Error(`Unity context bridge at ${bridgePath} must be a JSON object`);
+  }
+
+  if (typeof bridge.url !== 'string' || bridge.url.length === 0) {
+    throw new Error(`Unity context bridge at ${bridgePath} must include url`);
+  }
+
+  return bridge;
+}
+
+function validateUnityContext(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    throw new Error('Unity context response must be a JSON object');
+  }
+
+  if (!Array.isArray(payload.items)) {
+    throw new Error('Unity context response must include an items array');
+  }
+
+  return payload;
+}
+
+function fetchJson(url, authKey, timeoutMs = DEFAULT_UPSTREAM_TIMEOUT_MS) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(url);
+    const transport = parsed.protocol === 'https:' ? https : http;
+    const headers = { accept: 'application/json' };
+    if (authKey) {
+      headers.authorization = `Bearer ${authKey}`;
+    }
+
+    const req = transport.get(parsed, { headers }, (res) => {
+      const chunks = [];
+      let size = 0;
+
+      res.on('data', (chunk) => {
+        size += chunk.length;
+        if (size > 1024 * 1024) {
+          reject(new Error('Unity AI Context Bridge Editor Extension endpoint returned a response that is too large'));
+          req.destroy();
+          return;
+        }
+        chunks.push(chunk);
+      });
+
+      res.on('end', () => {
+        const body = Buffer.concat(chunks).toString('utf8');
+        if (res.statusCode < 200 || res.statusCode >= 300) {
+          reject(new Error(`Unity AI Context Bridge Editor Extension endpoint returned HTTP ${res.statusCode}: ${body}`));
+          return;
+        }
+
+        try {
+          resolve(JSON.parse(body));
+        } catch (err) {
+          reject(new Error(`Unity AI Context Bridge Editor Extension endpoint returned invalid JSON: ${err.message}`));
+        }
+      });
+    });
+
+    req.setTimeout(timeoutMs, () => {
+      req.destroy(new Error(`Unity AI Context Bridge Editor Extension endpoint timed out after ${timeoutMs}ms`));
+    });
+
+    req.on('error', reject);
+  });
+}
+
+async function getUnityContext(projectPath) {
+  const bridge = await readBridgeInfo(decodeProjectPath(projectPath));
+  return validateUnityContext(await fetchJson(bridge.url, bridge.authToken));
+}
+
+function createUnityMcpServer() {
+  const server = new McpServer(SERVER_INFO);
+
+  server.registerResource(
+    'unity-context-items',
+    new ResourceTemplate(RESOURCE_URI_TEMPLATE, { list: undefined }),
+    {
+      title: 'Unity Context Items',
+      description: 'Returns information about the Unity GameObjects, assets, and other editor items user selected in the Unity editor that are relevant to the active AI task.',
+      mimeType: 'application/json',
+    },
+    async (uri, variables) => {
+      const projectPath = decodeProjectPath(variables.projectPath);
+      const unityContext = await getUnityContext(variables.projectPath);
+      return {
+        contents: [
+          {
+            uri: getUnityContextResourceUri(projectPath),
+            mimeType: 'application/json',
+            text: jsonText(unityContext),
+          },
+        ],
+      };
+    },
+  );
+
+  server.registerTool(
+    'get_unity_context_items',
+    {
+      title: 'Get Unity Context Items',
+      description: 'Returns information about the Unity GameObjects, assets, and other editor items user selected in the Unity editor that are relevant to the active AI task.',
+      inputSchema: {
+        projectPath: z.string().describe('URL-encoded Unity project full path.'),
+      },
+      annotations: {
+        readOnlyHint: true,
+        openWorldHint: false,
+      },
+    },
+    async ({ projectPath }) => {
+      const unityContext = await getUnityContext(projectPath);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: jsonText(unityContext),
+          },
+        ],
+        structuredContent: unityContext,
+      };
+    },
+  );
+
+  return server;
+}
+
+function isAuthorized(req, authToken) {
+  if (!authToken) {
+    return true;
+  }
+
+  const bearer = req.headers.authorization;
+  const token = req.headers['x-auth-token'];
+  return bearer === `Bearer ${authToken}` || token === authToken;
+}
+
+function sendJson(res, statusCode, value) {
+  const body = JSON.stringify(value, null, 2);
+  res.writeHead(statusCode, {
+    'content-type': 'application/json; charset=utf-8',
+    'content-length': Buffer.byteLength(body, 'utf8'),
+  });
+  res.end(body);
+}
+
+function authMiddleware(authToken) {
+  return (req, res, next) => {
+    if (isAuthorized(req, authToken)) {
+      next();
+      return;
+    }
+
+    res.status(401).json({
+      error: 'Unauthorized',
+      message: 'Send Authorization: Bearer <token> or x-auth-token: <token>.',
+    });
+  };
+}
+
+async function startStdioServer() {
+  const server = createUnityMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+async function startHttpServer() {
+  const host = process.env.HOST || '127.0.0.1';
+  const port = Number(process.env.PORT || process.env.MCP_PORT || 3333);
+  const authToken = process.env.MCP_AUTH_TOKEN || process.env.AUTH_TOKEN || '';
+  const app = createMcpExpressApp();
+
+  app.get('/health', (req, res) => {
+    res.json({ ok: true, serverInfo: SERVER_INFO });
+  });
+
+  app.get('/context', authMiddleware(authToken), async (req, res) => {
+    try {
+      res.json(await getUnityContext(req.query.projectPath));
+    } catch (err) {
+      res.status(502).json({
+        error: 'Bad Gateway',
+        message: err.message,
+      });
+    }
+  });
+
+  app.post('/mcp', authMiddleware(authToken), async (req, res) => {
+    const server = createUnityMcpServer();
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: undefined,
+    });
+
+    try {
+      await server.connect(transport);
+      await transport.handleRequest(req, res, req.body);
+      res.on('close', () => {
+        transport.close().catch((err) => console.error('Error closing MCP HTTP transport:', err));
+        server.close().catch((err) => console.error('Error closing MCP HTTP server:', err));
+      });
+    } catch (err) {
+      console.error('Error handling MCP HTTP request:', err);
+      if (!res.headersSent) {
+        res.status(500).json({
+          jsonrpc: '2.0',
+          error: {
+            code: -32603,
+            message: 'Internal server error',
+          },
+          id: null,
+        });
+      }
+    }
+  });
+
+  app.get('/mcp', authMiddleware(authToken), (req, res) => {
+    sendJson(res, 405, {
+      jsonrpc: '2.0',
+      error: {
+        code: -32000,
+        message: 'Method not allowed.',
+      },
+      id: null,
+    });
+  });
+
+  app.delete('/mcp', authMiddleware(authToken), (req, res) => {
+    sendJson(res, 405, {
+      jsonrpc: '2.0',
+      error: {
+        code: -32000,
+        message: 'Method not allowed.',
+      },
+      id: null,
+    });
+  });
+
+  await new Promise((resolve, reject) => {
+    const listener = app.listen(port, host, () => {
+      console.error(`${SERVER_INFO.name} Streamable HTTP server listening on http://${host}:${port}/mcp`);
+      if (!authToken) {
+        console.error('MCP_AUTH_TOKEN is not set; HTTP auth is disabled.');
+      }
+      resolve(listener);
+    });
+
+    listener.on('error', reject);
+  });
+}
+
+if (require.main === module) {
+  const args = new Set(process.argv.slice(2));
+  const start = args.has('--http') ? startHttpServer : startStdioServer;
+
+  start().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@jamius19/unity-ai-context-bridge-mcp",
+  "version": "1.0.0",
+  "description": "MCP server that feeds AI tools the currently selected Unity GameObjects and assets of interest. Requires the \"Unity AI Context Bridge\" Unity package to be installed in the Unity project.",
+  "homepage": "https://github.com/jamius19/unity-ai-context-bridge-mcp",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jamius19/unity-ai-context-bridge-mcp.git"
+  },
+  "main": "index.js",
+  "type": "commonjs",
+  "bin": {
+    "uacb-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "start": "node index.js",
+    "start:stdio": "node index.js --stdio",
+    "start:http": "node index.js --http"
+  },
+  "author": "Jamius Siam",
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  }
+}