Skip to content

MCP reference ​

What netherite mcp (stdio) and /mcp on a running netherite serve (streamable HTTP) offer an agent. Every write returns the new hash; pass it back as baseHash and the write fails if the file changed in between.

Tools ​

Full-text search over IDs, titles, aliases, paths and text. Returns matching items, best first.

NameTypeRequiredDescription
querystringyes
typesgoal | project | task | adr | doc | context | runbook[]Only these item types.
statusstringOnly items with this status (goals, projects, ADRs) or state (tasks).
projectstringOnly items that belong to this project.
tagstringOnly items with this tag or label.
limitinteger

get ​

One item in full: its fields, text, links in both directions, progress, freshness and content hash.

NameTypeRequiredDescription
idstringyesItem ID, such as TASK-00042.
as_ofstringA date (2026-03-01): show the state as it stood then, rebuilt from git history. Needs git.

list ​

Items matching filters, in ID order. Use it to browse; use search to find by text.

NameTypeRequiredDescription
typegoal | project | task | adr | doc | context | runbook
statusstringOnly items with this status (goals, projects, ADRs) or state (tasks).
projectstringOnly items that belong to this project.
tagstringOnly items with this tag or label.
limitinteger
offsetinteger
as_ofstringA date (2026-03-01): show the state as it stood then, rebuilt from git history. Needs git.

create ​

Create an item with the next free ID, or with the id you give for an import: it must be a free ID of the type. Give its type, title and fields; the file name, dates and folder are handled for you.

NameTypeRequiredDescription
typegoal | project | task | adr | doc | context | runbookyes
titlestringyes
idstringAn explicit free ID of the type, for imports. Omit it for the next free ID.
fieldsobjectFields for the type (see the schema resource for each type).
bodystringText after the title heading, as Markdown. [[ID]] links to other items.
created_bystringA @handle. Defaults to the person running the server.

update ​

Change fields and/or one section of an item. Only the lines you change are touched. Use set_state for states and link for relationships.

NameTypeRequiredDescription
idstringyesItem ID.
setobjectFields to set. id and type cannot be changed.
unsetstring[]Fields to remove.
sectionobject
base_hashstringThe hash from an earlier result. The write fails if the file changed since.

set_state ​

Set a task's state, an ADR's status, or whether a doc, runbook or context item is active, deprecated or superseded. Making an item superseded needs superseded_by and updates both items. A retired item is left out of freshness and of agent context.

NameTypeRequiredDescription
idstringyesTask, ADR, doc, runbook or context ID.
statestringyesTask states: backlog, doing, blocked, done. ADR statuses: proposed, accepted, deprecated, superseded. Doc, runbook and context statuses: active, deprecated, superseded.
superseded_bystringThe item that replaces this one, of the same kind. Required when state is superseded.
base_hashstringThe hash from an earlier result. The write fails if the file changed since.

toggle_check ​

Tick or untick checklist items in an item's text: one item, a list of items, or all, in one write. The edit is all or nothing: an item that does not exist changes none. The result lists each item as it is now.

NameTypeRequiredDescription
idstringyesItem ID.
itemanyOne checklist item: its 0-based position, or its exact text.
itemsany[]Several checklist items, each a position or its exact text.
allbooleanEvery checklist item. Ticks them unless checked is false.
checkedbooleanSet to this state. Omit to flip each one (with all, omit to tick).
base_hashstringThe hash from an earlier result. The write fails if the file changed since.

Add a typed relationship from one item to another by ID. supersedes updates both ADRs.

NameTypeRequiredDescription
fromstringyesThe item that holds the relationship.
tostringyesThe item it points at.
kindbelongs_to | implements | explains | supersedes | depends_on | relatedyes
base_hashstringThe hash from an earlier result. The write fails if the file changed since.

Remove a typed relationship. Required ones, such as a task's project, cannot be removed.

NameTypeRequiredDescription
fromstringyesThe item that holds the relationship.
tostringyesThe item it points at.
kindbelongs_to | implements | explains | supersedes | depends_on | relatedyes
base_hashstringThe hash from an earlier result. The write fails if the file changed since.

delete ​

Delete an item. Refused while other items link to it, unless force is true.

NameTypeRequiredDescription
idstringyesItem ID.
forceboolean
base_hashstringThe hash from an earlier result. The write fails if the file changed since.

mark_reviewed ​

Record that a doc, runbook or context item was reviewed, by setting reviewed_at. Defaults to today.

NameTypeRequiredDescription
idstringyesDoc, runbook or context ID.
datestring
base_hashstringThe hash from an earlier result. The write fails if the file changed since.

lint ​

Check one item, or the whole workspace, for schema errors, broken links, duplicate IDs, stale docs and more. Each problem has a position, rule and severity.

NameTypeRequiredDescription
idstringOnly report on this item. Omit for the whole workspace.

context ​

The curated context for agents: context items marked for inclusion, highest priority first, within the token budget.

NameTypeRequiredDescription
projectstringOnly context for this project (and context not tied to one).

Resources ​

URIWhat
netherite://contextCurated context for agents, within the token budget.
netherite://timelineGoals, projects, tasks and decisions on one time axis, with holds, due dates and overdue flags. Needs git.
netherite://statsTasks created and done, cycle time, goal areas and knowledge health over 30 days, against the 30 before. Needs git.
netherite://item/{id}The raw Markdown file of an item, by ID.
netherite://stats/{period}The same for a period: 30d, quarter or year. Needs git.
netherite://schema/{type}JSON Schema for an item type.

The schema of each item type is read at netherite://schema/<type> (goal, project, task, adr, doc, context, runbook); see the schema reference.

MIT licensed. Nothing is sent anywhere: it runs on your machine.