@space-kraken/nebula-forge-mcp

MCP (Model Context Protocol) server that exposes forge workspace operations as tools, so an agentic executor (Claude Code, Cursor, any MCP client) can scaffold, couple and validate a forge workspace with the same guarantees as the CLI.

Every tool takes an explicit workspaceRoot, always runs the non-interactive path (nothing can hang on a prompt), returns structured JSON (what was created/edited, what validations ran) and surfaces forge's errors as message + actionable hint. Mutating tools keep the CLI's transactionality: a failed call leaves the workspace exactly as it was.

Install

The server runs over stdio; register it with your MCP client:

# Claude Code
claude mcp add forge -- npx -y @space-kraken/nebula-forge-mcp

// Claude Desktop, Cursor, or any mcpServers config
{
  "mcpServers": {
    "forge": { "command": "npx", "args": ["-y", "@space-kraken/nebula-forge-mcp"] }
  }
}

Requires Node >= 20. The server needs no credentials: every tool works on the workspace files only (synth/deploy stay in the CLI).

Tools

| Tool | What it does | |---|---| | list_model | The versioned model export (same as forge model --json) | | validate_workspace | Full load + validation verdict, with warnings | | generate_component | Create a component with bind/attach/subscribe couplings | | generate_endpoint | Route + controller + use case + test, in sync | | attach / detach | Manage couplings on existing components | | remove_component | Refuses while referenced; force cascades detaches | | regenerate_docs | Rewrite docs/architecture.md and AGENTS.md |

Point tools at a workspace by passing its absolute path as workspaceRoot (the directory holding forge.json). Creating a workspace itself is forge new — it installs dependencies, which an MCP tool should not do silently.

Versioning

The server is a thin shell over the CLI's programmatic API and pins @space-kraken/nebula-forge to the exact same version: forge-mcp x.y.z always drives forge x.y.z. Upgrade both together.

Development (from a checkout)

pnpm install && pnpm run build
claude mcp add forge-dev -- node <checkout>/packages/mcp/bin/run.js

Tool handlers live in src/tools.ts as pure functions over workspaceRoot (tests exercise them directly); src/server.ts only wires them into the stdio transport.