cwtools-mcp 0.1.0

package/README.md

@@ -0,0 +1,279 @@
+# cwtools-mcp
+
+[English](#english) | [中文](#zh-cn)
+
+<a id="english"></a>
+
+## English
+
+CWTools MCP is the external-agent entry point for this extension's Paradox /
+Stellaris semantic tools.
+
+### Default Mode: Extension Bridge
+
+By default, `cwtools-mcp` is a lightweight MCP proxy. It does **not** start a
+second `CWTools Server` process. Instead, it connects to the MCP bridge started
+inside the active VS Code-compatible extension host and reuses that host's:
+
+- existing CWTools language client;
+- current workspace root;
+- Problems diagnostics from the IDE;
+- rules/cache/localisation/user settings;
+- shared indexes and AI read tools.
+
+This keeps memory use low and makes MCP diagnostics match the IDE.
+
+Bridge mode is deliberately strict about project identity without requiring a
+project path in global MCP settings. By default, the proxy discovers the current
+client workspace from MCP roots, known per-session environment variables, or the
+MCP process cwd. That workspace must match the `workspaceRoot` served by the
+extension bridge. If they do not match, tool calls return `bridge_unavailable`
+instead of silently answering from a different project. `--workspace` remains an
+optional override for clients that cannot expose a per-project root.
+
+The extension writes both files below into the current host's own
+`globalStorage/mcp/` directory when the project is active:
+
+```text
+cwtools-mcp.cjs
+bridge-manifest.json
+```
+
+External agents should run the `cwtools-mcp.cjs` copied by the same host they are
+using. The proxy reads `bridge-manifest.json` next to itself. This is host-name
+agnostic: VS Code, Cursor, VSCodium, Antigravity, and other compatible hosts all
+work as long as they support the VS Code extension APIs and activate this
+extension.
+
+### Quick Setup
+
+Use the `globalStorage` path from the compatible host where the extension is
+active. The placeholder below means the directory that contains the host's
+`foreverskywalker.foreverskywalker-stellaris-cwtools` global storage folder.
+
+#### Codex
+
+```sh
+codex mcp add cwtools -- node "<host-globalStorage>/foreverskywalker.foreverskywalker-stellaris-cwtools/mcp/cwtools-mcp.cjs" --stdio
+```
+
+#### Claude Code
+
+```sh
+claude mcp add cwtools --scope user -- node "<host-globalStorage>/foreverskywalker.foreverskywalker-stellaris-cwtools/mcp/cwtools-mcp.cjs" --stdio
+```
+
+#### Antigravity
+
+Antigravity reads MCP servers from `~/.gemini/config/mcp_config.json`. Add this
+server entry:
+
+```json
+{
+  "mcpServers": {
+    "cwtools": {
+      "command": "node",
+      "args": [
+        "<host-globalStorage>/foreverskywalker.foreverskywalker-stellaris-cwtools/mcp/cwtools-mcp.cjs",
+        "--stdio"
+      ]
+    }
+  }
+}
+```
+
+Or merge it into an existing config with a Node one-liner:
+
+```sh
+node -e "const fs=require('fs'),os=require('os'),path=require('path');const p=path.join(os.homedir(),'.gemini','config','mcp_config.json');const s=process.argv[1];const cfg=fs.existsSync(p)?JSON.parse(fs.readFileSync(p,'utf8')):{};cfg.mcpServers={...(cfg.mcpServers||{}),cwtools:{command:'node',args:[s,'--stdio']}};fs.mkdirSync(path.dirname(p),{recursive:true});fs.writeFileSync(p,JSON.stringify(cfg,null,2)+'\n')" "<host-globalStorage>/foreverskywalker.foreverskywalker-stellaris-cwtools/mcp/cwtools-mcp.cjs"
+```
+
+If the compatible host is closed, the workspace is not active, the manifest is
+stale, or the client workspace differs from the bridge workspace, tool
+calls return `bridge_unavailable` with recovery instructions. The proxy
+intentionally does not silently fall back to a separate language server.
+
+### Optional Standalone Mode
+
+Use standalone mode only when you explicitly want the legacy behavior: the MCP
+process starts its own CWTools language server and builds its own diagnostic
+state.
+
+```sh
+cwtools-mcp --standalone --workspace /path/to/mod --game stellaris --stdio
+```
+
+HTTP transport is available in both modes:
+
+```sh
+cwtools-mcp --http --host 127.0.0.1 --port 3000
+cwtools-mcp --standalone --workspace /path/to/mod --http --host 127.0.0.1 --port 3000
+```
+
+### Standalone Rules And Vanilla Cache
+
+These options apply to standalone mode:
+
+```sh
+cwtools-mcp --standalone --workspace /path/to/mod --game stellaris --game-path "/path/to/Stellaris"
+cwtools-mcp --standalone --workspace /path/to/mod --game stellaris --cache "/path/to/.cwtools"
+cwtools-mcp --standalone --workspace /path/to/mod --game stellaris --rules "/path/to/rules/config"
+```
+
+When standalone mode lacks a vanilla `.cwb` cache or `--game-path`, vanilla IDs
+may be absent and diagnostics can differ from the IDE. Bridge mode avoids this by
+using the active extension host's loaded state.
+
+### Tools
+
+The MCP surface remains read-only. It exposes the generated CWTools semantic
+tools such as:
+
+- `query_types`
+- `query_rules`
+- `query_scope`
+- `get_diagnostics`
+- `explore_pdx_project` for a bounded live semantic graph with dependency edges and freshness
+- `query_workspace_index`
+- `query_localisation_index`
+- `get_pdx_block`
+- completion, document/workspace symbols, definition and reference lookup
+- deep semantic queries for scripted effects/triggers, enums, static modifiers,
+  variables, and entity info
+
+File edits are intentionally not exposed through this MCP server. External agents
+should edit files through their own environment and then call MCP diagnostics or
+semantic tools again.
+
+---
+
+<a id="zh-cn"></a>
+
+## 中文
+
+CWTools MCP 是本扩展提供给外部 Agent 的 Paradox / Stellaris 语义工具入口。
+
+### 默认模式：插件内 Bridge
+
+默认情况下，`cwtools-mcp` 是一个轻量 MCP 代理。它**不会**再启动第二个
+`CWTools Server` 进程，而是连接当前已激活的 VS Code 兼容宿主内的 MCP
+bridge，并复用该宿主中的：
+
+- 已有 CWTools 语言客户端；
+- 当前工作区根目录；
+- IDE Problems 面板诊断；
+- rules/cache/localisation/用户设置；
+- 共享索引和 AI 只读工具。
+
+这样可以降低内存占用，并让 MCP 诊断数量与 IDE 保持一致。
+
+Bridge 模式会严格校验项目身份，但不要求把项目路径写死到全局 MCP 设置里。默认情况下，
+代理会从 MCP roots、已知的按会话注入的环境变量或 MCP 进程 cwd 推断当前客户端工作区。
+这个工作区必须与扩展 bridge 暴露的 `workspaceRoot` 一致。不一致时工具调用会返回
+`bridge_unavailable`，不会静默使用另一个项目回答。`--workspace` 只保留给无法暴露
+按项目 root 的客户端作为可选覆盖项。
+
+项目激活时，扩展会把下面两个文件写入当前宿主自己的 `globalStorage/mcp/`
+目录：
+
+```text
+cwtools-mcp.cjs
+bridge-manifest.json
+```
+
+外部 Agent 应运行同一个宿主复制出来的 `cwtools-mcp.cjs`。代理会读取同目录的
+`bridge-manifest.json`。这条主路径不依赖宿主目录名：VS Code、Cursor、
+VSCodium、Antigravity，以及其他兼容 VS Code 扩展 API 的宿主都可以使用。
+
+### 快速接入
+
+请使用实际运行扩展的兼容宿主自己的 `globalStorage` 路径。下面的
+`<host-globalStorage>` 代表该宿主下
+`foreverskywalker.foreverskywalker-stellaris-cwtools` 全局存储目录所在位置。
+
+#### Codex
+
+```sh
+codex mcp add cwtools -- node "<host-globalStorage>/foreverskywalker.foreverskywalker-stellaris-cwtools/mcp/cwtools-mcp.cjs" --stdio
+```
+
+#### Claude Code
+
+```sh
+claude mcp add cwtools --scope user -- node "<host-globalStorage>/foreverskywalker.foreverskywalker-stellaris-cwtools/mcp/cwtools-mcp.cjs" --stdio
+```
+
+#### Antigravity
+
+Antigravity 从 `~/.gemini/config/mcp_config.json` 读取 MCP 服务器。添加下面这个
+server 条目：
+
+```json
+{
+  "mcpServers": {
+    "cwtools": {
+      "command": "node",
+      "args": [
+        "<host-globalStorage>/foreverskywalker.foreverskywalker-stellaris-cwtools/mcp/cwtools-mcp.cjs",
+        "--stdio"
+      ]
+    }
+  }
+}
+```
+
+也可以用下面的 Node 一行命令合并进已有配置，不会覆盖其他 MCP server：
+
+```sh
+node -e "const fs=require('fs'),os=require('os'),path=require('path');const p=path.join(os.homedir(),'.gemini','config','mcp_config.json');const s=process.argv[1];const cfg=fs.existsSync(p)?JSON.parse(fs.readFileSync(p,'utf8')):{};cfg.mcpServers={...(cfg.mcpServers||{}),cwtools:{command:'node',args:[s,'--stdio']}};fs.mkdirSync(path.dirname(p),{recursive:true});fs.writeFileSync(p,JSON.stringify(cfg,null,2)+'\n')" "<host-globalStorage>/foreverskywalker.foreverskywalker-stellaris-cwtools/mcp/cwtools-mcp.cjs"
+```
+
+如果兼容宿主未打开、工作区未激活、manifest 已失效，或客户端工作区与 bridge
+工作区不一致，工具调用会返回 `bridge_unavailable` 和恢复说明。代理不会静默回退并启动单独的语言服务。
+
+### 可选 Standalone 模式
+
+只有在明确需要旧行为时才使用 standalone 模式：MCP 进程会自行启动一份 CWTools
+语言服务器并构建独立诊断状态。
+
+```sh
+cwtools-mcp --standalone --workspace /path/to/mod --game stellaris --stdio
+```
+
+两种模式都支持 HTTP transport：
+
+```sh
+cwtools-mcp --http --host 127.0.0.1 --port 3000
+cwtools-mcp --standalone --workspace /path/to/mod --http --host 127.0.0.1 --port 3000
+```
+
+### Standalone 的规则与原版缓存
+
+下面这些参数只适用于 standalone 模式：
+
+```sh
+cwtools-mcp --standalone --workspace /path/to/mod --game stellaris --game-path "/path/to/Stellaris"
+cwtools-mcp --standalone --workspace /path/to/mod --game stellaris --cache "/path/to/.cwtools"
+cwtools-mcp --standalone --workspace /path/to/mod --game stellaris --rules "/path/to/rules/config"
+```
+
+如果 standalone 模式缺少 vanilla `.cwb` 缓存或 `--game-path`，原版 ID 可能缺失，
+诊断也可能与 IDE 不一致。Bridge 模式通过复用当前扩展宿主的已加载状态来避免这个问题。
+
+### 工具
+
+MCP 入口仍保持只读。它暴露生成出来的 CWTools 语义工具，例如：
+
+- `query_types`
+- `query_rules`
+- `query_scope`
+- `get_diagnostics`
+- `explore_pdx_project`：返回带依赖边与 freshness 的有界 live 语义图
+- `query_workspace_index`
+- `query_localisation_index`
+- `get_pdx_block`
+- 补全、document/workspace symbols、定义和引用查询
+- scripted effects/triggers、enums、static modifiers、variables、entity info 等深层语义查询
+
+文件写入不会通过这个 MCP server 暴露。外部 Agent 应使用自己的环境编辑文件，
+然后再调用 MCP 诊断或语义工具复查。

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const config_1 = require("./config");
+const nodeHostServices_1 = require("./hosts/nodeHostServices");
+const bridgeProxy_1 = require("./mcp/bridgeProxy");
+const transportHttp_1 = require("./mcp/transportHttp");
+const transportStdio_1 = require("./mcp/transportStdio");
+const server_1 = require("./server");
+// Tear down host-owned resources (the spawned CWTools Server child) exactly
+// once, then exit. MCP clients like Codex disconnect by closing the stdio pipe
+// rather than asking us to shut down; without this the LSP child's pipes keep
+// the event loop alive and orphan a multi-GB server process. host.dispose()
+// only kills the child THIS process spawned, never any other instance.
+function installLifecycle(host, stdio) {
+    let disposed = false;
+    const dispose = () => {
+        if (disposed)
+            return;
+        disposed = true;
+        try {
+            host.dispose?.();
+        }
+        catch {
+            // best-effort cleanup
+        }
+    };
+    const shutdown = () => {
+        dispose();
+        process.exit(0);
+    };
+    // Synchronous safety net for any other exit path.
+    process.once('exit', dispose);
+    process.once('SIGINT', shutdown);
+    process.once('SIGTERM', shutdown);
+    if (process.platform !== 'win32')
+        process.once('SIGHUP', shutdown);
+    // In stdio mode the client closing the pipe (EOF on our stdin) is the
+    // disconnect signal — shut down instead of lingering.
+    if (stdio) {
+        process.stdin.once('end', shutdown);
+        process.stdin.once('close', shutdown);
+    }
+}
+async function main() {
+    const config = (0, config_1.parseCliArgs)(process.argv.slice(2));
+    if (!config.standalone) {
+        if (config.http) {
+            await (0, transportHttp_1.runHttpTransport)(() => (0, bridgeProxy_1.createBridgeProxyMcpServer)(config), { host: config.host, port: config.port });
+        }
+        else if (config.stdio) {
+            const server = (0, bridgeProxy_1.createBridgeProxyMcpServer)(config);
+            await (0, transportStdio_1.runStdioTransport)(server);
+        }
+        else {
+            throw new Error('No MCP transport selected. Use --stdio or --http.');
+        }
+        return;
+    }
+    const host = (0, nodeHostServices_1.createNodeHostServices)(config);
+    installLifecycle(host, !!config.stdio && !config.http);
+    if (config.http) {
+        await (0, transportHttp_1.runHttpTransport)(() => (0, server_1.createCwtoolsMcpServer)(host), { host: config.host, port: config.port });
+    }
+    else if (config.stdio) {
+        const server = (0, server_1.createCwtoolsMcpServer)(host);
+        await (0, transportStdio_1.runStdioTransport)(server);
+    }
+    else {
+        throw new Error('No MCP transport selected. Use --stdio or --http.');
+    }
+}
+main().catch(error => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+});

