example-new

Scaffold a new mcpkit example matching the conventions in examples/CONVENTIONS.md.

Args

• $1 — example name (required, kebab-case, e.g. progress-reports). Used as both the directory name and the demokit Dir(...) value.
• --ui — optional flag. Scaffold an MCP-Apps-style example (HTML asset + iframe bridge + no walkthrough.go) instead of the default scripted-walkthrough shape.

If $1 is missing, ask the user for one before doing anything else.

Steps

1. Read examples/CONVENTIONS.md before generating anything. It is the source of truth — if it has changed since this skill was written, follow the doc, not this file. If anything below contradicts CONVENTIONS.md, CONVENTIONS.md wins.

2. Confirm the destination:

   • Path: examples/<name>/ (or examples/events/<name>/ if the user says it's an events example — ask if ambiguous).
   • Refuse if the directory already exists. Suggest /example-audit <name> instead.

3. Ask the user three questions (one shot, not back-and-forth):

   • One-paragraph description of what the example demonstrates (goes into demokit.Description(...) and the README intro).
   • List of MCP tools the example will register (names + one-line each). If UI, also which ones ship apps.
   • Whether the example needs static fixtures (testdata/) or live event injection (/inject POST endpoint) — see CONVENTIONS.md §3 "Fixtures." Skip for UI examples.

4. Generate files matching the layout in CONVENTIONS.md §1:

   Non-UI (default):

   • main.go — dual-mode dispatcher + serve() using common.MCPServerOptions(*addr, "[mcp] ") for the listen + canonical logger middleware (single-line replacement for the older 12-line block; see CONVENTIONS.md §2), srv.ListenAndServe(server.WithStreamableHTTP(true)), demokit.FilterArgs(os.Args[1:], demokit.BoolFlag("--serve"), demokit.ValueFlag("--url")) (add more ValueFlag(...) for example-specific flags). Append example-specific options (server.WithListTTL, server.WithExtension, etc.) onto the slice returned by MCPServerOptions. If the example needs side endpoints (e.g. /inject), wire them via server.WithMux(...) — never hand-roll an http.Server{}. Add the examples/common dependency to go.mod (require github.com/panyam/mcpkit/examples/common ... + replace ... => ../common).
   • walkthrough.go — runDemo() skeleton from CONVENTIONS.md §3. Pre-fill: title, Dir("<name>"), the description from step 3, two actors (Host / Server), a Setup section pointing to just serve, one placeholder Step() per tool with // TODO markers in the Run() body for the user to fill in, the closing "Where to look in the code" Section(), and common.SetupRenderer(demo) + demo.Execute(). Use common.ServerURL() (no args) as the default endpoint — honors --url, $MCPKIT_SERVER_URL, then falls back to :8080. Error-path steps use common.PrintRPCError(err, wantReason); pass wantReason="" unless asserting a specific spec-defined reason.
   • README.md — Quick Start (just serve / just demo), What it demonstrates (mirrors the step list), Architecture placeholder (Mermaid block stub if the topology is non-trivial — leave blank otherwise), Where to look in the code (mirrors walkthrough.go).
   • justfile — exactly the four baseline recipes (demo, serve, readme, build) with doc comments above each recipe and default: demo. No example-specific extras at scaffold time — the user adds those after.
   • Makefile — the make twin of the justfile during the transition: the same four baseline targets (demo, serve, readme, build) with ## help-text comments, .PHONY line, .DEFAULT_GOAL := demo.
   • go.mod — module name github.com/panyam/mcpkit/examples/<name> (or .../examples/events/<name>), Go 1.23+, dependencies on github.com/panyam/mcpkit/{core,server,client} and github.com/panyam/demokit at the version currently used by examples/file-inputs/go.mod. Add a local replace github.com/panyam/mcpkit => ../.. directive (relative path from the new example).
   • testdata/ — only if the user said static fixtures in step 3. Empty directory with a .gitkeep is fine; user adds the actual files.