mcp: Instructions file for Codex

@blueprint-chart/mcp — Coding Guidelines

General

• TypeScript everywhere, strict mode.
• Small, iterative, semantic commits — no co-author or body. Conventional types only: feat, fix, refactor, test, chore, docs, style.
• Makefile targets are the canonical way to run operations (make install, make dev, make test, make lint, make build).
• Code quality and readability are central — keep tools, resources, and render modules small and single-purpose.
• This package follows the same conventions as blueprint-chart. Where this file is silent, defer to that one.

Project Structure

Single-package npm project (@blueprint-chart/mcp) — no workspace, no Vue, no SCSS.

src/
  server.ts                  # Transport-agnostic MCP Server; wires tools, resources, prompts
  cli.ts                     # CLI entry: stdio default, --http for hosted; reads env vars
  parse.ts                   # parseDsl: wraps @blueprint-chart/lib's Peggy parser with ToolResult
  errors.ts                  # ErrorCode enum + ToolResult<T> shape
  tools/                     # Tool handlers: validate, inspect, recommend, render
  resources/                 # Resource handlers: docs-backed + samples-backed
  prompts/                   # Prompt templates (author_chart)
  render/                    # Headless render pipeline (jsdom + textShim + resvg)
  transports/                # stdio + StreamableHTTP entries; share `createServer()`
  lib/                       # Internal helpers (e.g. zod→JSON Schema stub)
bin/
  blueprint-chart-mcp.js     # CLI launcher
  loader.mjs                 # ESM resolver hook (resolves extensionless imports)
test/
  integration/               # In-memory MCP transport tests, transport-parity
  golden/                    # Render snapshot suite over @blueprint-chart/lib samples
docs/superpowers/            # Local-only spec/plan artifacts (gitignored)

Dependencies

Pinned npm packages (no workspace deps):