Graphtia documentation · reference
MCP operations and evidence
Understand the structural operations, compact catalog, result bounds and optional local recovery in Explorer.
The same operations in two tool catalogs
The canonical catalog exposes 26 individually named read-only operations. A compatible client can explicitly negotiate COMPACT_V2 to group those operations into six tools with a required action. Catalog grouping is separate from the format of each response; it does not add write authority or change project permission.
The compact groups are graphtia_project, graphtia_symbol, graphtia_relations, graphtia_analysis, graphtia_documents and graphtia_contracts. For example, get_symbol becomes graphtia_symbol with action: inspect. Use the catalog actually exposed by your connected client.
Workspace
get_project_summary, get_architecture_projection
Symbols and source
search_symbol, resolve_symbol, get_symbol, get_source_evidence, get_local_context
Relationships
get_callers, get_callees, get_dependencies, get_dependents, get_references, find_path, get_neighborhood
Analysis
get_blast_radius, get_related_tests, get_findings, audit_structure
Documents
get_document_catalog, search_documents, get_document
API and database declarations
get_api_catalog, get_contract_catalog, get_openapi_contract, get_db_schema, get_db_code_links
Choose how your agent receives evidence
Choose structured JSON for direct machine use, DIGEST for a shorter text view, or RECORDS/JSONL when you need to preserve a bounded result across export pages. These choices change representation; they do not expand permission or turn static evidence into execution.
A permitted, focused read returns bounded structural evidence. JSON is the default; DIGEST changes its text presentation. RECORDS and JSONL export the requested result in bounded pages.
JSON and DIGEST
DIGEST highlights the tool, project, revision, currentness and result limits. The structured result remains available for exact fields and evidence. If your client only exposes text, JSON is the safer default.
These selected request fields illustrate two presentations of an ordinary JSON result. Use the project, revision and symbol identities returned by the connected server for a real query.
{
"output_format": "JSON",
"presentation": "JSON"
}content contains JSON text. structuredContent retains the machine-readable result.
{
"output_format": "JSON",
"presentation": "DIGEST"
}content contains a concise text view. structuredContent retains the returned result.
Illustrative request options, not a measured query response. DIGEST can shorten the text; read structuredContent for the exact returned fields, coverage and continuation. For RECORDS and JSONL, omit presentation or set it to JSON; DIGEST is invalid.
What the output looks like
Illustrative output excerpt — not a captured execution. Metadata is omitted; ILLUSTRATIVE IDs cannot be reused.
JSON — selected structuredContent fields. The ordinary text response contains the same result in JSON form.
{
"project_id": "ILLUSTRATIVE_PROJECT_ID",
"revision": "ILLUSTRATIVE_PUBLISHED_REVISION",
"currentness": "UNKNOWN",
"complete": true,
"truncated": false,
"continuation_token": null,
"data": {
"id": "ILLUSTRATIVE_SYMBOL_ID",
"name": "calculateTotal",
"kind": "FUNCTION",
"source_uri": "workspace://src/totals.ts"
}
}DIGEST — illustrative opening text. The structured fields remain available independently of this shorter text.
get_symbol
Project: "ILLUSTRATIVE_PROJECT_ID"
Revision: "ILLUSTRATIVE_PUBLISHED_REVISION"
Currentness: "UNKNOWN" · complete: true · truncated: false
Static indexed evidence; no runtime or database execution verified. Full data and coverage are in structuredContent.
The request uses output_format and presentation. tool_output is a generic host-interface label, not a Graphtia request parameter. DIGEST changes the text view of an ordinary JSON result; it is not another analyzer or permission tier.
RECORDS and JSONL
Set output_format to RECORDS for reconstruction records in JSON, or JSONL for one JSON object per line inside the normal MCP text block. For either export format, omit presentation or set it to JSON; combining RECORDS or JSONL with DIGEST is invalid. JSONL is a representation of a bounded response, not an unbounded event stream.
{
"output_format": "RECORDS",
"presentation": "JSON",
"export_limit": 20
}Illustrative output options only. Supply the exact tool arguments and returned project, revision and target identity for the real query. JSONL uses the same record export, with an EXPORT_PAGE envelope line followed by reconstruction-record lines. Errors or non-export responses use a RESPONSE wrapper line.
Record and JSONL output excerpts
Illustrative output excerpt — not a captured execution. Metadata is omitted; ILLUSTRATIVE IDs cannot be reused.
RECORDS — one VALUE record at the empty pointer represents the root envelope. This excerpt omits export hashes, counts and other metadata; it is not a complete export page.
{
"output_format": "RECORDS",
"data": {
"format": "TOOL_RESULT_RECORDS_V1",
"records": [
{
"record_kind": "VALUE",
"record_index": 0,
"pointer": "",
"value": {
"project_id": "ILLUSTRATIVE_PROJECT_ID",
"revision": "ILLUSTRATIVE_PUBLISHED_REVISION",
"currentness": "UNKNOWN",
"complete": true,
"truncated": false,
"continuation_token": null,
"data": {
"id": "ILLUSTRATIVE_SYMBOL_ID",
"name": "calculateTotal",
"kind": "FUNCTION",
"source_uri": "workspace://src/totals.ts"
}
}
}
]
}
}JSONL — an EXPORT_PAGE envelope line followed by a VALUE record line. This is not a complete reconstruction input. Read each physical line as JSON, even when it wraps visually on screen.
{"record_kind":"EXPORT_PAGE","envelope":{"output_format":"JSONL","data":{"format":"TOOL_RESULT_RECORDS_V1","records":[]}}}
{"record_kind":"VALUE","record_index":0,"pointer":"","value":{"project_id":"ILLUSTRATIVE_PROJECT_ID","revision":"ILLUSTRATIVE_PUBLISHED_REVISION","currentness":"UNKNOWN","complete":true,"truncated":false,"continuation_token":null,"data":{"id":"ILLUSTRATIVE_SYMBOL_ID","name":"calculateTotal","kind":"FUNCTION","source_uri":"workspace://src/totals.ts"}}}
Reconstruct one source page at a time
Record exports can split large values and paginate one source response. Finish those export pages first, then use the next source-query token if one is returned. A complete export can still contain a partial analysis.
Keep one source_sha256 and snapshot_sha256 together. Reconstruct values at their JSON pointers; concatenate UTF-8 fragments in part and byte-offset order, verify their value_sha256, then parse. Preserve unknown fields and the numeric representation required by the advertised encoding. Verify the reconstructed source envelope before using it.
Finish export_continuation_token first. Only then may continuation_token advance the underlying source query. Export keeps the requested semantic page before ordinary output compaction; it cannot recover unsupported analysis, missing history or facts outside the requested budget.
DIGEST is a readable summary. SHA-256 values in an export check reconstruction integrity. Neither is an approval, a signature proving runtime correctness or a substitute for the source revision.
FULL and GROUPED relationships
For callers, callees, dependencies, dependents, references, neighborhoods and local context, relation_view defaults to FULL. GROUPED can compact eligible CALLS and REFERENCES with matching endpoints, complete evidence and truth when doing so makes the response smaller. It does not merge canonical identities or remove semantic relationships.
Consumers of GROUPED output must retain edge_presentation, original indices and the set/remove deltas needed to recover the original edge objects. Grouping is optional and does not guarantee a smaller response for every query.
Use returned identities and the indexed revision
Select the authorized workspace and reuse the IDs returned by the relevant query. A symbol ID, document ID, contract source and SQL table ID are different identities. Do not substitute a guessed filename for a symbol ID. Preserve the indexed revision when following relationships.
Read what a result actually establishes
Code queries inspect source and its supported static relationships. API declarations are not deployed endpoints; SQL declarations are not live database state; related tests are not execution results. Coverage, truncation, unresolved targets and currentness remain part of the answer. audit_structure is a structural query, separate from the disabled Argus/Audit workflow.
A formatted response can still be incomplete. Keep project_id and revision, currentness, complete, truncated, truncation_reason, coverage and limitations with the evidence. result_summary may describe omitted output or an invalidated continuation. An error is not an empty successful result.
How to read result limits · Understand index revisions
Continue only when a continuation is returned
Not every operation supports paging. For ordinary cursors, keep workspace, revision, filters and query settings; change a page size only when that operation permits it. Cursors last at most four hours in the current process and may expire earlier through eviction or restart. Export fragments and source-query pages are different continuations; collecting all fragments does not fill gaps in the underlying analysis.
Keep the next step tied to the same evidence
Continue a returned page when it is available, and recheck the project context when it is not.
Start with a focused question. Use the intended project and keep the returned source identities, revision and result limits.
Continue within that scope. When the operation returns a continuation, request the needed next page while preserving its context. Some operations require a narrower query instead.
Recheck before resuming. If the continuation or revision is no longer available, refresh the project context and ask again. Optional saved notes remain client-supplied context and do not replace source evidence or permission.
A connected agent asks a focused question within an approved project. Results retain the indexed revision and their limits. Continue only when the response supplies a continuation; otherwise narrow or refresh the query.
Optional recovery is experimental, requires explicit opt-in and uses an unencrypted local cache. It does not restore expired or revoked access.
Compare retained graph revisions
Revision comparison uses two retained graph versions. It is not a Git diff or a working-tree diff. If history is unavailable or pruned, the result must not be interpreted as an empty set of changes.
Optional local recovery
An experimental opt-in cache can retain client-supplied context and query recovery state. It is local and unencrypted; it is not authenticated chat history or verified code evidence. It can be cleared independently of your workspace files. Do not store secrets in it. Recovering cache state does not grant workspace access or extend an expired account session.