648 lines
16 KiB
Markdown
648 lines
16 KiB
Markdown
# MCP Server Tools Reference
|
||
|
||
The YAMS MCP server exposes **3 composite tools** — `query`, `execute`, and `session` — that consolidate all operations into a compressed tool surface (~800 tokens vs ~4,000 for individual tools). Agents discover operation schemas on demand via the built-in `describe` operation.
|
||
|
||
<!-- Design rationale: docs/design/mcp-code-mode.md (internal) -->
|
||
|
||
## Overview
|
||
|
||
```bash
|
||
# Start the MCP server (stdio transport)
|
||
yams serve
|
||
```
|
||
|
||
### Tool Surface
|
||
|
||
| Tool | Purpose | Operations |
|
||
|------|---------|------------|
|
||
| `query` | Read-only pipeline | `search`, `grep`, `list`, `list_collections`, `list_snapshots`, `suggest_context`, `semantic_dedupe`, `graph`, `get`, `status`, `describe` |
|
||
| `execute` | Write batch | `add`, `update`, `delete`, `restore`, `download` |
|
||
| `session` | Session lifecycle | `start`, `stop`, `pin`, `unpin`, `watch` |
|
||
|
||
### Progressive Discovery
|
||
|
||
Use the `describe` operation to discover the full parameter schema for any op at runtime — no need to memorize schemas:
|
||
|
||
```json
|
||
{"steps": [{"op": "describe", "params": {"target": "search"}}]}
|
||
```
|
||
|
||
Omit `target` to list all available operations:
|
||
|
||
```json
|
||
{"steps": [{"op": "describe"}]}
|
||
```
|
||
|
||
## Prompt Templates
|
||
|
||
### prompts/list
|
||
|
||
List available prompt templates (built-ins and file-backed). File-backed templates are Markdown files named `PROMPT-*.md` in the configured prompts directory (see user guide). Names are derived by stripping `PROMPT-` and extension and converting dashes to underscores.
|
||
|
||
**Response:**
|
||
```json
|
||
{
|
||
"prompts": [
|
||
{"name": "search_codebase", "description": "Search for code patterns in the codebase", "arguments": [...]},
|
||
{"name": "research_mcp", "description": "Research workflow for MCP (from PROMPT-research-mcp.md)"}
|
||
]
|
||
}
|
||
```
|
||
|
||
### prompts/get
|
||
|
||
Get a prompt template by name. File-backed prompts return the entire Markdown content as a single assistant message.
|
||
|
||
**Request:**
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"method": "prompts/get",
|
||
"params": {"name": "research_mcp"}
|
||
}
|
||
```
|
||
|
||
**Response:**
|
||
```json
|
||
{
|
||
"jsonrpc": "2.0",
|
||
"id": 1,
|
||
"result": {
|
||
"messages": [
|
||
{"role": "assistant", "content": {"type": "text", "text": "...markdown content..."}}
|
||
]
|
||
}
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Tool 1: `query` — Read Pipeline
|
||
|
||
Read-only operations with multi-step pipeline support. Each step's result is available as `$prev` in subsequent steps.
|
||
|
||
**Input Schema:**
|
||
```json
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"steps": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"op": {
|
||
"type": "string",
|
||
"enum": ["search", "grep", "list", "list_collections", "list_snapshots", "suggest_context", "semantic_dedupe", "graph", "get", "status", "describe"]
|
||
},
|
||
"params": { "type": "object" }
|
||
},
|
||
"required": ["op"]
|
||
}
|
||
}
|
||
},
|
||
"required": ["steps"]
|
||
}
|
||
```
|
||
|
||
**Annotations:** `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`
|
||
|
||
**Single-step shortcut:** When `steps` has exactly one element, the response is the direct result (no wrapper array).
|
||
|
||
### `$prev` Reference Syntax
|
||
|
||
String values in `params` can reference the previous step's result:
|
||
|
||
| Pattern | Resolves To |
|
||
|---------|-------------|
|
||
| `$prev` | Entire previous result object |
|
||
| `$prev.field` | Top-level field |
|
||
| `$prev.field[N]` | Array element at index N |
|
||
| `$prev.field[N].subfield` | Nested field within array element |
|
||
|
||
If resolution fails (missing field, out-of-bounds index), the param receives `null`. `$prev` is `{}` for the first step.
|
||
|
||
### Query Operations Reference
|
||
|
||
#### suggest_context
|
||
|
||
Suggest relevant memory snapshots for a draft topic or query by grouping existing search evidence by `snapshot_id`.
|
||
|
||
**Key Parameters:**
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `query` | string | *(required)* | Draft topic or query text |
|
||
| `limit` | integer | 5 | Maximum snapshot suggestions |
|
||
| `use_session` | boolean | false | Scope evidence to current or provided session |
|
||
| `session` | string | — | Specific session name |
|
||
| `global_search` | boolean | false | Bypass session isolation when session scoping is enabled |
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"steps": [{"op": "suggest_context", "params": {"query": "auth middleware refresh tokens", "limit": 3}}]
|
||
}
|
||
```
|
||
|
||
**Behavior note:**
|
||
|
||
When `session` scoping is enabled, `suggest_context` suppresses the most recently served snapshot set for the same normalized query. This keeps long-running sessions from immediately re-suggesting identical context on back-to-back calls.
|
||
|
||
**Response:**
|
||
```json
|
||
{
|
||
"query": "auth middleware refresh tokens",
|
||
"total": 2,
|
||
"suggestions": [
|
||
{
|
||
"snapshot_id": "2026-04-02T12:00:00Z",
|
||
"label": "auth rollout",
|
||
"directory_path": "/repo/auth",
|
||
"score": 2.1,
|
||
"supporting_result_count": 2,
|
||
"supporting_results": [
|
||
{"id": "123", "hash": "abc...", "title": "Auth ADR", "path": "/repo/auth/adr.md", "score": 1.1}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### semantic_dedupe
|
||
|
||
Inspect persisted semantic duplicate groups and their member documents.
|
||
|
||
**Key Parameters:**
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `group_key` | string | — | Return one specific semantic duplicate group |
|
||
| `document_ids` | array<int> | — | Return groups containing these documents |
|
||
| `limit` | integer | 25 | Maximum groups to return |
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"steps": [{"op": "semantic_dedupe", "params": {"limit": 10}}]
|
||
}
|
||
```
|
||
|
||
**Response:**
|
||
```json
|
||
{
|
||
"total": 1,
|
||
"groups": [
|
||
{
|
||
"group_key": "semantic:keep-newest:0.920:hash-a,hash-b",
|
||
"algorithm_version": "semantic-dedupe-v1",
|
||
"status": "suggested",
|
||
"review_state": "pending",
|
||
"canonical_document_id": 12,
|
||
"member_count": 2,
|
||
"max_pair_score": 0.97,
|
||
"threshold": 0.92,
|
||
"evidence_json": "{...}",
|
||
"members": [
|
||
{"document_id": 12, "role": "canonical", "decision": "keep"},
|
||
{"document_id": 19, "role": "duplicate", "pair_score": 0.93}
|
||
]
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### search
|
||
|
||
Search for documents using keyword, semantic, or hybrid search with optional fuzzy matching.
|
||
|
||
**Key Parameters:**
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `query` | string | *(required)* | Search query text |
|
||
| `limit` | integer | 10 | Maximum results |
|
||
| `type` | string | `"hybrid"` | `keyword`, `semantic`, or `hybrid` |
|
||
| `fuzzy` | boolean | true | Enable fuzzy matching |
|
||
| `similarity` | number | 0.7 | Fuzzy match threshold (0.0–1.0) |
|
||
| `hash` | string | — | Search by content hash (full or partial, min 8 chars) |
|
||
| `paths_only` | boolean | false | Return only file paths |
|
||
| `line_numbers` | boolean | false | Show line numbers with matches |
|
||
| `context` | integer | 0 | Lines of context around matches |
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"steps": [{"op": "search", "params": {"query": "database optimization", "limit": 5}}]
|
||
}
|
||
```
|
||
|
||
**Response:**
|
||
```json
|
||
{
|
||
"total": 42,
|
||
"type": "full-text",
|
||
"execution_time_ms": 25,
|
||
"results": [
|
||
{
|
||
"id": 123,
|
||
"hash": "abcd1234...",
|
||
"title": "Document Title",
|
||
"path": "/path/to/document",
|
||
"score": 0.95,
|
||
"snippet": "...relevant content preview..."
|
||
}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### grep
|
||
|
||
Search for regex patterns within document contents.
|
||
|
||
**Key Parameters:**
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `pattern` | string | *(required)* | Regular expression pattern |
|
||
| `paths` | array | all indexed | Files or directories to search |
|
||
| `ignore_case` | boolean | false | Case-insensitive search |
|
||
| `line_numbers` | boolean | false | Show line numbers |
|
||
| `context` | integer | 0 | Lines of context around matches |
|
||
| `word` | boolean | false | Match whole words only |
|
||
| `count` | boolean | false | Show only count of matching lines |
|
||
| `files_with_matches` | boolean | false | Show only filenames with matches |
|
||
| `max_count` | integer | 0 | Stop after N matches per file |
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"steps": [{"op": "grep", "params": {"pattern": "class\\s+\\w+Handler", "line_numbers": true, "context": 2}}]
|
||
}
|
||
```
|
||
|
||
#### list
|
||
|
||
List documents with filtering and sorting.
|
||
|
||
**Key Parameters:**
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `limit` | integer | — | Maximum documents |
|
||
| `offset` | integer | 0 | Pagination offset |
|
||
| `sort_by` | string | — | `name`, `size`, `created`, `modified`, `indexed` |
|
||
| `sort_order` | string | — | `asc` or `desc` |
|
||
| `recent` | integer | — | Show N most recent documents |
|
||
| `type` | string | — | Filter: `text` or `binary` |
|
||
| `extension` | string | — | Filter by file extension |
|
||
| `paths_only` | boolean | false | Return only file paths |
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"steps": [{"op": "list", "params": {"extension": ".py", "recent": 10, "sort_by": "modified", "sort_order": "desc"}}]
|
||
}
|
||
```
|
||
|
||
#### get
|
||
|
||
Retrieve a document by content hash with optional knowledge graph relationships.
|
||
|
||
**Key Parameters:**
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `hash` | string | *(required)* | Document content hash |
|
||
| `outputPath` | string | — | Write content to this path |
|
||
| `graph` | boolean | false | Include related documents |
|
||
| `depth` | integer | 2 | Graph traversal depth (1–5) |
|
||
| `include_content` | boolean | false | Include full content in response |
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"steps": [{"op": "get", "params": {"hash": "e3b0c442...", "include_content": true}}]
|
||
}
|
||
```
|
||
|
||
#### graph
|
||
|
||
Query the knowledge graph.
|
||
|
||
**Key Parameters:**
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `hash` | string | — | Document hash |
|
||
| `name` | string | — | Document name/path |
|
||
| `node_key` | string | — | Direct KG node key |
|
||
| `list_types` | boolean | — | List available node types with counts |
|
||
| `list_type` | string | — | List nodes of a specific type |
|
||
| `relation` | string | — | Filter by relation type |
|
||
| `depth` | integer | — | Traversal depth (1–5) |
|
||
| `limit` | integer | 100 | Maximum results |
|
||
| `reverse` | boolean | — | Traverse incoming edges |
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"steps": [{"op": "graph", "params": {"name": "src/main.cpp", "depth": 2, "relation": "CALLS", "limit": 50}}]
|
||
}
|
||
```
|
||
|
||
#### list_collections
|
||
|
||
List available collections. No required parameters.
|
||
|
||
```json
|
||
{"steps": [{"op": "list_collections"}]}
|
||
```
|
||
|
||
#### list_snapshots
|
||
|
||
List available snapshots. No required parameters.
|
||
|
||
```json
|
||
{"steps": [{"op": "list_snapshots"}]}
|
||
```
|
||
|
||
#### status
|
||
|
||
Get storage statistics and analytics.
|
||
|
||
**Parameters:**
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `detailed` | boolean | false | Include detailed breakdown |
|
||
| `file_types` | boolean | false | Include file type analysis |
|
||
|
||
**Example:**
|
||
```json
|
||
{"steps": [{"op": "status", "params": {"detailed": true}}]}
|
||
```
|
||
|
||
**Response:**
|
||
```json
|
||
{
|
||
"total_objects": 1000,
|
||
"total_bytes": 10485760,
|
||
"unique_blocks": 5000,
|
||
"deduplicated_bytes": 2097152,
|
||
"dedup_ratio": 0.2
|
||
}
|
||
```
|
||
|
||
#### describe
|
||
|
||
Return the full JSON Schema for any operation's parameters. See [Progressive Discovery](#progressive-discovery).
|
||
|
||
### Pipeline Examples
|
||
|
||
**Search → Get (retrieve top result's full content):**
|
||
```json
|
||
{
|
||
"steps": [
|
||
{"op": "search", "params": {"query": "authentication middleware", "limit": 1}},
|
||
{"op": "get", "params": {"hash": "$prev.results[0].hash", "include_content": true}}
|
||
]
|
||
}
|
||
```
|
||
|
||
**List → Grep (find pattern in recent documents):**
|
||
```json
|
||
{
|
||
"steps": [
|
||
{"op": "list", "params": {"limit": 50, "sort_by": "modified", "sort_order": "desc"}},
|
||
{"op": "grep", "params": {"pattern": "TODO|FIXME"}}
|
||
]
|
||
}
|
||
```
|
||
|
||
**Graph traversal (find dependencies of a file):**
|
||
```json
|
||
{
|
||
"steps": [
|
||
{"op": "graph", "params": {"name": "src/main.cpp", "relation": "IMPORTS", "depth": 2}},
|
||
{"op": "get", "params": {"hash": "$prev.nodes[0].hash"}}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Tool 2: `execute` — Write Batch
|
||
|
||
Write operations executed sequentially. Stops on first error unless `continueOnError` is set.
|
||
|
||
**Input Schema:**
|
||
```json
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"operations": {
|
||
"type": "array",
|
||
"items": {
|
||
"type": "object",
|
||
"properties": {
|
||
"op": {
|
||
"type": "string",
|
||
"enum": ["add", "update", "delete", "restore", "download"]
|
||
},
|
||
"params": { "type": "object" }
|
||
},
|
||
"required": ["op", "params"]
|
||
}
|
||
},
|
||
"continueOnError": {
|
||
"type": "boolean",
|
||
"default": false
|
||
}
|
||
},
|
||
"required": ["operations"]
|
||
}
|
||
```
|
||
|
||
**Annotations:** `readOnlyHint: false`, `destructiveHint: true`, `idempotentHint: false`
|
||
|
||
**Response:**
|
||
```json
|
||
{
|
||
"results": [
|
||
{"op": "add", "success": true, "hash": "sha256-abc123..."},
|
||
{"op": "update", "success": true, "matched": 1}
|
||
],
|
||
"totalOps": 2,
|
||
"succeeded": 2,
|
||
"failed": 0
|
||
}
|
||
```
|
||
|
||
### Execute Operations Reference
|
||
|
||
#### add
|
||
|
||
Store a document with optional metadata and tags.
|
||
|
||
**Key Parameters:**
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `path` | string | *(required)* | File path to store |
|
||
| `tags` | array | — | Document tags |
|
||
| `metadata` | object | — | Key-value metadata |
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"operations": [
|
||
{"op": "add", "params": {"path": "/tmp/notes.md", "tags": ["meeting", "2024-01"], "metadata": {"author": "Jane"}}}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### update
|
||
|
||
Update metadata for an existing document (identified by `hash` or `name`).
|
||
|
||
**Key Parameters:**
|
||
|
||
| Parameter | Type | Description |
|
||
|-----------|------|-------------|
|
||
| `hash` | string | Document hash |
|
||
| `name` | string | Document name/path |
|
||
| `metadata` | array | `key=value` pairs |
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"operations": [
|
||
{"op": "update", "params": {"name": "notes.md", "metadata": ["status=reviewed", "priority=high"]}}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### delete
|
||
|
||
Delete documents by name or glob pattern.
|
||
|
||
**Key Parameters:**
|
||
|
||
| Parameter | Type | Description |
|
||
|-----------|------|-------------|
|
||
| `name` | string | Document name or glob pattern |
|
||
| `names` | array | Multiple names/patterns |
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"operations": [
|
||
{"op": "delete", "params": {"name": "*.tmp"}}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### restore
|
||
|
||
Restore documents from a collection or snapshot to the filesystem.
|
||
|
||
**Key Parameters:**
|
||
|
||
| Parameter | Type | Default | Description |
|
||
|-----------|------|---------|-------------|
|
||
| `collection` | string | — | Collection name |
|
||
| `snapshot_id` | string | — | Snapshot ID |
|
||
| `output_directory` | string | *(required)* | Output directory |
|
||
| `dry_run` | boolean | false | Preview without writing |
|
||
| `overwrite` | boolean | false | Overwrite existing files |
|
||
| `include_patterns` | array | — | Only restore matching patterns |
|
||
| `exclude_patterns` | array | — | Exclude matching patterns |
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"operations": [
|
||
{"op": "restore", "params": {"collection": "docs", "output_directory": "/tmp/restore", "dry_run": true}}
|
||
]
|
||
}
|
||
```
|
||
|
||
#### download
|
||
|
||
Download and store an artifact by URL with optional checksum verification.
|
||
|
||
**Example:**
|
||
```json
|
||
{
|
||
"operations": [
|
||
{"op": "download", "params": {"url": "https://example.com/data.csv"}}
|
||
]
|
||
}
|
||
```
|
||
|
||
### Batch Example
|
||
|
||
**Add a file, then tag it:**
|
||
```json
|
||
{
|
||
"operations": [
|
||
{"op": "add", "params": {"path": "/tmp/design.md"}},
|
||
{"op": "update", "params": {"name": "design.md", "metadata": ["status=draft", "team=platform"]}}
|
||
]
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Tool 3: `session` — Session Lifecycle
|
||
|
||
Manage sessions for scoped work.
|
||
|
||
**Input Schema:**
|
||
```json
|
||
{
|
||
"type": "object",
|
||
"properties": {
|
||
"action": {
|
||
"type": "string",
|
||
"enum": ["start", "stop", "pin", "unpin", "watch"]
|
||
},
|
||
"params": { "type": "object" }
|
||
},
|
||
"required": ["action"]
|
||
}
|
||
```
|
||
|
||
**Annotations:** `readOnlyHint: false`, `destructiveHint: false`, `idempotentHint: false`
|
||
|
||
### Session Actions
|
||
|
||
| Action | Description |
|
||
|--------|-------------|
|
||
| `start` | Begin a new session |
|
||
| `stop` | End the current session |
|
||
| `pin` | Pin artifacts to the current session |
|
||
| `unpin` | Unpin artifacts from the current session |
|
||
| `watch` | Watch paths for changes during the session |
|
||
|
||
**Example — start a session:**
|
||
```json
|
||
{"action": "start", "params": {"label": "feature-review"}}
|
||
```
|
||
|
||
**Example — pin an artifact:**
|
||
```json
|
||
{"action": "pin", "params": {"hash": "abc123..."}}
|
||
```
|
||
|
||
---
|
||
|
||
## Utility Tool: `mcp.echo`
|
||
|
||
Always registered for protocol testing. Echoes back the input message.
|
||
|
||
```json
|
||
{"tool": "mcp.echo", "arguments": {"message": "hello"}}
|
||
```
|