Skip to content

MCP_TOOLS.md

Latest commit

 

History

History
291 lines (226 loc) · 18.5 KB

MCP_TOOLS.md

File metadata and controls

291 lines (226 loc) · 18.5 KB
Raw

MCP Tools Reference

Context Chronicle exposes 6 unified MCP tools. Each tool supports multiple operations via parameters, keeping the interface clean while maintaining full functionality.

Quick Reference

Tool Actions Category
memorySearch keyword / semantic / hybrid / graph search Retrieval
memoryManage add / list / why / timeline / reindex / entity / relation / get-entity / rag-audit / rag-clean / rag-backfill / embedding-list / embedding-use / embedding-test / embedding-custom / compaction-mode / feature-toggle / cleanup-expired / link-session / unlink-session / list-linked / open-log-dir / logs / memory-decay Constraint & Decision & KG & RAG & Config & Logs & Memory
memoryStatus health check + audit + embedding + KG stats Status
memoryCompact trigger compaction, dry-run preview Compaction
guardedBash firewall-protected shell execution Firewall
memoryHistory firewall logs / model history / config reload History

Error Format

All tools return structured JSON. On error:

{ "error": "Human-readable error", "hint": "Actionable suggestion" }

On success, the response shape depends on the tool and parameters. See examples below.

Background: Legacy Tools Consolidated Into memoryManage

Context Chronicle originally exposed separate MCP tools for constraint management, knowledge graph operations, embedding configuration, and RAG maintenance. All these functions now route through the single memoryManage tool with an action parameter. The legacy tool names (memoryEmbeddingStatus, memoryEmbeddingReindex, memoryGraphAdd, memoryGraphGet, etc.) are no longer registered.

This consolidation keeps the MCP interface clean (6 tools) while preserving 24 distinct operations.

Tool Details

memorySearch

Unified search across events, memory packets, and knowledge graph entities.

Param Type Default Description
query string required Search keywords
mode keyword/semantic/hybrid/graph hybrid Search algorithm
source events/graph/all all Where to search
limit number 10 Max results
minScore number 0.5 Minimum relevance (0-1)
sessionId string - Scope to session

CJK: Chinese/Japanese/Korean queries auto-route to trigram tokenizer.

Example — keyword search:

Request:  memorySearch { query: "pnpm", mode: "keyword", limit: 5 }
Response: { "query": "pnpm", "total": 3, "events": [{"id": 42, "content": "...pnpm install...", "score": 0.92}, ...], "graphResults": [] }

Example — semantic/hybrid search:

Request:  memorySearch { query: "how to configure embedding", mode: "hybrid", limit: 5 }
Response: { "query": "how to configure embedding", "total": 2, "events": [...], "graphResults": [] }

Example — graph search:

Request:  memorySearch { query: "React", mode: "graph", limit: 5 }
Response: { "query": "React", "total": 2, "graphResults": [{"entityType": "decision", "name": "React for frontend", "relations": [...]}, ...], "events": [] }

memoryManage

Unified constraint/decision/knowledge-graph management plus configuration, logs, and session linking. All 24 actions route through this single tool.

Param Type Description
action add / list / why / timeline / reindex / entity / relation / get-entity / rag-audit / rag-clean / rag-backfill / embedding-list / embedding-use / embedding-test / embedding-custom / compaction-mode / feature-toggle / cleanup-expired / link-session / unlink-session / list-linked / open-log-dir / logs / memory-decay What to do
content string Constraint/decision text (for add)
category string Grouping label
scope session / project / global Scope (default: project)
memoryId string Memory ID (for why)
question string Question to trace (for timeline)
entity object Entity data (for entity): { entityType, name }
relation object Relation data (for relation): { relationType, sourceName, targetName }
entityName string Entity to query (for get-entity)
depth number Relation depth (for get-entity, default 1)
limit number Max results (for get-entity, default 20)
relationType string Filter by relation type (for get-entity)
halfLifeTurns number (30|50|80|120|200|500|-1) Constraint half-life in turns (for memory-decay); -1 = Infinity

Examples — constraint management:

  • /memory-remember Must use pnpm -> { action: "add" }
  • /memory-rules -> { action: "list" }
  • /memory-why <id> -> { action: "why" }
  • Trace decision timeline -> { action: "timeline", question: "When was the firewall mode changed?" }
  • Trigger reindex -> { action: "reindex" }

Examples — knowledge graph:

  • Add KG entity -> { action: "entity", entity: { entityType: "decision", name: "React" } }
  • Add KG relation -> { action: "relation", relation: { relationType: "decision_affects", sourceName: "React", targetName: "Button.tsx" } }
  • Query KG entity -> { action: "get-entity", entityName: "Button.tsx", depth: 1 }

Examples — embedding & configuration:

  • List embedding presets -> { action: "embedding-list" }
  • Select a preset -> { action: "embedding-use", presetId: "openai-text-embedding-3-small" }
  • Test embedding connectivity -> { action: "embedding-test" }
  • Custom embedding -> { action: "embedding-custom", baseUrl: "...", model: "...", dimension: 1536 }
  • Change compaction mode -> { action: "compaction-mode", mode: "strict|relaxed" }
  • Toggle feature -> { action: "feature-toggle", feature: "auditGate", enabled: true }
  • Set memory decay half-life -> { action: "memory-decay", halfLifeTurns: 80 }

