# Outils MCP

Les 39 outils que barrel_server 1.15.1 enregistre sur /mcp, produits à partir de sa réponse tools/list (MCP 2025-06-18, capturée le 2026-11-14). Les descriptions sont le texte du serveur lui-même, en anglais. JSON : https://barrel-db.eu/docs/reference/mcp-tools.json

## Bases et documents

### changes

Annotations : lecture seule.

Read the changes feed from a cursor (absent = from the start). Returns the changes and the next cursor.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |
| `since` | string | non |  |

### db_create

Annotations : idempotent.

Create (or open) a database by name.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |

### db_info

Annotations : lecture seule.

Info about a database: document count, lineage, retention.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |

### db_list

Annotations : lecture seule.

List the databases currently open on this node (scoped to your grant).

Aucun argument.

### doc_delete

Annotations : destructif.

Delete a document by id.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |
| `id` | string | oui |  |
| `session` | string | non |  |

### doc_get

Annotations : lecture seule.

Read a document by id.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |
| `id` | string | oui |  |

### doc_put

Write a document (the doc object must carry its id). Optional session tags the write's provenance.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |
| `doc` | object | oui |  |
| `session` | string | non |  |

## Requêtes et recherche

### ngram_search

Annotations : lecture seule.

Exact substring or regex search over a database's documents via a trigram index. mode literal (default) or regex; each hit carries the document id and match spans.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |
| `query` | string | oui |  |
| `limit` | integer | non |  |
| `mode` | string | non |  |

### query

Annotations : lecture seule.

Run a BQL query. Rows are bounded by max_rows (default 100, cap 1000); pass the returned continuation to page. SUBSCRIBE statements are rejected: use query_subscribe.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |
| `query` | string | oui |  |
| `continuation` | string | non |  |
| `max_rows` | integer | non |  |
| `params` | object | non |  |

### query_subscribe

Start a live query from a BQL SUBSCRIBE statement. Returns a resource URI: read it for the materialized rows, subscribe to it for update notifications.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |
| `query` | string | oui |  |
| `params` | object | non |  |

### query_unsubscribe

Annotations : idempotent.

Stop a live query by sub id.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `sub` | string | oui |  |

### search

Annotations : lecture seule.

Search a database: mode bm25 or hybrid with a query string, mode vector with a query vector.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |
| `mode` | string | oui |  |
| `k` | integer | non |  |
| `query` | string | non |  |
| `vector` | tableau de any | non |  |

## Branches

### branch_create

Fork a database into a branch, optionally at a changes cursor.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |
| `name` | string | oui |  |
| `at` | string | non |  |

### branch_list

Annotations : lecture seule.

List a database's branches and its own lineage.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |

### merge

Annotations : destructif.

Merge a branch back into its parent.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `db` | string | oui |  |

## Espaces, sessions et passations

### handoff_accept

Accept a handoff by presenting its token: opens the shared space and creates a session in it (context is read in place).

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `token` | string | oui |  |
| `agent` | string | non |  |

### handoff_complete

Complete a handoff (revokes its token by default).

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `token` | string | oui |  |
| `notes` | string | non |  |
| `result` | any | non |  |
| `revoke` | boolean | non |  |

### handoff_create

Hand work off: issues a capability for the space and returns its token once; whoever holds the token accepts.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `space` | string | oui |  |
| `task_name` | string | oui |  |
| `completed` | tableau de any | non |  |
| `context` | any | non |  |
| `expires_at` | integer | non |  |
| `from_agent` | string | non |  |
| `from_session` | string | non |  |
| `pending` | tableau de any | non |  |
| `rights` | tableau de any | non |  |
| `to_agent` | string | non |  |

### handoff_list

Annotations : lecture seule.

Handoffs, filtered by space, status, to_agent, from_agent (capability callers see their own space only).

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `from_agent` | string | non |  |
| `space` | string | non |  |
| `status` | string | non |  |
| `to_agent` | string | non |  |

### session_add_message

Append a message to a session's history.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `content` | any | oui |  |
| `role` | string | oui |  |
| `session` | string | oui |  |
| `space` | string | oui |  |
| `metadata` | object | non |  |

### session_create

Create a working session in a space (sliding TTL).

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `space` | string | oui |  |
| `agent` | string | non |  |
| `data` | object | non |  |
| `ttl` | integer | non |  |

### session_get_messages

Annotations : lecture seule.

A session's messages in chronological order (since/before unix ms, limit, order asc|desc).

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `session` | string | oui |  |
| `space` | string | oui |  |
| `before` | integer | non |  |
| `limit` | integer | non |  |
| `order` | string | non |  |
| `since` | integer | non |  |

### session_touch

Slide a session's TTL.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `session` | string | oui |  |
| `space` | string | oui |  |

### space_create

Create a space: a shared context database agents reach with capability tokens. Management only.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `label` | string | non |  |
| `owner` | string | non |  |
| `purpose` | string | non |  |
| `session_ttl` | integer | non |  |
| `vectordb` | object | non |  |

### space_grant

Issue a capability token for a space (rights: read, write, admin). The token is shown once.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `space` | string | oui |  |
| `expires_at` | integer | non |  |
| `label` | string | non |  |
| `rights` | tableau de any | non |  |
| `subject` | string | non |  |

### space_info

Annotations : lecture seule.

The registry document of a space.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `space` | string | oui |  |

### space_revoke

Annotations : destructif, idempotent.

Revoke a grant of a space by token id.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `space` | string | oui |  |
| `token_id` | string | oui |  |

## Contextes et ensembles de travail

### context_attach

