# How to Get Definition Details Using the Definition MCP Tool in Code-Graph-RAG

> Learn how to get definition details using the definition MCP tool in Code-Graph-RAG. Retrieve code entity metadata like paths, signatures, and docstrings from the Memgraph knowledge graph.

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

---

**The `definition` MCP tool retrieves comprehensive metadata for code entities by accepting a qualified name and returning file paths, line ranges, signatures, and docstrings from the Memgraph knowledge graph.**

The `definition` tool is a deterministic, read-only query utility exposed by the `vitali87/code-graph-rag` repository. It enables programmatic access to code structure information through the Model Context Protocol (MCP), allowing clients to resolve symbols into their physical locations and documentation.

## Tool Architecture and Registration

The `definition` tool is registered within the `MCPToolsRegistry` class in [`codebase_rag/mcp/tools.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/tools.py) at lines 55-60. The registration maps the tool name (`cs.MCPToolName.DEFINITION`) to the handler method `self.definition`, which processes incoming requests.

When invoked, the handler delegates execution to the graph query layer implemented in [`codebase_rag/graph_query.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_query.py). This module constructs parameterized Cypher queries that execute against the Memgraph database to locate the node matching the provided **qualified name** (QN). The implementation enforces **project scoping** to ensure results are restricted to the specified repository, preventing cross-contamination between different codebases indexed in the same graph instance.

## Request Parameters and Response Schema

The tool requires a specific input structure and returns a standardized metadata payload.

**Input Parameters:**
- `qualified_name` – The fully-qualified identifier (e.g., `my_pkg.utils.calculate`)
- `project` – Optional repository name to scope the search

**Response Fields:**
- `path` – Repository-relative file path containing the definition
- `line` / `line_end` – 1-based start and optional end line numbers
- `qualified_name` – The canonical name of the entity
- `kind` – Node type label (`function`, `class`, `method`, `module`, etc.)
- `docstring` – Extracted documentation string, if available
- `source` – Raw source code snippet for the definition
- `signature` – Function or method signature including parameters and return types

## How to Call the Definition MCP Tool

You can invoke the tool through three primary interfaces: direct HTTP requests, the command-line interface, or the Python SDK.

### Using HTTP POST

Send a JSON payload to the MCP server endpoint (default port 8123):

```python
import requests
import json

MCP_URL = "http://127.0.0.1:8123/mcp"

payload = {
    "tool": "definition",
    "params": {
        "qualified_name": "my_pkg.utils.calculate",
        "project": "my_repo"
    }
}

response = requests.post(MCP_URL, json=payload)
print(json.dumps(response.json(), indent=2))

```

The server returns a JSON object containing the metadata fields described above.

### Using the CLI (cgr)

The `cgr` command-line tool provides a convenient wrapper for MCP calls:

```bash
cgr mcp definition \
    --qualified-name my_pkg.utils.calculate \
    --project my_repo

```

This command serializes the parameters, transmits them to the MCP server, and prints the formatted JSON response to stdout.

### Using the Python SDK

For programmatic integration, use the `MCPClient` wrapper from [`codebase_rag/mcp/client.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/client.py):

```python
from codebase_rag.mcp.client import MCPClient

client = MCPClient(base_url="http://127.0.0.1:8123")
definition = client.call(
    tool="definition",
    qualified_name="my_pkg.utils.calculate",
    project="my_repo"
)

print(definition["path"])        # Output: src/my_pkg/utils.py

print(definition["signature"])   # Output: (a: int, b: int) -> int

```

The SDK handles HTTP transport, JSON encoding, and error checking, returning a native Python dictionary matching the response schema.

## Summary

- The `definition` MCP tool is registered in [`codebase_rag/mcp/tools.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/mcp/tools.py) (lines 55-60) and handled by the `MCPToolsRegistry.definition` method.
- It queries the Memgraph knowledge graph via [`codebase_rag/graph_query.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_query.py) using Cypher to resolve qualified names.
- The tool is **read-only** and supports project scoping to isolate repository-specific results.
- Successful queries return file paths, line numbers, entity types, docstrings, source snippets, and signatures.
- Clients can invoke the tool via HTTP POST, the `cgr` CLI, or the `MCPClient` Python SDK.

## Frequently Asked Questions

### What format should I use for the qualified name parameter?

Provide the fully-qualified Python path using dot notation (e.g., `package.module.ClassName.method_name`). The tool performs exact matching against the `qualified_name` property stored in the graph nodes, so the identifier must match the symbol's canonical name as indexed during repository ingestion.

### Does the definition MCP tool modify the knowledge graph?

No. The tool is strictly **read-only**. It executes Cypher `MATCH` queries to retrieve existing nodes but does not create, update, or delete any graph data. All write operations to the knowledge graph are handled by separate ingestion pipelines, not the MCP query interface.

### Which file contains the Cypher query implementation for the definition tool?

The query logic resides in [`codebase_rag/graph_query.py`](https://github.com/vitali87/code-graph-rag/blob/main/codebase_rag/graph_query.py). This module contains the Cypher templates and parameter binding logic used by the `definition` handler to fetch node properties from Memgraph, including the logic for filtering by project name to ensure repository isolation.

### Can I retrieve definitions for entities that exist in multiple files?

Yes. While the primary resolution returns the canonical definition location, the underlying graph structure may contain multiple nodes if the qualified name appears in different projects. Always specify the `project` parameter to disambiguate results and ensure you receive metadata for the specific repository instance you are targeting.