How to Use the Resolve MCP Tool in Code-Graph-RAG

The Resolve MCP tool performs deterministic symbol lookups against the Code-Graph-RAG knowledge graph to return fully-qualified names for bare identifiers, qualified symbols, or specific file locations.

The resolve tool is a core component of the vitali87/code-graph-rag Model Context Protocol (MCP) server, providing fast, deterministic resolution of code symbols without LLM inference. By querying the indexed Memgraph database directly, it maps any target—whether a bare name, fully-qualified path, or specific line location—to its canonical definitions in the knowledge graph.

What Is the Resolve MCP Tool?

The Resolve MCP tool is a deterministic query engine that runs a fixed Cypher query against the Memgraph database backing Code-Graph-RAG. Unlike tools that leverage LLM inference, resolve executes directly on the indexed graph, ensuring that identical inputs always produce identical JSON outputs with minimal latency.

According to the source code in codebase_rag/tools/tool_descriptions.py (lines 187-193), the tool is registered as MCP_RESOLVE and is designed to bridge user queries—such as ambiguous variable names or file positions—with precise, fully-qualified symbols required for downstream analysis.

Target Syntax and Input Formats

The resolve tool accepts a single target parameter that can take three distinct forms, as documented in the MCP server guide at docs/guide/mcp-server.md (lines 66-68):

• qualified.name – A full dotted path (e.g., myproj.utils.helpers)
• bareName – A simple identifier (e.g., helper) that matches any symbol with that name
• path:line – A repository-relative file path with a 1-based line number (e.g., src/main.py:42)

This versatility allows developers to resolve symbols starting from incomplete information or exact cursor positions in their editor.

Prerequisites for Running Resolve

Before invoking the tool, the Code-Graph-RAG daemon must be running and your repository must be indexed.

1. Start the Memgraph daemon to enable graph queries:

cgr daemon up

2. Index the repository to populate the knowledge graph with definitions, imports, and call relationships:

cgr start --repo-path ./my-project --update-graph

The deterministic query logic resides in codebase_rag/graph_query.py, which builds and executes the Cypher query against the indexed nodes only after the graph is populated.

How to Call the Resolve Tool

Command-Line Interface

The most direct way to invoke resolve is through the cgr CLI. The tool returns a JSON object containing an array of matches ordered by relevance: exact matches first, then dotted-suffix matches, then same-name matches.

# Resolve a bare name

cgr mcp resolve --target helper

# Resolve a fully-qualified name

cgr mcp resolve --target myproj.services.UserService

# Resolve a specific file location

cgr mcp resolve --target src/app.py:27

Typical CLI output (pretty-printed):

{
  "target": "helper",
  "matches": [
    {"qualified_name": "myproj.utils.helper", "source": "src/utils/helper.py"},
    {"qualified_name": "myproj.services.helper", "source": "src/services/helper.py"}
  ]
}

HTTP / JSON-RPC API

The MCP server exposes an HTTP endpoint at http://localhost:8000/mcp that accepts POST requests. This is useful for integrating the tool into editors, CI pipelines, or custom scripts.

import requests, json

payload = {
    "tool": "resolve",
    "params": {"target": "Store.get"}
}
resp = requests.post("http://localhost:8000/mcp", json=payload)
print(json.dumps(resp.json(), indent=2))

Typical HTTP response:

{
  "result": [
    {"qualified_name": "myproj.store.Store.get", "source": "src/store.py"},
    {"qualified_name": "myproj.store.Store.get", "source": "src/store/__init__.py"}
  ],
  "metadata": {
    "deterministic": true,
    "query_time_ms": 4
  }
}

Python SDK

For Python applications, the CgrClient class in codebase_rag/sdk/__init__.py provides a high-level wrapper that handles the HTTP communication.

from codebase_rag.sdk import CgrClient

cgr = CgrClient()  # Assumes daemon is running on localhost

result = cgr.mcp_resolve(target="path/to/file.py:10")
print(result.matches)  # List of qualified name strings

Under the hood, the SDK forwards the same JSON payload as the raw HTTP example, as implemented in the client library.

Understanding the Response Structure

Regardless of the invocation method, the resolve tool returns matches in a specific order of relevance:

1. Exact matches – The target string matches a qualified name exactly
2. Dotted-suffix matches – The target matches the end of a longer qualified name (e.g., helpers matching myproj.utils.helpers)
3. Same-name matches – The bare name appears in multiple namespaces

Each match object contains the qualified_name and the source file path. Because the query is deterministic—implemented as a static Cypher query in codebase_rag/graph_query.py—you can safely cache these results for repeated use in code navigation or RAG grounding tasks.

Source Code Architecture

The implementation of the resolve tool spans several key modules in the repository:

• codebase_rag/tools/tool_descriptions.py (lines 187-193) – Stores the MCP_RESOLVE definition and textual description used by the server to register the tool
• codebase_rag/graph_query.py – Contains the deterministic Cypher query logic that performs the actual symbol lookup against Memgraph
• codebase_rag/mcp/__init__.py – Registers the tool functions with the MCP server and dispatches incoming resolve requests to the graph query layer
• codebase_rag/sdk/__init__.py – Provides the CgrClient class for programmatic access
• docs/guide/mcp-server.md (lines 66-68) – Public documentation describing the tool's interface

Summary

• The Resolve MCP tool provides deterministic, LLM-free symbol resolution by querying the Code-Graph-RAG knowledge graph directly
• It accepts three target formats: qualified.name, bareName, and path:line (e.g., src/main.py:42)
• Prerequisites require running cgr daemon up and indexing the repo with cgr start --update-graph
• Invocation methods include the cgr mcp resolve CLI, HTTP POST to localhost:8000/mcp, and the CgrClient Python SDK
• Results are ordered by relevance (exact, suffix, same-name) and sourced from codebase_rag/graph_query.py Cypher queries

Frequently Asked Questions

What makes the resolve tool deterministic?

The tool executes a fixed Cypher query against the Memgraph database without involving machine learning models or probabilistic reasoning. As implemented in codebase_rag/graph_query.py, the query logic is static, meaning identical inputs always yield identical JSON outputs with consistent performance characteristics.

Can I use resolve without indexing my repository first?

No. The resolve tool queries the knowledge graph populated by the indexing process. You must run cgr start --repo-path <path> --update-graph to create the nodes and edges that the deterministic query in codebase_rag/graph_query.py traverses when resolving symbols.

How does resolve handle ambiguous bare names?

When provided with a bare identifier like helper, the tool returns all qualified names containing that identifier, ordered by relevance: exact matches first, then dotted-suffix matches, then other same-name matches. This allows you to disambiguate symbols after receiving the full list of candidates from the graph.

What is the difference between resolve and other MCP tools like definition or callers?

While definition or callers might retrieve code snippets or relationship graphs, resolve specifically maps a target string to its canonical qualified names. It serves as a grounding step that converts user input—whether ambiguous or location-based—into precise identifiers required by other deterministic tools in the codebase_rag/mcp/ registry.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}