Coraline MCP Tools Reference

Coraline exposes 38 MCP tools when running as an MCP server (coraline serve --mcp). All tool names are prefixed with coraline_ to avoid collisions with other MCP servers.

coraline_semantic_search is available by default (the embeddings feature ships enabled) but only registered when an ONNX model is present in the shared model directory (~/.config/coraline/models/<model>/, where <model> is vectors.model from config, default nomic-embed-text-v1.5). Run coraline model download then coraline embed to activate it — see coraline model list for every supported model. The remaining 37 tools are always available.

Quick Reference

Graph Tools

coraline_search

Search for code symbols by name or pattern across the indexed codebase.

Input:

Output:

{
  "results": [
    {
      "node": {
        "id": "abc123",
        "kind": "Function",
        "name": "resolve_unresolved",
        "qualified_name": "coraline::resolution::resolve_unresolved",
        "file_path": "/path/to/resolution/mod.rs",
        "start_line": 42,
        "end_line": 95,
        "language": "Rust",
        "signature": "fn resolve_unresolved(conn: &mut Connection, ...)"
      },
      "score": 0.92
    }
  ],
  "count": 1
}

coraline_callers

Find all functions/methods that call a given symbol (incoming calls edges).

Input:

Output:

{
  "callers": [
    {
      "id": "def456",
      "kind": "Function",
      "name": "index_all",
      "qualified_name": "coraline::extraction::index_all",
      "file_path": "/path/to/extraction.rs",
      "start_line": 120,
      "line": 158
    }
  ],
  "count": 1
}

coraline_callees

Find all functions/methods that a given symbol calls (outgoing calls edges).

Input:

Output: Same shape as coraline_callers but field is callees.

coraline_impact

Analyze the impact radius of changing a symbol — finds everything that directly or transitively depends on it, via BFS over incoming calls and references edges.

Input:

Output:

{
  "nodes": [ ... ],
  "edges": [ ... ],
  "stats": {
    "node_count": 12,
    "edge_count": 15,
    "file_count": 4,
    "max_depth": 2
  }
}

coraline_dependencies

Get the outgoing dependency graph from a node — what does this symbol import, call, or reference, recursively up to a configurable depth?

Input:

Output:

{
  "root_id": "abc123",
  "nodes": [ ... ],
  "edges": [ ... ],
  "stats": { "node_count": 8, "edge_count": 10, "file_count": 3, "max_depth": 2 }
}

coraline_dependents

Get the incoming dependency graph — what symbols depend on (call, import, or reference) this node, recursively?

Input: Same as coraline_dependencies.

Output: Same shape as coraline_dependencies but traversal follows edges in reverse.

coraline_path

Find a path between two nodes in the graph, using BFS over all edge kinds.

Input:

Output:

{
  "from_id": "abc123",
  "to_id": "def456",
  "path_found": true,
  "path": ["abc123", "mid789", "def456"],
  "length": 3
}

Returns { "path_found": false } if no path exists.

coraline_stats

Return detailed graph statistics: total counts, per-language file breakdown, node kind breakdown, and edge kind breakdown.

Input: None.

Output:

{
  "totals": {
    "nodes": 1842,
    "edges": 4201,
    "files": 47,
    "unresolved_references": 123,
    "vectors": 0
  },
  "files_by_language": { "rust": 28, "typescript": 14, "toml": 5 },
  "nodes_by_kind": {
    "function": 412,
    "method": 287,
    "import": 201,
    "struct": 88
  },
  "edges_by_kind": {
    "contains": 1842,
    "calls": 987,
    "imports": 201,
    "exports": 178
  }
}

coraline_find_symbol

Find symbols by name pattern with richer metadata than coraline_search, including optional source code body. Good for Foo/__init__-style path patterns.

Input:

Output: { "symbols": [...], "count": N } — each symbol includes docstring, is_exported, is_async, is_static, score, and optionally body.

coraline_get_symbols_overview

Get an overview of all symbols in a file, grouped by kind and ordered by line number.

Input:

Output:

{
  "file_path": "src/lib.rs",
  "symbol_count": 14,
  "by_kind": {
    "function": [ ... ],
    "struct": [ ... ]
  },
  "symbols": [ ... ]
}

coraline_find_references

Find all nodes that reference (call, import, extend, implement, etc.) a given symbol.

Input:

Output: { "node_id": "...", "references": [...], "count": N } — each reference includes its edge_kind and the line number of the edge.

coraline_node

Get complete details for a specific node by ID, including its source code body read from disk.

Input:

Output: Full node record including body (source lines), visibility, decorators, type_parameters, is_async, is_static, is_abstract, and optionally incoming_edge_count / outgoing_edge_count.

Batch Tools

Fetch results for multiple symbols in one call instead of N round trips — roughly 60% fewer tokens than the equivalent sequence of single-symbol calls.

coraline_batch_get_nodes

