Skip to main content
Glama

CoherenceMCP

CoherenceMCP is an MCP server that keeps an agent from building the average version of what you asked for. When an agent isn't told a value, it fills in the most probable answer from its training, which is generic. CoherenceMCP gives the agent a fixed procedure that settles every value of the project from a real source, keeps the result in a record the agent can't drift from, has you confirm the foundation and then approve the whole shape, and checks at the end that the built product's visual values all trace back to the record.

Drop it into an existing project that needs to be made coherent, or start from an idea: "build me an app that does…", "a game that plays like…", "a website for my business that…".

How it works

The server runs one state machine for every project:

  1. derive: the agent answers the open points of the project, starting with the root: what it's for, for whom, and what it refuses to be. You see the root and approve or deny it before anything is derived from it. Every point after that gets the same seven questions: what the point serves, what happens to a person there, what the average version would do, what this project does instead and what that rules out, who has already done it well (reuse before custom), what would show it's wrong, and what it leaves open. Every answer needs a permitted source: your words, the conversation, research, existing work, settled points, or an observation.

  2. walk: the agent walks the experience and the construction to find anything still undetermined. Gaps become new open points.

  3. review: the server writes the shape to .coherence/shape.md. You approve it or deny it with a reason; a denial reopens only what it touches.

  4. compile: after approval, the record becomes build orders, each carrying exactly the context it needs.

  5. build: orders are carried out one at a time under a closed world. The product may only use what the manifest pins: exact references to existing work, tokens, content, and rules.

  6. verify: the server scans the project for values that don't trace back to the record and checks that every settled point was built.

The server refuses calls out of order or in the wrong form and says why. next always returns the current step.

Related MCP server: Agent Orchestrator MCP Server

What the server checks, and what it doesn't

The server checks form and traces. It does not judge whether an answer is true or good.

  • It checks that a quote of your words appears in the request the agent recorded, and that a derived answer names settled points. It does not open research links or confirm that the works an answer lists were examined.

  • The scan reads the files the orders touched and the token files. It finds colors, lengths, durations, font families, and media paths that match no manifest value. A value in a token file that the manifest doesn't hold is refused like any other.

  • The scan does not read copy, logic, or structure, so it is strongest on interface work, where most of a project's concrete values are the kinds it can see.

That is why your two approvals matter: the root before anything is built on it, and the whole shape before the build.

docs/shape.md is the full shape of the tool. library/procedure.txt is what the agent follows, library/method.txt is the working method underneath it, and library/design/process.txt supplies design guidance for points about content, layout, type, color, imagery, and behavior.

Tools

Tool

Use

begin

Your request word for word, idea or existing, your questions, and any conversation context

next

The current step with the context it needs

settle

Answer an open point

walk

Report the experience and construction walks, and any gaps

decide

Record your approval or denial, of the root and later of the shape

compile

Turn the approved record into build orders

complete

Finish a build order

gap

Report something the record doesn't settle, instead of filling it

revise

Reopen a point that turned out wrong; what depends on it reopens too

verify

Check the built product against the record

read

Read the procedure, the method, or the design guidance

Every tool except read also takes project, the absolute path of the project's folder. It is required when the server serves any project (Claude Desktop) and optional otherwise.

The record lives in .coherence/ in the project. The server also writes every step it hands out and every answer it accepts to .coherence/steps.jsonl.

Run it

Requires uv and Python 3.10+. The server works in the project's folder, because its final check reads the project's files.

uv sync
uv run coherence-mcp --project /path/to/your/project

That starts the server over stdio. The folder it works in is, in order:

  • --project, or COHERENCE_PROJECT: one fixed folder. A call that names a different project is refused.

  • --any-project: any folder, named by the project argument of every call. A call without it is refused, so the server never writes a record somewhere nobody chose.

  • Otherwise the current folder, unless a call names another.

Set COHERENCE_LIBRARY_DIR to use a different copy of the library. Set COHERENCE_PACKET_TOKENS to bound the packets for a small local model: the point, its question, the request, and the chain to the root stay whole, and the packet names whatever else it had to leave out.

Connect to Claude Code

Add this to the project's .mcp.json, with the path to this repository. Claude Code starts the server in the project, so the project is the current folder:

{
  "mcpServers": {
    "coherence": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/coherence-mcp", "coherence-mcp"]
    }
  }
}

Connect to Claude Desktop

Claude Desktop starts its servers outside any project, so run the server with --any-project. Then Claude names the folder on every call, and one server can work on several projects from different chats. Open Settings, then Developer, then Edit Config, and add this to claude_desktop_config.json, with the path to this repository:

