@godpowers/mcp 2.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Godpowers
+
+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,37 @@
+# @godpowers/mcp
+
+- [DECISION] `@godpowers/mcp` is the first-party read-only MCP companion package for Godpowers.
+- [DECISION] The main `godpowers` package stays dependency-free at runtime, and the MCP SDK dependency lives only in this companion package.
+- [DECISION] Version 2.6.0 exposes five tools: `status`, `next`, `gate_check`, `lint_artifact`, and `trace_requirement`.
+- [DECISION] Mutation tools are intentionally absent through the 3.0.0 release.
+
+## Install
+
+```bash
+npm install -g godpowers @godpowers/mcp
+```
+
+## Run
+
+```bash
+godpowers-mcp serve --project=.
+```
+
+## Codex Setup
+
+```bash
+godpowers-mcp setup --host=codex --project=.
+godpowers-mcp setup --host=codex --project=. --write
+```
+
+- [DECISION] The first command prints a registration plan without writing files.
+- [DECISION] The second command writes a managed `[mcp_servers.godpowers]` block to `~/.codex/config.toml`.
+- [DECISION] No automatic host registration runs during package install.
+
+## Tool Boundary
+
+- [DECISION] `status` wraps `lib/dashboard.js` and returns rendered dashboard text plus structured status.
+- [DECISION] `next` wraps `lib/dashboard.js` and returns the recommended next command from disk state.
+- [DECISION] `gate_check` wraps `lib/gate.js` and returns the executable tier gate verdict.
+- [DECISION] `lint_artifact` wraps `lib/artifact-linter.js` for one file inside the project root.
+- [DECISION] `trace_requirement` wraps `lib/requirements.js` and returns requirement, roadmap, linkage, and ledger evidence.

package/bin/godpowers-mcp.js

