Power your agent
Cài đặt từ nhà phát hành. Không phải endpoint của PlugMCP.
Host a copy with our keys and logs.
Chưa có bản phát hành đóng gói nào trong registry. Làm theo README của kho mã.
URL từ xa hay một lệnh trên máy của bạn? Hai cách cài đặt khác nhau thế nào
Chạy trên PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
MởPathfinder is an MCP (Model Context Protocol) server written in Rust that gives AI coding agents the same code intelligence a human developer gets from an IDE — but without a GUI.
Instead of treating source code as flat text, Pathfinder understands your code structurally through Tree-sitter AST parsing and semantically through Language Server Protocol (LSP) integration. This means AI agents can navigate, search, and explore code at the symbol level — functions, classes, methods — rather than fragile line-by-line string matching.
Traditional AI coding workflows suffer from:
Pathfinder solves these problems by providing:
src/auth.ts::AuthService.login).ripgrep_ms, tree_sitter_parse_ms, lsp_ms) and optional --lsp-trace for raw JSON-RPC debugging.locate, trace, inspect).Language maturity is verified by the automated conformance suite (WS-9, 16 assertions C-1 through C-16):
gopls for Go, typescript-language-server for TS/JS, rust-analyzer for Rust, pyright for Python).Choose one of the following methods:
Homebrew (macOS & Linux):
brew tap irahardianto/pathfinder-mcp
brew install pathfinder-mcp
cargo install from crates.io:
cargo install pathfinder-mcp
Build from source:
git clone https://github.com/irahardianto/pathfinder.git
cd pathfinder
cargo build --release
# The binary will be at target/release/pathfinder-mcp
Verify the installation:
pathfinder-mcp --help
Contributing from source? Enable the git hooks (one-time):
git config core.hooksPath .githooks
This activates pre-commit (fmt/clippy/build/doc/test/security gates), commit-msg
(Conventional Commits validation), and pre-push (integration test suite). See
Contributing for details and environment variable overrides.
Add Pathfinder to your MCP client's server configuration. The exact format depends on your client.
Example (JSON config for most MCP clients):
{
"mcpServers": {
"pathfinder": {
"command": "pathfinder-mcp",
"args": ["/path/to/your/workspace"]
}
}
}
With LSP trace enabled (for debugging):
{
"mcpServers": {
"pathfinder": {
"command": "pathfinder-mcp",
"args": ["--lsp-trace", "/path/to/your/workspace"]
}
}
}
pathfinder-mcp [OPTIONS] <WORKSPACE_PATH>
Arguments:
<WORKSPACE_PATH> Path to the workspace root directory
Options:
--lsp-trace Enable raw LSP JSON-RPC tracing to stderr (DEBUG level)
-h, --help Print help
-V, --version Print version
Pathfinder communicates over stdio using the MCP protocol. Logs are emitted as structured JSON to stderr (since stdout is reserved for MCP transport).
Pathfinder ships with a set of agent directives — pre-written rules and skills that teach your AI agent how to use Pathfinder tools correctly, reliably, and efficiently. Without these, the agent falls back to generic file-reading behaviour and misses most of Pathfinder's value.
Why this matters: An AI agent that doesn't know about semantic paths or which of
locate/trace/inspectto reach for will make avoidable mistakes — calling a tool that no longer exists, constructing malformed semantic paths, or misreading anullevidence field as a confirmed zero. The directives encode all of this knowledge directly into the agent's system context.
The directives live in docs/agent_directives/ and mirror the rules and skills used during Pathfinder's own development:
docs/agent_directives/
├── AGENTS.md # Always-on routing rule: which Pathfinder tool to use for each action
├── instructions.md # MCP server instructions: semantic path format, tool selection guide
└── skills/
└── pathfinder/
└── SKILL.md # On-demand skill: concrete navigation workflows and error recovery
AGENTS.md — an always-on rule injected into every agent turn. It tells the agent:
src/auth.ts::AuthService.login)skills/pathfinder/SKILL.md — a detailed on-demand skill the agent activates when it needs deeper guidance. It covers:
locate, trace, inspect) and each tool's key parametersToolStatus/Confidence/Evidence tri-state contract (null = unknown, [] = confirmed zero)max_depth, max_references, max_dependencies) and the graceful fallback to host toolsCopy the directives into your project's .agents/ directory. Antigravity auto-discovers all rules and skills placed there:
# From your project root (not the Pathfinder repo)
mkdir -p .agents/skills
cp /path/to/pathfinder/docs/agent_directives/AGENTS.md .agents/
cp -r /path/to/pathfinder/docs/agent_directives/skills/* .agents/skills/
Optionally, copy the MCP server instructions for lightweight tool context on every session:
cp /path/to/pathfinder/docs/agent_directives/instructions.md ~/.gemini/antigravity/mcp/pathfinder/instructions.md
The routing rule runs on every agent turn automatically (trigger: always_on). The workflow skill is activated on demand when the agent needs detailed guidance. The instructions.md is loaded by Antigravity alongside the tool schemas for lightweight per-session context.
For clients that support system prompt injection or custom instructions, paste the content of AGENTS.md into your system prompt or custom instructions field. Then reference skills/pathfinder/SKILL.md as additional context or attach it as a project document.
For clients that support agent rule files (e.g., .cursorrules, .clinerules), you can drop the AGENTS.md content directly into those files.
For any MCP-compatible client, the minimum effective setup is to inject the AGENTS.md routing rule into the agent's persistent context. This single file prevents the most common mistakes. The workflow skill is optional but significantly improves the quality of complex multi-step tasks.
Pathfinder exposes exactly 3 high-precision MCP tools. Every tool operates within the workspace sandbox and returns structured JSON responses with dual-channel human-readable text.
Pathfinder is structured as a Rust workspace with 5 crates, each with a clear responsibility:
pathfinder/
├── crates/
│ ├── pathfinder/ # MCP server, CLI, tool routing
│ │ └── src/
│ │ ├── main.rs # CLI entry point (clap)
│ │ ├── server.rs # MCP tool router (3 consolidated tools)
│ │ └── server/
│ │ ├── types.rs # Parameter & response types (contracts 1-5)
│ │ ├── helpers.rs # Dual-channel formatting & validation
│ │ └── tools/ # Core tool handlers
│ │ ├── inspect.rs # inspect tool handler (single & batch)
│ │ ├── semantic_path.rs # locate(file+line) handler
│ │ └── navigation/ # LSP-backed navigation
│ │ ├── definition.rs # locate tool handler
│ │ ├── impact.rs # trace(scope=callers) handler
│ │ ├── references.rs # trace(scope=references) handler
│ │ ├── overview.rs # trace(scope=overview) handler
│ │ ├── deep_context.rs # inspect(include_dependencies) handler
│ │ └── grep_support.rs # Navigation fallback search
│ │
│ ├── pathfinder-common/ # Shared types, ToolStatus, Evidence<T>, config, sandbox
│ ├── pathfinder-treesitter/ # The Surgeon — AST parsing, symbol extraction, containment
│ ├── pathfinder-search/ # The Scout — internal ripgrep search engine & matchers
│ └── pathfinder-lsp/ # The Lawyer — LSP client, probe-gated readiness, process supervisor
│ ├── docs/ │ ├── agent_directives/ # AI agent rules and skills │ ├── requirements/ # PRD and specifications │ ├── research_logs/ # Design decisions and research │ └── audits/ # Code audit findings │ ├── Cargo.toml # Workspace manifest ├── LICENSE # MIT License └── README.md
### The Three Engines
Pathfinder internally delegates work to three specialized engines, each abstracted behind a trait for testability:
| Engine | Crate | Trait | Responsibility |
|---|---|---|---|
| **The Surgeon** | `pathfinder-treesitter` | `Surgeon` | AST parsing, symbol extraction, semantic path resolution, repo map generation |
| **The Scout** | `pathfinder-search` | `Scout` | Ripgrep-powered full-text search with Tree-sitter enrichment for AST-aware filtering |
| **The Lawyer** | `pathfinder-lsp` | `Lawyer` | LSP process lifecycle, go-to-definition, call hierarchy, references, and go-to-implementation navigation |
Each engine can be mocked independently for unit testing, and the server gracefully degrades when an engine is unavailable (e.g., falls back to Tree-sitter heuristics when no LSP is running).
### Core Concepts
#### Semantic Paths
Pathfinder identifies code symbols using semantic paths — a human-readable notation that mirrors how developers think about code structure:
src/auth.ts::AuthService.login # Method src/utils/math.go::CalculateDiscount # Function lib/models.py::User # Class
Format: `<relative_file_path>::<Symbol>[.<Method>]`
#### Version Hashes
Every file read returns a `version_hash` (SHA-256 digest of the file content). This is a content fingerprint that agents can use to detect when a file has changed between reads — useful for coordinating multi-step workflows and detecting concurrent modifications.
### Supported Languages
#### Tree-sitter Support (Built-in, Zero Configuration)
Tree-sitter grammars are compiled directly into the Pathfinder binary — no external tools needed. All symbol extraction, semantic path resolution, and AST-aware filtering work out of the box.
| Language | Extension(s) | Notes |
|---|---|---|
| Go | `.go` | Function, interface, struct, and type alias extraction |
| Java | `.java` | Class, interface, enum, record, and method extraction with inner class hierarchy |
| TypeScript | `.ts` | Class, function, arrow function, interface, and type extraction (also handles `.mts`) |
| TSX | `.tsx` | All TypeScript symbols **plus** JSX element extraction as child symbols |
| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | Functions, classes, JSX elements in `.jsx` files, and ES/CommonJS modules (`.mjs`, `.cjs`) |
| Python | `.py` | Function, class, and method extraction |
| Rust | `.rs` | Functions, structs, enums, traits; `impl` block methods merged under their parent type |
| Vue SFC | `.vue` | **Multi-zone**: `<script>` parsed as TypeScript (AST-aware), `<template>` and `<style>` accessible for text search |
#### LSP Support (Optional, Auto-detected)
Pathfinder automatically detects which language servers are available in your workspace by scanning for marker files (`Cargo.toml`, `go.mod`, `tsconfig.json`, etc.). LSP processes start eagerly in the background (warm start) and are shut down after an idle timeout.
To maximise navigation coverage, install the language server(s) for your project:
| Language | LSP Server | Install Command | Auto-detect Marker |
|---|---|---|---|
| **Rust** | `rust-analyzer` | `rustup component add rust-analyzer` | `Cargo.toml` at workspace root |
| **Go** | `gopls` | `go install golang.org/x/tools/gopls@latest` | `go.mod` (scans up to depth 2) |
| **TypeScript / JavaScript / Vue** (including `.mjs`, `.cjs`, `.mts`, `.cts`) | `typescript-language-server` | `npm install -g typescript-language-server typescript` | `tsconfig.json` or `package.json` (depth 2) |
| **Python** | `pyright` | `npm install -g pyright` | `pyproject.toml`, `setup.py`, or `requirements.txt` (depth 2) |
| **Java** | `jdtls` | [Eclipse JDT Language Server](https://github.com/eclipse-jdtls/eclipse.jdt.ls) | `pom.xml`, `build.gradle`, `build.gradle.kts`, `settings.gradle`, or `settings.gradle.kts` (depth 2) |
> **Vue note:** Pathfinder handles Vue SFC parsing internally with Tree-sitter. The `typescript-language-server` validates the `<script>` block — no separate `volar` or `vue-language-server` installation is required.
> **Concurrent LSP handling:** When Pathfinder detects a concurrent LSP instance (e.g., your IDE is already running `gopls`), it automatically isolates build caches to avoid lock contention. Isolated caches are stored under `.pathfinder/` in your project root, which is automatically added to `.gitignore`. Navigation tools automatically probe readiness and report `ToolStatus::NotReady` or `ToolStatus::Degraded` with actionable recovery guidance.
## Observability
Pathfinder emits structured JSON logs to stderr with per-engine timing breakdowns:
```json
{
"timestamp": "2026-03-31T05:30:00Z",
"level": "INFO",
"message": "search completed",
"ripgrep_ms": 12,
"tree_sitter_parse_ms": 45,
"total_matches": 23,
"duration_ms": 62
}
Enable --lsp-trace for full JSON-RPC request/response logging at DEBUG level — useful for diagnosing LSP communication issues.
Pathfinder implements a 3-tier sandbox model:
../../etc/passwd) are rejected at Tier 1.WorkspaceRoot type enforces that only valid, existing directories are accepted as workspace roots.SandboxConfig.allow_override; additional deny patterns can be added via SandboxConfig.additional_deny.<script>, <template>, <style>)code_only, comments_only, all)known_files, group_by_file, exclude_glob (E4)explore (capabilities.lsp.per_language)explore temporal filtering (changed_since) and extension filters (E6)read with source_only/compact/symbols/full detail modes and line range filtering (E2)trace(scope="references") — LSP textDocument/referencestrace(scope="callers") — call hierarchy (renamed from analyze_impact)search(mode="symbol") — resolve bare symbol names to semantic pathsread(paths=[...]) — batch multi-file reading with per-file error resiliencetrace(scope="overview") — composite source + callers + callees + referenceslocate(file, line) — convert file:line locations to semantic pathslocate, trace, inspect) with a dual-channel ToolStatus/Confidence/Evidence response contractContributions are welcome! Pathfinder follows strict engineering practices:
git checkout -b feature/amazing-feature)git commit -m 'feat: add amazing feature')git push origin feature/amazing-feature)# Run tests
cargo test --workspace
# Run with clippy (pedantic + all-features, matches the pre-commit gate)
cargo clippy --workspace --all-targets --all-features
# Format
cargo fmt --all --check
# Dependency audit
cargo deny check
The workspace enforces
clippy::pedantic,warn(unwrap_used),warn(expect_used),warn(missing_docs), anddeny(unsafe_code). Six structural lints —too_many_lines,cognitive_complexity,too_many_arguments,type_complexity,struct_excessive_bools,large_enum_variant— aredenyd atpriority = 1: a new, unattributed violation fails the build on its own.deny(notforbid) is deliberate —forbidconflicts with proc-macros (clap::Parser,async_trait) that emit group-level#[allow(clippy::pedantic)]/#[allow(clippy::complexity)]in their macro expansions, which would otherwise hard-error withE0453workspace-wide. This is defense-in-depth alongside the pre-commit hook's structural-suppress gate (see below) and the no---no-verifypolicy in git-workflow-principles.md.
Pathfinder ships versioned git hooks in .githooks/ (not .git/hooks/, which
is local-only and untracked). Enable them once per clone:
git config core.hooksPath .githooks
All gates degrade gracefully: a gate whose toolchain isn't installed reports
SKIP, never a false FAIL, so the hooks work on any contributor's machine
from day one. Only the secrets scan and the staged-diff half of the
structural-suppress gate are non-skippable — security-mandate.md always wins.
Environment variable overrides (all optional):
Bypassing with git commit --no-verify / git push --no-verify should not be
routine practice (git-workflow-principles.md). The structural-suppress
gate ratchets pre-existing #[allow]/#[expect] overrides on the six
structural lints above against .githooks/suppression-baseline.txt: new
suppressions are always rejected, and paying down existing debt is locked in
by re-running:
.githooks/update-suppression-baseline.sh
Distributed under the MIT License. See the LICENSE file for details.
The Headless IDE — an MCP server that gives AI coding agents AST-aware semantic code intelligence and LSP navigation.
Công cụ
Chưa có danh sách công cụ. Máy chủ từ xa sẽ có danh sách sau lần kiểm tra tình trạng đầu tiên.
Câu hỏi thường gặp
Sao chép cấu hình stdio cho Cursor, Claude Desktop, Claude Code hoặc VS Code trên trang này. Cấu hình dùng bản cài đặt của nhà phát hành, không phải proxy của PlugMCP.
Bản ghi này không liệt kê biến môi trường bắt buộc nào.
Pathfinder chạy cục bộ qua stdio.
Kiểm tra lần cuối: 2026-10-28. The Headless IDE — an MCP server that gives AI coding agents AST-aware semantic code intelligence and LSP navigation.