{"id":"c032bab6-8969-4438-81e1-fc461d6622a9","slug":"fastsearch-mcp","kind":"mcp","name":"fastsearch-mcp","summary":"⚡ Lightning-fast file search MCP server using NTFS Master File Table - WizFile performance for Claude Desktop","owner":"sandraschi","repoUrl":"https://github.com/sandraschi/fastsearch-mcp","license":"MIT","licenseTier":"permissive","trust":"community","stars":5,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-07-15T21:28:58.000Z","addedAt":"2026-10-21T07:59:57.309Z","logoUrl":"https://avatars.githubusercontent.com/u/34750307?u=166281f79cd1114c24ba073dc02fd578660cbff0&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents","search","developer-tools"],"tags":["agentic","claude-desktop","code-mode","cplusplus","fastmcp","file-search","mft","named-pipes"],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-25T21:31:17.498Z","sample":false,"url":"https://conduits.dev/tools/fastsearch-mcp","language":"Python","transports":["stdio"],"install":{"npm":"fastsearch-mcp"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# FastSearch MCP\n\n<p align=\"center\">\n  <a href=\"https://github.com/casey/just\"><img src=\"https://img.shields.io/badge/just-ready_to_go-7c5cfc?style=flat-square&logo=just&logoColor=white\" alt=\"Just\"></a>\n  <a href=\"https://github.com/astral-sh/ruff\"><img src=\"https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json\" alt=\"Ruff\"></a>\n  <a href=\"https://python.org\"><img src=\"https://img.shields.io/badge/Python-3.13+-3776AB?style=flat-square&logo=python&logoColor=white\" alt=\"Python\"></a>\n  <a href=\"https://github.com/PrefectHQ/fastmcp\"><img src=\"https://img.shields.io/badge/FastMCP-3.2-7c5cfc?style=flat-square\" alt=\"FastMCP\"></a>\n</p>\n\n  \n> 📖 **[Installation Guide](INSTALL.md)** — quick start, manual setup, and troubleshooting\n\nLightning-fast file search via direct NTFS Master File Table access — zero indexing, zero caching. FastMCP 3.2 with CodeMode, prompts, and skills.\n\n> **Core Principle:** FastSearch MCP follows the WizFile philosophy. Every request reads straight from the NTFS MFT. We never build background indexes, caches, or persistent file databases.\n\n## Quick Start\n\n```powershell\ngit clone https://github.com/sandraschi/fastsearch-mcp\ncd fastsearch-mcp\njust onboard\n```\n\n`just onboard` requests Administrator elevation **ONCE** via UAC to register the `FastSearchMCP` Windows Service under `LocalSystem`, then automatically runs IPC named pipe diagnostic tests (`\\\\.\\pipe\\FastSearchMCP`). Once complete, all user tools (Claude Desktop, Web UI, Python MCP) execute MFT searches with **zero UAC prompts**.\n\nRun `just` to open the interactive dashboard showing all available commands. Run `just bootstrap` to install dependencies, then `just serve` or `just dev` to start.\n\n### Manual Setup\n\nIf you don't have `just` installed:\n\n##  Why FastSearch MCP\n\n- **Direct NTFS MFT reads** for sub-second search across millions of files.\n- **Zero indexing & zero persistence** keeps startup instant and memory under 50 MB.\n- **FastMCP 3.2**: sampling, CodeMode (`--agentic`), `@mcp.prompt()`, `@mcp.skill()`\n- **Privilege separation**: elevated C++ service handles filesystem duties, Python bridge stays in user space.\n- **Fast service checks** - <1ms overhead per search (optimized from 5 seconds).\n- **Clear error messages** - Actionable guidance when service is unavailable.\n\n##  Architecture Overview\n\n```\nClaude Desktop\n       JSON-RPC (stdin/stdout)\nPython MCP Bridge (user privileges)\n       Named pipe (`\\\\.\\pipe\\FastSearchMCP`)\nC++ Windows Service (LocalSystem)\n      \nNTFS Master File Table (live)\n```\n\n- **C++ Windows Service (`service/`)**\n  - Runs as `LocalSystem`.\n  - Opens NTFS volumes directly and answers search requests on demand.\n  - Emits structured logging to the Windows Event Log for diagnostics.\n  - No background threads, no file caches, no startup scans.\n\n- **Python MCP Bridge (`src/fastsearch_mcp/`)**\n  - FastMCP 3.2: **sampling** via `ctx.sampling()`, **CodeMode** agentic discovery (`--agentic`), **prompts** (`@mcp.prompt()`), and **skills** (`@mcp.skill()`).\n  - Implements 18 FastMCP 3.2 tools (`fastsearch_search`, `disk_analyzer`, `service_status`, etc.).\n  - Marshals requests to the service via named pipes and reformats results for Claude.\n  - Fast service availability checks (<1ms) before each search.\n  - Clear error messages when service is unavailable (no silent fallbacks).\n\n##  Architecture Guardrails (Non-Negotiable)\n\n- **Never add indexing, background scanning, or persistent metadata stores.**\n- **Never introduce in-memory caches of file lists or search results.**\n- **Always query NTFS live and stop once `max_results` is reached.**\n- **Always maintain instant startup, real-time accuracy, and minimal memory usage.**\n\nSee `docs/WIZFILE_COMPARISON.md` for the rationale.\n\n## FastMCP 3.2: Sampling, CodeMode, Prompts, Skills, Gateway\n\n- **Sampling**: Tools can request LLM completions from the client via `ctx.sampling()` (FastMCP 3.2 `Context` injection). No server-side configuration needed — the client provides the sampling handler.\n- **CodeMode agentic discovery**: Run with `--agentic` flag or `MCP_AGENTIC=true` to collapse all tools into discovery + execute meta-tools, using FastMCP 3.2's `CodeMode().attach(mcp)` transform.\n- **Prompts**: 3 built-in `@mcp.prompt()` templates: file search guide, disk analysis guide, service troubleshooting. Auto-registered at import time.\n- **Skills**: 3 composable `@mcp.skill()` workflows: find recently modified files, cleanup disk space, forensic file audit.\n- **Unified gateway**: Run as a proxy that aggregates or bridges other MCP servers (transport bridging, session isolation, forwards sampling/elicitation/logging/progress):\n  ```bash\n  # Single backend\n  set FASTSEARCH_GATEWAY_URL=http://127.0.0.1:8000/mcp\n  uv run python -m fastsearch_mcp.gateway\n\n  # Or use the console script\n  fastsearch-gateway\n  ```\n  Optional: `FASTSEARCH_GATEWAY_CONFIG` for multi-server JSON config; `MCP_TRANSPORT`, `MCP_HOST`, `MCP_PORT` to run the gateway over HTTP.\n\n##  Installation\n\n### Prerequisites\n- [uv](https://docs.astral.sh/uv/) installed (RECOMMENDED)\n- Python 3.12+\n\n###  Quick Start\nRun immediately via `uvx`:\n```bash\nuvx fastsearch-mcp\n```\n\n###  Claude Desktop Integration\nAdd to your `claude_desktop_config.json`:\n```json\n\"mcpServers\": {\n  \"fastsearch-mcp\": {\n    \"command\": \"uv\",\n    \"args\": [\"--directory\", \"D:/Dev/repos/fastsearch-mcp\", \"run\", \"fastsearch-mcp\"]\n  }\n}\n```\n### Quick Start\n\n#### For IDE Users (Cursor, Windsurf, Zed)  **Recommended**\n\n1. Install service: Download `fastsearch-mcp-setup.msi`  Run as Administrator\n2. Install Python package: `pip install fastsearch-mcp`\n3. Configure IDE: `npx -y fastsearch-mcp`\n\n#### For Claude Desktop Users\n\n1. Install service: Download `fastsearch-mcp-setup.msi`  Run as Administrator\n2. Install extension: Drag `fastsearch-mcp-0.4.0.mcpb` into Claude Desktop\n   - **Note**: MCPB format is Claude Desktop specific. The \"drag-and-drop into settings UI\" UX is unconventional.\n   - **Benefit**: MCPB includes prompt templates (system prompts, user guides) that help Claude understand capabilities.\n   - **Alternative**: Use NPX installation above for standard MCP config (works with Claude Desktop too).\n   - **See**: [`docs/MCPB_STATUS.md`](docs/MCPB_STATUS.md) for detailed explanation of MCPB limitations and prompt template alternatives.\n\n#### For Developers\n\nSee [Local Installation](docs/INSTALLATION_METHODS.md#1-local-installation-development) for full setup.\n\n##  Running the MCP Server Locally\n\n```powershell\n.venv\\Scripts\\Activate.ps1\npython scripts/start_server.py\n```\n\nAdd `fastsearch-mcp` to Claude Desktop's MCP configuration (see `mcp.config.json`) to auto-launch with Claude.\n\n##  Development Notes\n\n- `pytest` runs the Python test suite (18/18 tests passing). With the FastSearch service running (Windows), `pytest tests/test_live_pipe.py -v` runs live pipe + search integration tests.\n- **Tests page:** In the webapp, open `/tests` to run the same live tests from the UI.\n- `scripts/check-repo-standards.ps1` enforces logging + doc standards.\n- **Search functionality fully operational** - All search tools working with direct NTFS MFT access.\n- **Service running** - FastSearch Windows service operational and responding to requests.\n- **Performance optimized** - Service checks optimized to <1ms (from 5 seconds).\n\nSee `docs/RECENT_IMPROVEMENTS.md` for details on recent improvements.\n\n##  Key Documentation\n\n- `docs/RECENT_IMPROVEMENTS.md`  **NEW** - Recent improvements and search functionality status.\n- `docs/STATUS_REPORT.md`  Current project status and what's working.\n- `docs/TECHNICAL_ARCHITECTURE.md`  deep dive into the C++ + MCP bridge design.\n- `docs/PRODUCT_REQUIREMENTS.md`  product goals and non-negotiable principles.\n- `docs/SERVICE_AVAILABILITY_CHECKS.md`  How service availability is checked and error handling.\n- `docs/PIPE_CONNECTION_TROUBLESHOOTING.md`  Pipe not found (error 2): diagnosis, Event Log, fixes.\n- `docs/STATUS_NOTE_MEMOPS.md`  Short ops status note for pipe connect failures.\n- `docs/WIZFILE_COMPARISON.md`  why direct MFT access beats indexing.\n\n##  Contributing\n\nWe welcome contributions that preserve the direct-MFT architecture.\n\n1. Open an issue describing the change.\n2. Confirm it does **not** add indexing, caching, or background scanning.\n3. Create a feature branch and add tests where applicable.\n4. Run `pytest` and the markdown linter (`scripts/lint-markdown.ps1`).\n5. Submit a PR referencing the relevant docs.\n\n\n## 🛡️ Industrial Quality Stack\n\nThis project adheres to **SOTA 14.1** industrial standards for high-fidelity agentic orchestration:\n\n- **Python (Core)**: [Ruff](https://astral.sh/ruff) for linting and formatting. Zero-tolerance for `print` statements in core handlers (`T201`).\n- **Webapp (UI)**: [Biome](https://biomejs.dev/) for sub-millisecond linting. Strict `noConsoleLog` enforcement.\n- **Protocol Compliance**: Hardened `stdout/stderr` isolation to ensure crash-resistant JSON-RPC communication.\n- **Automation**: [Justfile](./justfile) recipes for all fleet operations (`just lint`, `just fix`, `just dev`).\n- **Security**: Automated audits via `bandit` and `safety`.\n## 🌐 Webapp Dashboard & Dedicated Search Page\n\nThis MCP server includes a free, premium web interface for file search, monitoring, and service control.\nBy default, the web dashboard runs on port **10844** with REST API bridge on port **10845**.\n\n**Features & Pages:**\n- **Dedicated Search Page (`/search`)**: SOTA file search UI with live service status badge, instant drive shortcuts (`C:\\`, `D:\\`), category filters (Code, Docs, Images, Media, Archives, Apps), interactive data table with sorting/pagination, file preview drawer (text, hex, image), JSON/CSV export, and query history.\n- **System Insight (`/`)**: Real-time service operational status and health metrics.\n- **NTFS Search Service (`/service`)**: Start, stop, restart, repair, or monitor the C++ named pipe service.\n- **Tests (`/tests`)**: Live integration test suite verifying named pipe connections and queries.\n- **Tools, Actions, AI Assistant, System Logs, Settings**.\n\nTo start the webapp:\n1. `uv run python run_server.py` (API bridge on port 10845)\n2. `cd web_sota && npm run dev` (Frontend on port 10844)\n3. Open `http://localhost:10844/search` in your browser.\n\n##  License\n\nMIT — see [LICENSE](LICENSE).\n"}