Fetch multiple nodes by ID in a single call.

Input:

Output: { "nodes": [...], "count": N, "not_found": [...] }

coraline_batch_callers

Get callers for multiple symbols in a single call.

Input:

Output: { "callers": { "<node_id>": [...] }, "node_count": N }

coraline_batch_callees

Get callees for multiple symbols in a single call.

Input:

Output: { "callees": { "<node_id>": [...] }, "node_count": N }

Advanced Search Tools

Specialized lookups over indexed nodes, faster than full-text coraline_search for these specific shapes — also roughly 60% fewer tokens for the matched use case.

coraline_search_by_signature

Find symbols by type signature pattern (case-insensitive substring match) — e.g. functions by return type or parameters.

Input:

coraline_search_by_docstring

Search symbols by documentation/comment content — find code by what it does, not just its name.

Input:

coraline_search_exported_symbols

Search only public/exported symbols — filters out internal implementation details to browse the public API surface.

Input:

coraline_find_by_kind_in_file

Get all symbols of a specific kind in one file — fast file-scoped exploration.

Input:

Context Tool

coraline_context

Build structured context for an AI task description. Searches the graph, traverses relationships, and returns relevant code snippets in Markdown or JSON format.

Input:

Output: A Markdown or JSON document containing relevant symbols and code, ready to paste as context for an LLM.

Audit Tool

coraline_audit_docs

Audit Markdown documentation coverage against the indexed code graph.

Detects two classes of issues:

• stale_refs: inline code-span symbol references in Markdown that do not resolve to indexed symbols
• undocumented_exports: exported code symbols with no inbound references edge from Markdown docs

Input:

Output:

{
  "summary": {
    "doc_files_indexed": 12,
    "doc_sections_indexed": 89,
    "stale_refs_count": 3,
    "undocumented_exports_count": 7
  },
  "stale_refs": [
    {
      "reference": "resolve_unresolved",
      "doc_file": "docs/ARCHITECTURE.md",
      "section": "Resolution",
      "line": 42,
      "column": 18
    }
  ],
  "undocumented_exports": [
    {
      "name": "audit_docs",
      "qualified_name": "coraline::audit::audit_docs",
      "kind": "function",
      "file": "crates/coraline/src/audit.rs",
      "line": 48
    }
  ]
}

File Tools

coraline_read_file

Read the contents of a file within the project.

Input:

coraline_list_dir

List the contents of a directory within the project.

Input:

coraline_get_file_nodes

Get all indexed symbols (nodes) for a specific file.

Input:

Output: { "file_path": "...", "nodes": [...], "count": N }

coraline_find_file

Find files by name or glob pattern. Recursively walks the project tree, skipping .git, node_modules, target, and .coraline directories.

Input:

Output:

{
  "pattern": "*.rs",
  "files": ["src/lib.rs", "src/db.rs", "src/graph.rs"],
  "count": 3
}

coraline_status

Show project index statistics: total files, nodes, edges, and unresolved reference counts. Optionally include the full coraline doctor --json report for self-healing UIs.

Input:

Output (without include_doctor):

{
  "project_root": "/abs/path/to/project",
  "database": "/abs/path/to/project/.coraline/coraline.db",
  "database_size_bytes": 2097152,
  "stats": {
    "nodes": 4201,
    "edges": 9872,
    "files": 128,
    "unresolved_references": 153
  }
}

Output (with include_doctor: true): the same fields above, plus:

{
  "doctor_report": {
    "probes": [
      { "name": "config", "ok": true, "detail": "...", "fix": null },
      { "name": "database", "ok": true, "detail": "...", "fix": null },
      { "name": "git hooks", "ok": false, "detail": "...", "fix": "..." },
      { "name": "vec_ext", "ok": true, "detail": "...", "fix": null },
      {
        "name": "model file",
        "ok": false,
        "detail": "...",
        "fix": "Run `coraline model download`..."
      }
    ],
    "exit_code": 1
  },
  "doctor_needs_attention": true
}

doctor_needs_attention is derived from exit_code == 0 (inverted) so a UI can render a single bool to decide whether to surface a “fix this” prompt. The probes array carries the per-check name / ok / detail / fix fields — fix is the human-readable remediation hint (e.g. “Run coraline model download to enable semantic search.”).

Back-compat: when include_doctor is omitted (or false), the response shape is identical to the prior version — only the four legacy top-level keys appear.

Connection hygiene: the tool opens the SQLite database for the index stats query and drops that handle before invoking coraline doctor, so the WAL writer lock isn’t held by both queries simultaneously.

coraline_get_config

Read the current project configuration from .coraline/config.toml.

Input: None.

Output: Full CoralineConfig as JSON with all four sections (indexing, context, sync, vectors).

coraline_update_config

Update a single configuration value using dot-notation path.

Input:

coraline_sync

Trigger an incremental sync of the index. Detects files added, modified, or removed since the last index run and updates only what changed. Run after editing source files to keep the graph current.

