Overview

Code Pathfinder exposes 6 MCP tools to AI assistants. Each tool provides specific code intelligence capabilities based on the indexed call graph and code structure.

All tools support pagination via limit and cursor parameters where applicable.

Tool 1: get_index_info

Retrieves project statistics and index metadata. Use this at the start of analysis to understand project scope.

Purpose

• Get high-level project overview
• Check if indexing is complete
• Retrieve build performance metrics
• Understand codebase scale

Input Parameters

None required.

Response Schema

{
  "project_path": "/absolute/path/to/project",
  "python_version": "3.11",
  "indexed_at": "2026-01-10T10:30:00Z",
  "build_duration_ms": 1234,
  "stats": {
"total_functions": 456,
"total_call_edges": 1203,
"total_modules": 89,
"total_files": 67,
"taint_summaries": 234
  }
}

Example

User Query:

Get project information and stats

AI Response:

Tool 2: find_symbol

Locates functions, classes, or methods by name with partial matching support.

Purpose

• Find symbols by name (exact or fuzzy)
• Discover functions matching a pattern
• Get symbol metadata (types, decorators, parameters)
• Navigate to symbol definitions

Input Parameters

Response Schema

{
  "symbols": [
{
  "name": "validate_user",
  "fully_qualified_name": "app.auth.validate_user",
  "type": "function",
  "file_path": "/project/app/auth.py",
  "line_number": 45,
  "metadata": {
    "return_type": "bool",
    "parameters": ["username", "password"],
    "decorators": ["@require_auth"],
    "is_async": false
  }
}
  ],
  "next_cursor": "abc123",
  "total_matches": 5
}

Example Queries

Example Response

Tool 3: get_callers

Identifies all functions that invoke a target function (reverse call graph analysis). Answers "Who uses this function?"

Purpose

• Find all callers of a function
• Understand function usage
• Identify impact of changes
• Trace backwards in call graph

Input Parameters

Response Schema

{
  "target_function": "app.auth.validate_user",
  "callers": [
{
  "caller_fqn": "app.api.login_endpoint",
  "caller_file": "/project/app/api.py",
  "caller_line": 78,
  "call_sites": [
    {
      "file": "/project/app/api.py",
      "line": 82,
      "column": 12
    }
  ]
}
  ],
  "next_cursor": "xyz789",
  "total_callers": 12
}

Example Queries

Example Response

Tool 4: get_callees

Lists all functions invoked by a given function (forward call graph). Answers "What does this function depend on?"

Purpose

• Find function dependencies
• Understand what a function calls
• Trace forward in call graph
• Analyze function complexity

Input Parameters

Response Schema

{
  "source_function": "app.api.login_endpoint",
  "callees": [
{
  "callee_fqn": "app.auth.validate_user",
  "callee_file": "/project/app/auth.py",
  "callee_line": 45,
  "resolution_status": "resolved",
  "call_site": {
    "file": "/project/app/api.py",
    "line": 82,
    "column": 12
  },
  "type_inference": {
    "confidence": "high",
    "method": "static_analysis"
  }
}
  ],
  "unresolved_calls": [
{
  "name": "external_api_call",
  "reason": "Dynamic import or external library"
}
  ],
  "next_cursor": "def456",
  "total_callees": 8
}

Example Queries

Example Response

Tool 5: get_call_details

Provides granular information about a specific call between two functions.

Purpose

• Get precise call site locations
• Analyze call arguments
• Understand type resolution
• Debug specific call relationships

Input Parameters

Response Schema

{
  "caller": "app.api.login_endpoint",
  "callee": "app.auth.validate_user",
  "call_details": {
"file": "/project/app/api.py",
"line": 82,
"column": 12,
"arguments": [
  { "name": "username", "value": "request.form['username']" },
  { "name": "password", "value": "request.form['password']" }
],
"resolution": {
  "status": "resolved",
  "confidence": "high",
  "method": "static_type_inference"
},
"context": {
  "in_try_block": true,
  "in_loop": false,
  "is_conditional": false
}
  }
}

Example Queries

Example Response

Tool 6: resolve_import

Maps Python import paths to actual file locations.

Purpose

• Resolve import statements
• Find module file paths
• Handle ambiguous imports
• Navigate import chains

Input Parameters

Response Schema

{
  "import_path": "app.auth",
  "matches": [
{
  "file_path": "/project/app/auth.py",
  "module_fqn": "app.auth",
  "match_type": "exact"
}
  ],
  "match_status": "exact" | "partial" | "ambiguous" | "not_found",
  "suggestions": [
"app.authentication",
"app.auth_utils"
  ]
}

Example Queries

Example Response

Pagination

Most tools support pagination for large result sets:

{
  "limit": 20,
  "cursor": "next_page_token_here"
}

To get the next page, use the next_cursor from the previous response:

Error Handling

All tools return structured errors:

{
  "error": {
"code": "SYMBOL_NOT_FOUND",
"message": "Symbol 'invalid_function' not found in index",
"details": {
  "searched_name": "invalid_function",
  "suggestions": ["validate_function", "valid_function"]
}
  }
}

Common error codes:

• SYMBOL_NOT_FOUND - Symbol doesn't exist
• INVALID_FQN - Malformed fully qualified name
• INDEX_NOT_READY - Project not yet indexed
• PAGINATION_ERROR - Invalid cursor

Best Practices

1. Start with get_index_info to verify the server is ready
2. Use find_symbol for fuzzy matching before get_callers/callees
3. Paginate large results instead of requesting everything at once
4. Cache results when possible to reduce server load
5. Use fully qualified names (FQN) for precise targeting