show-me-mcp

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

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 being prepared for npm publication. To try this checkout:

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

After publication, install with pi install npm:show-me-mcp@alpha. 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. npm publication is pending; local package validation does not establish a registry release.