MCP tools
The read and write data commands the MCP server provides, and what they return.
Read
list_projects
Reads the list of your project grounds. It returns the following.
- Slug (
slug) - Name (
name) - Last activity (
latestActivityAt) - Active or not (
isActive) - Transplanting status (
transplanting) - Node count (
nodeCount), open bug count (openBugs), season count (seasonCount) - Current season name (
nowSeasonLabel) - Description excerpt (
description) - Wiki page count (
wikiCount) — only when there are pages - The team it belongs to (
org, the team slug) and your role there (role:owner/editor/viewer) — only for team grounds. As aviewer, write tools are rejected with 403
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Optional | view | summary / full | full also returns the ground’s intent (seedMeta: goal, end date, budget, audience) |
get_graph
Reads the tree drawn on one project ground, along with its details.
- Nodes (
nodes): includingplan/implements/ dormant flags - Dependencies (
edges) - APIs (
apis) - Seasons (
seasons) - Bugs (
bugs) - Transplanting status (
project.transplanting) - The ground’s intent (
project.seedMeta) — the goal, end date, budget, and audience a person wrote down. Read it before proposing structure
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | Slug of the ground whose tree to read | |
| Optional | view | summary / full | Default summary. full returns every field, soft-deleted nodes included |
| Optional | rootId | node id | Only this node (a trunk, a limb …) and the branches below it |
| Optional | depth | number | How many levels down from rootId (0 = just that node). Omit for all |
| Optional | maxType | trunk / limb / twig / leaf / vein | Only up to this level. e.g. twig: trunk, limb and twig, without leaf and vein |
| Optional | role | structure / object / action | Only what has that role |
| Optional | season | season id | Only nodes that grew in that season |
| Optional | descriptions | none / excerpt / full | How much description to include. Default excerpt (200 chars) |
| Optional | bugStatus | active / wild / chasing / resolved / all | Which bugs to include. active (default): every unresolved bug (wild + chasing) |
When the tree has grown large, these parameters let you read part of it instead of all at once: “Show me only what grew in the previous season.” “Read this project’s tree without descriptions.” “Read the bugs currently open in this project.”
get_impact
Checks the blast radius — the nodes affected when something breaks, following dependencies and API flow.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | node | node id | Starting point to check from (node) |
| Required | bug | bug id | Starting point to check from (bug) |
| Optional | direction | affected / dependsOn / both | affected (default): what is affected when the starting point breaks. dependsOn: what can affect the starting point |
| Optional | maxDepth | number | Maximum hops to traverse. Unbounded if omitted |
list_bugs
Reads the bug list of a project ground, with each bug’s risk (score, 0–8) and impact (impactCount).
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Optional | status | active / wild / chasing / resolved / all | active (default): wild + chasing |
| Optional | limit | number | Maximum count |
| Optional | order | asc / desc | Order of registration. asc (default): oldest first |
| Optional | view | summary / full | summary (default): leaves out description and metadata |
get_bug
Reads one bug, by its number (ref: 14 — the #014 shown in the UI) or its id. Returns the full description plus its blast radius.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | ref | number or id | Bug number (14) or bug-<uuid> |
| Optional | descriptions | none / excerpt / full | How much description to include. full (default): all of it |
| Optional | solution | none / open / full | full (default): all of it. open: only the unchecked items left to do |
list_seasons
Reads the list of seasons.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Optional | view | summary / full | full includes UI-only metadata |
list_events
Reads the change history of a project ground (create / update / delete / plan_commit).
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Optional | limit | number | Default 50, max 200 |
| Optional | before | ISO timestamp | Only events older than this (paging) |
| Optional | entityType | node / edge / api / bug | One kind of entity only |
| Optional | entityId | id | One entity’s history only (usually with entityType) |
Write — tree, dependencies, APIs
create_node
Follows the plant vocabulary hierarchy: violations are rejected, and softer issues come back as warnings that steer you to adjust.
- Build from the leaf. When adding a leaf or vein, create only the ancestors (trunk, limb, twig) still missing on its path, then attach the leaf. Don’t lay down every trunk, then every limb, filling one layer at a time.
- A trunk can’t be a plan. A trunk is the frame of the tree and is always created committed;
metadata.planon a trunk is rejected.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | type | trunk / limb / twig / leaf / vein | |
| Required | label | The name shown on the tree | |
| Optional | parent | node id | Omit to place it at the top level (a new trunk) |
| Optional | season | season id | Omit to place it in the now season |
| Optional | description | ||
| Optional | tags | list of strings | |
| Optional | metadata | object | For a leaf or vein, put the implementing file paths in metadata.implements |
| Optional | sproutedAt | ISO timestamp | The real creation time — when the file was actually created, not when it was imported |
update_node
Edits an existing node. Record realized code in metadata.implements.
A node that already grew in a past season keeps its place in time and in the tree — parent, season, type, and sproutedAt can’t be changed; only label, description, metadata, and tags can. While the ground is first transplanting, its place can be changed too, whatever the season.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | id | node id | |
| Required | patch | object | Only the fields to change |
delete_node
Deletes an existing node. Its record stays, though — turn the slider back and you can still see the trace of the branch (soft-delete). While the ground is first transplanting, you can remove the trace as well (hard-delete).
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | id | node id | |
| Optional | cascade | true / false | Deletes the active descendants too |
| Optional | hard | true / false | Permanent delete. Only while transplanting; irreversible |
create_edge / delete_edge
Edits dependencies (edges) between nodes. Direction is source → target.
Parameters
Create (create_edge)
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | source | node id | The side that relies on the other / where data leaves |
| Required | target | node id | |
| Required | type | dependency / data_flow | dependency: source depends on target. data_flow: data flows from source to target |
| Optional | label | ||
| Optional | metadata | object |
Delete (delete_edge)
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | id | edge id |
create_api / update_api / delete_api
Edits call flows between nodes. Direction is caller (start) → callee (end).
Parameters
Create (create_api)
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | start | node id | The caller |
| Required | end | node id | The callee |
| Optional | label | ||
| Optional | description | ||
| Optional | metadata | object |
Update (update_api)
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | id | api id | |
| Required | patch | object | Only the fields to change |
Delete (delete_api)
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | id | api id |
Write — grounds & bugs
create_project
Creates a new project ground. A new ground starts in transplant mode.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | URL identifier. Lowercase letters, digits, hyphens; 1–50 chars | |
| Required | name | Display name | |
| Optional | description | ||
| Optional | org | team slug | Creates the ground in that team. Only the team’s owner can |
create_bug
Reports a new bug.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | title | One-line summary | |
| Required | target | {kind, id?} | kind: node / api / ground. Use {kind: "ground"} for a problem with the project itself |
| Optional | description | ||
| Optional | solution | ||
| Optional | score | 0–8 | Risk. Default 4 |
| Optional | status | open / in_progress / resolved / closed | Status. Default open |
The description and solution are written in markdown. In the solution, - [ ] item lines make a checklist you can keep track of.
update_bug / delete_bug
Edits or deletes a bug.
Parameters
Update (update_bug)
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | id | bug id | |
| Required | patch | object | Only the fields to change. One checklist item: solutionItem |
Delete (delete_bug)
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | id | bug id |
Growth
commit_plan
Confirms a plan node and promotes it into the growth record. It needs metadata.implements (proof it was realized) to be confirmed.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | id | plan node id |
record_commit
Writes a commit record into metadata.commits of every node whose realization proof (implements) matches a changed file.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | sha | Commit SHA (short is fine) | |
| Required | files | list of paths | Files the commit changed (repo-relative) |
| Optional | message | Commit message |
create_season
Opens a new season and makes it now. The agent asks the user first, and the season is created only when it sends confirm: true.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | label | The season name the person chose (a version, phase or period) | |
| Optional | confirm | true | Only on the second call, after the user agreed. Omit on the first |
Wiki
Records the spec of the project as it is built now. Changes are kept as revisions.
list_wiki
The ground’s wiki pages. Bodies come back as 200-character excerpts by default.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Optional | node | node id or none | If given, reads the pages attached to that node. none reads the pages not attached to any node |
| Optional | kind | overview / concept / component / rule / glossary / none | Reads only pages of that kind. none reads only pages not yet classified |
| Optional | body | none / excerpt / full | How much of the body to include: default excerpt |
| Optional | limit | number | Maximum number of pages to read |
| Optional | order | asc / desc / tree | Order by last update: default desc. tree reads in table-of-contents order (the order you read from the overview) |
get_wiki
Reads one wiki page in full. Pass rev to read an older revision.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | Ground slug | |
| Required | ref | page slug or id | |
| Optional | rev | number | Revision to read. Omit to read the current page |
list_wiki_revisions
Reads the list of a page’s revisions.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | ref | page slug or id | |
| Optional | limit | number | |
| Optional | order | asc / desc | By revision number. Default desc |
write_wiki
Edits a page. A name that doesn’t exist yet creates a new page. The default replace mode overwrites the whole body, so read it with get_wiki first. By default, edits by the same author within 30 minutes don’t become a new revision, but you can force one by passing newRevision: true.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | Ground slug | |
| Required | page | Page name. Lowercase letters, digits, hyphens (e.g. deploy-notes) | |
| Optional | title | Display title. Required when creating a page | |
| Optional | kind | overview / concept / component / rule / glossary | Page kind (overview, concept, component, rule, glossary). Each kind needs different sections |
| Optional | parent | page slug or id, null | The page this one sits under in the table of contents. null puts it at the top (only the overview belongs there) |
| Optional | position | number | Order among pages under the same parent (ascending) |
| Optional | body | Markdown body. With append, the text to add | |
| Optional | mode | replace / append / restore | Default replace. append adds a missing section at the end; restore brings back the revision in rev |
| Optional | rev | number | The revision to bring back with restore |
| Optional | baseRev | number | The revision you read. If someone changed the page since, the write is refused instead of overwriting |
| Optional | newRevision | true / false | Break the 30-minute fold and start a new revision |
| Optional | node | node id or null | Node to attach the page to. null detaches; omit to leave it as is |
| Optional | rename | New page name. Keeps the id and revision history |
delete_wiki
Deletes a page.
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | slug | ||
| Required | ref | page slug or id |
Feedback on Umtri
You can send problems with the product or requests for improvement. When needed, the agent checks with the user before sending.
send_feedback
Files a suggestion (improvement, the default) or a defect report (bug).
Parameters
| Kind | Name | Values | Notes |
|---|---|---|---|
| Required | title | One-line summary | |
| Optional | kind | bug / improvement | Default improvement |
| Optional | body | What you expected, what happened, why it matters (markdown) | |
| Optional | source | Where it came up — a ground slug, tool name or screen |