Path resolution and MCP checks in pathfinder

Tool and measured results

I built pathfinder in Rust to find real paths after local LLM tool_call errors. Models of 32B or fewer repeatedly produced typos, wrong extensions and skipped directory levels.

The MCP server filters candidates and reranks them with ColBERT (Late Interaction). INT8 uses 16MB, CPU-only inference and under 10ms latency, with no GPU VRAM.

On a ~4,000-file monorepo, accuracy was close to filesystem MCP while context use was about 10,000 tokens lower. Candidate filtering reduced the O(n) output from list_directory ancestor checks.

The Rust ModernBERT implementation also supports a CLI for searching multiple projects, alongside development-assistance LLM integration.

Local model path failures

In these tasks, 7B–32B local models had more path errors than Claude / GPT-4-class models.

Common failure patterns:

Errors and retries increase context. Tool-side resolution aims to reduce those retries and inputs.

Exact-path prompt instructions did not resolve the failures, so I added tool-side recovery. The tests did not isolate parameter count as the sole cause.

Architecture

pathfinder is a Rust MCP server communicating via stdin/stdout JSON-RPC 2.0 with LLM clients (Claude Code, Zed Editor, etc.).

Three-Phase Path Resolution

When the LLM generates an inaccurate path, pathfinder resolves it through three phases:

1. Lexical scoring — Internal implementation is undisclosed; under 1ms.
2. History correlation — A ring buffer prioritizes candidates related to recent resolutions.
3. ColBERT reranking — Top candidates are ranked by MaxSim, taking about 5–8ms.

When lexical scoring produces a high-confidence match, neural re-ranking is skipped entirely. Most queries resolve in under 1ms.

ColBERT Model

Semantic re-ranking uses a ColBERT (Late Interaction) architecture model.

Inference runs through ONNX Runtime with HuggingFace Tokenizers for text encoding. No Python dependencies.

MCP Tools

Primary tools exposed by pathfinder:

• path_resolve — Takes a failed path and returns the most likely real path. Accepts intent_text (a short purpose description like “Go config loader”) to improve accuracy
• tool_retry_with_resolve — Resolves the path and automatically retries the original operation (read_file, list_dir, etc.) in a single tool call
• candidate_list — Returns top candidates as a ranked list for ambiguous cases
• roots_list / reindex_paths / server_version — Administrative tools

After read_file returns ENOENT, tool_retry_with_resolve resolves and retries the operation in one tool_call.

Path Resolution Example

When the LLM typos a directory name:

  path_resolve:
  check_path: "content/ja/docs/tech/infrastrcture/podman-quadlet-systemd-ubuntu.md"
                                      ^^^^^^^^^^^ typo
  →  resolved: "content/ja/docs/tech/infrastructure/podman-quadlet-systemd-ubuntu.md"
  

  $ pathfinder --help
pathfinder — semantic path finder & MCP resolution server

USAGE
    pathfinder [OPTIONS]          Interactive semantic directory finder (default).
    pathfinder --mcp [OPTIONS]    Start as an MCP server.

FINDER OPTIONS
    --include-builds    Include build/artifact dirs (target, dist, …).

MCP OPTIONS
    --root <PATH>       Add a project root directory to watch and index.
                        May be specified multiple times.  Defaults to $PWD.

GENERAL OPTIONS
    -h, --help          Print this help message and exit.
    -V, --version       Print version, model, and PCA config to stderr and exit.

MCP TOOLS
  1. path_resolve            Resolve a failed file path to the best match.
  2. tool_retry_with_resolve Resolve + retry the operation in one call.
  3. roots_list              Return configured root directories.
  4. reindex_paths           Force a full index rebuild.

ENVIRONMENT VARIABLES
    PF_MCP_INFERENCE    Inference mode: "general" (default) or "code".
    Models (both INT8 quantized):
      general → mxbai-edge-colbert (17M, 48-dim)
      code    → lateon-code-edge (17M, 48-dim)
  

Searching projects in the CLI

Alongside the MCP server, I built an interactive CLI using the same ColBERT inference engine. It is designed for browsing code across multiple projects — domain, infrastructure, and presentation layers — from a single terminal.

Controls

Launch pf (code-aware) or pfg (general) from the shell to open a semantic search interface.

• Vim keybindings for navigating the candidate list
• Drill down through directory hierarchy to the deepest nesting level, where file listings appear
• Right arrow (→) opens the selected file in less
• Selecting a result cds to its directory

  pf          # Code-aware mode (lateon-code-edge)
pfg         # General mode (mxbai-edge-colbert)
  

The Rust ModernBERT implementation returned results nearly immediately in subjective use.

Benchmarks: Comparison with filesystem MCP

Benchmarked on a monorepo application sample with approximately 4,000 files.

Path Resolution Accuracy

pathfinder standalone accuracy test (70 test cases, 12 categories):

Context Token Consumption

Accuracy was comparable to the filesystem MCP server, but there was a ~10,000 token difference in context consumption.

filesystem MCP ancestor checks return more list_directory output as file count grows. Scale beyond this 4,000-file sample remains untested.

pathfinder returns filtered candidates to reduce unnecessary context in 8K–32K windows.

Resource Footprint

No GPU use means no additional VRAM is required alongside vLLM or llama.cpp. CPU resources are still used.

Caveats

• Lexical scoring is undisclosed and used with ctree in the in-house OSS LLM pipeline.
• Of 70 cases, two cross-language intent_text queries remain unresolved.
• Tens of thousands of files have not been tested.
• PF_MCP_INFERENCE selects code-aware or general models.
• MCP protocol 2024-11-05 supports Claude Code, Zed Editor and other clients.