# Pathfinder > The Headless IDE β€” an MCP server that gives AI coding agents AST-aware semantic code intelligence and LSP navigation. - **Type:** MCP server - **Install:** `agentstack add mcp-irahardianto-pathfinder` - **Verified:** Yes β€” security-reviewed for prompt injection and unsafe behavior - **Seller:** [irahardianto](https://agentstack.voostack.com/s/irahardianto) - **Installs:** 0 - **Category:** [Search](https://agentstack.voostack.com/c/search) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [irahardianto](https://github.com/irahardianto) - **Source:** https://github.com/irahardianto/pathfinder ## Install ```sh agentstack add mcp-irahardianto-pathfinder ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About 🧭 Pathfinder [](https://github.com/irahardianto/pathfinder/actions/workflows/ci.yml) [](https://app.deepsource.com/gh/irahardianto/pathfinder/) [](https://github.com/irahardianto/pathfinder/actions/workflows/github-code-scanning/codeql) [](https://dependabot.com/) [](https://github.com/irahardianto/pathfinder/actions/workflows/slsa-provenance.yml) The Headless IDE β€” an MCP server that gives AI coding agents AST-aware code intelligence, semantic navigation, and LSP-backed discovery. Getting Started Β· Agent Directives Β· View Tools Β· Request Feature ## About Pathfinder **Pathfinder** is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) 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. ### Why Pathfinder? Traditional AI coding workflows suffer from: - **Blind navigation** β€” agents read entire files to find one symbol, wasting context. - **No semantic understanding** β€” flat text search returns hits in comments, strings, and dead code equally. - **Fragile path construction** β€” agents guess file structures instead of discovering them. Pathfinder solves these problems by providing: - 🌳 **AST-Aware Navigation** β€” jump to symbols using semantic paths (e.g., `src/auth.ts::AuthService.login`). - πŸ” **Semantic Search** β€” filter search results by AST context (code-only, comments-only, or all) powered by ripgrep + Tree-sitter. - πŸ“‘ **LSP-Powered Discovery** β€” go-to-definition, call hierarchy (incoming/outgoing), and real-time indexing status. - πŸ—ΊοΈ **Structural Mapping** β€” a token-budgeted repository skeleton that surfaces every symbol and its semantic path. - πŸ›‘οΈ **Sandbox Security** β€” a 3-tier file access model prevents path traversal attacks and unauthorized file access. - πŸ“Š **Built-in Observability** β€” per-engine telemetry (`ripgrep_ms`, `tree_sitter_parse_ms`, `lsp_ms`) and optional `--lsp-trace` for raw JSON-RPC debugging. ### Key Features - πŸ› οΈ **7 MCP Tools** β€” covering code exploration, semantic search, file reading, symbol inspection, navigation, impact tracing, and LSP health. - 🌐 **8 Languages** β€” native Tree-sitter support for Go, Java, TypeScript, TSX, JavaScript, Python, Rust, and Vue SFCs. - πŸ—οΈ **5 Rust Crates** β€” modular workspace architecture for clean separation of concerns. - ⚑ **Zero Configuration** β€” auto-detects languages and LSP servers in your workspace. ## Getting Started ### Prerequisites - **Rust toolchain** (1.75+ recommended) β€” [Install via rustup](https://rustup.rs/) - **An MCP-compatible AI client** β€” such as [Antigravity](https://antigravity.dev/), Claude Desktop, Cursor, or any tool supporting MCP stdio transport. - **(Optional) Language servers** β€” for LSP navigation support (e.g., `gopls` for Go, `typescript-language-server` for TS/JS, `rust-analyzer` for Rust, `pyright` for Python). ### Installation Choose one of the following methods: **Homebrew (macOS & Linux):** ```sh brew tap irahardianto/pathfinder-mcp brew install pathfinder-mcp ``` **cargo install from crates.io:** ```sh cargo install pathfinder-mcp ``` **Build from source:** ```sh 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:** ```sh pathfinder-mcp --help ``` ### Configuration #### MCP Client Configuration Add Pathfinder to your MCP client's server configuration. The exact format depends on your client. **Example (JSON config for most MCP clients):** ```json { "mcpServers": { "pathfinder": { "command": "pathfinder-mcp", "args": ["/path/to/your/workspace"] } } } ``` **With LSP trace enabled (for debugging):** ```json { "mcpServers": { "pathfinder": { "command": "pathfinder-mcp", "args": ["--lsp-trace", "/path/to/your/workspace"] } } } ``` #### CLI Usage ``` pathfinder-mcp [OPTIONS] Arguments: 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). ## Agent Directives 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 the difference between `read` for a source file vs a config file will make avoidable mistakes β€” calling the wrong tool, constructing malformed paths, or wasting context reading entire files for single symbols. The directives encode all of this knowledge directly into the agent's system context. ### What's Included The directives live in [`docs/agent_directives/`](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: - To prefer Pathfinder's semantic tools over built-in text tools whenever possible - How to form correct semantic paths (e.g., `src/auth.ts::AuthService.login`) - Which tool to reach for each action (reading, searching, navigating) - When to fall back gracefully if Pathfinder is unavailable **`skills/pathfinder/SKILL.md`** β€” a detailed on-demand skill the agent activates when it needs deeper guidance. It covers: - Step-by-step workflows for exploring, auditing, and debugging codebases - Efficient search with `mode` (text/regex/symbol), `filter_mode`, `exclude_glob`, `known_files`, and `group_by_file` - Error recovery patterns for `SYMBOL_NOT_FOUND`, LSP degradation, and timeout scenarios ### Setup by Client #### Antigravity Copy the directives into your project's `.agents/` directory. Antigravity auto-discovers all rules and skills placed there: ```sh # 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: ```sh 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. #### Claude Desktop / Cursor / Other MCP Clients 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. #### General Approach 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. ## Tools Pathfinder exposes 7 tools. Every tool operates within the workspace sandbox and returns structured JSON responses. ### πŸ—ΊοΈ Exploration & Search | Tool | Description | |---|---| | `explore` | Get the structural skeleton of the project β€” directory tree, file listing, or full AST symbol hierarchy. Three detail levels: `structure` (dirs + package files), `files` (dirs + all filenames), `symbols` (default β€” full AST hierarchy). Token-budgeted with configurable `depth` and `max_tokens`. Supports `changed_since`, `include_extensions`, and `exclude_extensions` for focused exploration. | | `search` | Search for text patterns, regex, or resolve symbol names across the codebase. Three modes: `text` (default β€” literal search), `regex` (pattern search), `symbol` (resolve bare name to semantic paths). AST-aware filtering (code-only by default). Token-efficiency parameters: `known_files`, `exclude_glob`, `path_glob`. | ### πŸ“– Reading & Inspection | Tool | Description | |---|---| | `read` | Read file contents β€” single file or batch (max 10). Auto-detects source vs config files. Source files (.rs, .ts, .go, .py, .vue, .js, .java) get AST-parsed content with detail levels (`source_only`, `compact`, `symbols`, `full`). Config files get raw content. Supports `start_line`/`end_line` for line ranges. | | `inspect` | Extract a symbol's source code by semantic path, optionally with its dependency graph. Default: source only (fast, Tree-sitter). With `include_dependencies=true`: also fetches callee signatures (LSP-powered). | ### 🧭 Navigation & Tracing | Tool | Description | |---|---| | `locate` | Jump to a symbol's definition, or resolve a file+line to its semantic path. Two auto-detected modes: provide `semantic_path` for definition lookup, or `file`+`line` for semantic path resolution. LSP-powered with ripgrep fallback. | | `trace` | Trace a symbol's relationships β€” callers/callees, all references, or full overview. Three scopes: `callers` (default β€” call hierarchy), `references` (all usages including imports, type annotations), `overview` (combined source + callers + callees + references). Essential for understanding blast radius before refactoring. | ### πŸ”§ Utility | Tool | Description | |---|---| | `health` | Check per-language LSP readiness β€” including `navigation_ready`, `indexing_status`, `supports_call_hierarchy`, and `degraded_tools`. Use to diagnose why navigation tools returned degraded results. Supports `action="restart"` to force-restart a stuck LSP. | ## Architecture 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 (7 consolidated tools) β”‚ β”‚ └── server/ β”‚ β”‚ β”œβ”€β”€ types.rs # Parameter & response types β”‚ β”‚ β”œβ”€β”€ helpers.rs # Shared utilities β”‚ β”‚ └── tools/ # One module per tool category β”‚ β”‚ β”œβ”€β”€ search.rs # search tool handler β”‚ β”‚ β”œβ”€β”€ repo_map.rs # explore tool handler β”‚ β”‚ β”œβ”€β”€ source_file.rs # read tool handler (single file) β”‚ β”‚ β”œβ”€β”€ read_files.rs # read tool handler (batch) β”‚ β”‚ β”œβ”€β”€ find_symbol.rs # search(mode=symbol) handler β”‚ β”‚ β”œβ”€β”€ file_ops.rs # file I/O utilities β”‚ β”‚ β”œβ”€β”€ symbols.rs # symbol extraction β”‚ β”‚ β”œβ”€β”€ 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 β”‚ β”‚ └── health.rs # health tool handler β”‚ β”‚ β”‚ β”œβ”€β”€ pathfinder-common/ # Shared types, errors, config, sandbox β”‚ β”œβ”€β”€ pathfinder-treesitter/ # The Surgeon β€” AST parsing & symbol extraction β”‚ β”œβ”€β”€ pathfinder-search/ # The Scout β€” ripgrep-powered code search β”‚ └── pathfinder-lsp/ # The Lawyer β€” LSP client & lifecycle management β”‚ β”œβ”€β”€ 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: `::[.]` #### 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**: `` parsed as TypeScript (AST-aware), `` and `` 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 … ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source β€” we do not rehost the code. - **Author:** [irahardianto](https://github.com/irahardianto) - **Source:** [irahardianto/pathfinder](https://github.com/irahardianto/pathfinder) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** β€” Free ## Security capabilities Automated source analysis of v0.1.0 β€” what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source β€” more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** β€” security scan: passed β€” Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-irahardianto-pathfinder - Seller: https://agentstack.voostack.com/s/irahardianto - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack β€” the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.