Add a context to a working set: the contexts you work with, which context_materialize and context_import can copy locally for offline use. Omit working_set to create one; the answer's id is the working set to pass next. Logical: nothing is opened or copied. Example: {"context": "otp/tools"}.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `context` | string | oui | A context name (e.g. "otp/sasl") or id (ctx_...). |
| `credential_ref` | string | non | Name of a token in the node's ctx_credentials, for a remote location. |
| `mode` | string | non | Which location of the card to use. Default: local if the card has one, else remote. Une valeur parmi `local`, `remote`. |
| `working_set` | string | non | Working-set id (ws_...). Omit to create a new working set. |

### context_capabilities

Annotations : lecture seule.

What a context query may look like: the accepted statement shapes with examples, the merges, the limits (contexts per query, largest LIMIT, timeouts), working-set budgets and whether the node is offline. Call it before a first context_query. No arguments.

Aucun argument.

### context_detach

Annotations : destructif.

Remove a context from a working set; a saved slice of it is deleted. Returns the working set. Example: {"working_set": "ws_...", "context": "otp/eunit"}.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `context` | string | oui | A context name (e.g. "otp/sasl") or id (ctx_...). |
| `working_set` | string | oui | Working-set id (ws_...), from context_attach or context_working_sets. |

### context_discover

Annotations : lecture seule.

Find contexts about a topic: every word of q must appear in a card's name, title, description or topics (a plural matches its stem). A filter, not a ranking: other contexts may still hold answers. Returns {contexts, summary}. Example: {"q": "release"}.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `q` | string | oui | Words to look for, e.g. "release handling". |

### context_import

Import a published snapshot (a directory written by an export, holding manifest.json) into this node, read only, as a working-set member that answers offline for that generation. Omit working_set to create one. Example: {"dir": "/srv/export_sasl_g1"}.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `dir` | string | oui | Path of the export directory on this node. |
| `name` | string | non | Local database name for the copy. Default: derived from the context and generation. |
| `working_set` | string | non | Working-set id (ws_...). Omit to create a new working set. |

### context_inspect

Annotations : lecture seule.

Read one context card: where it lives (local db, or remote endpoint and db), title, topics, embedding. Example: {"context": "otp/sasl"}.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `context` | string | oui | A context name (e.g. "otp/sasl") or id (ctx_...). |

### context_list

Annotations : lecture seule.

List the registered contexts: named datasets, each a database on this node or on a remote Barrel server. Returns {contexts: [card]}; pass a card's name (or id) to the other context tools. Example: {"prefix": "otp/"}.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `prefix` | string | non | Only names starting with this text, e.g. "otp/". |
| `unlisted` | boolean | non | Include cards registered as unlisted. Défaut `false`. |

### context_materialize

Save the documents a query returns into a working set so they answer offline: one frozen slice per answering context, holding exactly those documents (by id). Omit working_set to create one. A context already in the working set must be detached first. Example: {"from_query": {"query": "SELECT b.id FROM bm25_top_k('test', k => 5) AS b", "contexts": ["otp/eunit"]}}.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `from_query` | object | oui | The query whose rows (by id) are saved. |
| `include` | object | non | What to copy besides documents. |
| `max_bytes` | integer | non | Refuse the slice when the fetched documents are larger than this. Au moins 1. |
| `working_set` | string | non | Working-set id (ws_...). Omit to create a new working set. |

### context_offline

Annotations : idempotent.

Read or switch the node's offline mode. Offline, remote contexts are skipped and never contacted; local databases, slices and snapshots still answer. Omit offline to read the mode. Example: {"offline": true}.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `offline` | boolean | non | true to go offline, false to go back online. |

### context_query

Annotations : lecture seule.

Run one BQL statement over several contexts (names or ids) or over a working set. Returns rows (or groups per context), one sources entry per context saying whether it answered and what its answer covers, and a summary: read it first. Row queries need LIMIT (<= 1000); add ORDER BY a selected field to merge rows in order. isError is true when no context answered. Example: {"query": "SELECT id, lines FROM c ORDER BY lines DESC LIMIT 10", "contexts": ["otp/tools", "otp/sasl"]}.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `query` | string | oui | One BQL statement. Strings use single quotes. Shapes: see context_capabilities. |
| `contexts` | tableau de string | non | Context names or ids. Give this or working_set, not both. De 1 à 8 éléments. |
| `deadline_ms` | integer | non | Deadline for the whole request, at most 60000. Défaut `5000`. Au moins 1. |
| `max_parallel` | integer | non | Remote contexts queried at once, at most 16. Défaut `8`. Au moins 1. |
| `merge` | string | non | Leave unset for the default: ordered with ORDER BY, grouped otherwise, score for comparable vector_top_k. Une valeur parmi `ordered`, `grouped`, `interleave`, `score`. |
| `offline` | boolean | non | true: answer from local copies only, never contact a remote server. Default: the node's offline mode. |
| `params` | object | non | Values for $name parameters in the statement. |
| `per_context_timeout_ms` | integer | non | Deadline per context, at most 60000. Défaut `4000`. Au moins 1. |
| `working_set` | string | non | A working-set id (ws_...) instead of contexts: queries its members, local copies first. |

### context_working_set_delete

Annotations : destructif.

Delete a working set and the slices it saved (imported snapshots stay). Example: {"working_set": "ws_..."}.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `working_set` | string | oui | Working-set id (ws_...), from context_attach or context_working_sets. |

### context_working_sets

Annotations : lecture seule.

List the working sets on this node with their member names, or, given working_set, read one in full: each member's mode, membership (what its answers cover), answers_offline, budget, usage and a summary. Example: {} or {"working_set": "ws_..."}.

| Argument | Type | Obligatoire | Description |
|---|---|---|---|
| `working_set` | string | non | Working-set id (ws_...), from context_attach or context_working_sets. |
