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.

Related MCP server: visualspec

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.

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.

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.