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

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 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. 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):

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:

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:

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 (lines 55-60) and handled by the MCPToolsRegistry.definition method.
• It queries the Memgraph knowledge graph via 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. 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.

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