cwtools-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createCwtoolsMcpServer = createCwtoolsMcpServer;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const toolRegistrar_1 = require("./mcp/toolRegistrar");
+const toolHandlers_1 = require("./mcp/toolHandlers");
+const resources_1 = require("./mcp/resources");
+// Server-level guidance surfaced to the model at connect time (MCP `instructions`).
+// Tells a Paradox coding agent to ground every claim in these tools.
+const SERVER_INSTRUCTIONS = [
+    'CWTools is a read-only semantic service for Paradox mods. Ground every',
+    'claim about the mod in these tools instead of memory — PDX identifiers and syntax',
+    'are routinely hallucinated.',
+    '',
+    'Use it whenever working in a Paradox mod (common/, events/, localisation/, gfx/, …):',
+    '- Start structural and dependency questions with explore_pdx_project. It returns a',
+    '  bounded live CWTools semantic subgraph, file facts, provenance, and freshness.',
+    '- Before using ANY game ID, verify it exists: query_types for typed entities;',
+    '  query_scripted_effects / query_scripted_triggers / query_static_modifiers /',
+    '  query_enums / query_variables for those kinds.',
+    '- Check trigger/effect/scope-change/modifier syntax with query_rules; check the scope',
+    '  valid at a position with query_scope.',
+    '- Check common/event/interface/gfx schema shape with query_cwt_schema before writing',
+    '  fields, block topology, or entity-path assumptions.',
+    '- Before declaring code correct, review get_diagnostics (whole project). Honor the',
+    '  readiness/freshness fields: if readiness.ready is false the project is still loading —',
+    '  retry; an empty result then is not authoritative.',
+    '- Navigate with query_definition / query_definition_by_name / query_references /',
+    '  document_symbols / workspace_symbols; read structured blocks with get_pdx_block',
+    '  instead of reading whole files. get_entity_info gives a file\'s referenced types/vars.',
+    '- Results carry vanillaCache metadata: if available is false, vanilla IDs are missing',
+    '  and references to them may show as false errors.',
+    '',
+    'This server never writes files — perform edits with your own environment, then',
+    're-check with get_diagnostics.',
+].join('\n');
+function createCwtoolsMcpServer(host, options = {}) {
+    // Undefined => treat as supported (e.g. the in-extension host never sets it).
+    const supported = host.projectSupported !== false;
+    const server = new index_js_1.Server({
+        name: 'cwtools-mcp',
+        version: '0.1.0',
+    }, {
+        capabilities: {
+            resources: {},
+            tools: {},
+        },
+        instructions: SERVER_INSTRUCTIONS,
+    });
+    const callTool = (0, toolHandlers_1.createToolCallHandler)(host, options.dispatcher);
+    // Tools stay listed even on unsupported workspaces so the model can always see
+    // CWTools exists (instead of falling back to hunting for a CLI). The heavy work
+    // is gated at call time below, not by hiding the toolset.
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+        tools: (0, toolRegistrar_1.listRegisteredTools)(),
+    }));
+    server.setRequestHandler(types_js_1.ListResourcesRequestSchema, async () => ({
+        resources: (0, resources_1.listResources)(),
+    }));
+    server.setRequestHandler(types_js_1.ReadResourceRequestSchema, async (request) => (0, resources_1.readResource)(host, request.params.uri));
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        // On an unsupported workspace, reject before dispatch so the language server
+        // is never spawned (memory). The message is actionable: the resolved
+        // workspace is almost always the cause when this fires on a real mod.
+        if (!supported) {
+            return (0, toolHandlers_1.toMcpCallToolResult)({
+                ok: false,
+                status: 'denied',
+                source: 'cwtools-mcp',
+                error: {
+                    code: 'project_not_supported',
+                    message: `CWTools is disabled for this workspace (${host.workspaceRoot}): ${host.projectSupportReason ?? 'not a Paradox mod.'} ` +
+                        'If this IS a mod, point the server at the mod root — set the working directory (or pass --workspace <mod>) — or pass --force-start to override.',
+                },
+            });
+        }
+        const args = request.params.arguments && typeof request.params.arguments === 'object'
+            ? request.params.arguments
+            : {};
+        const result = await callTool(request.params.name, args);
+        return (0, toolHandlers_1.toMcpCallToolResult)(result);
+    });
+    return server;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "cwtools-mcp",
+  "version": "0.1.0",
+  "description": "Read-only MCP server exposing CWTools Paradox/Stellaris semantic tools to external agents",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Aa728848/cwtools-mcp.git"
+  },
+  "keywords": [
+    "mcp",
+    "cwtools",
+    "stellaris",
+    "paradox",
+    "language-server"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "cwtools-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "package.json"
+  ],
+  "scripts": {
+    "prebuild": "npm run build -w cwtools-shared",
+    "build": "tsc -p tsconfig.json",
+    "bundle": "esbuild dist/cli.js --bundle --platform=node --format=cjs --target=node18 --outfile=dist/cwtools-mcp.cjs",
+    "prepack": "npm run build",
+    "test:contracts": "ts-mocha -p tsconfig.test.json \"src/test/**/*.test.ts\""
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chokidar": "^4.0.3",
+    "cwtools-shared": "0.1.0",
+    "vscode-jsonrpc": "^8.2.0"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.1"
+  }
+}