Examples — RAG maintenance:

  • Audit RAG quality -> { action: "rag-audit" }
  • Clean polluted indices -> { action: "rag-clean" }
  • Backfill missing indices -> { action: "rag-backfill" }

Examples — session & logs:

  • Link another session -> { action: "link-session", dbPath: "/path/to/session.db", label: "previous-project" }
  • Unlink a session -> { action: "unlink-session", linkedSession: "ses_abc123" }
  • List linked sessions -> { action: "list-linked" }
  • Cleanup expired sessions -> { action: "cleanup-expired" }
  • Open log directory -> { action: "open-log-dir" }
  • View plugin logs -> { action: "logs", level: "error", tag: "Audit", tail: 50 }

logs action details: Returns recent plugin log entries from ~/.opencode/context-chronicle/logs/. Supports filtering by severity level (debug, info, warn, error), subsystem tag (Audit, Firewall, Search, Compaction, Embedding, CLI), and result count (tail). Each entry includes timestamp, level, tag, session ID, and message. Example response:

{
  "entries": [
    {
      "ts": "2026-06-30T10:15:00Z",
      "level": "error",
      "tag": "Firewall",
      "session": "ses_abc",
      "message": "Blocked: rm -rf /"
    },
    {
      "ts": "2026-06-30T10:14:55Z",
      "level": "warn",
      "tag": "Audit",
      "session": "ses_abc",
      "message": "Stop Gate: repeated failure detected"
    }
  ],
  "count": 2,
  "totalLines": 1204
}

memoryStatus

Plugin health overview. Use includeGraph: true for KG audit.

Param Type Default Description
sessionId string current Scope status to session
includeGraph boolean false Include knowledge graph audit
includeEmbedding boolean false Include embedding provider status
includeSettings boolean false Include full settings (TUI panel)

Example — basic health check:

Request:  memoryStatus {}
Response: {
  "status": "running",
  "database": "~/.opencode/context-chronicle/db.sqlite",
  "stats": {
    "total_events": 1234,
    "active_constraints": 5,
    "audits": { "total": 12, "passed": 10, "failed": 2 }
  },
  "perfMetrics": { "avgSearchMs": 2.3 },
  "vectorIndexReady": true
}

Example — with embedding and graph:

Request:  memoryStatus { includeEmbedding: true, includeGraph: true }
Response: {
  ...health fields...,
  "embedding": { "provider": "openai-text-embedding-3-small", "dimension": 1536, "stale": false },
  "graphAudit": { "entityCount": 42, "relationCount": 15, "byType": [{"type": "decision", "count": 8}, ...] }
}

memoryCompact

Trigger context compaction to free context window space.

Param Type Default Description
sessionId string current Session to compact
dryRun boolean false Preview without executing
force boolean false Skip pressure threshold check

Example — dry run preview:

Request:  memoryCompact { dryRun: true }
Response: {
  "dryRun": true,
  "pressureScore": 42,
  "threshold": 30,
  "wouldCompact": true,
  "estimatedEventsCompacted": 230,
  "estimatedTokensSaved": 8500
}

Example — force compaction:

Request:  memoryCompact { force: true }
Response: {
  "compacted": true,
  "eventsCompacted": 230,
  "tokensSaved": 8500,
  "summary": "Compacted 230 events from session. Key constraints preserved: 5."
}

guardedBash

Execute shell commands through the firewall. Blocked commands return structured JSON with reason and fix suggestions.

Example — allowed command:

Request:  guardedBash { command: "ls -la src/" }
Response: { "exitCode": 0, "stdout": "...", "stderr": "" }

Example — blocked command:

Request:  guardedBash { command: "rm -rf /" }
Response: {
  "blocked": true,
  "reason": "Dangerous pattern matched: destructive delete targeting root",
  "pattern": "rm -rf /",
  "suggestion": "Use targeted deletion with explicit paths"
}

memoryHistory

View historical data and manage configuration.

Param Type Default Description
type firewall / model / reload firewall What to view/do
limit number 10 Max entries

Example — firewall history:

Request:  memoryHistory { type: "firewall", limit: 5 }
Response: {
  "type": "firewall",
  "entries": [
    { "ts": "2026-06-30T10:15:00Z", "command": "rm -rf /", "action": "blocked", "pattern": "rm -rf" },
    { "ts": "2026-06-30T10:10:00Z", "command": "curl ... | bash", "action": "warned", "pattern": "curl pipe bash" }
  ]
}

Example — model switch history:

Request:  memoryHistory { type: "model", limit: 5 }
Response: {
  "type": "model",
  "entries": [
    { "ts": "2026-06-30T09:30:00Z", "from": "claude-sonnet-4-20250514", "to": "claude-opus-4-20250514", "reason": "User switched model" }
  ]
}

Example — config reload:

Request:  memoryHistory { type: "reload" }
Response: { "reloaded": true, "configPath": "~/.opencode/context-chronicle/config.json" }