Input: None.

Output:

{
  "files_checked": 42,
  "files_added": 1,
  "files_modified": 3,
  "files_removed": 0,
  "nodes_updated": 47,
  "duration_ms": 380
}

coraline_semantic_search

Search indexed nodes using natural-language vector similarity. Included in the default build; only registered as an MCP tool once an ONNX model is present in the shared model directory (~/.config/coraline/models/<model>/, <model> from vectors.model). To activate:

coraline model download   # download the configured model (default nomic-embed-text-v1.5, ~137 MB)
coraline embed            # generate embeddings for all indexed nodes

Run coraline model list to see every supported model, including the code-specialised jina-embeddings-v2-base-code. Results and coverage are scoped to whichever model is currently configured — embeddings from a previously-configured model are ignored, not mixed in.

Structured error when the model is missing:

If the ONNX model can’t be loaded (not downloaded yet, or tokenizer.json/weights missing), the tool call fails with isError: true and a structured EMBEDDING_MODEL_MISSING envelope in structuredContent, so an agent can branch on code instead of parsing free-form text:

{
  "code": "EMBEDDING_MODEL_MISSING",
  "message": "Embedding model is not present. Run `coraline model download` to download it.",
  "recover": {
    "command": "coraline model download",
    "docs": "https://github.com/greysquirr3l/coraline#embeddings (debug: load failed: ...)"
  }
}

Input:

Output:

{
  "results": [
    {
      "node_id": "abc123",
      "name": "resolve_unresolved",
      "similarity": 0.87,
      "file_path": "src/resolution/mod.rs"
    }
  ],
  "count": 1
}

Memory Tools

Project memories are Markdown files stored in .coraline/memories/. They persist across sessions and help AI assistants maintain project context.

coraline_write_memory

Write or update a project memory.

Input:

coraline_read_memory

Read a project memory by name.

Input:

Output: { "name": "...", "content": "..." }

coraline_list_memories

List all available memories for the project.

Input: None.

Output: { "memories": ["project_overview", "architecture_notes", ...], "count": N }

coraline_delete_memory

Delete a project memory.

Input:

coraline_edit_memory

Edit a memory file by replacing text — either as a literal string match or a regex pattern.

Input:

Cluster & Process Trace Tools

Louvain community detection (coraline_cluster_overview, coraline_cluster_members) and per-node execution-flow traces (coraline_process_for) are computed at index time during the post-extraction passes (run automatically by coraline index and coraline sync). Both column types are nullable — nodes.cluster_id IS NULL and edges.process_id IS NULL mean “not clustered” / “not part of any traced process” respectively. The tools return data only when the post-extraction passes have completed at least once.

coraline_cluster_overview

List Louvain clusters discovered during indexing, ordered by size, with one representative node per cluster.

Input:

Output:

{
  "clusters": [
    {
      "cluster_id": 0,
      "size": 42,
      "sample_node_id": "abc123",
      "sample_qualified_name": "coraline::extraction::index_all",
      "sample_kind": "function",
      "sample_language": "rust"
    },
    {
      "cluster_id": 1,
      "size": 17,
      "sample_node_id": "def456",
      "sample_qualified_name": "coraline::db::query",
      "sample_kind": "function",
      "sample_language": "rust"
    }
  ],
  "count": 2
}

coraline_cluster_members

List all nodes that share the given cluster_id, ordered by qualified_name. Use the output of coraline_cluster_overview to pick a cluster_id.

Input:

Output:

{
  "cluster_id": 0,
  "nodes": [ ... full node records ... ],
  "count": 42
}

coraline_process_for

Return the call-graph trace (entry point + nodes + edges) for the given node. Walks backward through incoming calls edges to find the owning entry point, then DFS forward through the call graph (with cycle protection + depth cap, default 50) to surface every node and edge in the process trace. Returns null when the node isn’t reachable from any entry point.

Input:

Output (node reachable):

{
  "entry_point": { /* full node record */ },
  "depth_reached": 3,
  "nodes": [ ... full node records ... ],
  "edges": [
    {
      "source": "abc123",
      "target": "def456",
      "kind": "calls",
      "line": 158,
      "column": 4,
      "confidence": 1.0,
      "process_id": 1
    }
  ]
}

Output (node unreachable): JSON null.

Each edge includes its process_id (matches the entry point’s trace ordinal) and confidence (same scale as coraline_callers / coraline_callees).

MCP Client Configuration

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "coraline": {
      "command": "/path/to/coraline",
      "args": ["serve", "--mcp", "--path", "/path/to/your/project"]
    }
  }
}

Claude Code

Add to .claude/mcp.json in your project workspace:

{
  "mcpServers": {
    "coraline": {
      "command": "coraline",
      "args": ["serve", "--mcp"]
    }
  }
}

When --path is omitted, the working directory is used as the project root.