gdep-mcp 0.1.0

package/README.md

@@ -0,0 +1,76 @@
+# gdep-mcp
+
+> MCP server for [gdep](https://github.com/pirua-game/gdep) — Game Codebase Analysis Tool
+
+Enables Claude Desktop, Cursor, and other MCP-compatible AI agents to analyze game projects
+(Unity, Unreal Engine 5, C++, C#) using gdep.
+
+## Install
+
+```bash
+npm install -g gdep-mcp
+```
+
+Automatically installs the `gdep` Python package and `mcp[cli]` dependencies.
+
+## Usage
+
+Add to your AI agent config:
+
+**Claude Desktop** (`claude_desktop_config.json`):
+```json
+{
+  "mcpServers": {
+    "gdep": {
+      "command": "gdep-mcp"
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json`):
+```json
+{
+  "mcpServers": {
+    "gdep": {
+      "command": "gdep-mcp"
+    }
+  }
+}
+```
+
+> Each tool accepts `project_path` as a call parameter — no path needed in the config.
+
+## Requirements
+
+- Node.js 18+
+- Python 3.11+
+- .NET Runtime 8.0+ (for C#/Unity analysis)
+
+## Available Tools (13)
+
+| Tool | Description |
+|------|-------------|
+| `get_project_context` | Project overview — call first |
+| `analyze_impact_and_risk` | Change impact + lint |
+| `trace_gameplay_flow` | Call chain tracing (C++→BP) |
+| `inspect_architectural_health` | Tech debt diagnosis |
+| `explore_class_semantics` | Class structure + AI summary |
+| `execute_gdep_cli` | Raw CLI access |
+| `find_unity_event_bindings` | Unity Inspector bindings |
+| `analyze_unity_animator` | Unity Animator state machine |
+| `analyze_ue5_gas` | UE5 GAS full analysis |
+| `analyze_ue5_behavior_tree` | BehaviorTree structure |
+| `analyze_ue5_state_tree` | StateTree structure |
+| `analyze_ue5_animation` | ABP + Montage analysis |
+| `analyze_ue5_blueprint_mapping` | C++ → Blueprint mapping |
+
+## Links
+
+- [GitHub Repository](https://github.com/pirua-game/gdep)
+- [Full Documentation](https://github.com/pirua-game/gdep/blob/main/README.md)
+- [Benchmark](https://github.com/pirua-game/gdep/blob/main/docs/BENCHMARK.md)
+
+## License
+
+Apache-2.0

package/bin/gdep-mcp.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+/**
+ * gdep-mcp — CLI entry point
+ *
+ * Usage:
+ *   gdep-mcp
+ *
+ * Launches the gdep MCP server (Python).
+ * Each tool call passes project_path as a parameter — no args needed here.
+ * The Python gdep package must be installed: pip install gdep
+ */
+
+const { spawn } = require('child_process');
+const os = require('os');
+const fs = require('fs');
+const path = require('path');
+
+const pyCmd = os.platform() === 'win32' ? 'python' : 'python3';
+
+function findServerScript() {
+  const { execSync } = require('child_process');
+  try {
+    const pipShow = execSync(`${pyCmd} -m pip show gdep`, { encoding: 'utf8' });
+    const locationMatch = pipShow.match(/Location: (.+)/);
+    if (locationMatch) {
+      // pip install gdep installs to site-packages/gdep_mcp/server.py
+      const candidate = path.join(locationMatch[1].trim(), 'gdep_mcp', 'server.py');
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  } catch {}
+  return null;
+}
+
+const serverScript = findServerScript();
+
+let child;
+if (serverScript) {
+  child = spawn(pyCmd, [serverScript], {
+    stdio: 'inherit',
+    env: { ...process.env, PYTHONUTF8: '1' },
+  });
+} else {
+  child = spawn(pyCmd, ['-m', 'gdep_mcp.server'], {
+    stdio: 'inherit',
+    env: { ...process.env, PYTHONUTF8: '1' },
+  });
+}
+
+child.on('error', (err) => {
+  console.error(`Failed to start gdep MCP server: ${err.message}`);
+  console.error('Make sure gdep is installed: pip install gdep "mcp[cli]"');
+  process.exit(1);
+});
+
+child.on('exit', (code) => {
+  process.exit(code ?? 0);
+});

package/bin/postinstall.js

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * gdep-mcp — postinstall script
+ *
+ * Automatically installs the gdep Python package and MCP dependencies
+ * after `npm install -g gdep-mcp`.
+ *
+ * Steps:
+ *   1. Check Python 3.11+ is available
+ *   2. pip install gdep  (from PyPI)
+ *   3. pip install "mcp[cli]"
+ *   4. Print Claude Desktop config snippet
+ */
+
+const { execSync, spawnSync } = require('child_process');
+const path = require('path');
+const os = require('os');
+
+const BOLD = '\x1b[1m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const CYAN = '\x1b[36m';
+const RESET = '\x1b[0m';
+
+function log(msg)  { console.log(msg); }
+function ok(msg)   { console.log(`${GREEN}✓${RESET} ${msg}`); }
+function warn(msg) { console.log(`${YELLOW}⚠${RESET}  ${msg}`); }
+function info(msg) { console.log(`${CYAN}→${RESET} ${msg}`); }
+
+log(`\n${BOLD}gdep-mcp postinstall${RESET}\n`);
+
+// ── 1. Python check ───────────────────────────────────────────
+const pyCmd = os.platform() === 'win32' ? 'python' : 'python3';
+let pyVersion = null;
+try {
+  pyVersion = execSync(`${pyCmd} --version`, { encoding: 'utf8' }).trim();
+  ok(`Python found: ${pyVersion}`);
+} catch {
+  warn('Python 3.11+ not found. Please install Python and re-run:');
+  warn('  pip install gdep "mcp[cli]"');
+  process.exit(0); // soft fail — don't block npm install
+}
+
+const versionMatch = pyVersion.match(/Python (\d+)\.(\d+)/);
+if (versionMatch) {
+  const [, major, minor] = versionMatch.map(Number);
+  if (major < 3 || (major === 3 && minor < 11)) {
+    warn(`Python 3.11+ required (found ${major}.${minor}). Please upgrade.`);
+    process.exit(0);
+  }
+}
+
+// ── 2. pip install gdep ───────────────────────────────────────
+info('Installing gdep Python package...');
+const pipInstall = spawnSync(pyCmd, ['-m', 'pip', 'install', '--upgrade', 'gdep', 'mcp[cli]'], {
+  stdio: 'inherit',
+  shell: true,
+});
+
+if (pipInstall.status !== 0) {
+  warn('pip install failed. Try manually: pip install gdep "mcp[cli]"');
+  process.exit(0);
+}
+ok('gdep and mcp[cli] installed successfully.');
+
+// ── 3. Print config snippet ───────────────────────────────────
+const serverScript = path.join(__dirname, 'server.js');
+log(`
+${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}
+${GREEN}${BOLD} gdep-mcp installed!${RESET}
+
+Add this to your Claude Desktop config
+(claude_desktop_config.json):
+
+${CYAN}{
+  "mcpServers": {
+    "gdep": {
+      "command": "gdep-mcp",
+      "args": ["/path/to/your/game/project"]
+    }
+  }
+}${RESET}
+
+${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}
+`);

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "gdep-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for gdep — Game Codebase Analysis Tool (Unity/UE5/C++/C#)",
+  "keywords": ["mcp", "game", "unity", "unreal", "ue5", "dependency", "analysis", "claude", "cursor", "ai"],
+  "author": "pirua-game",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pirua-game/gdep.git"
+  },
+  "homepage": "https://github.com/pirua-game/gdep",
+  "bin": {
+    "gdep-mcp": "./bin/gdep-mcp.js"
+  },
+  "scripts": {
+    "postinstall": "node bin/postinstall.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "README.md"
+  ]
+}