# pi-show-me

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. The native Pi extension is distributed as `pi-show-me` on npm. |

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.

## Install in Pi

The native Pi entry registers `describe_display` and `render_display` directly, without an MCP adapter. The alpha package is published on npm. Install it with `pi install npm:pi-show-me@alpha`. To try this checkout:

```bash
pi install /absolute/path/to/show-me-mcp
```

Disable duplicate tools from an existing MCP adapter before enabling the native extension. Reload Pi after installation.

Artifacts are saved under `.pi/artifacts/show-me` in the current project. Override this with `SHOW_ME_ARTIFACT_DIR`. Text layout uses the current terminal width, or `SHOW_ME_TERMINAL_COLUMNS` when set; supported widths are 24–240 columns. Non-interactive sessions default to 120 columns. HTML and Mermaid return file paths; text forms also return a fenced preview. Diff keeps the applicable patch separate from its wrapped preview.

The npm package also exposes `show-me-mcp` as a stdio MCP command. Pi exposes only the two current tools; the MCP command retains legacy `render_visual` support.

## 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.

Licensed under [Apache-2.0](LICENSE). The first npm release is `0.1.0-alpha.1` (tag: `alpha`).

## Migrating from show-me-mcp

The npm package has been renamed to `pi-show-me`. The repository and MCP command retain the name `show-me-mcp`. Replace the old Pi package and reload Pi:

```bash
pi remove npm:show-me-mcp
pi install npm:pi-show-me@alpha
```