Agents: kit tools over MCP
kition-kits-mcp gives Claude, Cursor or any MCP client each kit’s tools on a workspace: inspect, run, query, batch and check, with drafts a person reviews and merges.
kition-kits-mcp is a stdio MCP server. It gives any MCP client (Claude Code, Claude Desktop,
Cursor, Codex, DeepSeek Harness, your own agent) the kits' tools on one workspace folder. The
agent creates, inspects, edits and checks files there through each kit's headless executable. No
Kition app has to run, and the server is free on any machine with no licence key. The published
kits are Note, for Markdown, and Table, for .ktable tables.
Connect your agent
Pick one way to get the server:
- npm:
npx -y @kition/kits-mcp --workspace <folder>downloads and startskition-kits-mcpfor your platform (macOS arm64 and x64, Linux arm64 and x64 with glibc, Windows x64), with the published kits. Node.js 20 or later.npm install -g @kition/kits-mcpinstalls it as the commandkition-kits-mcp. - Installed binary: take
bin/<platform>/kition-kits-mcpfrom the SDK release's bundle for your platform (Distribution), or build it from kition-sdk withcargo build --release -p kition-kits --bin kition-kits-mcp. It then needs the kits: give--kits-dir <folder>(the bundle'skits/, whose executables are inbin/<platform>/, or one folder per kit holding itskit.jsonand itskition-<kit>executable) or--kit <kition-note>; see The server.
--workspace is the only folder the server reads or writes. A relative path is resolved against
the folder the client starts the server in. Replace <folder> with an absolute path where the
client does not start servers in your project (Claude Desktop, Codex).
Claude Code: in the project folder,
claude mcp add kition -- npx -y @kition/kits-mcp --workspace "$PWD"
# installed binary:
claude mcp add kition -- kition-kits-mcp --workspace "$PWD" --kits-dir <kits-folder>
Add --scope project to share it through the project's .mcp.json. /mcp shows whether the
server started. The Claude Code plugin in kition-sdk (plugins/claude-code, marketplace
kition, plugin kition-kits) adds a skill per kit and draft review commands, and starts the
same server.
Claude Desktop, and any client with an mcpServers file (claude_desktop_config.json,
.mcp.json, ...):
{
"mcpServers": {
"kition": {
"command": "npx",
"args": ["-y", "@kition/kits-mcp", "--workspace", "/absolute/path/to/folder"]
}
}
}
Cursor: .cursor/mcp.json in the project:
{
"mcpServers": {
"kition": {
"command": "npx",
"args": ["-y", "@kition/kits-mcp", "--workspace", "${workspaceFolder}"]
}
}
}
Codex: ~/.codex/config.toml:
[mcp_servers.kition]
command = "npx"
args = ["-y", "@kition/kits-mcp", "--workspace", "/absolute/path/to/folder"]
With the installed binary, the command is kition-kits-mcp (its path, if it is not on the
PATH), and the arguments are ["--workspace", "<folder>", "--kits-dir", "<kits-folder>"].
Options for every form:
--unified: one set of ten tools for every kit (kit_inspect,kit_run,kit_check, ...), routed by the file's extension, instead of ten<prefix>_<action>tools per kit (note_inspect,note_run, ...). Use it when several kits are installed or the client limits tools or tool-definition tokens; with Note alone, both give ten tools.--drafts: the agent's edits go to drafts the person reviews (Drafts).--sandbox: run every kit process in the operating system's sandbox.--list-kitsprints the kits the server found and exits.--schemasprints every tool's argument and result JSON Schema.--helplists every option.
Other clients:
- Kition running: its loopback endpoint
POST /v1/mcp/kitsalso edits files open in kit editors live. - Agent skill: skill/SKILL.md tells a coding agent how to use the tools.
The server
# from the unpacked SDK bundle
bin/<platform>/kition-kits-mcp --workspace <folder> --kits-dir kits
# or one kit: --kit bin/<platform>/kition-note (repeatable)
--kits-dir names the bundle's kits/, where each kit's kit.json is; the server finds each
kit's executable in the bundle's bin/<platform>/, beside itself, through
KITION_KIT_<KIT>_BINARY, or on the PATH, and says on standard error which kit it found no
executable for (--list-kits gives the same reason).
@kition/kits-mcp passes --kits-dir itself, for the kits its platform package carries, when
you give neither --kits-dir nor --kit. KITION_KITS_MCP names another kition-kits-mcp for
it to start.
Options: --unified (one kit_<action> set for every kit), --drafts (the agent's edits are
drafts unless a call says draft: false; a kit whose kit.json declares no agent.drafts
refuses them, see Drafts), --guard premise|epoch|off and --require-basis (see
What others changed), --sandbox, --help.
The server is free on any machine and takes no licence key: only collaboration is paid.
kition-kits-mcp --schemas prints every tool's argument and result JSON Schema (input,
output; the same as Kition's contracts/kit/mcp-tools.schema.json).
Each kit whose executable is set adds its tools (prefix = the kit, such as note):
| Tool | Does |
|---|---|
<prefix>_inspect | the document as JSON, with a rendered preview with preview: true; target is the part to list and, for a kit with a render command (agent.render), the view drawn ({ time }, { range, frames }, { sequence }, …), and preview in the answer says what the picture shows |
<prefix>_commands | search the kit's commands by keywords |
<prefix>_run | run command steps in order, then save ({ path, target?, steps: [{ command, params?, on?, at? }] }: on the ids a step acts on, at { part?, time? } where; the kit's selection and current part are put back after the call; preview: true with view draws the after-picture at that view through the kit's render command) |
<prefix>_query, <prefix>_batch | read and edit objects through the object model |
<prefix>_draft_ready, <prefix>_draft_reopen | drafts a person reviews |
<prefix>_check | what the kit finds wrong with the file: { diagnostics: [{ code, severity, target, message, fix? }] } |
<prefix>_create | a new file at path (size optional) |
<prefix>_export | the file written in another format the kit exports, as a new file to (format, options for the kit's export command) |
Every tool names its file by path (workspace-relative); <prefix>_query follows objects with
follow (slides.0.shapes), never path. draft is an argument of _inspect, _query, _run,
_batch, and _check. Failed calls answer isError with structuredContent.error.code
(not-found, read-only, unknown-command, …) and error.index for the failing step. Objects are also kit://
resources. Tell the model to call <prefix>_check after editing and to fix what it reports.
What a write changed
Every accepted <prefix>_run and <prefix>_batch (on the file, or on a headless draft) answers
what the whole call changed, so the model need not inspect again just to see it. The server reads
it from the document's data model through the kit (Kit Process Protocol model.version before the
first step, model.changes after the last; kits do nothing for it):
| Member | Meaning |
|---|---|
changes | { created, changed, moved, deleted, truncated? }, objects named by the ids _inspect and _query use (tool ids where the kit declares them), each list ordered by id. A created object is { id, type, fields, values, at? } (at: { parent, field, index } where a list or tree holds it); a changed one { id, type, fields, edits: [{ field, before, after }] }; a moved one { id, type, from, to } (an object both moved and changed is in both lists); a deleted one { id, type, fields: [], at? } (at: where a list or tree held it). Values are given as they are, except texts over 80 characters ({ excerpt, length }) and blobs ({ size }); a list or tree field's change is told by moved, created, deleted. A map field that owns no objects is told per changed key ({ field: "attrs.stretch", before: 100, after: 200 }, null for a key added or taken out), and a json value, or a key's value, down to its changed leaves (object members, items of arrays of one length: look.kind.start, attrs.markers.1.time) when that is at most 16 edits and fewer bytes than the value whole, else whole; each path stands in fields for the field, so a batch's map.set of one key conflicts with others' change of that key only. Where the kit's schema says how held objects are named (pathName, a layer's property tree), an edit inside them also gives named, the place in the words of the kit's commands ({ field: "props.children.2.children.7.value.v", named: "transform/opacity.value.v" }). An object without a tool id that an object with one holds (through a list or tree, or a ref the schema marks owns: a paragraph in a shape's text body) is told as an edit of the nearest such holder, field being the path from it (body.paragraphs.0.text): created { field: "body.paragraphs.2", before: null, after: { text: "New" } }, deleted the other way round, moved { field: "body.paragraphs", before: "body.paragraphs.1", after: "body.paragraphs.0" } |
revision | the document's revision after the call (see What others changed); the same after a call that changed nothing; left out for a kit without an object model |
changesUnavailable | why changes is null: the kit has no object model, the document was replaced (reloaded) while the call ran, or the file is open in an editor that does not report it (one that lists the Kit UI capability changes does, from its replica). Never an empty change set in its place |
diagnostics | { new, resolved }: the kit's check before the first step and after the last, matched by code and target |
A failed (rolled-back) call answers none of them. Arguments: changes (true by default: at
most 50 objects across the lists, truncated counting what each list left out; "all" lifts the
cap; false leaves changes out) and check (true by default; false skips both checks). On
the mock kit a debug build's run took 1.4 ms bare, 5.4 ms with the change set and 5.8 ms with the
checks too.
A shift of many objects is stated once (footprint): when at least 4 objects one after another
in one list had one numeric field changed by the same amount and nothing else changed in them (a
ripple edit moving every later clip), their entries are replaced by { parent, field, from, count, shift: { field, by } } (from and count index the list as it is after the call; by is a
number, or a string for whole numbers kept as strings, a video kit's ticks). A list's own entry
that says no more than that the list changed ({ id: "V1", fields: ["clips"], edits: [] }) is
left out when the footprint or the created, deleted or moved objects of that list say it.
At least 4 objects whose every change is the same shifts and that are in no such run (scattered
through a list, or in none the change set names: 200 nodes of a scene moved by one offset) are one
entry by their ids, { ids: [...], edits: [{ field: "location.2", by: 1 }] }. An object's change
may say what it carries with it that is no stored change, carries: { count, what } (a parent's
move: { count: 200, what: "world location" }), as its kit answers it (model.carried).
Inside one object, at least 4 edits of one leaf of the items of a held list shifted by one amount
(200 keyframes moved half a second: keys.0.time, keys.1.time, …) are one edit { field: "keys.*.time", named?, count, shift: { by } }, and fields names that pattern. The indexes a
list's created, deleted or moved objects shifted are stated once too, { parent, field, from, count, shift: { index } } in footprint for each run of at least 4 items kept whose index moved
by one amount (the bottom layer of 200 moved to the top: { from: 1, count: 199, shift: { index: 1 } }), unless a footprint of a field already states that list. In others, an object others
created is told by its id, type, at, its fields' names and only the values of its naming fields
(name, title, label, text, caption, kind) and position fields; changes: "all"
tells every value.
changes: "all" lists every object and no footprint.
A tool id on an integer field without prefix (a clip 9) is a number in changes,
others, conflicts, _query's objects and a batch's loaded, as the kit's commands take it;
on, _query's objects and a batch's target take 9 or "9". A position's parent takes the
form of its type.
What others changed
Several agents, and people editing the file, may work on one document at once. Every answer of
<prefix>_inspect, _query, _run and _batch on a file the headless kit edits (or a headless
draft) carries revision, a short token (qxa7) naming the document's state it describes. The
server keeps each document's journal: every accepted write, by the agent that made it, and every
change found in the file (by outside, compared object by object with what the server had read,
by the ids the tools use). A file open in an editor that lists the Kit UI capability changes
has a journal too, of the editor's document: before every call the server reads the editor's
replica version, and what changed since the version it was up to that no agent call made (each
write moves it past its own change) is someone else's, an entry by person when the editor
reported the change as the person's, else by other, with its change set. Its revisions are the
editor's own: a basis from the headless kit's answers is unknown there, and the other way
round. Every tool on a document's contents takes basis, the revision of
the last answer the agent was given:
| Member | Meaning |
|---|---|
others | what others changed since basis, merged into one change set as changes reads (capped at 50 objects, truncated counting what each list left out; when it lists fewer than changed, parts created, deleted or moved come first, then the objects the pending call names, then the rest, so a slide another program duplicated is always named), with by (the other agents' names, outside, and in the open editor person or other), unnamed (changes made in the file to objects no tool id names, counted by type and list: { "Media": { "changed": 1 } }; the root's own fields and derived values are named by its object id instead when the kit keeps it on every read), renumbered (one line naming the ids another program renumbered in the file) and unknown: true when part of it cannot be told object by object; left out when nothing |
conflicts | on a refused write: [{ id?, reason, now? }], reason deleted, relocated, changed or unknown; now where the object is now ({ parent, field, index } and its position fields, one named like those three in now.fields; or a part as { "slide": n }) |
interface | (_inspect) the protocol, the kit and its version, khp/2 [email protected]; serverInfo.version is the kit's |
A write with basis is checked before anything runs against its premises: its targets (the ids
in each step's on and in the parameter a command declares as its targets, the objects a batch
operation names, and the declared targets of a batch's command operations), every object any
other parameter names, the part a step addresses (at.part, the run's target), and the fields
a batch replaces (set, text.set). An object a parameter names: in a step's or a batch
command operation's other parameters, a set operation's value and a create operation's
fields, each string that is a parameter's whole value, an item of a list, or a member of an
object or of a list's objects (one level deep, nothing deeper), and each whole number there when
the parameter names objects ("x-khp-role": "object", or an index spelling: an integer tool id,
from: 5; a count or an element index is no id), counts as a target, on any field,
when the WHOLE string names an object of the document as it was at basis (one others' changes
name and did not create, or one the document has now, by tool id or object id). So a shape given
as id to a command that declares ids, or as a connector's from and to, is checked as a
declared target is; free text that names no object is nothing, and a part of a string never
counts (a text that is exactly an object's id does). It is refused as a whole with error.code conflict (retryable), others, conflicts and the
revision to pass next, when others since basis:
- deleted a target, or a part named by its id (
deleted); - moved a target or an object holding it, created, deleted or moved objects before it in its list
so that its index changed, or changed which part a part number (
{"slide": 3}) names (relocated). Indexes are followed through every entry sincebasis, the agent's own included. A part's noun names the type whose tool id carries it (slidethe type with prefixslide:), and the parts are the root's list of that type; a kit's declared nouns (agent.parts,pageandslideincluded) address parts by id only, and when no type's tool id carries the noun as a prefix the part's type is the one named as the noun (sheet→Sheet), its id as listed. A part addressed by number conflicts by its tool id (slide:271),nowgiving its number now; - moved a target in time, order or space: changed a field the kit's schema marks
position(a clip'sstart), or a path inside one (location.0, one coordinate of a json position), which is a move, not a change of content (relocated,nowwith those fields' values now; a position field namedparent,fieldorindexis innow.fields, apart from the list place). A command declared position-independent (x-khp-position: independent, a clip's opacity) is not refused when its target only moved, its index shifted or a holder moved: the write runs, andotherssays the target moved; - changed what a step names by a place (
relocated): a step that gives a parameter the command marksx-khp-role: place(a track, a time; also beside itstargetsparameter, where a placed clip lands), a value in the command's index spelling in any parameter ("#3",parent: "#2"),at.timeto a command that readstime(also besideonor itstargetsparameter: a source by id written at the playhead), or, with noonand notargetsparameter, the current time, names whatever is there (the kit'scontext.undersays what: nothing, for a time that selects no object). Its premise is that the objects under the place now (Kit Process Protocolcontext.under) are those that were there atbasis. For a place in time the kit gives as a span over its items' time fields (within.time), the guard replays which items covered it after each change sincebasisfrom the times the change sets carry (a changedstart's value before, a deleted item's times, kept by the journal and never shown): refused exactly when others put an item under the place or took one from it, and a change next to the place (a neighbour trimmed, a clip inserted after it) does not refuse. A place in the index spelling is followed through every change sincebasis: the object it named must be at that index still (when others moved it, the conflict names that object withnow, where it is, besides the one"#3"names now). An index among a tree's children (a layer of a group) is followed alike, through inserts, deletes and moves below it and across groups; when the guard cannot read the list an index counts in, the write is refused (unknown). A command that counts its index from the other end (x-khp-index-order: "reversed", a stack shown top-first) is followed from that end, and a conflict of a place by index says where the object is now in the command's spelling (now.spelled,"#2"). For a window the kit gives by indexes alone, an object under the place now that others created or moved, or one at or next to the window atbasisthat others deleted or moved, refuses it. For a place no window can declare (a world point, which depends on geometry, the hierarchy and visibility), the kit answerscoversand the guard asks it (context.covered) whether each object others moved, reparented, hid, deleted or created sincebasiswas under the place then, from the values the change sets carry: refused when an object under the place now was put there by others, or one that was there is not (the conflict names it withnow, where it went, andplace.under, what is there now); a move, delete or reparent elsewhere does not refuse. The objects under the place are targets too, as if named by id: their content and positions are premises, every field and every position unless the kit states fewer (below). Each conflict names the object,nowwhere it is (index andpositionfields), andplace, the place as the step named it withunder, what it names now, so a retry can name the object by id. A kit that cannot say what a place names (nocontext.under) has such a write refused after any create, delete, move or position change by others (place.unknown). A step with no time of its own that readstimeafter an earlier step of the same run (which may have moved it) is refused after any change by others (place.unknown), unless the kit says its time names nothing. A place parameter is no object a step mentions. A whole number in thetargetsparameter of a command that declaresx-khp-index-numbersis a place counted from 1 when it names no object atbasisor now, else an id.ontakes ids only: an index spelling there isinvalid-paramswhen the command declares one; - what a call needs, stated by the kit: the guard asks
context.underfor every step of a write withbasis, and the kit may answerpremises,{ id, fields?, positions? }for an object the call names (by id, by place, or one it reads that no parameter names, a sequence item holding the caption it edits). Where it givesfields(paths as receipts give them, positional or in the kit's words,named), only a change by others at, inside or holding one of them ischanged(a held object with a tool id counts at its path under the object,sequence.videoTracks.0.items.3); a path may name a list item by a member instead of its index,keys[time=2]ormarkers[id=7], which the guard follows through every save sincebasis: touched when an item matching it was changed or removed or an item now matching it did not before, not by index shifts of other items; where it givespositions(fields the schema marksposition, and the list holding the object by its field,clipsorcomp.layers, for its index there), only a change of those isrelocated([]: the call does not depend on where the object is, asx-khp-position: independentsays for every call of a command). An object the kit says nothing of keeps every field and every position.fieldsmay name a derived value (~topology: a value the kit computes and never stores, which change sets tell beside the stored fields,beforeandafterwhen small): a write by face index holds the mesh's topology, not the whole mesh, and applies after a vertex moved. A change set whose derived values the server could not read refuses such a premise for any change of the object; - changed a field a batch replaces, or any field of a command's target but its
positionfields, since what a command writes is not known (changed). A change inside the target counts: an object without a tool id is reported under the nearest object holding it that has one, at a path (editing a shape's text is a change of the shape atbody.paragraphs.0.text, which conflicts with a batch replacingbodybut not one replacingcolor), and a change of an object with a tool id the target holds (a text body with its own id) is a change of the target. Holding is the schema's ownership: list and tree fields, and refs declaredowns; a shared object a plain ref points to is not held. A batch naming a held object by the object id a query answered is checked by following the paths others' changes give to it; - changed the part itself, for a step that acts on its part: a step with no
on, notargetsparameter given, no place, and no parameter naming an object, that addresses a part (at.part, the run'starget; a comp's marker, its settings, a slide's own properties) has that part as its target (changed, with the part's tool id). Only the part's own fields count, and changes held in it without a tool id of their own (a comp'sattrsunder its item); not its position, not its lists of objects (a layer added), not the objects with tool ids it holds (a layer's opacity). A step that names an object keeps its part as a premise of existence (and, by number, of position) only.
A step whose parameters the command's schema does not take (additionalProperties: false) is
refused as invalid-params, in the kit's words, before the guard: a misspelt parameter whose value
happens to name a changed object is never a conflict. A top-level parameter's value of a type its
schema does not allow (type, or a oneOf/anyOf of types; null counts as left out) is refused
the same way; nothing deeper is checked there (an array's items, an object's members, enum,
bounds), which stays the kit's to refuse when the step runs, after the guard.
Limits of the place premise: a place the kit gives as a window of indexes (no within.time) is
told approximately: an object next to the window that others deleted, moved, or moved in time
refuses the write though the place may name the same objects. A place in time is replayed exactly
only from change sets that carry the times. SDK editor receipts retain private
$was position values; custom change adapters must preserve them. When the
historical placement cannot be established, the kit must answer cannot-say and
the held comparison refuses unknown.
Times are compared as 64-bit floats: exact for tick counts below 2^53 (about ten hours at 254 016
000 000 ticks a second). For a kit that marks no position field, a place is followed by indexes
only: a change of an object's time that keeps its order is not seen.
The server reads the document for the guard as the agent (a batch with origin { kind: agent }
and no operations, which makes no edit and no undo step), as a kit process requires.
A change made in the file
When the file changed since the agent's last call on it ended (another program saved it), the
next call has the kit read it again, once, and compares the document as the server last served
it with the document as read now. The first is read from the document the kit still holds,
before anything asks the kit to open the file (a kit may read a clean document again when it is
opened and its file changed), and only when the kit holds it at the object-model version the
server last served; otherwise (the kit read the file on its own, or was started again) the change
is unknown. The two reads are paired object by object, not compared by object id: a kit that
builds its replica from its file mints new object ids on every read, and only tool ids survive
(the pairing: data model, "Two reads of one file compared"). So
others tells the colleague's edit as a receipt would (shape:9/2 at body.paragraphs.0.text,
before and after), a picture whose shared media got a new id did not change, and changes of
objects no agent can name (layouts, masters, media) are counted by type in unnamed. A file
saved again unchanged (in another form: a package's parts reordered or stored) is no change:
nothing is reported or refused. Parts addressed by number are followed through the change as
through any other (a slide inserted before the one a step numbers is relocated, its deletion
deleted).
When another program renumbered objects (two shapes swapped their numbers, their content
unchanged), others says so in one line (renumbered) instead of telling each shape's text as
changed into the other's, and a write naming one of them is refused as unknown with its id,
saying to inspect again. The revision that refusal gives is the agent's own basis, not the
current one: a revision means "you have seen the document up to here", and a retry with a later
one would make the stale id current and write into the other shape. So a retry is refused again
until a read (_inspect, _query) gives the agent the ids as they are now.
A change of a shared object (media, a layout) never refuses a write to an object that points at it: the write's target did not change, and a shared object is another object, as for any object a write does not act on.
On the mock kit (a debug build, ten slides, thirty shapes with text, a table, two connectors,
median of 10, on a shared machine) a write with basis took 40 to 80 ms with no change made in
the file, 280 to 650 ms after an unrelated change (the two reads walk the document in a few
batched loads each, and one more load names the ids inside json values), and 190 to 240 ms when
refused; others for one text edit is about 230 bytes. On the presentation kit's 20-slide test
deck, 50 writes after 50 file changes took 170 to 260 ms each (median), none refused. The pairing is O(N log N) in the
objects of both reads. A document of any size is walked: on the mock kit, a deck of 2,100 slides
and 21,026 objects took 19 s per write after an unrelated change (debug build; each read of the
document about 4.4 s, the kit's read again 1.2 s, the comparison 2 s), the change told object by
object and no write on an untouched shape refused. Only the change set is kept afterwards.
What a kit must provide for outside changes to be compared precisely
- Tool ids (
toolId, OM9) on the objects agents address (slides, shapes, notes): they pair the two reads by construction. The tool id's field may have any name,idincluded (loads answer every declared field infields). ownson the refs and maps that hold parts of an object (a shape's text body, a table's cells): objects without tool ids pair by their place under a paired holder, and their changes are told at a path under it.- Object ids kept in json values and map keys as whole strings or
:-separated key segments (a connector'slook.kind.start, a cell's<row id>:<col id>), never inside longer text.
Nothing else: no stable object ids across reads, no kit-side diff.
Changes by others to anything else never refuse: the write runs and its answer carries others.
The agent's own writes never count against it. A basis the journal no longer covers (it keeps
256 entries and 20,000 objects of change sets per document by default,
KitManager::with_journal_limits; it drops the oldest entries first and never the newest, so the
revision handed out before the latest change is always covered, however large that change), or an
entry since that cannot be told object by object (a kit without an object model, a file changed
while the document had unsaved edits), is refused with unknown: inspect again. An agent's undo
(edit.undo in the agents' scope) is refused as conflict when the agents' last step is another
agent's, so an agent never takes back another's edit.
Each MCP connection is its own agent: the client's clientInfo.name and a suffix drawn for the
connection (claude-code-x3k9), the author of its writes in the journal and the label of the
origin of its batches; the person stays the principal its edits are attributed to (A11). A
server that does not tell connections apart (mcp::handle_with) is one agent, agent- and a
suffix drawn per process.
--guard epoch refuses any write with basis after anyone else's change; --guard off disables
staleness refusals but still answers others; raw batch declaration and model validation
still apply. --require-basis refuses _run and _batch without basis
(invalid-params). A call without basis keeps the A56 notice: after the file changed outside,
the next read says so once (changedOutside) and the next _run or _batch is refused once;
reads do not clear the refusal. On the mock kit a debug build's run took 5.8 ms without basis
and 7.0 ms with it (median of 20, another agent writing between runs); a revision is about 4
characters, a typical others of one changed object about 175.
Receipts, replacements and declarations
Kit authors should follow the call-context guide for declarations, isolated batch planning, projected objects, callbacks and history limits. Environment tasks use the same guarded calls for replay.
Example: examples/agent-mcp appends a section to a note, then has the Note kit check it.
Drafts
With draft: true on a call (or every call, with --drafts), the agent's edits go to its
draft of the file and the file stays as it is. The draft lives in the workspace's
.kition/drafts/<key>/ (draft.json: path, kit, mode, state, baseSha256, times), so
it survives the server; <prefix>_inspect, _query, and _check with draft: true read it.
The agent asks for review with <prefix>_draft_ready. It never merges: merge and discard are
not tools.
Only a kit whose kit.json declares agent.drafts keeps drafts (KHP A12) and offers
<prefix>_draft_ready and <prefix>_draft_reopen (A35). A call that asks another kit for a
draft (draft: true) is refused with unsupported. Under --drafts, the server's choice not to
edit files directly holds for every kit: an edit (<prefix>_run, <prefix>_batch) of a kit
without agent.drafts is refused with unsupported and changes nothing, unless the call says
draft: false, which edits the file itself; reads, exports and new files are not edits and run.
The server's instructions name those kits. So no edit is left in a draft that no tool can hand to
the person and drafts list does not show, and no file is edited against the server's mode
without the call saying so. @kition/embed's agent port answers the same in a page whose kit
keeps no drafts.
The person, through your page's server, reviews and merges with kition-kits-mcp drafts or
workspaceDrafts in @kition/script/node:
import { workspaceDrafts } from '@kition/script/node'
const drafts = workspaceDrafts({ server: 'bin/<platform>/kition-kits-mcp', workspace, kitsDir: 'kits' }) // the SDK bundle's
const [draft] = await drafts.list() // { path, state: 'ready', stale, mode, … }
const comparison = await drafts.compare(draft.path, { previews: true }) // { diff, summary, previews }
await drafts.merge(draft.path) // the person approved: the draft becomes the file
| Command | Answers |
|---|---|
drafts list | { drafts: [{ path, kit, mode, state, baseSha256, created, updated, stale }] } |
drafts compare <path> [--previews] | { path, kit, mode, state, stale, diff, summary: { base, draft }, previews? }; diff is { created, changed, moved, deleted, texts, truncated?, renumbered? }, using the receipt vocabulary and ids for any declared object model; otherwise null with diffUnavailable |
drafts merge <path> [--overwrite] | { path, merged, sha256 }; refused as stale when the file changed since the draft forked |
drafts discard <path> | { path, discarded } |
Compare keeps at most 50 objects, 50 entries per nested list, and 80 Unicode characters per
value, with diff.truncated counting omissions and { excerpt, length } for long values.
File copies export and pair their states. See the comparison shape and limits.
A refusal prints { "error": { code, message } } and exits with status 1 (not-found, stale, or
a tool's error code). A file's replica is rebuilt each time a kit opens the file, so a draft
merges onto the version it forked from: the merge writes the draft as the file when the file is
unchanged since. Kition's own agent keeps drafts in the person's open editor instead.
Open embed (agentPort)
When the person has the file open in your page (@kition/embed), your agent can work in that
editor instead of on the file: editor.agentPort() serves the same tools over MCP, and your page
and server relay the messages (Embed: in your page, relayAgentPort, createAgentRelay). There:
- edits go to the agent's draft unless the page allows live edits; finish with
<prefix>_draft_readyand the person merges or discards it in the page; pathis the open document's name; only the tools the kit's editor supports are listed (<prefix>_query/_batchwith an object model,_checkwith checks, the draft tools with drafts);- the answers and error codes are those of
kition-kits-mcp.
Without a relay, the agent works headless on the file as above, and the page reloads when the file's version changes. examples/agent-mcp/live.mjs drafts in an open note through the example page.
Kition kit platform: KitAgent 1.4: tools (A1–A6), object-model tools (A16), error
codes (A18), resources (A19), Verify (A21–A23), DeepSeek Harness (D1).