Skip to main content
Glama
README.md
# 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.

## 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](docs/shape.md) is the full shape of the tool. [library/procedure.txt](library/procedure.txt) is what the agent follows, [library/method.txt](library/method.txt) is the working method underneath it, and [library/design/process.txt](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](https://docs.astral.sh/uv/) and Python 3.10+. The server works in the project's folder, because its final check reads the project's files.

```bash
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:

```json
{
  "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:

```json
{
  "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

```bash
uv run pytest
```

## License

MIT

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