pi-show-me

Source repository: 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: goals, responsibilities, five display forms, quality assurance, and delivery scope.
• Expression elements: element meanings, use cases, and composition examples.
• Extensibility: separation between user expression libraries, component libraries, and the core engine.
• Module design: the adopted design, seams, and incremental validation strategy.
• First quality slice: implemented HTML layout repair, expression libraries, and MCP tools.
• Four built-in forms: input, repair, and delivery contracts for Mermaid, pseudocode, text trees, and diff.
• Acceptance criteria: quality checks, failure examples, existing evidence, and upcoming milestones.
• Domain glossary: shared project terminology.
• Existing prototype: operation and limitations.
• Primitive contract v0.1: 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:

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.

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 for its inputs.

Licensed under Apache-2.0. 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:

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