{
  "mcpServers": {
    "coherence": {
      "command": "uv",
      "args": ["run", "--quiet", "--project", "/path/to/coherence-mcp", "coherence-mcp", "--any-project"]
    }
  }
}

On Windows, if Claude Desktop can't find uv, use its full path (where uv). Or skip uv at launch and point command at the installed script, C:\\path\\to\\coherence-mcp\\.venv\\Scripts\\coherence-mcp.exe, with args of ["--any-project"]. Restart Claude Desktop afterwards.

In a chat, say which folder the project lives in, or which folder to make it in, for example "Use coherence to build a site for my bakery in D:\bakery". Claude passes that folder on every call. The build steps write files there, so Claude needs file access to that folder: use the Code tab, or give the chat a filesystem extension for the folder. Claude Code sessions in the Code tab load the project's .mcp.json as in Claude Code.

Test

uv run pytest

License

MIT

Available Tools

11 tools
add_entriesA

Add matrix entries to a session, after the current entry ('next') or at the end.

Use when the work needs another entry, such as a Fix or Redesign the user authorized after a Review.

Inputs: entries (required), session_id (required), position.

complete_stepA

Finish the current SOP step (not a verify step) and receive the next one.

handoff: one to three sentences naming the actual result and how the next step uses it. responsible_step: required on a trace step — the procedure step (0–9) where the cause lies.

Inputs: session_id (required), handoff, responsible_step.

current_stepA

Re-issue the current step with its SOP, plan item, procedure text, and earlier results. Use after an interruption or condensed context.

Inputs: session_id (required).

end_sessionC

End a session. summary: what was delivered and any remaining limitations.

Inputs: session_id (required), summary.

escalateB

End the current entry because its decision belongs elsewhere, and start the right entry in its place.

Use when the unit should not exist or should move (escalate to its parent scope), or when a Fix needs the structure replaced (escalate to redesign). reason: what the step showed.

Inputs: reason (required), session_id (required), to_scope, to_situation.

get_matrixA

Return the scope and situation matrix with its selector questions. Call this before start_session.

Inputs: no named parameters.

get_process_stepB

Return one procedure step from process.txt in full (0–10), for steps an SOP step names only by its Keep rule.

Inputs: step (required).

get_statusA

Show a session's goal, entries, plan, position, and recorded results. Without a session_id, list recent sessions.

Inputs: session_id.

report_verificationB

Finish a verify step.

outcome: 'done', or the number (0–9) of the procedure step responsible for the earliest discrepancy. findings: each discrepancy with its evidence and responsible step, or what was checked when done.

Inputs: outcome (required), session_id (required), findings.

start_sessionA

Start a design session and receive its session_id, the working method, and the first entry's SOP.

request: the user's words. end_goal: the observable condition that holds when the work is complete. entries: the matrix entries in the order they will run, worked backward from the end goal. task_conditions: device, platform, audience, existing identity, available assets, stage of completion, and whether identity is open to change.

Inputs: entries (required), request (required), end_goal (required), task_conditions.

submit_planA

Write or revise the plan for the current entry: one item per SOP step, in order. The first plan starts the work.

Inputs: plan (required), session_id (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 11 tools

    Disambiguation4/5

    The tools map to mostly distinct workflow phases: matrix discovery, session start, planning, step execution, verification, status, escalation, and ending. Mild overlap exists between current_step and get_process_step (both return procedure-step content) and between complete_step and report_verification (both advance work), but the descriptions clarify when each should be used.

    Naming Consistency4/5

    Most names follow a clear snake_case verb_noun pattern such as submit_plan, get_matrix, start_session, complete_step, and end_session. Deviations like current_step (noun phrase) and escalate (bare verb) are minor and still readable, so the set is mostly consistent.

    Tool Count5/5

    Eleven tools is well-scoped for a session/workflow management server. Each tool appears to earn its place across the session lifecycle, from matrix selection and session start through planning, step execution, verification, escalation, status, and end.

    Completeness4/5

    The surface covers the core lifecycle: get matrix, start session, submit plan, advance steps, verify, inspect status, escalate, add entries, fetch procedure steps, and end session. Minor gaps remain around editing or removing entries and richer session listing, but agents can likely work around them.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables dynamic creation and orchestration of hierarchical AI agent teams with role-based personas and domain knowledge injection. Supports multi-agent collaboration, session management, and complex task execution through structured team workflows.
      15
      -