# show-me-mcp

Source repository: [alchemistklk/show-me-mcp](https://github.com/alchemistklk/show-me-mcp).

Help agents explain complex ideas clearly and automatically fix layout problems in the resulting artifacts.

The agent chooses the display form and organizes the content. The MCP handles layout, detects and repairs occlusion, overlap, text overflow, and connector conflicts, and verifies the final artifact. The intended workflow does not require agents or users to repeatedly adjust diagrams by hand.

## Project documentation

- [Project specification](docs/project-spec.md): goals, responsibilities, five display forms, quality assurance, and delivery scope.
- [Expression elements](docs/expression-elements.md): element meanings, use cases, and composition examples.
- [Extensibility](docs/extensibility.md): separation between user expression libraries, component libraries, and the core engine.
- [Module design](docs/module-design.md): the adopted design, seams, and incremental validation strategy.
- [First quality slice](docs/quality-slice.md): implemented HTML layout repair, expression libraries, and MCP tools.
- [Four built-in forms](docs/native-forms.md): input, repair, and delivery contracts for Mermaid, pseudocode, text trees, and diff.
- [Acceptance criteria](docs/acceptance.md): quality checks, failure examples, existing evidence, and upcoming milestones.
- [Domain glossary](CONTEXT.md): shared project terminology.
- [Existing prototype](docs/prototype-status.md): operation and limitations.
- [Primitive contract v0.1](docs/primitive-contract-v0.1.md): compatibility reference for the existing interface.

## Goals and current status

| Goal | Current implementation |
| --- | --- |
| Five forms: pseudocode, text trees, Mermaid, diff, and HTML | All five are available through the new interface. HTML supports declarative libraries; the other four are built-in capabilities, each with a defined support scope. |
| Automatic layout repair inside the MCP | HTML label avoidance, Mermaid reflow and reinspection, text wrapping by display width, and diff display formatting are implemented. Arbitrarily complex diagrams are not guaranteed to be repairable. |
| Final display quality verification | HTML and Mermaid artifacts are verified in Chromium; text forms validate width and content preservation. Evidence records the verification scope and content hashes. |
| Public repository and Pi plugin distribution | The repository is public on GitHub. No standalone Pi plugin or package has been published. |

PNG is an optional artifact format, not a core display category. The existing `terminal | image | both` options and PNG fallback belong to the legacy prototype, not the target design.

## Run locally

Node.js and npm are required. Text trees, pseudocode, and diff do not need a browser. HTML, Mermaid, and the full test suite require a local Chrome or Chromium executable, which can be specified with `SHOW_ME_CHROMIUM_BIN`. The legacy image path also requires `rsvg-convert`. The project does not automatically download a browser or use your personal browser profile.

```bash
npm ci
npm test
npm run render:fixture
npm run render:composition
npm run render:quality-demo
npm run render:native-demo
node bin/mcp-server.mjs
```

If your machine uses the `with-env` environment wrapper, prefix the commands with it. Examples write their artifacts to `artifacts/`. Local Pi configuration, tool caches, dependencies, and generated artifacts are excluded from Git.

The MCP tools `describe_display` and `render_display` map to `describe` and `render`, supporting `html | mermaid | pseudocode | tree | diff`. Query a form's schema and examples before using an unfamiliar input format. Only HTML accepts expression-library references. The legacy `render_visual` tool remains available for compatibility; see the [prototype guide](docs/prototype-status.md) for its inputs.

The license and Pi plugin distribution approach still need to be decided before package publication. The package retains `private: true`; a public GitHub repository does not mean an npm package or Pi plugin has been released.