MCP Server

// how it works

Agents that build from the map — and self-correct

The server runs over stdio and exposes seven tools across three roles: context (read-only), feedback, and safe mutation. A typical agent loop starts by reading the real graph, consults the rules before wiring anything, makes changes through rule-checked engines, then runs a drift check and self-corrects on any error-level finding. Context is resolved fresh on every tool call, so the agent always sees the current revision.

• ›get_architecture — pull the current To-Be graph: nodes and edges described by name, plus the graph revision.
• ›get_rules — the Rules Matrix: a whitelist of legal source-edge-target combinations plus a blacklist of anti-patterns. Default deny.
• ›create_node_safely / sync_properties — mutations that pass the Rules Engine before anything commits.
• ›check_drift — scan the code at AST level, compare against the cloud architecture, return findings and a verdict.
• ›get_unimplemented / fill_surgical_region — the surgical work queue and an autonomous, contract-checked fill.

// the safety angle

Writes only commit when the edges pass

create_node_safely adds a node and optional edges. Every edge is evaluated against the Rules Matrix locally with evaluateEdge — so the agent gets one clear reason in a single turn — and then again by the server's Rules Engine inside one atomic transaction keyed on baseRevision. On any violation, nothing is written and the violations come back as { code, message, suggestion }. sync_properties copies property declarations between classes using AST surgery: only property declarations are added, methods are never touched, added fields carry a @solarch:bound marker, and existing properties are never overwritten.

// agent attempts an illegal wiringcreate_node_safely({  type: "Controller",  properties: { ControllerName: "OrdersController" },  edges: [{ kind: "QUERIES", direction: "outgoing", nodeId: "<table-id>" }]})// nothing written — returned verbatim to the agent:{  "created": false,  "reason": "Pre-check failed — nothing was written.",  "violations": [{    "code": "ERR_RULE_VIOLATION",    "message": "Controller -[QUERIES]-> Table: not allowed",    "suggestion": "Route through a Service / Repository"  }]}

// with your AI agent

Agents verify their work before they finish

check_drift is the feedback half of a ReAct-style loop. After the agent generates or edits code, it scans the local codebase at the TypeScript AST level, compares it against the cloud architecture, and returns structured findings — rule violations, components missing in code, unapproved additions, and property drifts — plus a verdict. When clean is false, the verdict tells the agent to fix the error-level findings and re-check before finishing. Errors never throw: every tool returns a { code, message, suggestion } payload the agent can act on, and a missing login or link returns ERR_NOT_CONFIGURED naming the exact CLI command to run.

• ›clean: true → "No architecture violations. Safe to proceed."
• ›clean: false → the verdict lists how many error-level findings exist and what to do next.
• ›Uses the same diff engine and map.json match cache as solarch diff — the agent's drift never diverges from the CLI's.

// surgical fill

A work queue of unimplemented bodies, and an autonomous fill

After codegen, method bodies the Constructor can't write deterministically are left as NOT_IMPLEMENTED skeletons behind @solarch:surgical markers. get_unimplemented scans the repo and returns each remaining region with its business description, the exceptions it must throw, the dependencies it may use, and the exact file and line — fully local, no login. fill_surgical_region goes further: it prompts an LLM with each region's surgical contract, writes the body, re-audits the contract and retries on violation, then runs the project's typecheck and tests — only contract-passing fills are saved, failures keep their stub.

# the recommended flowget_unimplemented   # -> work queue: descriptions, throws, deps, file:linefill_surgical_region   # write the body; keep the @solarch:surgical markercheck_drift         # verify the architecture still holds

// install

Link once with the CLI, then register the server

Identity and the project binding are shared with the Solarch CLI, so you authenticate once. solarch login writes credentials to ~/.solarch; solarch link writes solarch.json in your repo root. Then register solarch-mcp in your MCP client — Cursor mcp.json, Claude Desktop config, and similar. The server talks over stdio and logs only to stderr; if --root is omitted it uses the process working directory. Because context resolves on every call, you can run login/link while the server is up — no restart needed.

$ solarch login    # Settings -> API Keys -> paste key -> ~/.solarch$ solarch link     # in the repo root, writes solarch.json# then start your MCP client; the server logs to stderr:[solarch-mcp] ready on stdio - root: /path/to/your/nestjs-repo

// one engine

The same engines as the CLI — single source of truth

@solarch/mcp depends on @solarch/cli and @solarch/ast-core, and its tool bodies call the exact same engines the CLI uses: the SolarchApi client, the diffGraphs drift engine, evaluateEdge rule evaluation, and the ~/.solarch + solarch.json configuration come straight from @solarch/cli/lib. The tool bodies are pure functions that know nothing about the transport, which keeps them testable against a mock API. There is no separate format invented for agents — node and edge types map directly to the cloud schema.

• ›Node and edge kinds come from @solarch/ast-core — the same taxonomy the canvas and backend speak.
• ›Mutations go through graph/apply with baseRevision — atomic and idempotent, like a CLI push.
• ›Drift uses the shared map.json match cache, so agent and human see identical findings.