Kizen Plugin Reference MCP Server#

Serves the generated plugin reports in ../ (the <api_name>.md files) to agents over the Model Context Protocol.

Why this exists#

The reports are large by design — kitchen_sink.md alone is ~5,150 lines. Too much to load wholesale into a context window, but exactly what you want to consult selectively while building. This server gives any MCP client targeted retrieval over them, and lets non-Claude tools (which can't read files off disk) use the same reports as a shared source of truth.

If your agent can read the repo directly, you don't need this server — just read ../kitchen_sink.md and grep it. The server earns its keep when the client has no filesystem access, or when you want find_method ranking across every plugin at once.

Tools#

Tool	Purpose
`list_plugins`	The menu: name, version, one-line description for every report. Start here.
`get_plugin(api_name)`	Full markdown for one plugin: `kizen.json`, file tree, and complete source.
`search_plugins(query, context?, max_results?)`	Case-insensitive grep across all reports, with line context — find which plugins use an API or pattern.
`find_method(method, mode?, ignore_case?, max_examples?)`	Symbol-aware: find which plugins call a method. Returns a plugin-ranked summary with example call sites. A bare name (`showToast`) also matches dotted calls (`this.showToast(`). `mode`: `call` (default, requires `(`), `any` (bare identifier), `regex`.

Each plugin is also a resource: kizen-plugin://<api_name>.

Setup#

Shell

cd docs/examples/mcp-server
npm install

There is no server to start. This is a stdio MCP server: your client spawns node server.mjs as a child process and talks JSON-RPC over its stdin/stdout. Register the command (below) and the client handles the lifecycle — no port, no daemon, nothing running in the background. Launching it yourself just leaves a process waiting forever for input that never arrives.

Verify it end-to-end (drives the server over stdio as a real MCP client):

Shell

npm run smoke-test

In both configs below, replace <repo-root> with the absolute path to your clone of this repository — the one containing docs/, which holds this examples/ folder. It must be absolute: the client spawns the server from an arbitrary working directory.

Claude Code#

Shell

claude mcp add kizen-plugin-reference --scope user -- \
  node <repo-root>/docs/examples/mcp-server/server.mjs

--scope user makes it available in every project for that user. Each teammate runs this on their own machine.

Other MCP clients (generic stdio config)#

JSON

{
  "mcpServers": {
    "kizen-plugin-reference": {
      "command": "node",
      "args": ["<repo-root>/docs/examples/mcp-server/server.mjs"]
    }
  }
}

Configuration#

Env var	Default	Meaning
`KIZEN_EXAMPLES_DIR`	parent dir of `server.mjs` — i.e. `examples/`	Directory of `<api_name>.md` reports to serve.

Point KIZEN_EXAMPLES_DIR at ~/.kizenappbuilder/examples/ to serve every report you have generated locally instead of only the two committed here.

Every .md in that directory is treated as a plugin report, with one exception: the names in NON_REPORT_FILES (server.mjs) are skipped, so the examples directory's own README.md isn't served as a plugin called "README". Add any further hand-written markdown to that set.

Keeping reports fresh#

The server reads whatever .md files are present, so refreshing the data is just regenerating those files — reconnect the client afterward and that's it.

Reports are generated by the @kizenapps/cli CLI. From a plugin repo:

Shell

cd /path/to/plugin-kitchen-sink
npx --yes @kizenapps/cli report -o <repo-root>/docs/examples/kitchen_sink.html

npx --yes @kizenapps/cli report always writes two files: the .html you name, and a .md sibling with the same basename. Only the .md is committed here — see ../README.md for why, and for the regeneration one-liner that covers both committed reports.