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

> Learn to use the Resolve MCP tool in Code-Graph-RAG to get fully-qualified names for symbols and file locations directly from the knowledge graph.

- Repository: [Vitali Avagyan/code-graph-rag](https://github.com/vitali87/code-graph-rag)
- Tags: how-to-guide
- Published: 2026-09-05

---

**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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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:

```bash
cgr daemon up

```

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

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

```

The deterministic query logic resides in [`codebase_rag/graph_query.py`](https://github.com/vitali87/code-graph-rag/blob/main/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.

```bash

# 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):**

```json
{
  "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.

```python
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:**

```json
{
  "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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/sdk/__init__.py) provides a high-level wrapper that handles the HTTP communication.

```python
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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_query.py)** – Contains the deterministic Cypher query logic that performs the actual symbol lookup against Memgraph
- **[`codebase_rag/mcp/__init__.py`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/sdk/__init__.py)** – Provides the `CgrClient` class for programmatic access
- **[`docs/guide/mcp-server.md`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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`](https://github.com/vitali87/code-graph-rag/blob/main/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.