@@ -0,0 +1,147 @@
+#!/usr/bin/env node
+
+const path = require('path');
+
+const server = require('../lib/server');
+const setup = require('../lib/setup');
+
+function parseArgs(argv, cwd = process.cwd()) {
+  const args = argv.slice(2);
+  const opts = {
+    command: 'serve',
+    project: cwd,
+    runtimeRoot: null,
+    host: 'codex',
+    write: false,
+    json: false,
+    homeDir: null,
+    help: false
+  };
+
+  if (args[0] && !args[0].startsWith('-')) {
+    opts.command = args[0];
+    args.shift();
+  }
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    switch (arg) {
+      case '--project':
+        if (args[i + 1]) {
+          opts.project = path.resolve(args[i + 1]);
+          i++;
+        }
+        break;
+      case '--runtime-root':
+        if (args[i + 1]) {
+          opts.runtimeRoot = path.resolve(args[i + 1]);
+          i++;
+        }
+        break;
+      case '--host':
+        if (args[i + 1]) {
+          opts.host = args[i + 1];
+          i++;
+        }
+        break;
+      case '--home':
+        if (args[i + 1]) {
+          opts.homeDir = path.resolve(args[i + 1]);
+          i++;
+        }
+        break;
+      case '--write':
+        opts.write = true;
+        break;
+      case '--json':
+        opts.json = true;
+        break;
+      case '-h':
+      case '--help':
+        opts.help = true;
+        break;
+      default:
+        if (arg.startsWith('--project=')) {
+          opts.project = path.resolve(arg.slice('--project='.length));
+        } else if (arg.startsWith('--runtime-root=')) {
+          opts.runtimeRoot = path.resolve(arg.slice('--runtime-root='.length));
+        } else if (arg.startsWith('--host=')) {
+          opts.host = arg.slice('--host='.length);
+        } else if (arg.startsWith('--home=')) {
+          opts.homeDir = path.resolve(arg.slice('--home='.length));
+        }
+        break;
+    }
+  }
+
+  return opts;
+}
+
+function renderHelp() {
+  return [
+    'Godpowers MCP',
+    '',
+    'Usage:',
+    '  godpowers-mcp serve --project=.',
+    '  godpowers-mcp setup --host=codex --project=. --write',
+    '',
+    'Commands:',
+    '  serve    Run the read-only MCP server over stdio.',
+    '  setup    Print or write an explicit host registration.',
+    '',
+    'Options:',
+    '  --project=<path>       Project root read by MCP tools.',
+    '  --runtime-root=<path>  Godpowers runtime root for local checkouts.',
+    '  --host=<name>         Host registration target. Currently codex.',
+    '  --home=<path>         Home directory for setup tests or explicit installs.',
+    '  --write               Write setup output. Without this, setup is read-only.',
+    '  --json                Emit JSON for setup.',
+    '  -h, --help            Show this help.'
+  ].join('\n');
+}
+
+async function main() {
+  const opts = parseArgs(process.argv);
+  if (opts.help || opts.command === 'help') {
+    console.log(renderHelp());
+    return;
+  }
+
+  if (opts.command === 'setup') {
+    const plan = setup.setupPlan({
+      host: opts.host,
+      projectRoot: opts.project,
+      runtimeRoot: opts.runtimeRoot,
+      homeDir: opts.homeDir
+    });
+    const result = opts.write ? setup.writeRegistration(plan) : plan;
+    if (opts.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(setup.render(result));
+    }
+    return;
+  }
+
+  if (opts.command !== 'serve') {
+    console.error(`Unknown command: ${opts.command}`);
+    process.exit(1);
+  }
+
+  await server.serveStdio({
+    projectRoot: opts.project,
+    runtimeRoot: opts.runtimeRoot
+  });
+}
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(`Godpowers MCP failed: ${error.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  parseArgs,
+  renderHelp
+};

package/lib/runtime.js

@@ -0,0 +1,82 @@
+const fs = require('fs');
+const path = require('path');
+
+function exists(filePath) {
+  return fs.existsSync(filePath);
+}
+
+function isRuntimeRoot(root) {
+  if (!root) return false;
+  const pkgPath = path.join(root, 'package.json');
+  if (!exists(pkgPath)) return false;
+  if (!exists(path.join(root, 'lib', 'dashboard.js'))) return false;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    return pkg.name === 'godpowers';
+  } catch (error) {
+    return false;
+  }
+}
+
+function addCandidate(candidates, value) {
+  if (!value) return;
+  const resolved = path.resolve(value);
+  if (!candidates.includes(resolved)) candidates.push(resolved);
+}
+
+function candidateRoots(opts = {}) {
+  const candidates = [];
+  addCandidate(candidates, opts.runtimeRoot);
+  addCandidate(candidates, process.env.GODPOWERS_RUNTIME_ROOT);
+  addCandidate(candidates, path.resolve(__dirname, '..', '..', '..'));
+  addCandidate(candidates, process.cwd());
+
+  try {
+    const pkgPath = require.resolve('godpowers/package.json', {
+      paths: [process.cwd(), __dirname]
+    });
+    addCandidate(candidates, path.dirname(pkgPath));
+  } catch (error) {
+    // Optional peer dependency. Local checkouts resolve through the candidates above.
+  }
+
+  return candidates;
+}
+
+function resolveRuntimeRoot(opts = {}) {
+  for (const root of candidateRoots(opts)) {
+    if (isRuntimeRoot(root)) return root;
+  }
+  throw new Error('Could not find a Godpowers runtime root. Pass --runtime-root or install godpowers beside @godpowers/mcp.');
+}
+
+function requireRuntime(moduleName, opts = {}) {
+  const root = resolveRuntimeRoot(opts);
+  return require(path.join(root, 'lib', `${moduleName}.js`));
+}
+
+function resolveProject(projectRoot) {
+  return path.resolve(projectRoot || process.cwd());
+}
+
+function resolveProjectFile(projectRoot, filePath) {
+  const root = resolveProject(projectRoot);
+  if (!filePath) throw new Error('file path is required');
+  const abs = path.isAbsolute(filePath)
+    ? path.resolve(filePath)
+    : path.resolve(root, filePath);
+  const relative = path.relative(root, abs);
+  if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    throw new Error('artifact path must stay inside the project root');
+  }
+  return abs;
+}
+
+module.exports = {
+  isRuntimeRoot,
+  candidateRoots,
+  resolveRuntimeRoot,
+  requireRuntime,
+  resolveProject,
+  resolveProjectFile
+};

package/lib/server.js

@@ -0,0 +1,26 @@
+const { McpServer } = require('@modelcontextprotocol/sdk/server/mcp.js');
+const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
+
+const pkg = require('../package.json');
+const tools = require('./tools');
+
+function createServer(opts = {}) {
+  const server = new McpServer({
+    name: 'godpowers-mcp',
+    version: pkg.version
+  });
+  tools.registerTools(server, opts);
+  return server;
+}
+
+async function serveStdio(opts = {}) {
+  const server = createServer(opts);
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}
+
+module.exports = {
+  createServer,
+  serveStdio
+};

package/lib/setup.js

@@ -0,0 +1,133 @@
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const pkg = require('../package.json');
+
+const BEGIN = '# godpowers:mcp:begin';
+const END = '# godpowers:mcp:end';
+
+function resolveProject(projectRoot) {
+  return path.resolve(projectRoot || process.cwd());
+}
+
+function serverCommand(projectRoot, version = pkg.version) {
+  return {
+    command: 'npx',
+    args: [
+      '-y',
+      '-p',
+      `godpowers@${version}`,
+      '-p',
+      `@godpowers/mcp@${version}`,
+      'godpowers-mcp',
+      'serve',
+      '--project',
+      resolveProject(projectRoot)
+    ]
+  };
+}
+
+function codexConfigPath(homeDir = os.homedir()) {
+  return path.join(homeDir, '.codex', 'config.toml');
+}
+
+function codexBlock(projectRoot, version = pkg.version) {
+  const command = serverCommand(projectRoot, version);
+  return [
+    BEGIN,
+    '[mcp_servers.godpowers]',
+    `command = ${JSON.stringify(command.command)}`,
+    `args = ${JSON.stringify(command.args)}`,
+    END
+  ].join('\n');
+}
+
+function genericJson(projectRoot, version = pkg.version) {
+  const command = serverCommand(projectRoot, version);
+  return {
+    mcpServers: {
+      godpowers: command
+    }
+  };
+}
+
+function setupPlan(opts = {}) {
+  const projectRoot = resolveProject(opts.projectRoot);
+  const host = opts.host || 'codex';
+  const homeDir = opts.homeDir || os.homedir();
+  const version = opts.version || pkg.version;
+  return {
+    host,
+    projectRoot,
+    version,
+    writes: false,
+    automaticRegistration: false,
+    codexConfigPath: codexConfigPath(homeDir),
+    command: serverCommand(projectRoot, version),
+    codexToml: codexBlock(projectRoot, version),
+    genericJson: genericJson(projectRoot, version)
+  };
+}
+
+function replaceManagedBlock(current, block) {
+  const pattern = new RegExp(`${BEGIN}[\\s\\S]*?${END}`);
+  if (pattern.test(current)) {
+    return current.replace(pattern, block);
+  }
+  const prefix = current.trimEnd();
+  return `${prefix}${prefix ? '\n\n' : ''}${block}\n`;
+}
+
+function writeRegistration(plan) {
+  if (plan.host !== 'codex') {
+    throw new Error('Only codex registration writes are supported. Use setup without --write for a JSON snippet.');
+  }
+  const filePath = plan.codexConfigPath;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const current = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+  const next = replaceManagedBlock(current, plan.codexToml);
+  fs.writeFileSync(filePath, next);
+  return {
+    ...plan,
+    writes: true,
+    written: filePath
+  };
+}
+
+function render(plan) {
+  const lines = [
+    'Godpowers MCP setup',
+    '',
+    `Host: ${plan.host}`,
+    `Project: ${plan.projectRoot}`,
+    `Package: @godpowers/mcp@${plan.version}`,
+    '',
+    'Read-only server command:',
+    `  ${plan.command.command} ${plan.command.args.join(' ')}`,
+    '',
+    'Codex config block:',
+    plan.codexToml,
+    '',
+    'Generic JSON registration:',
+    JSON.stringify(plan.genericJson, null, 2),
+    '',
+    plan.writes
+      ? `Wrote explicit registration: ${plan.written}`
+      : 'No files written. Re-run setup with --write to opt in.'
+  ];
+  return lines.join('\n');
+}
+
+module.exports = {
+  BEGIN,
+  END,
+  serverCommand,
+  codexConfigPath,
+  codexBlock,
+  genericJson,
+  setupPlan,
+  replaceManagedBlock,
+  writeRegistration,
+  render
+};

package/lib/tools.js

@@ -0,0 +1,202 @@
+const path = require('path');
+const z = require('zod/v4');
+
+const runtime = require('./runtime');
+
+const TOOL_NAMES = [
+  'status',
+  'next',
+  'gate_check',
+  'lint_artifact',
+  'trace_requirement'
+];
+
+function toolResult(value) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(value, null, 2)
+      }
+    ],
+    structuredContent: value
+  };
+}
+
+function toolError(error) {
+  return {
+    isError: true,
+    content: [
+      {
+        type: 'text',
+        text: error && error.message ? error.message : String(error)
+      }
+    ]
+  };
+}
+
+async function withErrors(fn) {
+  try {
+    return toolResult(await fn());
+  } catch (error) {
+    return toolError(error);
+  }
+}
+
+function projectRootFor(input, opts) {
+  return runtime.resolveProject(input.project || opts.projectRoot || process.cwd());
+}
+
+function statusTool(input = {}, opts = {}) {
+  const projectRoot = projectRootFor(input, opts);
+  const dashboard = runtime.requireRuntime('dashboard', opts);
+  const result = dashboard.compute(projectRoot, { git: input.git !== false });
+  return {
+    project: projectRoot,
+    dashboard: result,
+    rendered: dashboard.render(result, { brief: Boolean(input.brief) })
+  };
+}
+
+function nextTool(input = {}, opts = {}) {
+  const projectRoot = projectRootFor(input, opts);
+  const dashboard = runtime.requireRuntime('dashboard', opts);
+  const result = dashboard.compute(projectRoot, { git: input.git !== false });
+  return {
+    project: projectRoot,
+    next: result.next,
+    actionBrief: result.actionBrief,
+    dashboard: result
+  };
+}
+
+function gateTool(input = {}, opts = {}) {
+  const projectRoot = projectRootFor(input, opts);
+  const gate = runtime.requireRuntime('gate', opts);
+  return gate.check({
+    tier: input.tier,
+    projectRoot
+  });
+}
+
+function lintTool(input = {}, opts = {}) {
+  const projectRoot = projectRootFor(input, opts);
+  const linter = runtime.requireRuntime('artifact-linter', opts);
+  const artifactPath = runtime.resolveProjectFile(projectRoot, input.path);
+  const result = linter.lintFile(artifactPath, { projectRoot });
+  return {
+    project: projectRoot,
+    artifact: path.relative(projectRoot, artifactPath).split(path.sep).join('/'),
+    lint: {
+      type: result.type,
+      findings: result.findings,
+      summary: result.summary
+    }
+  };
+}
+
+function traceRequirementTool(input = {}, opts = {}) {
+  const projectRoot = projectRootFor(input, opts);
+  const requirements = runtime.requireRuntime('requirements', opts);
+  const derived = requirements.derive(projectRoot);
+  const id = String(input.id || '').trim();
+  const requirement = derived.requirements.find((item) => item.id === id) || null;
+  const increment = requirement && requirement.increment
+    ? derived.increments.find((item) => item.id === requirement.increment) || null
+    : null;
+  return {
+    project: projectRoot,
+    id,
+    found: Boolean(requirement),
+    requirement,
+    increment,
+    summary: derived.summary,
+    ledger: requirements.LEDGER_PATH
+  };
+}
+
+function registerTools(server, opts = {}) {
+  server.registerTool('status', {
+    title: 'Godpowers status',
+    description: 'Read Godpowers dashboard state from disk.',
+    inputSchema: {
+      project: z.string().optional().describe('Project root. Defaults to the server project.'),
+      brief: z.boolean().optional().describe('Include compact rendered dashboard text.'),
+      git: z.boolean().optional().describe('Set false to skip git status checks.')
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true
+    }
+  }, async (input) => withErrors(() => statusTool(input, opts)));
+
+  server.registerTool('next', {
+    title: 'Godpowers next',
+    description: 'Read the recommended next Godpowers command from disk state.',
+    inputSchema: {
+      project: z.string().optional().describe('Project root. Defaults to the server project.'),
+      git: z.boolean().optional().describe('Set false to skip git status checks.')
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true
+    }
+  }, async (input) => withErrors(() => nextTool(input, opts)));
+
+  server.registerTool('gate_check', {
+    title: 'Godpowers gate check',
+    description: 'Run a read-only executable tier gate check.',
+    inputSchema: {
+      project: z.string().optional().describe('Project root. Defaults to the server project.'),
+      tier: z.enum(['prd', 'design', 'arch', 'roadmap', 'stack', 'repo', 'build', 'harden'])
+        .describe('Gate tier to check.')
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true
+    }
+  }, async (input) => withErrors(() => gateTool(input, opts)));
+
+  server.registerTool('lint_artifact', {
+    title: 'Godpowers artifact lint',
+    description: 'Lint one artifact path inside the project root.',
+    inputSchema: {
+      project: z.string().optional().describe('Project root. Defaults to the server project.'),
+      path: z.string().describe('Artifact path relative to the project root.')
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true
+    }
+  }, async (input) => withErrors(() => lintTool(input, opts)));
+
+  server.registerTool('trace_requirement', {
+    title: 'Godpowers requirement trace',
+    description: 'Trace one PRD requirement id to linkage and roadmap evidence.',
+    inputSchema: {
+      project: z.string().optional().describe('Project root. Defaults to the server project.'),
+      id: z.string().describe('Requirement id such as P-MUST-01.')
+    },
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      idempotentHint: true
+    }
+  }, async (input) => withErrors(() => traceRequirementTool(input, opts)));
+}
+
+module.exports = {
+  TOOL_NAMES,
+  registerTools,
+  statusTool,
+  nextTool,
+  gateTool,
+  lintTool,
+  traceRequirementTool,
+  toolResult,
+  toolError
+};

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@godpowers/mcp",
+  "version": "2.6.0",
+  "description": "Read-only MCP server for Godpowers runtime status, routing, gates, artifact linting, and requirement tracing.",
+  "bin": {
+    "godpowers-mcp": "./bin/godpowers-mcp.js"
+  },
+  "main": "./lib/server.js",
+  "type": "commonjs",
+  "scripts": {
+    "test": "node scripts/test-protocol.js",
+    "pack:check": "node scripts/check-package-contents.js"
+  },
+  "keywords": [
+    "godpowers",
+    "mcp",
+    "model-context-protocol",
+    "ai-coding"
+  ],
+  "author": "Godpowers",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aihxp/godpowers.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://github.com/aihxp/godpowers/tree/main/packages/mcp#readme",
+  "bugs": {
+    "url": "https://github.com/aihxp/godpowers/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.1.13"
+  },
+  "peerDependencies": {
+    "godpowers": ">=2.6.0"
+  },
+  "peerDependenciesMeta": {
+    "godpowers": {
+      "optional": true
+    }
+  }
+}