Agents · kition-kits-mcp
Copy for AI
Real tools for your agents
Every kit is an MCP server with basic KHP support. Register one stdio server with your client and your agent inspects files, runs the kit’s own commands, checks its output and leaves drafts for a person to merge.
- 1server for every kit
- 10tools per kit, or 10 in all with
--unified - 0keys: free on any machine
Published today: the Note and Table kits’ packages. The other kits run here as previews; their packages are not published yet. Works with React, Vue, Svelte, plain JS, Node, Next.js and any MCP client.
Get the servernpx downloads it
# Node.js 20+; macOS, Linux (glibc) and Windows x64 npx -y @kition/kits-mcp --help # or install the command kition-kits-mcp once npm install -g @kition/kits-mcpThe package brings the server and the published kits (Note and Table) for your platform. Your client starts it; you do not run it yourself.
Register it with your clientone server, every kit
claude mcp add kition -- npx -y @kition/kits-mcp --workspace "$PWD"Run it in the project folder: the shell fills in its absolute path. Add --scope project to share it through the project’s .mcp.json, and /mcp shows whether the server started.
With the server installed instead
claude mcp add kition -- kition-kits-mcp --workspace "$PWD" --kits-dir <kits-folder>{ "mcpServers": { "kition": { "command": "npx", "args": ["-y", "@kition/kits-mcp", "--workspace", "/absolute/path/to/folder"] } } }Any client with an mcpServers file. Use absolute paths: Claude Desktop does not start servers in your project folder.
With the server installed instead
{ "mcpServers": { "kition": { "command": "kition-kits-mcp", "args": ["--workspace", "/absolute/path/to/folder", "--kits-dir", "/absolute/path/to/kits"] } } }{ "mcpServers": { "kition": { "command": "npx", "args": ["-y", "@kition/kits-mcp", "--workspace", "${workspaceFolder}"] } } }In the project’s .cursor/mcp.json (or ~/.cursor/mcp.json for every project). Cursor fills in ${workspaceFolder}, the folder that holds .cursor/.
With the server installed instead
{ "mcpServers": { "kition": { "command": "kition-kits-mcp", "args": ["--workspace", "${workspaceFolder}", "--kits-dir", "/absolute/path/to/kits"] } } }[mcp_servers.kition] command = "npx" args = ["-y", "@kition/kits-mcp", "--workspace", "/absolute/path/to/folder"]Codex does not start servers in your project folder: give the folder’s absolute path.
With the server installed instead
[mcp_servers.kition] command = "kition-kits-mcp" args = ["--workspace", "/absolute/path/to/folder", "--kits-dir", "/absolute/path/to/kits"]transport stdio command npx args -y @kition/kits-mcp --workspace /absolute/path/to/folder # options --unified · --drafts · --sandboxA stdio server: register the command and its arguments. --workspace is the only folder it reads or writes.
With the server installed instead
transport stdio command kition-kits-mcp args --workspace /absolute/path/to/folder --kits-dir /absolute/path/to/kits # options --unified · --drafts · --sandbox
Or let your agent do it
01One prompt for Claude Code, Cursor or Codex: it says where the server comes from, how to register it on this project, the loop to follow, and where the machine-readable docs are.
Set up the Kition SDK kit tools (an MCP server) for this project, then use them for the files they cover. 1. Read https://developer.kition.ai/agents.md (setup for each client) and https://developer.kition.ai/skill/SKILL.md (how to use the tools). 2. Get the server with `npx -y @kition/kits-mcp` (Node.js 20 or later); it brings the published kits. 3. Register it as a stdio MCP server named "kition" in this client, with --workspace set to this project's absolute path. Show me the config change before you write it, and ask before you edit a file outside this project. 4. Check that it starts and lists its tools (note_* per kit, or kit_* with --unified). 5. When you edit a file with it: _inspect it first, find real command ids with _commands, change it with _run, then call _check and fix what it reports. With drafts on, finish with _draft_ready and never merge: I review and merge. Only the Note kit (Markdown) is published; the other kits are not yet. Machine-readable docs: https://developer.kition.ai/llms.txt (index), https://developer.kition.ai/llms-full.txt (the docs and way-in pages in one file), https://developer.kition.ai/commands.jsonl (the published kits' agent commands), https://developer.kition.ai/skill/SKILL.md (agent skill).
The plugin starts the same server on your project folder with one tool set for all kits, adds the Note kit’s editing skill, and gives you draft review commands: /kition-kits:drafts-list, drafts-compare, drafts-merge, drafts-discard. Only you start a merge or a discard.
# from a kition-sdk checkout
claude plugin marketplace add ./plugins/claude-code
claude plugin install kition-kits@kitionAny other coding agent: give it the agent skill, SKILL.md. It tells the agent how to use the tools; the full setup is in the agent guide.
How it works
02- Your agentAny MCP client
Claude Code, Cursor, Codex or your own agent starts kition-kits-mcp as a stdio server on one workspace folder.
- kition-kits-mcpOne workspace, every kit
It launches each kit’s headless executable and offers its tools. No Kition app runs; paths outside the workspace are refused.
- A personReviews the draft
With drafts on, the file stays as it is until a person compares the draft and merges it. The agent never merges.
The tools
03<prefix>_inspectThe document as JSON; preview: true adds a rendered preview.<prefix>_commandsSearch the kit’s commands by keywords. Use the ids it returns, never guessed ones.<prefix>_runRun command steps in order, then save: { path, steps: [{ command, params }] }.<prefix>_query · <prefix>_batchRead and edit objects through the object model, for many small changes.<prefix>_checkWhat the kit finds wrong with the file: { diagnostics: [{ code, severity, target, message, fix? }] }.<prefix>_create · <prefix>_exportA new file, or the file in another format.<prefix>_draft_ready · <prefix>_draft_reopenAsk for review of the agent’s draft, or reopen it. Merge and discard are not tools.
Failed calls answer isError with structuredContent.error.code (not-found, read-only, unknown-command, invalid-params, conflict, …). kition-kits-mcp --schemas prints every tool’s argument and result JSON Schema.
Default · per kit
note_*, sheet_*, …Each kit adds its own ten tools, named by its prefix, so the tool name says which kit it is for. Choose it with one or two kits installed.
$ kition-kits-mcp --workspace . --kits-dir kits
# tools/list: ten per kit, named by its prefix
note_inspect note_commands
note_run note_check
note_query note_batch
note_export note_create
note_draft_ready note_draft_reopen
# + sheet_*, slide_*, doc_* … for each kit installed--unified · one set
kit_*, routed by extensionTen tools for every kit; each call goes to the kit for its file’s extension. Choose it with several kits, or when your client limits tools or tool-definition tokens. The Claude Code plugin uses it.
$ kition-kits-mcp --workspace . --kits-dir kits --unified
# tools/list: ten, however many kits
kit_inspect kit_commands
kit_run kit_check
kit_query kit_batch
kit_export kit_create
kit_draft_ready kit_draft_reopen
# notes/plan.md → note · deck.pptx → slideWith Note alone, both give ten tools.
Tell your agent to call _check after every edit and fix what it reports, errors first, matching on code rather than the message. The kit checks its own file, so the agent sees what it broke before a person does.
_inspect { path } # look first
_commands { path, query } # real command ids, never guessed
_run { path, steps: [...] } # edit, then save
_check { path } # fix each error, then warning
↻ until _check is clean
_draft_ready { path } # with drafts: hand it to the personStart the server with --drafts (or pass draft: true) and the agent’s edits go to a draft in the workspace’s .kition/drafts/; the file stays as it is. The agent hands it over with _draft_ready. You compare and merge, on the command line or from your server.
kition-kits-mcp drafts list --workspace .
kition-kits-mcp drafts compare notes/plan.md --previews \
--workspace . --kits-dir <kits-folder>
# refused as stale if the file changed since the draft forked
kition-kits-mcp drafts merge notes/plan.md --workspace . --kits-dir <kits-folder>
kition-kits-mcp drafts discard notes/plan.md --workspace . --kits-dir <kits-folder>KHP tiers
04Kit Harness Protocol (KHP) is the open standard behind the tools. A kit conforms at a tier, and khp check tests it; each tier includes the one before.
| Tier | A kit at this tier has | Kits today |
|---|---|---|
Basicbasic | _inspect, _commands, _run and _check; a schema for every agent-facing command; stable errors; atomic runs; the draft tools when the kit declares drafts. | The other 15 kits |
Agent-readyagent-ready | Basic, plus works without its editor, full schema coverage, no network, a real check with its catalogue, a real preview, create and export, determinism. | Design |
Agent-ready completeagent-ready-complete | Agent-ready, plus a kit guide for agents, edits that address only what they change by id, name or path, and running under a sandbox. | None yet |
Read the standard at kitharness.org.
The bench
05Multi-turn edits are where agents break files: a later turn revisits an earlier slide and damages content it was not asked to touch. Multi-turn slide edits: 30/30 clean with KHP vs 18/30 with flat MCP tools (p = 0.0001).
What it does not show: that KHP makes a single simple edit more likely to succeed, or that it is the cheapest interface for every task.
- KHP tools
- Flat MCP tools
Show as a table
| Runs out of 30 | KHP tools | Flat MCP tools |
|---|---|---|
| Runs that finished clean | 30 | 18 |
| Runs that damaged other content | 0 | 12 |
Pilot results from khp-bench, run by KHP’s maintainer: method, limits and how to reproduce.
A complete example
06An agent adds a section with a task to a note in a workspace folder over MCP, then asks the kit to check the file.
kition-sdk · examples/agent-mcp/run.mjsconst server = await connect(mcp, ['--workspace', workspace, '--kit', note])
// The note: one more section, with a task under it.
const before = inspected(await call('note_inspect', { path: file, preview: false })).details.headings
await call('note_run', {
path: file,
steps: [{
command: 'block.append',
params: { markdown: `## Agent review ${before + 1}\n\n- [ ] Check the numbers` },
}],
})
const after = inspected(await call('note_inspect', { path: file, preview: false })).details
// Verify: the kit checks its own file.
const answer = await server.call('note_check', { path: file })
const diagnostics = answer.structuredContent?.diagnostics ?? []
const errors = diagnostics.filter((item) => item.severity === 'error')Your page’s server lists the drafts, compares one with previews, and merges it when the person approves. In an open editor, the same review happens in the page: Embed.
Agents that work in Git worktrees can use the command line instead: kiv, Git for kit files diffs and merges slide files and lands parallel branches.
import { workspaceDrafts } from '@kition/script/node'
// the SDK bundle's server and kits
const drafts = workspaceDrafts({
server: 'bin/<platform>/kition-kits-mcp', workspace, kitsDir: 'kits',
})
// { path, state: 'ready', stale, mode, … }
const [draft] = await drafts.list()
// { diff, summary, previews }
const comparison = await drafts.compare(draft.path, { previews: true })
// the person approved: the draft becomes the file
await drafts.merge(draft.path)Limits and requirements
07- The installed server finds the kits from
--kits-dir(one folder per kit, itskit.jsonand executable),--kit <path>,KITION_KIT_<KIT>_BINARY, or thePATH;--list-kitssays what it found. --workspaceis the only folder it reads or writes; every tool names its file bypathrelative to it, and paths outside it are refused.--sandboxruns every kit process in the operating system’s sandbox (macOS, Linux); off by default.
- Without
--unified, each kit whose executable is set adds its own tools, prefixed with the kit’s name (note,sheet,slide,doc, …). - In an open editor,
editor.agentPort()serves the same tools on the live document, relayed by your page and server. - The Claude Code plugin’s launcher is a POSIX shell script (macOS and Linux); on Windows, register the server yourself.
Give your agent real tools
npm i @kition/script