package/dist/config.d.ts

@@ -0,0 +1,20 @@
+export interface CwtoolsMcpConfig {
+    workspaceRoot: string;
+    game?: string;
+    serverPath?: string;
+    gamePath?: string;
+    cachePath?: string;
+    rulesPath?: string;
+    bridgeManifestPath?: string;
+    stdio: boolean;
+    http: boolean;
+    host: string;
+    port: number;
+    enableWrites: boolean;
+    allowedTools: string[];
+    forceStart: boolean;
+    standalone: boolean;
+    workspaceRootExplicit: boolean;
+}
+export declare function parseCliArgs(argv: string[]): CwtoolsMcpConfig;
+export declare function helpText(): string;

package/dist/config.js

@@ -0,0 +1,212 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseCliArgs = parseCliArgs;
+exports.helpText = helpText;
+const path = __importStar(require("path"));
+function parseCliArgs(argv) {
+    const config = {
+        workspaceRoot: process.cwd(),
+        stdio: true,
+        http: false,
+        host: '127.0.0.1',
+        port: 3000,
+        enableWrites: false,
+        allowedTools: [],
+        forceStart: false,
+        standalone: false,
+        workspaceRootExplicit: false,
+    };
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        switch (arg) {
+            case '--workspace':
+                config.workspaceRoot = path.resolve(readValue(argv, ++index, arg));
+                config.workspaceRootExplicit = true;
+                break;
+            case '--game':
+                config.game = readValue(argv, ++index, arg);
+                break;
+            case '--server-path':
+                config.serverPath = path.resolve(readValue(argv, ++index, arg));
+                break;
+            case '--game-path':
+                config.gamePath = path.resolve(readValue(argv, ++index, arg));
+                break;
+            case '--cache':
+                config.cachePath = path.resolve(readValue(argv, ++index, arg));
+                break;
+            case '--rules':
+                config.rulesPath = resolveRulesPath(readValue(argv, ++index, arg));
+                break;
+            case '--bridge-manifest':
+                config.bridgeManifestPath = path.resolve(readValue(argv, ++index, arg));
+                break;
+            case '--stdio':
+                config.stdio = true;
+                config.http = false;
+                break;
+            case '--http':
+                config.http = true;
+                config.stdio = false;
+                break;
+            case '--host':
+                config.host = readValue(argv, ++index, arg);
+                break;
+            case '--port':
+                config.port = readPort(readValue(argv, ++index, arg));
+                break;
+            case '--enable-writes':
+                config.enableWrites = true;
+                break;
+            case '--force-start':
+                config.forceStart = true;
+                break;
+            case '--standalone':
+                config.standalone = true;
+                break;
+            case '--allow-tool':
+                config.allowedTools.push(readValue(argv, ++index, arg));
+                break;
+            case '--help':
+            case '-h':
+                throw new Error(helpText());
+            default:
+                if (arg?.startsWith('--allow-tool=')) {
+                    config.allowedTools.push(arg.slice('--allow-tool='.length));
+                }
+                else if (arg?.startsWith('--workspace=')) {
+                    config.workspaceRoot = path.resolve(arg.slice('--workspace='.length));
+                    config.workspaceRootExplicit = true;
+                }
+                else if (arg?.startsWith('--game=')) {
+                    config.game = arg.slice('--game='.length);
+                }
+                else if (arg?.startsWith('--server-path=')) {
+                    config.serverPath = path.resolve(arg.slice('--server-path='.length));
+                }
+                else if (arg?.startsWith('--game-path=')) {
+                    config.gamePath = path.resolve(arg.slice('--game-path='.length));
+                }
+                else if (arg?.startsWith('--cache=')) {
+                    config.cachePath = path.resolve(arg.slice('--cache='.length));
+                }
+                else if (arg?.startsWith('--rules=')) {
+                    config.rulesPath = resolveRulesPath(arg.slice('--rules='.length));
+                }
+                else if (arg?.startsWith('--bridge-manifest=')) {
+                    config.bridgeManifestPath = path.resolve(arg.slice('--bridge-manifest='.length));
+                }
+                else if (arg?.startsWith('--host=')) {
+                    config.host = arg.slice('--host='.length);
+                }
+                else if (arg?.startsWith('--port=')) {
+                    config.port = readPort(arg.slice('--port='.length));
+                }
+                else if (arg === '--http') {
+                    config.http = true;
+                    config.stdio = false;
+                }
+                else if (arg === '--standalone') {
+                    config.standalone = true;
+                }
+                else {
+                    throw new Error(`Unknown argument: ${arg}\n\n${helpText()}`);
+                }
+        }
+    }
+    return config;
+}
+function resolveRulesPath(value) {
+    const resolved = path.resolve(value);
+    if (resolved.toLowerCase().endsWith('.zip')) {
+        throw new Error('--rules must be a directory, not a .zip archive');
+    }
+    return resolved;
+}
+function readPort(value) {
+    const port = Number(value);
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+        throw new Error(`Invalid --port value: ${value}`);
+    }
+    return port;
+}
+function readValue(argv, index, flag) {
+    const value = argv[index];
+    if (!value || value.startsWith('--')) {
+        throw new Error(`Missing value for ${flag}`);
+    }
+    return value;
+}
+function helpText() {
+    return [
+        'Usage:',
+        '  cwtools-mcp [--stdio] [--bridge-manifest <path>] [--workspace <path>]',
+        '  cwtools-mcp --http [--host 127.0.0.1] [--port 3000] [--bridge-manifest <path>] [--workspace <path>]',
+        '  cwtools-mcp --standalone --workspace <path> [--game stellaris] [--stdio] [--server-path <path>]',
+        '  cwtools-mcp --standalone --workspace <path> --http [--host 127.0.0.1] [--port 3000]',
+        '  cwtools-mcp --standalone --workspace <path> --enable-writes',
+        '  cwtools-mcp --standalone --workspace <path> --enable-writes --allow-tool write_localisation',
+        '',
+        'Default bridge mode:',
+        '  The script connects to the extension-host MCP bridge written by the active',
+        '  VS Code-compatible host. The manifest (bridge-manifest.json) is looked up next',
+        '  to this script first, then auto-detected under the host globalStorage of VS Code,',
+        '  Insiders, VSCodium, Cursor, and Antigravity. It does not start a second CWTools',
+        '  language server. The client workspace (MCP roots, environment workspace, cwd,',
+        '  or --workspace when supplied) must match the bridge workspace exactly. If the',
+        '  compatible host is closed or the workspace does not match, tool calls return an',
+        '  actionable unavailable error.',
+        '  Use --standalone only when you intentionally want the legacy self-hosted LSP mode.',
+        '',
+        'Vanilla data (needed for vanilla IDs and correct mod-vs-vanilla diagnostics):',
+        '  (auto)              If neither flag is given, the VS Code cwtools extension cache',
+        '                      in globalStorage is auto-detected and reused.',
+        '  --game-path <dir>   Vanilla install/data dir; the server builds the cache from it (slow first run).',
+        '  --cache <dir>       Dir holding a pre-built <game>.cwb cache (overrides auto-detection),',
+        '                      loaded directly instead of rebuilding. Without any, results are mod-only.',
+        '',
+        'Rules source (priority: --rules > installed extension > dev checkout):',
+        '  --rules <dir>       Explicit CWT rules directory (a .zip is rejected). When omitted, the',
+        '                      rules the installed VS Code extension pulled into globalStorage are used.',
+        '',
+        'Project gate:',
+        '  (default)           Tools are always listed. The language server starts only when the',
+        '                      workspace is (or sits in/above) a Paradox mod (descriptor.mod, common/,',
+        '                      events/, localisation/, .cwtools/). On other workspaces tool calls are',
+        '                      rejected with a reason and no server spawns.',
+        '  --force-start       Treat the workspace as supported even without mod markers.',
+    ].join('\n');
+}