Symvanta

Official25 tools

by Symvanta · JavaScript

Hosted code graph over MCP: exact callers, dependencies, and cross-repo blast radius for AI agents.

Symvanta Code Graph MCP Server

This MCP server exposes a hosted code graph to Claude Code, enabling AI agents to query exact callers, dependencies, and cross-repo blast radius. It registers the Symvanta MCP server endpoint (default https://mcp.symvanta.com/mcp), supports configuration for on-prem/self-hosted, and can use OAuth on first connection.

🛠️ Key Features

Hosted code graph over MCP
Exact callers, dependencies, and cross-repo blast radius
Default endpoint https://mcp.symvanta.com/mcp (configurable for on-prem/self-hosted)
OAuth on first connection
Tool decision matrix and conventions via a symvanta skill

🚀 Use Cases

Provide standing context at session start for agent tool usage
Avoid shell search by directing agents to Symvanta code-graph tools
Wrap common workflows with slash commands

⚡ Developer Benefits

One-step setup without manually editing .mcp.json
Consistent tool selection through a full tool decision matrix
“symvanta” skill consolidates conventions and routing

⚠️ Limitations

Description provided does not specify authentication beyond OAuth on first connection, or performance/scale characteristics.

Topics: claude-code, code-graph, code-intelligence, mcp, mcp-server. Tool count: 25.

Topics

claude-codecode-graphcode-intelligencemcpmcp-server

Captured live from the server via tools/list.

init

Call first. Returns the active project, repositories, and index health in one call, plus a `usage` field (decision matrix + routing). Non-empty repositories = proceed with graph queries; empty = tell the user to attach repos on the dashboard and stop, do not fall back to Grep.

Parameters1

feedback

object

optional

Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

locate

Search/lookup. Pick a mode, or omit with a bare query to AUTO-ROUTE (text, then semantic on empty; response carries answered_by). Modes: - text (replaces grep): literal identifier/string, one row/occurrence. queries:[...] (<=10 terms) searches several in one call (and implies this mode when mode is omitted). pathsOnly:true = "filePath:lineNumber" only (~5x cheaper). maxPerFile caps rows/file (default 5). Empty carries did_you_mean; do NOT retry reworded, use semantic. - symbol: symbols by name/symbolPath in one repo. kind filters node kind, layer one layer. Tests last unless includeTests:true. - semantic: vector search for symbols similar to a natural-language query (names unknown). - file: fuzzy filename search (basename); filenames only. - config (replaces grep for env/config keys): key/env-var usages with nearest-symbol context; queries:[...] batches several keys. - codebase: cross-repo candidate scan; narrow with repositoryIds.

Parameters16

mode	string	optional	Force a mode. Omit + bare query = AUTO-ROUTE (text, then semantic on empty). queries without a mode implies text.
projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Single-repo scope (not codebase; that is project-wide, use repositoryIds).
commitSha	string	optional	Pin an indexed revision (text/symbol/semantic/config; ignored by file/codebase).
query	string	optional	Search term or NL query. Required for symbol/semantic/codebase; text/config: query or queries; file: query or name.
queries	array	optional	text/config. Up to 10 terms; interleaved, deduped, each tagged matchedQuery. Without an explicit mode, implies mode:text. Accepts a JSON-array string.
name	string	optional	mode:file. Filename fragment; defaults to query.
kind	string	optional	mode:symbol. Filter by node kind.
layer	string	optional	mode:symbol. Scope to one layer (e.g. browser, node, common, test).
pathPrefix	string	optional	text/symbol/config. Restrict to paths under this prefix.
pathsOnly	boolean	optional	mode:text. "filePath:lineNumber" only, no snippets (~5x fewer tokens).
includeTests	boolean	optional	text/symbol/semantic. Include test files. Default false ranks them last; auto-on for test queries.
maxPerFile	integer	optional	mode:text. Cap occurrences/file (default 5; capped file carries moreInFileTruncated). 0 = uncapped.
repositoryIds	array	optional	mode:codebase. Narrow to these repository ids; omit to scan all.
limit	integer	optional	Max results. Per-mode caps apply (text 200/20, symbol 20, semantic 5, file 10, config 20/20, codebase 20/10).
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "mode": {
      "description": "Force a mode. Omit + bare query = AUTO-ROUTE (text, then semantic on empty). queries without a mode implies text.",
      "type": "string",
      "enum": [
        "text",
        "symbol",
        "semantic",
        "file",
        "config",
        "codebase"
      ]
    },
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "description": "Single-repo scope (not codebase; that is project-wide, use repositoryIds).",
      "type": "string",
      "minLength": 1
    },
    "commitSha": {
      "description": "Pin an indexed revision (text/symbol/semantic/config; ignored by file/codebase).",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "query": {
      "description": "Search term or NL query. Required for symbol/semantic/codebase; text/config: query or queries; file: query or name.",
      "type": "string",
      "minLength": 1
    },
    "queries": {
      "description": "text/config. Up to 10 terms; interleaved, deduped, each tagged matchedQuery. Without an explicit mode, implies mode:text. Accepts a JSON-array string.",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1
      }
    },
    "name": {
      "description": "mode:file. Filename fragment; defaults to query.",
      "type": "string",
      "minLength": 1
    },
    "kind": {
      "description": "mode:symbol. Filter by node kind.",
      "type": "string",
      "enum": [
        "module",
        "class",
        "function",
        "interface",
        "endpoint",
        "schema",
        "struct",
        "enum",
        "protocol",
        "actor",
        "extension",
        "initializer",
        "property",
        "package",
        "product",
        "target",
        "project",
        "workspace",
        "test_suite",
        "test_case",
        "test_hook",
        "community",
        "cycle",
        "resource"
      ]
    },
    "layer": {
      "description": "mode:symbol. Scope to one layer (e.g. browser, node, common, test).",
      "type": "string",
      "minLength": 1,
      "maxLength": 32
    },
    "pathPrefix": {
      "description": "text/symbol/config. Restrict to paths under this prefix.",
      "type": "string",
      "minLength": 1
    },
    "pathsOnly": {
      "description": "mode:text. \"filePath:lineNumber\" only, no snippets (~5x fewer tokens).",
      "type": "boolean"
    },
    "includeTests": {
      "description": "text/symbol/semantic. Include test files. Default false ranks them last; auto-on for test queries.",
      "default": false,
      "type": "boolean"
    },
    "maxPerFile": {
      "description": "mode:text. Cap occurrences/file (default 5; capped file carries moreInFileTruncated). 0 = uncapped.",
      "default": 5,
      "type": "integer",
      "minimum": 0,
      "maximum": 1000
    },
    "repositoryIds": {
      "description": "mode:codebase. Narrow to these repository ids; omit to scan all.",
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "description": "Encoded repository id from list_repositories."
      }
    },
    "limit": {
      "description": "Max results. Per-mode caps apply (text 200/20, symbol 20, semantic 5, file 10, config 20/20, codebase 20/10).",
      "default": 20,
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

relate

Graph relationship traversal via one kind (real edges, not text). Kinds (1-10 symbols; heritage/chain one): - callers: direct callers. granularity:'file' (default) one row/file, 'site' one row/caller. - dependencies: outgoing calls/imports. - blast_radius: upstream impact walk (every caller, importer and referencer up to 3 hops, no per-hop sampling) + co-change siblings; risk {level,signals}. includeCrossRepo defaults ON here (off for others). blastRadiusTotalCount is the number of distinct symbols that 3-hop walk reached, not the row count: the blastRadius array is capped by expansionLimit. blastRadiusTruncated:true means the rows are a sample of that total; blastRadiusTotalAtLeast:true means the count stopped at its 10000 bound, so quote it as "N+". The walk stops at 3 hops, so it can miss impact further away; it never overcounts. Never report the number of listed rows as the impact size. - implementers: classes implementing interfaces via heritage edges. - heritage: full hierarchy (ancestors+descendants) of ONE type. maxDepth caps it. - chain: call-chain paths for a node (nodeId OR selectors[0]); chain params tune the walk. - path: shortest connection between selectors[0] (from) and selectors[1] (to). Direction-agnostic hop-labeled path; found:false when none within 6 hops. minimal:true = {id,name,filePath,startLine}-only (~50% cheaper) on callers/dependencies/blast_radius/implementers; granularity on callers/blast_radius. Rows may carry confidence (tiers in init usage); a cross-repo callers/dependencies row joined by a SCIP moniker also carries package (the package name that bridged the repos). 0 results: call locate (mode:text), not Grep; reason:"no_edges_indexed" = no edges.

Parameters24

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
commitSha	string	optional	Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:"architecture" as a preserved snapshot.
kind	string	optional	Relationship to traverse. See the tool description for each kind.
selectors	array	optional	Symbols to traverse from (1-10). heritage uses selectors[0]; chain: OR nodeId.
limit	integer	optional	Per-selector candidate cap (not heritage/chain).
includeCrossRepo	boolean	optional	Walk cross-repo edges. Default true for blast_radius, false otherwise.
expansionLimit	integer	optional	Caps returned count (not heritage/chain). Default 15.
intent	string	optional	Rerank by trigram similarity (not heritage/chain).
granularity	string	optional	callers/blast_radius. 'file' one row/file, 'site' one row/node.
minimal	boolean	optional	{id,name,filePath,startLine}-only, ~50% cheaper; not heritage/chain.
minimalImplementers	boolean	optional	Alias of minimal for implementers.
maxDepth	integer	optional	Max depth for heritage; also caps the kind:path walk (clamped to <=6).
nodeId	string	optional	Start node for chain (OR selectors[0]).
direction	string	optional	chain. 'downstream' leaves, 'upstream' entry points, 'both' (default).
depth	integer	optional	chain. Chain length.
edgeFilter	string	optional	chain. 'calls' \| 'imports' \| 'calls_imports' (default).
terminalFilter	string	optional	chain. Restrict to paths ending at a node matching this.
maxPaths	integer	optional	chain. Cap on returned paths.
followPolymorphism	boolean	optional	chain. Walk polymorphic dispatch edges (default false; untraversed hops in polymorphicBranchPoints).
landmarkFilter	string	optional	chain. Keep only paths through a node matching this.
pruneSetupMethods	boolean	optional	chain. Drop framework bootstrap steps.
staysWithinClass	boolean	optional	chain. Surface intra-class dispatch order.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "commitSha": {
      "description": "Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:\"architecture\" as a preserved snapshot.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "kind": {
      "default": "callers",
      "description": "Relationship to traverse. See the tool description for each kind.",
      "type": "string",
      "enum": [
        "callers",
        "dependencies",
        "blast_radius",
        "implementers",
        "heritage",
        "chain",
        "path"
      ]
    },
    "selectors": {
      "description": "Symbols to traverse from (1-10). heritage uses selectors[0]; chain: OR nodeId.",
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "nodeId": {
            "description": "Graph node id from a prior result.",
            "type": "string",
            "minLength": 1
          },
          "symbol": {
            "description": "Symbol name, e.g. a function or class name.",
            "type": "string",
            "minLength": 1
          },
          "symbolPath": {
            "description": "Full symbolPath as find_node/locate returns.",
            "type": "string",
            "minLength": 1
          },
          "filePath": {
            "description": "Repo-relative file path holding the symbol.",
            "type": "string",
            "minLength": 1
          }
        }
      }
    },
    "limit": {
      "description": "Per-selector candidate cap (not heritage/chain).",
      "default": 5,
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "includeCrossRepo": {
      "description": "Walk cross-repo edges. Default true for blast_radius, false otherwise.",
      "type": "boolean"
    },
    "expansionLimit": {
      "description": "Caps returned count (not heritage/chain). Default 15.",
      "default": 15,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "intent": {
      "description": "Rerank by trigram similarity (not heritage/chain).",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "granularity": {
      "description": "callers/blast_radius. 'file' one row/file, 'site' one row/node.",
      "default": "file",
      "type": "string",
      "enum": [
        "file",
        "site"
      ]
    },
    "minimal": {
      "description": "{id,name,filePath,startLine}-only, ~50% cheaper; not heritage/chain.",
      "default": false,
      "type": "boolean"
    },
    "minimalImplementers": {
      "description": "Alias of minimal for implementers.",
      "default": false,
      "type": "boolean"
    },
    "maxDepth": {
      "description": "Max depth for heritage; also caps the kind:path walk (clamped to <=6).",
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    },
    "nodeId": {
      "description": "Start node for chain (OR selectors[0]).",
      "type": "string",
      "minLength": 1
    },
    "direction": {
      "description": "chain. 'downstream' leaves, 'upstream' entry points, 'both' (default).",
      "default": "both",
      "type": "string",
      "enum": [
        "upstream",
        "downstream",
        "both"
      ]
    },
    "depth": {
      "description": "chain. Chain length.",
      "type": "integer",
      "minimum": 1,
      "maximum": 6
    },
    "edgeFilter": {
      "description": "chain. 'calls' | 'imports' | 'calls_imports' (default).",
      "default": "calls_imports",
      "type": "string",
      "enum": [
        "calls",
        "imports",
        "calls_imports"
      ]
    },
    "terminalFilter": {
      "description": "chain. Restrict to paths ending at a node matching this.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "maxPaths": {
      "description": "chain. Cap on returned paths.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "followPolymorphism": {
      "description": "chain. Walk polymorphic dispatch edges (default false; untraversed hops in polymorphicBranchPoints).",
      "type": "boolean"
    },
    "landmarkFilter": {
      "description": "chain. Keep only paths through a node matching this.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pruneSetupMethods": {
      "description": "chain. Drop framework bootstrap steps.",
      "type": "boolean"
    },
    "staysWithinClass": {
      "description": "chain. Surface intra-class dispatch order.",
      "type": "boolean"
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

source

Raw file/git access at the indexed commit, for cloud agents with no clone; with a clone prefer your own Read/Grep/git. Ops: - read: content of filePath, whole file or slice startLine..endLine. ifHash (a prior read's hash) returns {unchanged:true}, no content. compact:true strips blank/comment-only lines. - list: files+subdirs at path. grep: ripgrep pattern (glob/pathPrefix). tree: layout from path. stat: size/lines/language/binary for filePath. blame: authorship for filePath. diff: fromSha..toSha. Keys: {op:"read",filePath:"src/a.ts"}, {op:"grep",pattern:"foo"}, {op:"list",path:"src"}. filePath is the file, path the directory. Gated by the Source Access add-on; else source_access_required.

Parameters19

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
op	string	optional	See the tool description for each op. Omitted: inferred from the other args (pattern -> grep, fromSha/toSha -> diff, filePath/path -> read, nothing -> list).
filePath	string	optional	read/stat/blame: the file to open (required; `path` is accepted as an alias).
startLine	integer	optional	read/blame: first line, 1-based.
endLine	integer	optional	read/blame: last line, 1-based.
ifHash	string	optional	read: a prior read's hash; if it still matches, returns {unchanged:true}, no content.
compact	boolean	optional	read: strip blank/comment-only lines (heuristic; content no longer maps 1:1 to lines).
path	string	optional	list/tree/diff: dir path in the repo (default root). On read/stat/blame it is read as filePath, on grep as pathPrefix.
maxDepth	integer	optional	tree: max recursion depth, default 3.
pattern	string	optional	grep: ripgrep pattern (required; `query` is accepted as an alias).
query	string	optional	grep: alias for pattern.
glob	string	optional	grep: limit to files matching this glob.
pathPrefix	string	optional	grep: limit to files under this prefix.
limit	integer	optional	grep: max matches.
fromSha	string	optional	diff: base commit (required), reachable from the indexed branch.
toSha	string	optional	diff: target commit (required), reachable from the indexed branch.
commitSha	string	optional	Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:"architecture" as a preserved snapshot.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "op": {
      "description": "See the tool description for each op. Omitted: inferred from the other args (pattern -> grep, fromSha/toSha -> diff, filePath/path -> read, nothing -> list).",
      "type": "string",
      "enum": [
        "read",
        "list",
        "grep",
        "tree",
        "stat",
        "blame",
        "diff"
      ]
    },
    "filePath": {
      "description": "read/stat/blame: the file to open (required; `path` is accepted as an alias).",
      "type": "string",
      "minLength": 1
    },
    "startLine": {
      "description": "read/blame: first line, 1-based.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "endLine": {
      "description": "read/blame: last line, 1-based.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "ifHash": {
      "description": "read: a prior read's hash; if it still matches, returns {unchanged:true}, no content.",
      "type": "string",
      "minLength": 1
    },
    "compact": {
      "description": "read: strip blank/comment-only lines (heuristic; content no longer maps 1:1 to lines).",
      "default": false,
      "type": "boolean"
    },
    "path": {
      "description": "list/tree/diff: dir path in the repo (default root). On read/stat/blame it is read as filePath, on grep as pathPrefix.",
      "type": "string"
    },
    "maxDepth": {
      "description": "tree: max recursion depth, default 3.",
      "type": "integer",
      "minimum": 1,
      "maximum": 10
    },
    "pattern": {
      "description": "grep: ripgrep pattern (required; `query` is accepted as an alias).",
      "type": "string",
      "minLength": 1
    },
    "query": {
      "description": "grep: alias for pattern.",
      "type": "string",
      "minLength": 1
    },
    "glob": {
      "description": "grep: limit to files matching this glob.",
      "type": "string"
    },
    "pathPrefix": {
      "description": "grep: limit to files under this prefix.",
      "type": "string"
    },
    "limit": {
      "description": "grep: max matches.",
      "type": "integer",
      "minimum": 1,
      "maximum": 500
    },
    "fromSha": {
      "description": "diff: base commit (required), reachable from the indexed branch.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "toSha": {
      "description": "diff: target commit (required), reachable from the indexed branch.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "commitSha": {
      "description": "Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:\"architecture\" as a preserved snapshot.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

history

Indexed commit history. Ops: - commits: recent commits (metadata + file list); <=200/call, default 50. With a clone prefer git log. - commit: one commit by sha with its diff summary (added/modified/deleted/renamed); null if outside the indexed window. - recently_changed: files ranked by change frequency in the indexed window ("what's hot").

Parameters10

op	string	required	commits: recent commits (metadata + file list). commit: one commit in detail. recently_changed: most-changed files over the window.
projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
sha	string	optional	op:commit. The commit to read (7-64 hex).
since	string	optional	ISO datetime lower bound.
until	string	optional	ISO datetime upper bound.
author	string	optional	Filter by author name or email substring.
path	string	optional	Restrict to commits touching this repo-relative path.
limit	integer	optional	Max rows (default 50, max 200).
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "op": {
      "type": "string",
      "enum": [
        "commits",
        "commit",
        "recently_changed"
      ],
      "description": "commits: recent commits (metadata + file list). commit: one commit in detail. recently_changed: most-changed files over the window."
    },
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "sha": {
      "description": "op:commit. The commit to read (7-64 hex).",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,64}$"
    },
    "since": {
      "description": "ISO datetime lower bound.",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "until": {
      "description": "ISO datetime upper bound.",
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z))$"
    },
    "author": {
      "description": "Filter by author name or email substring.",
      "type": "string"
    },
    "path": {
      "description": "Restrict to commits touching this repo-relative path.",
      "type": "string"
    },
    "limit": {
      "description": "Max rows (default 50, max 200).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "op"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

library

Library catalog lookups. Ops: - packages: list indexed npm packages (specifier, ecosystem, owner/name, indexed-at, sha). Tenant-scoped, no projectId. - version: one package's resolved version for a project (sha, version, dep type, indexed-at, status indexed|indexing|failed|not_found). "indexing" means a job for that revision is in flight, so retrying later converges; "failed" carries a reason and does not change on its own.

Parameters5

op	string	required	packages: list indexed packages. version: resolve one specifier's indexed version.
projectId	string	optional	Project id from init/list_projects. Omit for the active project.
specifier	string	optional	op:version. Package specifier, e.g. "react".
limit	integer	optional	op:packages. Max rows (default 50, max 200).
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "op": {
      "type": "string",
      "enum": [
        "packages",
        "version"
      ],
      "description": "packages: list indexed packages. version: resolve one specifier's indexed version."
    },
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "specifier": {
      "description": "op:version. Package specifier, e.g. \"react\".",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "limit": {
      "default": 50,
      "description": "op:packages. Max rows (default 50, max 200).",
      "type": "integer",
      "minimum": 1,
      "maximum": 200
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "op"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

ref

Session-scoped branch / working-tree overlay. Ops: - use: pin a repository's reads to a branch (latest indexed revision). Branch must be tracked+indexed (open a PR, or add on the dashboard); else "indexing_in_progress". commitSha overrides. - clear: remove the pin, revert to default. - index_working_tree: overlay UNCOMMITTED edits (changedFiles path+content, optional deletedPaths/baseSha) on a short-lived synthetic revision pinned here; find_node/locate/relate reflect them, source and locate mode:semantic do NOT. Cap 100 files/256KB.

Parameters8

op	string	required	use: pin reads to a tracked branch. clear: revert to the default branch. index_working_tree: overlay uncommitted edits on a synthetic revision and pin it.
branch	string	optional	op:use. The tracked branch to pin.
changedFiles	array	optional	Changed/added files with current contents, repo-relative paths.
baseSha	string	optional	Indexed base your edits sit on. Omit for the default-branch tip.
deletedPaths	array	optional	Repo-relative deleted paths.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
projectId	string	optional	Project id from init/list_projects. Omit for the active project.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "op": {
      "type": "string",
      "enum": [
        "use",
        "clear",
        "index_working_tree"
      ],
      "description": "use: pin reads to a tracked branch. clear: revert to the default branch. index_working_tree: overlay uncommitted edits on a synthetic revision and pin it."
    },
    "branch": {
      "description": "op:use. The tracked branch to pin.",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "changedFiles": {
      "minItems": 1,
      "maxItems": 100,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024,
            "description": "Repo-relative file path."
          },
          "content": {
            "type": "string",
            "maxLength": 262144,
            "description": "Full current file content."
          }
        },
        "required": [
          "path",
          "content"
        ]
      },
      "description": "Changed/added files with current contents, repo-relative paths."
    },
    "baseSha": {
      "description": "Indexed base your edits sit on. Omit for the default-branch tip.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "deletedPaths": {
      "description": "Repo-relative deleted paths.",
      "maxItems": 200,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 1024
      }
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "op"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

adr

Architecture decision records: the WHY behind code, anchored to a symbol/file/project. Survive reindexes; find_node attaches a node's decisions. Ops: - record: needs title+decision. Anchor with repository+symbolPath or +filePath; omit both for project-wide. Optional context, consequences, status. - list: records for a project, filter by repository/symbolPath/filePath/status. - update: needs id; status:"superseded"+supersededById, or "deprecated".

Parameters14

op	string	required	record: create a decision record. list: read records. update: amend or supersede one.
projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
title	string	optional	record: short imperative title, e.g. "No pgvector".
decision	string	optional	record: what was decided.
context	string	optional	Why (constraints, alternatives rejected).
consequences	string	optional	Trade-offs accepted.
status	string	optional	record/update: lifecycle status.
symbolPath	string	optional	Anchor: symbolPath as find_node / locate returns.
filePath	string	optional	Anchor: repo-relative file path.
id	integer	optional	update: record id (from adr list or find_node decisions).
supersededById	integer	optional	update: id of the replacement record.
limit	integer	optional	list: max records (default 20).
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "op": {
      "type": "string",
      "enum": [
        "record",
        "list",
        "update"
      ],
      "description": "record: create a decision record. list: read records. update: amend or supersede one."
    },
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "title": {
      "description": "record: short imperative title, e.g. \"No pgvector\".",
      "type": "string",
      "minLength": 3,
      "maxLength": 200
    },
    "decision": {
      "description": "record: what was decided.",
      "type": "string",
      "minLength": 3,
      "maxLength": 20000
    },
    "context": {
      "description": "Why (constraints, alternatives rejected).",
      "type": "string",
      "maxLength": 20000
    },
    "consequences": {
      "description": "Trade-offs accepted.",
      "type": "string",
      "maxLength": 20000
    },
    "status": {
      "description": "record/update: lifecycle status.",
      "type": "string",
      "enum": [
        "proposed",
        "accepted",
        "superseded",
        "deprecated"
      ]
    },
    "symbolPath": {
      "description": "Anchor: symbolPath as find_node / locate returns.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "filePath": {
      "description": "Anchor: repo-relative file path.",
      "type": "string",
      "minLength": 1,
      "maxLength": 2000
    },
    "id": {
      "description": "update: record id (from adr list or find_node decisions).",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "supersededById": {
      "description": "update: id of the replacement record.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "limit": {
      "description": "list: max records (default 20).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "op"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

diff_impact

Impact of a diff between two indexed revisions of one repo (base..head): changed files + symbols, union blast radius (layers + cross-repo fallout), affected endpoints, test suites, and co-change reminders. Replaces per-symbol relate (kind:blast_radius) loops before merging. Defaults: head = session's effective revision, base = previous indexed. For UNCOMMITTED edits, run ref (op:"index_working_tree"), then call with no shas.

Parameters7

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
base	string	optional	Base revision (7-40 hex). Omit for the previous indexed.
head	string	optional	Head revision (7-40 hex). Omit for the session's effective revision.
includeCrossRepo	boolean	optional	Include cross-repo fallout (default true).
expansionLimit	integer	optional	Cap on impacted nodes (default 25); totals always reported.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "base": {
      "description": "Base revision (7-40 hex). Omit for the previous indexed.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "head": {
      "description": "Head revision (7-40 hex). Omit for the session's effective revision.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "includeCrossRepo": {
      "description": "Include cross-repo fallout (default true).",
      "type": "boolean"
    },
    "expansionLimit": {
      "description": "Cap on impacted nodes (default 25); totals always reported.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

estimate_scope

Pre-flight estimate before graph traversal: coarse count of files a task likely touches and whether it spans layers (common/browser/node/electron-main/...) or repositories. Decides single-file edit vs consulting the graph. Heuristic, from symbol-name + text matches.

Parameters3

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
description	string	required	Natural-language description of the intended change.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "description": {
      "type": "string",
      "minLength": 3,
      "maxLength": 2000,
      "description": "Natural-language description of the intended change."
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "description"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

list_projects

List all projects with indexing summaries. Find a project by name or check which exist.

Parameters1

feedback

object

optional

Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

list_repositories

List repositories in a project. Find repository names to scope a query to one repo.

Parameters2

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

list_file_symbols

List symbols in one file (name + kind + line bounds). Step 1 of the two-step read: get line bounds, then pass startLine/endLine to source (op:read) for that slice only (~4-15x fewer tokens). For one symbol + signature, use find_node {symbol, filePath}.

Parameters5

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
commitSha	string	optional	Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:"architecture" as a preserved snapshot.
filePath	string	required	Repo-relative file path to list symbols for.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "commitSha": {
      "description": "Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:\"architecture\" as a preserved snapshot.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "filePath": {
      "type": "string",
      "minLength": 1,
      "description": "Repo-relative file path to list symbols for."
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "filePath"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

map

Token-efficient repo (or subtree) skeleton: directory tree with each file's classes (methods in parens), functions, and HTTP endpoints, from the graph. Orient before drilling in. Scope with "path", cap with "maxDepth", density:"full" adds properties. view:"architecture" instead returns a module map (Louvain clusters with hubs, paths and cross-module coupling), plus namedModules/totalModules: a module NAME comes from a generated summary and is provisional, its id (the member-set hash in the header) is the stable key, so pin modules by id and re-read names rather than caching them.

Parameters8

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
commitSha	string	optional	Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:"architecture" as a preserved snapshot.
path	string	optional	Repo-relative subtree (e.g. "src/v1/mcp"). Omit for the whole repo.
maxDepth	integer	optional	Drop files deeper than this many path segments. Omit for no cap.
density	string	optional	"compact" (default): classes/methods/functions/endpoints. "full" adds properties.
view	string	optional	"tree" (default): file/symbol skeleton. "architecture": module map with hubs, coupling, cycles. Module names come from generated summaries: cite a module by its id (the member-set hash printed in the header), which is stable across calls and reindexes.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "commitSha": {
      "description": "Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:\"architecture\" as a preserved snapshot.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "path": {
      "description": "Repo-relative subtree (e.g. \"src/v1/mcp\"). Omit for the whole repo.",
      "type": "string",
      "minLength": 1
    },
    "maxDepth": {
      "description": "Drop files deeper than this many path segments. Omit for no cap.",
      "type": "integer",
      "minimum": 1,
      "maximum": 9007199254740991
    },
    "density": {
      "description": "\"compact\" (default): classes/methods/functions/endpoints. \"full\" adds properties.",
      "type": "string",
      "enum": [
        "compact",
        "full"
      ]
    },
    "view": {
      "description": "\"tree\" (default): file/symbol skeleton. \"architecture\": module map with hubs, coupling, cycles. Module names come from generated summaries: cite a module by its id (the member-set hash printed in the header), which is stable across calls and reindexes.",
      "type": "string",
      "enum": [
        "tree",
        "architecture"
      ]
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

list_tests_for

Test suites and cases whose suite name matches a symbol name (case-insensitive substring). Call before adding tests to see existing coverage and mirror its shape.

Parameters5

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
commitSha	string	optional	Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:"architecture" as a preserved snapshot.
selector	string	required	Symbol name to match against test suite names.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "commitSha": {
      "description": "Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:\"architecture\" as a preserved snapshot.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "selector": {
      "type": "string",
      "minLength": 1,
      "description": "Symbol name to match against test suite names."
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "selector"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

quick_lookup

Fast substring lookup of symbol DEFINITIONS by name: rows {name, kind, filePath, startLine, repositoryName} (displayName only when distinct from name), no ranking, no semantic. Cheaper alternative to locate (mode:symbol) for latency-sensitive pre-fetch (grep-augment hook); interactive search should prefer locate/find_node. Reads the latest indexed revision, no ref pin.

Parameters5

query	string	required	Substring to match against symbol names (no ranking).
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
projectId	string	optional	Project id from init/list_projects. Omit for the active project.
limit	integer	optional	Max results (max 20).
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Substring to match against symbol names (no ranking)."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "limit": {
      "description": "Max results (max 20).",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

freshness

Returns lastIndexedSha, lastIndexedAt, and the current remote HEAD sha for a repository: detect index drift from remote. Reports what Symvanta knows, not local git. currentRemoteSha is null when no GitHub credential is configured. Echoes the active ref pin (pinnedBranch, pinnedSha).

Parameters3

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

index_health

Per-project index health. pendingLibraryVersions: cross-repo specifiers still indexing (an empty result may mean "not indexed yet", not "not in code"); call when a query is surprisingly empty. A row with status "skipped" is never going to arrive (a dev or optional dependency, which the catalog does not index) and status "failed" means discovery found no source, so only "indexing" is worth waiting on. architecture: per-repo Louvain module count + modularity Q (low Q = tangled), plus circular-dependency and mutually-recursive-symbol counts (inspect via map view:"architecture"). versionDrift: joined cross-repo SCIP edges whose consumer-pinned package version differs from the sibling's current version (package, pinned vs current, edge count). externalsCoverage: per-repo count of external references joined onto a sibling definition vs left as materialized stubs. unindexableRepositories: repos whose last index produced no graph and left a status (no_default_branch = the remote has no resolvable default branch, e.g. an empty repo; awaiting_upload = an upload-provider repo with no zip yet; remote_head_unresolvable = the remote could not be reached to resolve its head, so this is a network or credential problem, not a repository one), with the worker's log line as indexStatusDetail; explains a silently-empty repo. degradedRepositories: repos that DID index but lost a derived artifact (community_detection_skipped = Louvain clustering did not run, so map view:"architecture" has no modules; raise COMMUNITY_EDGE_CEILING or set COMMUNITY_DETECTION=true, then reindex). Both carry a human-readable reason.

Parameters3

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

find_http_route

Resolve an HTTP route by path + optional method to endpoint + handler (filePath + line bounds). Use instead of grep/locate for URL paths: follows framework router metadata (Express, Fastify, Hono, Laravel, FastAPI, etc.) and resolves dynamic segments, prefix groups, and middleware-mounted routers text search misses.

Parameters6

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
commitSha	string	optional	Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:"architecture" as a preserved snapshot.
path	string	required	Route path, e.g. "/api/users/:id". Partial paths match.
method	string	optional	HTTP method filter, e.g. GET or POST.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "commitSha": {
      "description": "Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:\"architecture\" as a preserved snapshot.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "path": {
      "type": "string",
      "minLength": 1,
      "description": "Route path, e.g. \"/api/users/:id\". Partial paths match."
    },
    "method": {
      "description": "HTTP method filter, e.g. GET or POST.",
      "type": "string",
      "minLength": 1
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "path"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

find_node

Resolve 1-10 symbols to filePath + line bounds + signature. selectors: array keyed by symbol (bare name) / symbolPath / filePath / nodeId; a flat query/name/single field also works. includeSource=true adds the excerpt, includeSummaries=true AI summaries. A node from a SCIP-indexed package also carries scip_package_name (and scip_package_version / scip_manager when known). For a class/interface/struct/protocol it carries a compact heritage field (<=5 ancestors, <=20 descendants, omitted when empty); includeHeritage:false skips it, includeCrossRepo:true walks cross-repo heritage. {resolved:false, candidates} = no confident match.

Parameters13

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
commitSha	string	optional	Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:"architecture" as a preserved snapshot.
selectors	array	required	Symbols to resolve (1-10), each by nodeId, symbol, symbolPath, or filePath.
limit	integer	optional	Max results (default 5, max 20).
includeSummaries	boolean	optional	Attach generated summaries when available.
includeSource	boolean	optional	Attach source for resolved nodes.
sourceMode	string	optional	With includeSource: "signature" returns the declaration only.
expansionLimit	integer	optional	Cap on expanded related nodes (default 15, max 100).
includeHeritage	boolean	optional	Default true. Include a compact heritage field for a class/interface/struct/protocol. false skips it on bulk scans.
includeCrossRepo	boolean	optional	With includeHeritage on, walk cross-repo heritage edges. No-op when includeHeritage is off.
includeCommunity	boolean	optional	Attach the symbol's Louvain module (community name). Off by default (extra edge lookup).
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "commitSha": {
      "description": "Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:\"architecture\" as a preserved snapshot.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "selectors": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "nodeId": {
            "description": "Graph node id from a prior result.",
            "type": "string",
            "minLength": 1
          },
          "symbol": {
            "description": "Symbol name, e.g. a function or class name.",
            "type": "string",
            "minLength": 1
          },
          "symbolPath": {
            "description": "Full symbolPath as find_node/locate returns.",
            "type": "string",
            "minLength": 1
          },
          "filePath": {
            "description": "Repo-relative file path holding the symbol.",
            "type": "string",
            "minLength": 1
          }
        }
      },
      "description": "Symbols to resolve (1-10), each by nodeId, symbol, symbolPath, or filePath."
    },
    "limit": {
      "default": 5,
      "description": "Max results (default 5, max 20).",
      "type": "integer",
      "minimum": 1,
      "maximum": 20
    },
    "includeSummaries": {
      "description": "Attach generated summaries when available.",
      "default": false,
      "type": "boolean"
    },
    "includeSource": {
      "description": "Attach source for resolved nodes.",
      "default": false,
      "type": "boolean"
    },
    "sourceMode": {
      "description": "With includeSource: \"signature\" returns the declaration only.",
      "type": "string",
      "enum": [
        "none",
        "signature"
      ]
    },
    "expansionLimit": {
      "default": 15,
      "description": "Cap on expanded related nodes (default 15, max 100).",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "includeHeritage": {
      "description": "Default true. Include a compact heritage field for a class/interface/struct/protocol. false skips it on bulk scans.",
      "default": true,
      "type": "boolean"
    },
    "includeCrossRepo": {
      "description": "With includeHeritage on, walk cross-repo heritage edges. No-op when includeHeritage is off.",
      "default": false,
      "type": "boolean"
    },
    "includeCommunity": {
      "description": "Attach the symbol's Louvain module (community name). Off by default (extra edge lookup).",
      "default": false,
      "type": "boolean"
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "selectors"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

ask_codebase

Synthesis Q&A for behavior/architecture questions: answer + citations in one call. HEAVY (~2-4 s, ~3-5 k tokens): prefer context, find_node, or locate when they suffice. scope:"repo" (default) = ONE repo; scope:"all" = cross-repo (repositoryIds narrows, omit spans all; rejects repository). If sufficient_to_answer=true, answer without further tool calls. commitSha pins a revision.

Parameters9

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
commitSha	string	optional	Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:"architecture" as a preserved snapshot.
query	string	optional	Alias of question.
question	string	optional	The behavior question, e.g. "how does X work".
scope	string	optional	repo (default) = single-repo. all = cross-repo; repositoryIds narrows, omit spans all.
repositoryIds	array	optional	scope:all only. Restrict to these encoded repository ids.
limit	integer	optional	Max candidate symbols fed to synthesis (default 10, max 30).
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "commitSha": {
      "description": "Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:\"architecture\" as a preserved snapshot.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "query": {
      "description": "Alias of question.",
      "type": "string",
      "minLength": 1
    },
    "question": {
      "description": "The behavior question, e.g. \"how does X work\".",
      "type": "string",
      "minLength": 1
    },
    "scope": {
      "description": "repo (default) = single-repo. all = cross-repo; repositoryIds narrows, omit spans all.",
      "default": "repo",
      "type": "string",
      "enum": [
        "repo",
        "all"
      ]
    },
    "repositoryIds": {
      "description": "scope:all only. Restrict to these encoded repository ids.",
      "minItems": 1,
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "description": "Encoded repository id from list_repositories."
      }
    },
    "limit": {
      "description": "Max candidate symbols fed to synthesis (default 10, max 30).",
      "default": 10,
      "type": "integer",
      "minimum": 1,
      "maximum": 30
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

add_repository

Attach a public GitHub repository to the active project (owner + repo_name; clone URL derived). Idempotent. First attach dispatches an indexing job; response carries indexing_status ("queued" | "already_indexed") and indexing_job_id to poll. Data available once the index is stable.

Parameters5

owner	string	required	GitHub owner (user or org)
repo_name	string	required	Repository name
default_branch	string	optional	Default branch (default main)
projectId	string	optional	Project id from init/list_projects. Omit for the active project.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^[a-zA-Z0-9\\-_.]+$",
      "description": "GitHub owner (user or org)"
    },
    "repo_name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^[a-zA-Z0-9\\-_.]+$",
      "description": "Repository name"
    },
    "default_branch": {
      "description": "Default branch (default main)",
      "type": "string",
      "minLength": 1,
      "maxLength": 255
    },
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "owner",
    "repo_name"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

reindex_repository

Dispatch a reindex job for an already-attached repository (repositoryId from list_repositories / add_repository). Optional commit_sha pin. force:true re-applies the current parser even when unchanged at HEAD: it bypasses the per-file hash-skip AND re-runs the SCIP indexer subprocesses (no same-sha .scip cache serve), so a parser fix inside a SCIP runner, an external-moniker re-pin, or a toolchain upgrade takes effect without a version bump.

Parameters5

repositoryId	string	required	Encoded repository ID (from list_repositories/add_repository)
commit_sha	string	optional	Pin to a commit (omit for latest)
force	boolean	optional	Re-parse every file AND re-run the SCIP indexer subprocesses even if unchanged at HEAD (for a parser fix without a version bump)
projectId	string	optional	Project id from init/list_projects. Omit for the active project.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "repositoryId": {
      "type": "string",
      "minLength": 1,
      "description": "Encoded repository ID (from list_repositories/add_repository)"
    },
    "commit_sha": {
      "description": "Pin to a commit (omit for latest)",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "force": {
      "description": "Re-parse every file AND re-run the SCIP indexer subprocesses even if unchanged at HEAD (for a parser fix without a version bump)",
      "type": "boolean"
    },
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "repositoryId"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

context

First-touch task orientation. Pass a natural-language task; returns the top 5 relevant files with their symbols and best-matching snippets in one call (~1-1.5k tokens, ~500 ms, no LLM). Replaces chaining locate (text) + locate (semantic) + list_file_symbols. Known symbol: find_node/locate. Synthesized explanation: ask_codebase.

Parameters5

task	string	required	Natural-language task. Returns ranked files with symbols and matching snippets, no LLM call.
projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
commitSha	string	optional	Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:"architecture" as a preserved snapshot.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "task": {
      "type": "string",
      "minLength": 3,
      "maxLength": 1024,
      "description": "Natural-language task. Returns ranked files with symbols and matching snippets, no LLM call."
    },
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "commitSha": {
      "description": "Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:\"architecture\" as a preserved snapshot.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "task"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

bundle

Run up to 10 independent tool calls in parallel in one round-trip. Calls share the bundle-level project/repository scope unless a call sets its own args.repository, which scopes that call alone. Supported: locate (args.mode text|symbol|semantic|file|config, not codebase), relate (kind:callers only), find_node, list_file_symbols, find_http_route. Returns results in input order; unsupported tool names return {error}.

Parameters5

projectId	string	optional	Project id from init/list_projects. Omit for the active project.
repository	string	optional	Repository full name, e.g. "owner/repo". Omit when the project has one repository.
commitSha	string	optional	Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:"architecture" as a preserved snapshot.
calls	array	required	Calls to run in parallel; each uses the bundle's project/repository scope unless its args.repository names another one.
feedback	object	optional	Optional: report how a previous answer worked out; piggybacks on any call.

Raw schema

{
  "type": "object",
  "properties": {
    "projectId": {
      "type": "string",
      "minLength": 1,
      "description": "Project id from init/list_projects. Omit for the active project."
    },
    "repository": {
      "type": "string",
      "minLength": 1,
      "description": "Repository full name, e.g. \"owner/repo\". Omit when the project has one repository."
    },
    "commitSha": {
      "description": "Pin reads to one indexed revision (7-40 hex). Graph tools error with revision_not_indexed when it is not an indexed revision of the scoped repository, or revision_not_servable when that revision's graph was superseded by a later reindex, and echo the revision served back as commitSha; source ops read git objects, so any commit works there. Exception: a kept revision (revisions rows flagged architectureSnapshot) still serves map view:\"architecture\" as a preserved snapshot.",
      "type": "string",
      "pattern": "^[0-9a-fA-F]{7,40}$"
    },
    "calls": {
      "minItems": 1,
      "maxItems": 10,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "tool": {
            "type": "string",
            "minLength": 1,
            "description": "Tool name to call"
          },
          "args": {
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {},
            "description": "Arguments for the call"
          }
        },
        "required": [
          "tool",
          "args"
        ]
      },
      "description": "Calls to run in parallel; each uses the bundle's project/repository scope unless its args.repository names another one."
    },
    "feedback": {
      "description": "Optional: report how a previous answer worked out; piggybacks on any call.",
      "type": "object",
      "properties": {
        "answerId": {
          "type": "string",
          "minLength": 36,
          "maxLength": 36,
          "description": "answer_id from a previous ask_codebase response"
        },
        "outcome": {
          "type": "string",
          "enum": [
            "useful",
            "dead_end",
            "corrected"
          ],
          "description": "How the answer worked out."
        },
        "correction": {
          "description": "Only when the user corrected the answer",
          "type": "string",
          "maxLength": 2000
        }
      },
      "required": [
        "answerId",
        "outcome"
      ]
    }
  },
  "required": [
    "calls"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

README.md12 KBView on GitHub

Symvanta plugin for Claude Code

One-step setup for working in a Symvanta-indexed codebase. Installing this plugin:

registers the Symvanta MCP server (default https://mcp.symvanta.com/mcp, configurable for on-prem / self-hosted, OAuth on first connection), so you do not edit .mcp.json by hand;
injects standing context once at the start of every session so the agent reaches for the Symvanta code-graph tools instead of shell search;
ships a symvanta skill with the full tool decision matrix and conventions;
adds slash commands that wrap the common graph workflows.

Commands

Each command routes to the right Symvanta MCP tool so you do not have to remember tool names:

/symvanta:ask [question]: answer a behavior question (how does X work, why does Y happen) via ask_codebase, with file citations.
/symvanta:blast [symbol]: blast-radius safety check before editing a symbol.
/symvanta:trace [symbol]: map a function's call chain, callers, and dependencies.
/symvanta:route [METHOD /path]: find the handler for an HTTP route.
/symvanta:status: connection and index health snapshot (project, repositories, freshness, edge counts).
/symvanta:architecture: high-level module map (Louvain functional modules, PageRank hubs, cross-module coupling, and the repo-wide load-bearing functions) via map view:"architecture".
/symvanta:scope [symbol or change]: pre-flight scope/impact estimate before you size a change (estimate_scope).
/symvanta:branch [name | clear]: pin this session's reads to a tracked feature branch, or clear the pin (ref).
/symvanta:working-tree: overlay your uncommitted edits so the graph reflects changes you have not pushed (ref op:"index_working_tree").
/symvanta:tests [symbol]: find the tests that cover a symbol (list_tests_for).
/symvanta:recent [path]: recently changed files and recent commits (history).
/symvanta:setup [local]: write the Symvanta routing block into the project's CLAUDE.md (or CLAUDE.local.md with local). Re-running replaces the marked block in place. Subagents read CLAUDE.md, so the routing reaches them too.

Install

In Claude Code:

code

/plugin marketplace add https://symvanta.com/plugin/marketplace.json
/plugin install symvanta@symvanta

Sign in with OAuth when prompted on first connection. Your workspace's Getting Started page in the Symvanta dashboard shows the exact marketplace URL for your account.

Configuration

The plugin points at Symvanta Cloud (https://mcp.symvanta.com/mcp) by default, so Cloud users configure nothing. To point at a different Symvanta server, set the Symvanta MCP server URL (mcpUrl) plugin option: accept or change it when you enable the plugin, or later via the /plugin interface (Symvanta -> configure). Leave it blank to fall back to the Cloud default.

Use the full endpoint URL including the /mcp path, with no trailing slash, for example https://mcp.your-company.com/mcp. A bare host or a trailing slash will fail to connect.

Authentication. Every Symvanta MCP server (Cloud, staging, or on-prem) advertises its own OAuth endpoints, so Claude Code signs you in with OAuth on first connection whatever URL mcpUrl points at, nothing to configure in the plugin. On-prem supports the same OAuth flow: its gateway completes sign-in against your Symvanta cloud / license and the server verifies the issued token. Static API-key / bearer-token auth also exists for headless automation, but that is configured on the server or in your own MCP settings, not in this plugin.

Updating

code

/plugin update symvanta@symvanta

Then restart Claude Code. Claude Code reads the plugin (including hooks/hooks.json) when it loads, not continuously, so a running session keeps the previously loaded version until you restart. Until then a /plugin update is downloaded but not active.

What runs on your machine

The plugin executes small, readable Node hook scripts locally:

session-start.js: prints standing context once at the start of a session. Reads the checkout's git remote (owner/name) so it can tell the agent to call init with repository set to it, which binds the session to the project that holds this checkout instead of the workspace default. Sends nothing anywhere.
The augment hook family (on by default): five hooks sharing one core (lib.js). Each can only add context, never block: every error, timeout, or missing token is a clean pass-through, and the intercepted tool always runs untouched. Every hook first checks that the checkout it fires in is attached to a Symvanta project (one init call per checkout per ten minutes, memoized); a checkout attached nowhere, or a git checkout with no remote, keeps the hooks silent, so you never see another codebase's symbols while working in an unindexed one.
- grep-augment.js: on Grep/Glob, looks up matching indexed symbol definitions (scoped to the repo you are searching, up to two identifiers from the pattern in parallel, 60s cache) and adds them alongside the raw search results.
- edit-augment.js: on Edit/Write of a code file, injects the edited symbol's blast radius (upstream symbol count, files, layers, cross-repo edges, risk tier) before the change lands; a Write over an existing file lists the definitions the overwrite replaces. New files and non-code files stay silent.
- read-augment.js: on the first Read of a code file per session, injects the file's symbol skeleton (names, kinds, line bounds) plus any architecture decision records anchored to it. Repeat reads exit instantly.
- grep-rescue.js: after a Grep that found nothing, suggests graph candidates (auto text/semantic search) so a dead end becomes a lead; a grep with results exits right after the stdin parse, no reads, no network.
- prompt-augment.js: identifier-shaped tokens in your message (backticked spans, snake_case, camelCase) resolve to indexed definitions at turn start. Plain prose never qualifies, so conversational prompts stay silent.

What the augmenters read, send, and write, exactly

To call the graph they need your Symvanta MCP token. They reuse the one Claude Code already stored when you connected, so there is no setup. The read is deliberately narrow and each script is short enough to audit in minutes:

They read only mcpOAuth[<the Symvanta entry>].accessToken from ~/.claude/.credentials.json (on macOS, Claude Code stores this in the login Keychain instead, under service Claude Code-credentials, so the hooks read that when the file is absent). Never your Anthropic token (claudeAiOauth) or any non-Symvanta server's token.
That token is sent only to the Symvanta MCP server, the same place it was issued for.
What leaves the machine per lookup: extracted identifier terms, matched symbol names, repo-relative file paths, and the checkout's GitHub remote as owner/name (the attachment check). Never file contents, and never your message text (the prompt hook sends at most two identifier tokens, not the prompt).
They write local files under ~/.symvanta/, never uploaded anywhere: grep-cache/ (the 60s result cache, one small file per key), repo-cache.json (path-to-repo memo), workspace-cache.json (per-checkout attachment memo, 10 minutes), keychain-cache.json (macOS only: a 5-minute memo of the Keychain read, so a busy session doesn't shell out to security on every tool call), read-seen/ (per-session first-read markers), and grep-augment.log (one JSONL line per run: hook, terms, repo, match count, latency, cache hit). The log exists so /symvanta:status can show what the hooks are doing; delete any of these files anytime.

Switches (restart Claude Code after changing):

code

# Supply your own token instead (dashboard -> Settings -> MCP connection ->
# regenerate gives a Passport mcp:read token); the credentials file is then
# never read:
export SYMVANTA_MCP_TOKEN="<token>"

# Turn the whole family off (no reads, no network on any tool call):
export SYMVANTA_AUGMENT=off        # the legacy SYMVANTA_GREP_AUGMENT=off also works

# Or turn off individual hooks:
export SYMVANTA_EDIT_AUGMENT=off   # Edit/Write blast radius
export SYMVANTA_READ_AUGMENT=off   # first-read skeleton + ADRs
export SYMVANTA_GREP_RESCUE=off    # empty-grep suggestions
export SYMVANTA_PROMPT_AUGMENT=off # prompt term lookup

You can also delete any hook's block from hooks/hooks.json to remove it entirely.

Bash and every tool without a hook above run untouched. All code navigation happens through the Symvanta MCP server over HTTPS, gated by OAuth. No telemetry, no background processes.

How the Grep/Glob augmenter works

Every gate fails safe to the same pass-through, and both pass-through and success land on "Grep runs normally": the hook can only add context, never block or delay the search to failure. SYMVANTA_GREP_AUGMENT=off short-circuits before anything is read or sent.

flowchart TD
    A["Agent runs Grep or Glob"] --> B{{"Claude Code fires the PreToolUse hook"}}
    B --> D{"SYMVANTA_GREP_AUGMENT = off?"}
    D -->|yes| RUN["Grep/Glob runs normally; results unchanged"]
    D -->|no, default| TX["Extract up to 2 identifiers from the pattern; derive the repo from the search path"]
    TX --> CACHE{"Fresh 60s cache hit?"}
    CACHE -->|yes| F["Format matching definitions as additionalContext"]
    CACHE -->|no| TOK["Token: SYMVANTA_MCP_TOKEN, else the stored Symvanta token from ~/.claude/.credentials.json (macOS: login Keychain)"]
    TOK --> C["quick_lookup per term, in parallel, repo-scoped, hard cap 1.5s; falls back to locate mode:symbol"]

    subgraph cloud["Symvanta cloud (only the search TERMs leave your machine)"]
        C --> M["mcp.symvanta.com"]
        M --> DB[("Code graph in Postgres")]
        DB --> M
    end

    C --> OK{"Token valid and matches, in time?"}
    OK -->|no, error, or timeout| LOG["Append one line to ~/.symvanta/grep-augment.log"]
    OK -->|yes| CW["Cache for 60s"] --> F
    F --> EM["Emit JSON to Claude Code"] --> LOG
    LOG --> RUN
    RUN --> O["Agent sees its grep results PLUS the Symvanta definitions, then reaches for find_node / relate / ask_codebase"]

Uninstall

code

/plugin uninstall symvanta@symvanta
/plugin marketplace remove symvanta

Layout

code

.claude-plugin/plugin.json   manifest + MCP server registration
hooks/hooks.json             SessionStart + augment family wiring (PreToolUse, PostToolUse, UserPromptSubmit)
hooks/session-start.js       standing-context injector
hooks/lib.js                 shared augment core (auth, transport, cache, log)
hooks/grep-augment.js        Grep/Glob definition augmenter
hooks/edit-augment.js        Edit/Write blast-radius augmenter
hooks/read-augment.js        first-read file skeleton + ADR augmenter
hooks/grep-rescue.js         empty-grep graph suggestions (PostToolUse)
hooks/prompt-augment.js      prompt identifier lookup (UserPromptSubmit)
hooks/augment-stats.js       local activity summary for /symvanta:status
commands/                    slash commands (ask, blast, trace, route, status, architecture, scope, branch, working-tree, tests, recent)
skills/symvanta/SKILL.md     tool decision matrix and conventions
scripts/                     sync-skill.mjs (SKILL from source) + check-tool-prefixes.mjs (CI guard)

License

MIT

Install

Tools (25)

initlocaterelatesourcehistorylibraryrefadr

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://mcp.symvanta.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "code-graph": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://mcp.symvanta.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

Symvanta Code Graph MCP Server

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

init

locate

relate

source

history

library

ref

adr

diff_impact

estimate_scope

list_projects

list_repositories

list_file_symbols

map

list_tests_for

quick_lookup

freshness

index_health

find_http_route

find_node

ask_codebase

add_repository

reindex_repository

context

bundle

Symvanta plugin for Claude Code

Commands

Install

Configuration

Updating

What runs on your machine

What the augmenters read, send, and write, exactly

How the Grep/Glob augmenter works

Uninstall

Layout

License

Install

Remote endpoint

Related servers