Overview

Code Pathfinder exposes 12 MCP tools to AI assistants — 8 for code intelligence (Python, Java, Go) and 4 for Docker analysis (Dockerfiles, docker-compose).

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

Quick Reference

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

Tool 7: find_module

Search for Python modules by name. Returns module information including file path and function counts.

Purpose

• Find module file locations
• Understand module structure and size
• Navigate between modules
• Discover modules by partial name

Input Parameters

Example Queries

Example Response

Tool 8: list_modules

List all modules in the indexed project with their file paths and function counts.

Purpose

• Get a complete overview of project modules
• Understand project structure
• Find the largest/most complex modules

Input Parameters

None required.

Example Queries

Tool 9: find_dockerfile_instructions

Search Dockerfile instructions with semantic filtering. Supports instruction-specific filters for FROM, RUN, USER, EXPOSE, COPY, ADD, and more.

Purpose

• Find unpinned base images (has_digest: false)
• Locate specific instruction types
• Audit exposed ports
• Check USER directives for non-root enforcement

Input Parameters

Example Queries

Example Response

Tool 10: find_compose_services

Search docker-compose services with configuration filters. Find services by name, privileged mode, volumes, or exposed ports.

Purpose

• Find privileged containers (security risk)
• Locate services exposing specific ports
• Find services mounting sensitive volumes (e.g., Docker socket)
• Audit service configurations

Input Parameters

Example Queries

Example Response

Tool 11: get_dockerfile_details

Get a complete breakdown of a single Dockerfile with all instructions and multi-stage build analysis.

Purpose

• Understand full Dockerfile structure
• Analyze multi-stage build dependencies
• Check for security best practices (USER, HEALTHCHECK)
• Identify unpinned images

Input Parameters

Example Queries

Example Response

Tool 12: get_docker_dependencies

Retrieve dependency information for Docker entities — compose services (depends_on) or Dockerfile stages (COPY --from). Traverses upstream and downstream dependency chains.

Purpose

• Map service dependencies in docker-compose
• Analyze multi-stage Dockerfile build order
• Understand deployment topology
• Trace dependency chains

Input Parameters

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