Skip to content

MCP Server

YAMS runs as a Model Context Protocol server over stdio (NDJSON, JSON-RPC 2.0), giving AI assistants read + write access to your content-addressed store.

Run

yams serve                              # stdio transport
yams serve --verbose                    # logs on stderr
docker run -i ghcr.io/trvon/yams:latest serve

Client configuration

Client Config file
Claude Desktop ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) · %APPDATA%\Claude\claude_desktop_config.json (Windows) · ~/.config/Claude/claude_desktop_config.json (Linux)
Continue.dev IDE config — contextProviders entry
Cursor / Zed / custom Any MCP-compliant stdio client

Claude Desktop

{
  "mcpServers": {
    "yams": {
      "command": "yams",
      "args": ["serve"],
      "env": { "YAMS_STORAGE": "/path/to/your/data" }
    }
  }
}

Continue.dev

{
  "contextProviders": [
    {
      "name": "mcp",
      "params": { "serverCommand": "yams", "serverArgs": ["serve"] }
    }
  ]
}

Restart the client after editing its config.

Docker

docker run -i --rm \
  -v ~/.local/share/yams:/data -e YAMS_STORAGE=/data \
  ghcr.io/trvon/yams:latest serve

-i is required — stdio transport needs an attached stdin.

Tools

The server exposes 3 composite tools. All operations are reached through these; this keeps AI context windows tight (~800 tokens vs. ~4,000 for one-tool-per-op designs).

Tool Purpose Operations
query Read 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

Discover operation parameter schemas at runtime with describe:

{"name": "query", "arguments": {"steps": [{"op": "describe", "params": {"target": "search"}}]}}

Full operation schemas: docs/api/mcp_tools.md. Protocol implementation: include/yams/mcp/mcp_server.h.

query examples

// search
{"name": "query", "arguments": {
  "steps": [{"op": "search", "params": {"query": "configuration management", "limit": 5}}]}}

// grep with regex + context
{"name": "query", "arguments": {
  "steps": [{"op": "grep", "params": {"pattern": "class\\s+\\w+Handler", "line_numbers": true, "context": 2}}]}}

// pipeline: search → fetch top hit (uses $prev)
{"name": "query", "arguments": {
  "steps": [
    {"op": "search", "params": {"query": "auth middleware", "limit": 1}},
    {"op": "get", "params": {"hash": "$prev.results[0].hash", "include_content": true}}
  ]}}

// advisory retrieval — ranked snapshot suggestions + supporting hits
{"name": "query", "arguments": {
  "steps": [{"op": "suggest_context", "params": {"query": "auth token refresh flow", "limit": 3}}]}}

// persisted semantic duplicate groups
{"name": "query", "arguments": {
  "steps": [{"op": "semantic_dedupe", "params": {"limit": 10}}]}}

suggest_context inside a session suppresses already-served snapshot sets for the same normalized query, so long-running sessions don’t re-suggest the same context each turn.

execute example

{"name": "execute", "arguments": {
  "operations": [{"op": "add", "params": {"path": "/tmp/notes.md", "tags": ["meeting"]}}]}}

Stops on first error unless continueOnError: true.

session example

{"name": "session", "arguments": {"action": "start", "params": {"label": "review"}}}

Prompt templates

prompts/list and prompts/get expose built-in templates (search_codebase, summarize_document, rag/*) plus any file-backed templates you drop in:

  1. YAMS_MCP_PROMPTS_DIR (env override)
  2. [mcp_server].prompts_dir in config.toml
  3. $XDG_DATA_HOME/yams/prompts (~/.local/share/yams/prompts)
  4. ./docs/prompts when running from the repo

Filename PROMPT-<name>.md is exposed as <name> with dashes → underscores (e.g. PROMPT-research-mcp.md → research_mcp).

Hot / cold modes

Control daemon path selection on server startup:

Flag Env Values
--list-mode YAMS_LIST_MODE hot_only · cold_only · auto
--grep-mode YAMS_GREP_MODE hot_only · cold_only · auto
--retrieval-mode YAMS_RETRIEVAL_MODE hot_only · cold_only · auto

paths_only: true on list/search operations engages hot paths where supported and shrinks responses.

Testing

# initialize
echo '{"jsonrpc":"2.0","method":"initialize","params":{"clientInfo":{"name":"test","version":"1.0"}},"id":1}' \
  | yams serve

# list tools — expect query, execute, session
echo '{"jsonrpc":"2.0","method":"tools/list","id":2}' | yams serve

# one-shot search via query
echo '{"jsonrpc":"2.0","method":"tools/call","id":3,"params":{"name":"query","arguments":{"steps":[{"op":"search","params":{"query":"test"}}]}}}' \
  | yams serve

Verbose trace:

export SPLOG_LEVEL=debug
yams serve --verbose 2>debug.log

Minimal Python and Node.js clients: drive the yams serve subprocess with newline-delimited JSON on stdin and read responses line-by-line from stdout. See docs/api/mcp_tools.md for end-to-end examples.

Troubleshooting

Symptom Fix
Client times out on connect Pre-warm daemon: yams status; check protocol version (supported 2024-11-05 … 2025-06-18)
No tools/list response Client isn’t sending notifications/initialized after initialize
Claude Desktop doesn’t list YAMS Check config path/JSON; use absolute yams path; restart Claude Desktop
Docker container exits immediately Missing -i — stdio needs an attached stdin
Ctrl+C doesn’t stop server Update to latest; else kill -TERM <pid>

Readiness: during startup the daemon may report initializing. yams status and server responses indicate not-ready services and progress. If model preloading prolongs init, switch to lazy loading and re-check with yams stats -v.

Security

  • Stdio runs with the calling process’s permissions — no network surface.
  • Docker: pin a version tag (not latest), run non-root, use read-only mounts, and cap resources.
  • Set YAMS_STORAGE explicitly to avoid surprises from per-user defaults.

Performance

  • Pre-index with yams add before exposing to an assistant.
  • Use paths_only: true and tight limit values for large corpora.
  • Pick the search type that fits: keyword for exact, fuzzy for approximate, hybrid for default.

References