WarmHub exposes a full MCP tool catalog for organizations, repositories, shapes, things, assertions, commits, subscriptions, actions, and meta (capability discovery). In repo-scoped mode, orgName/repoName are omitted from all tool schemas. In global mode, they’re required on repo-level tools.
Orientation and capability discovery. The meta category covers two tools:
Tool
Description
warmhub_capabilities
Static, endpoint-scoped overview of the MCP tool catalog: tools grouped by category, a workflow cookbook, wref syntax, and a pointer to the full write operation contract. Read-only; no arguments.
warmhub_repo_describe
Per-repo live view: schema, shape descriptions, field types, summary stats, wref syntax, operation contract, and write examples generated from the repo’s own shapes. Documented under Repository Tools.
Call warmhub_capabilities first to orient on what tools exist; then call warmhub_repo_describe to learn the repo-specific shapes and write examples.
Takes no arguments. Returns a static orientation payload with the following fields:
Response Field
Type
Description
categories
object[]
One entry per tool category (org, repo, shape, thing-read, commit, subscription, action, meta), each with name, description, and the tools (name, description, readOnly) advertised on the current endpoint.
cookbook
object[]
Common workflows as { task, steps: [{ tool, note }] } — e.g. discovering shapes, searching by content, writing first data.
wrefSyntax
object
Local and canonical wref forms, version modifiers, path/name constraints, and write-path preview rules.
commitContractRef
object
Pointer to warmhub_repo_describe, which returns the full write operation contract, operation variants, and live write examples scoped to a specific repo.
The payload reflects the endpoint scope. On the repo-scoped endpoint (/mcp/:org/:repo), categories omits global-only tools: warmhub_org_list, warmhub_org_get, warmhub_repo_list, and warmhub_repo_create.
Call warmhub_capabilities first to orient an agent, then call warmhub_repo_describe for per-repo schema and write examples.
warmhub_org_list and warmhub_org_get are global-only. The per-org administration tools (warmhub_org_set_description, warmhub_org_archive, warmhub_org_unarchive) are available in both global and repo-scoped mode; repo-scoped callers operate on the org baked into the URL.
Tool
Description
warmhub_org_list
List organizations (archived hidden by default). (global only)
The most important tool for agent bootstrapping. Returns:
Repository metadata
Shape definitions with field types and optional shape-level description
Per-shape queryHints with queryableFields, wrefFields, and suggested MCP query patterns
Per-field descriptions inlined into each field entry. Fields without descriptions appear as bare type strings (e.g. "string"); fields with descriptions appear as { "type": "number", "description": "Horizontal position" }. Descriptions are extracted from typed field objects.
Three tools cover the built-in Content shape — Readme, Agents, and the synthesized LlmsTxt — discriminated by a kind argument.
Tool
Description
warmhub_repo_content_get
Fetch repo Content markdown by kind. For readme/agents, returns a synthesized empty stub when nothing has been written — never null. kind: llms-txt always returns a synthesized response with the rendered sitemap and a structured refs field. Read-only.
warmhub_repo_content_set
Set Content/Readme or Content/Agents markdown (commits an add or revise operation). Writes to kind: llms-txt are rejected — it is synthesized and cannot be stored. Requires things:write.
warmhub_repo_content_generate
AI-generate a draft for kind: readme or kind: agents from the repo’s current shapes, things, and assertions. Returns { content: string }. Does not commit. Requires things:write.
For kind: readme and kind: agents, returns the stored content thing after the first write. When nothing has been written yet, the response is a synthesized empty stub ({ synthesized: true, shape: "Content", name: "...", data: { content: "" }, active: true }).
For kind: llms-txt, always returns a synthesized response. data.content contains the full rendered markdown, and the response includes a refs field with partitioned outbound/inbound references; cross-org refs the caller cannot read are omitted. (MCP requests are always authenticated; for the anonymous reduced-body variant of llms.txt, see Content Shape.)
One of readme, agents, or llms-txt. llms-txt is read-only — set attempts are rejected.
content
string
yes
Markdown content to store
Returns the standard single-operation commit result: operationCount, one operations[] entry (name, operation, version, dataHash), plus optional committer, createdByEmail, and message metadata. Unlike warmhub_commit_submit, this helper does not return partial-result fields; rejected writes surface as tool errors.
List all items at HEAD with optional filters (shape, kind, glob match). Use to enumerate a repo’s current state; for fuzzy lookups use warmhub_thing_search.
warmhub_thing_get
Fetch one thing/assertion/collection by wref. For many wrefs in one call use warmhub_thing_get_many; to resolve a wref’s canonical identity first use warmhub_wref_resolve.
warmhub_thing_graph
Get one thing and its embedded assertion/about/wref graph to a bounded depth.
warmhub_thing_get_many
Batch-fetch things by wref in one call — prefer over looping warmhub_thing_get. Missing wrefs are returned in a missing array.
warmhub_thing_history
List version history for a thing. Provide wref for one thing’s history, or shape/about to survey history across matching things. With about, resolveCollections:true includes assertions about collections containing the target identity.
warmhub_thing_about
List assertions whose about target resolves to the supplied target identity. For identity-scoped inputs, use resolveCollections:true to include assertions about Pair/Triple/Set/List collections containing the target; pinned @vN inputs stay version-exact. Use warmhub_thing_refs with direction:"inbound" for broader backlink discovery.
warmhub_thing_query
Query things by structured filters (shape, kind, about, glob match). Best for exact/structured lookups; for fuzzy or semantic search use warmhub_thing_search.
warmhub_thing_search
Full-text/vector/hybrid search across thing data. Best for fuzzy lookups; for exact field matches use warmhub_thing_query with a glob filter.
warmhub_thing_refs
List inbound or outbound refs for a target wref. Use direction:"inbound" to find what references X. Pair with warmhub_thing_get to resolve details.
warmhub_wref_resolve
Resolve a wref (local or canonical) to its canonical thing identity. Accepts cross-repo canonical wrefs (wh:org/repo/Shape/name); pair with warmhub_thing_get to fetch the resolved data.
Returns the root thing with readable assertion about links and readable wref-typed fields embedded as objects. Refs the caller cannot read remain string wrefs, with no internal IDs or denial reasons exposed.
Return things even when retracted at HEAD or at the requested version (mirrors warmhub_thing_get)
Missing wrefs are returned in a missing array. When a top-level version is supplied and the input wref is not already pinned, missing entries are version-qualified (Shape/name@vN) so the round-trip is unambiguous; per-wref pins survive intact (no double-pinning). Duplicates in wrefs are not deduped — they count toward the 500-entry cap and produce duplicate items/missing entries.
By default, this tool returns assertions whose about target resolves to the supplied target identity. It does not expand collection member refs, so assertions about Pair, Triple, Set, or List collection things that contain the target appear only when resolveCollections:true is set on identity-scoped inputs: bare wrefs, @HEAD, or @ALL. Pinned @vN inputs stay version-exact and do not expand collection members.
For broader graph discovery, use warmhub_thing_refs with direction:"inbound" to find current things that reference the target through wref fields. Use warmhub_thing_about when you specifically need assertion records and about-target filtering.
Param
Type
Required
Description
wref
string
yes
Target thing wref
shape
string
no
Filter assertions by shape
match
string
no
Glob pattern to filter assertion wrefs
resolveCollections
boolean
no
Include assertions about Pair/Triple/Set/List collections containing the target thing for identity-scoped inputs; ignored for pinned @vN inputs
includeRetracted
boolean
no
Resolve a retracted target and include retracted assertions
Filter by about target (not supported with vector mode)
match
string
no
Glob pattern to filter wrefs
resolveCollections
boolean
no
When about is set, also include assertions about collections containing the target (text mode only)
mode
string
no
"text" (default), "vector", or "hybrid"
includeRetracted
boolean
no
Include retracted entities
componentId
string
no
Filter results to items owned by the given component
excludeComponents
boolean
no
Exclude component-owned items from results. Cannot be combined with componentId.
excludeInfraShapes
boolean
no
Hide internal infra shapes from results
limit
integer
no
Max results. Must be between 1 and 500.
cursor
string
no
Pagination cursor from previous response (text mode only — vector and hybrid reject cursor). When about or resolveCollections is set, pages may be sparse — paginate until nextCursor is absent.
Direction "inbound" returns things that reference the target wref. Direction "outbound" returns things the target wref references.
Use inbound refs as a broad discovery tool when you are unsure whether data points directly at a thing or at a collection containing it. Inbound refs are not a substitute for warmhub_thing_about when you need assertion-only results or assertion filters.
Cross-repo wref lookups (canonical form wh:org/repo/Shape/name) require effective repo:read permission on the target repo. Public repos are readable by anyone. For private repos, callers without that access see an error — except warmhub_thing_search with a cross-repo about (returns { items: [] }) and warmhub_thing_get_many (puts unreadable wrefs into missing[]) — both to keep batch and search streaming-friendly.
The tool returns per-operation results. Per-op failures show up as operations[] entries with status: "error" and partial: true. For the full operation contract and shape-specific write examples, call warmhub_repo_describe and inspect the commitContract field. Opinion-bearing assertions must be binary propositions.
See MCP Error Handling for the full failure taxonomy. Ambiguous append failures (a separate class from per-op failures) return a tool-result error with continuation recovery state; the failed append may have landed server-side, so inspect repository state before deciding whether to resume.
Param
Type
Required
Description
committer
string
no
Optional wref identifying the actor on whose behalf the writes are made (e.g. Agent/bot-1). Omit to attribute to the authenticated user via createdByEmail.
componentId
string
no
Attribute writes to an installed component. See component identity rules below.
message
string
no
Optional message recorded with each thing-version produced by this call
operations
array
yes
Operations array (non-empty). When resuming after an ambiguous append failure, pass only the operations that haven’t been acknowledged (the prior attempt’s slice from operationOffset onward).
streamId
string
no
When resuming after an ambiguous append failure, copy the streamId from the prior error’s continuation payload.
allocatedTokens
array
no
When resuming, copy allocatedTokens from the prior error’s continuation payload. Must accompany the matching streamId.
operationOffset
integer
no
When resuming, copy operationOffset from the prior error’s continuation payload.
Component identity rules:
User tokens may claim components installed by that user.
Callers with org:configure for the org may claim any installed component in the org.
Action tokens derive the component from the running subscription and reject mismatched explicit values.
REVISE shape/thing/assertion: { operation: "revise", kind, name, data }
RETRACT: { operation: "retract", name, reason? } — withdraws the entity from default reads; kind is an optional hint
Token rules: $N allocates in the last segment of add-operation names. #N references prior allocations in the same stream. Write path rejects @ALL.
Per-operation result warnings:
Successful and noop result entries can include:
{
"warnings": {
"undeclaredFields": ["status", "filePath"],
"undeclaredFieldsTruncated": true,
"totalUndeclared": 600
}
}
warnings.undeclaredFields lists top-level keys present in the submitted data but not declared in the target shape. When the list is capped, undeclaredFieldsTruncated: true is set and totalUndeclared reports the full count. This warning is informational; it does not turn the operation into a failure.
For add operations, skipExisting: true returns noop when the target already exists instead of failing.
Unauthorized component claims reject with FORBIDDEN.
Both warmhub_shape_get and warmhub_shape_list include a queryHints block (queryableFields, wrefFields, suggestedPatterns) to help agents choose warmhub_thing_query, warmhub_thing_search, and warmhub_thing_refs patterns for each shape.
Shape to subscribe to. For webhook subscriptions, provide either shapeName or filterJson.shape — except for shape lifecycle subscriptions, which omit both and rely on a {"kind":"shape", ...} filter.
filterJson
object
no
Filter object for matching write operations (required for webhook, not needed for cron)
webhookUrl
string
no
Webhook endpoint URL (required for both kinds)
fallbackWebhookUrl
string
no
Optional fallback endpoint called after a terminal delivery failure
cronConfig
object
no
Cron configuration with cronspec and optional timezone (required when kind is "cron")
Returns repo-scoped action notification records for action deliveries, including terminal failures and optional success notifications. This is distinct from the web app’s cross-repo user notification feed.
