# MCP Server

The ContextNest (Community) server exposes vault operations as MCP tools that any MCP-compatible AI client can call. Every tool is named `context_*` (with a handful of server-level `nest_*` tools on the cross-nest endpoint). Tool list verified against `Community/src/mcp/tools.ts`.

## Endpoints

The server offers two MCP surfaces:

- **Per-nest** — `POST/GET/DELETE <base>/nests/<nest-id>/mcp` — the full toolset, including writes. Scoped to a single nest.
- **Server-level (cross-nest)** — `ALL <base>/mcp` — one stateless connection for everything readable across the nests you can see, plus a small set of safe writes. Carries `nest_index` and read tools; the only writes are `nest_create` and `context_create` (creating into a brand-new nest, where there is no cross-nest authz to get wrong).

## Configuration

Point your MCP client at the endpoint (streamable HTTP). For a local stdio-style setup:

```json
{
  "mcpServers": {
    "contextnest": {
      "command": "contextnest-mcp-server",
      "args": ["--vault", "/path/to/your/vault"]
    }
  }
}
```

## Always-on tools

These `context_*` tools are registered on every per-nest connection (from `TOOL_DEFINITIONS` in `tools.ts`).

### Retrieval & read

| Tool | Purpose |
|------|---------|
| `context_init` | Load the vault's `CONTEXT.md` (operating instructions / behavioral guidelines). Call this FIRST in every conversation. |
| `context_overview` | Complete map of the vault: node count, types, tags, and a title+snippet for every node. |
| `context_search` | Full-text keyword search across all node content, titles, tags, and metadata. |
| `context_query` | Structured selector query (`#tag`, `type:X`, `[[Title]]`, `scope:X`; combine with `+` AND, `|` OR, `-` NOT). Graph-aware; `hops` sets traversal depth (default 2). |
| `context_table_query` | Deterministic row lookup against a TABLE node (CSV fact store): `where <col> <op> <value> … [select cols] [limit N]`. Same query + same version = same rows. |
| `context_get` | Full content of a specific node by title or ID. |
| `context_list` | Browse vault contents with optional type / tag / status / limit filters. |
| `context_resolve` | Full context resolution — run a selector and return complete node content within a token budget. |
| `context_export` | Export the ENTIRE nest as one markdown bundle (every accessible document's full content), respecting an optional token budget. |
| `context_comments` | Get the review comments/annotations on a document — anchored quotes, threaded replies, open/resolved status. |

### Authoring

| Tool | Purpose |
|------|---------|
| `context_create` | Create a new knowledge node (title must be unique). |
| `context_update` | Update a node — replace or append content, set tags, move it through its lifecycle. Whether the edit publishes is decided by the nest's stewardship rules, not the caller. |
| `context_delete` | Delete a node by title or id, removing everything keyed to it (history, review state, annotations, watchers, grants, steward assignments). Irreversible. |
| `context_move` | Refile a node to a new folder/id (Community-edition concern — the id rewrite spans governance tables). |

### Governance & review

| Tool | Purpose |
|------|---------|
| `context_stewards` | Show the data stewards for a node, or list all stewards for the vault. |
| `context_request_deletion` | Ask for a document / folder / whole nest to be deleted when you can't delete it yourself — opens a request for an owner/admin. |
| `context_deletion_queue` | Show deletion requests waiting on an owner/admin: what was flagged, who asked, and why. |
| `context_resolve_deletion` | Action a deletion request — delete the flagged target, or reject with a note. Owner/admin only. |
| `context_review_queue` | Show documents pending review (need a steward to approve/reject before they're available to AI). |
| `context_my_drafts` | List YOUR unsubmitted drafts (and any that came back rejected) — invisible to the review queue and to AI until submitted and approved. |
| `context_submit_review` | Submit a node for steward review; marks it pending and notifies stewards. |
| `context_approve` | Approve a pending node — its approved version becomes available to AI queries. Approvers only. |
| `context_reject` | Reject a pending node with a required note explaining what needs to change. Stewards only. |
| `context_versions` | Show a node's version history — edits, authors, approval status, and which version is currently approved for AI. |
| `context_assign_steward` | Assign a steward to govern a scope (nest, tag, or a specific document). |

### Sharing & sync

| Tool | Purpose |
|------|---------|
| `context_share_nest` | Share the whole nest with a person (viewer = read, editor = read+edit, admin = full except deleting the nest). |
| `context_grant` | Share a SINGLE document or folder with a person (read or write). Owner/admin only. |
| `context_unsynced_list` | List folders under the data root that are sync candidates (not yet converted into a nest). Server-admin only in non-open mode. |
| `context_sync_folder` | Convert a sibling folder under the data root into a real nest (imports markdown, seeds governance, removes the source folder). Server-admin only in non-open mode. |

> Note: `context_delete` and `context_move` are present in `tools.ts` and registered on the per-nest surface, in addition to the tools listed in the update brief.

## Server-level (`/mcp`) toolset

The cross-nest endpoint advertises a reduced set: `nest_index`, `nest_create`, `context_query`, `context_search`, `context_get`, `context_list`, `context_overview`, `context_resolve`, and `context_create`. Reads span the nests you can see; the only writes are `nest_create` and `context_create` (into a new nest).

## Workflow-plane tools (`workflow_*`)

A second family of tools — `workflow_run`, `workflow_run_step`, `workflow_run_close`, `workflow_run_get`, `workflow_runs_list`, `workflow_edges_list`, `workflow_edge_create`, `workflow_edge_delete`, `workflow_edge_types_list`, `workflow_edge_type_upsert`, `workflow_edge_type_delete` — is advertised **only when `FEATURE_WORKFLOW_PLANE` is enabled**. The flag is read per request (the server is rebuilt per call), so toggling it at runtime takes effect immediately. When off, these tools do not appear in the tool list at all.

## Deprecated legacy aliases

Earlier releases exposed a different tool vocabulary (e.g. `read_document`, `list_documents`, `search`, `create_document`, `update_document`, `delete_document`, `publish_document`, `vault_info`, `resolve`, `get_history`, …). These older names are retained as **deprecated aliases** that map onto the canonical `context_*` catalog above, so existing clients keep working. New integrations should use the `context_*` names.

## Error handling

Tool results carry structured error signaling, not just prose. A denial / not-found / failure sets `isError: true` on the MCP `CallToolResult` and attaches a machine-readable `{ code, message }` in `structuredContent` — codes are the engine's `ERROR_CODES` (`DOCUMENT_NOT_FOUND`, `DOCUMENT_ALREADY_EXISTS`, `UNAUTHORIZED_ACTION`, `VERSION_NOT_FOUND`, `INTERNAL`). Chat clients keep reading the unchanged prose `content`; machine callers (such as `ctx` driving the server over MCP) read the structured half and map it back to a typed engine error instead of string-matching a sentence. The read/query/create/update/delete/versions and `context_submit_review` tools also return their catalog JSON payload as `structuredContent` alongside the prose.

## How it works

The server wraps the same engine used by the CLI, reading from and writing to nests on disk (or a hosted store), so any MCP client — Claude, Cursor, VS Code with Copilot, and others — can operate on your knowledge through the tools above. Under stewardship, writes and reads respect approval state: unapproved drafts are gated from AI queries until a steward approves them.