{"id":"d121be85-e0d2-4fc9-81d3-226aeb2601e2","slug":"loda-mcp-server","kind":"mcp","name":"loda-mcp-server","summary":"LLM-Optimized Document Access - A Model Context Protocol server for token-efficient document search using Bloom filters","owner":"patrickkarle","repoUrl":"https://github.com/patrickkarle/loda-mcp-server","license":"MIT","licenseTier":"permissive","trust":"community","stars":0,"match":null,"fewStars":true,"format":"mcp","createdAt":"2025-11-28T19:40:09.000Z","addedAt":"2026-10-21T20:09:13.388Z","logoUrl":"https://avatars.githubusercontent.com/u/212584393?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["files-documents","cloud-infra","search"],"tags":[],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T21:06:04.882Z","sample":false,"url":"https://conduits.dev/tools/loda-mcp-server","language":"JavaScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# LODA MCP Server\n\n> **LLM-Optimized Document Access** - A Model Context Protocol server for token-efficient document search in Claude Desktop and Claude Code.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green.svg)](https://nodejs.org/)\n[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-blue.svg)](https://modelcontextprotocol.io/)\n[![Tests](https://img.shields.io/badge/Tests-46%20Passing-brightgreen.svg)](#testing)\n\n---\n\n## What is LODA?\n\n**LODA** (LLM-Optimized Document Access) is a search strategy designed specifically for how LLMs consume documents. Instead of returning raw matches or arbitrary chunks, LODA understands document structure and returns the most relevant *sections* within your token budget.\n\n### The Problem\n\nWhen LLMs work with large documents, they face a fundamental challenge:\n\n| Traditional Approach | Problem |\n|---------------------|---------|\n| Load entire document | Exceeds context limits |\n| Keyword search | No relevance ranking, returns too much |\n| RAG/Vector search | Requires infrastructure, 200-500ms latency |\n| Chunk-based retrieval | Arbitrary boundaries break coherence |\n\nWe discovered a **\"gap zone\"** at 25-35% document positions where traditional smart retrieval actually performed *worse* than brute-force loading.\n\n### The Solution\n\nLODA combines lightweight techniques to achieve **vector search quality** at **grep-like speeds**:\n\n```\n┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────┐\n│  Large Document │────▶│  LODA Search Engine  │────▶│ Relevant Sections│\n│   (5000+ lines) │     │  • Bloom Filters     │     │  within budget   │\n│                 │     │  • Token Budget      │     │  (~200 tokens)   │\n│                 │     │  • Relevance Scoring │     │                  │\n└─────────────────┘     │  • Smart Caching     │     └─────────────────┘\n                        └──────────────────────┘\n```\n\n**Results:**\n- **70-95% token savings** compared to loading full document\n- **1-5ms search latency** (cached) vs 200-500ms for RAG\n- **Zero external dependencies** - no vector database needed\n\n---\n\n## Quick Start\n\n### 1. Installation\n\n```bash\ngit clone https://github.com/patrickkarle/loda-mcp-server.git\ncd loda-mcp-server\nnpm install\n```\n\n### 2. Configure Claude Desktop\n\nFind your config file:\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\nAdd this to the file:\n\n```json\n{\n  \"mcpServers\": {\n    \"loda\": {\n      \"command\": \"node\",\n      \"args\": [\"/full/path/to/loda-mcp-server/document_access_mcp_server.js\", \"--mode=stdio\"]\n    }\n  }\n}\n```\n\n### 3. Configure Claude Code\n\nAdd to your project's `.claude/settings.json` or global `~/.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"loda\": {\n      \"command\": \"node\",\n      \"args\": [\"/full/path/to/loda-mcp-server/document_access_mcp_server.js\", \"--mode=stdio\"]\n    }\n  }\n}\n```\n\n### 4. Use It!\n\nAsk Claude:\n\n> \"Use loda_search to find the authentication section in api-docs.md\"\n\n> \"Search architecture.md for deployment instructions with a 500 token budget\"\n\n---\n\n## How LODA Works\n\n### 1. Bloom Filter Elimination\n\nBefore scoring, LODA uses [Bloom filters](https://en.wikipedia.org/wiki/Bloom_filter) to instantly eliminate sections that definitely don't contain your search terms. This O(1) operation typically eliminates 80%+ of sections.\n\n### 2. Section-Aware Parsing\n\nLODA respects your document's structure. It understands markdown headings and returns complete logical sections, not arbitrary text chunks.\n\n### 3. Relevance Scoring\n\nEach candidate section is scored based on:\n- **Query term presence** in content (0.8 base score)\n- **Header match bonus** (+0.2 for header matches)\n- **Multi-term coverage** (all terms weighted equally)\n\n### 4. Token Budget Selection\n\nYou specify a token budget, LODA returns the best sections that fit:\n\n```javascript\n// \"I need info about auth, but only have 500 tokens of context\"\n{\n  query: \"authentication\",\n  contextBudget: 500\n}\n```\n\n### 5. Aggressive Caching\n\nDocument structures and Bloom filters are cached with TTL (60s default). Repeated searches on the same document are 10x+ faster.\n\n---\n\n## API Reference\n\n### loda_search\n\nThe main search tool.\n\n**Parameters:**\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `documentPath` | string | Yes | - | Path to document (relative to staging or absolute) |\n| `query` | string | Yes | - | Search keywords or phrase |\n| `contextBudget` | number | No | null | Maximum tokens to return (null = unlimited) |\n| `maxSections` | number | No | 5 | Maximum sections to return |\n\n**Example Request:**\n\n```json\n{\n  \"documentPath\": \"api-docs.md\",\n  \"query\": \"authentication oauth\",\n  \"contextBudget\": 500,\n  \"maxSections\": 3\n}\n```\n\n**Example Response:**\n\n```json\n{\n  \"query\": \"authentication oauth\",\n  \"documentPath\": \"/path/to/api-docs.md\",\n  \"sections\": [\n    {\n      \"id\": \"section-5\",\n      \"header\": \"OAuth 2.0 Authentication\",\n      \"level\": 3,\n      \"score\": 1.0,\n      \"lineRange\": [27, 41],\n      \"tokenEstimate\": 88\n    },\n    {\n      \"id\": \"section-4\",\n      \"header\": \"API Key Authentication\",\n      \"level\": 3,\n      \"score\": 0.8,\n      \"lineRange\": [15, 26],\n      \"tokenEstimate\": 66\n    }\n  ],\n  \"metadata\": {\n    \"totalSections\": 21,\n    \"candidatesAfterBloom\": 5,\n    \"scoredAboveZero\": 3,\n    \"returnedSections\": 2,\n    \"totalTokens\": 154,\n    \"budgetStatus\": \"SAFE\",\n    \"truncated\": false,\n    \"cacheHit\": true\n  }\n}\n```\n\n### Budget Status Values\n\n| Status | Meaning |\n|--------|---------|\n| `UNLIMITED` | No budget was specified |\n| `SAFE` | Total tokens under 80% of budget |\n| `WARNING` | Total tokens between 80-100% of budget |\n| `EXCEEDED` | Over budget (first section always returned) |\n\n### Other Tools\n\n| Tool | Description |\n|------|-------------|\n| `list_document_sections` | Get hierarchical structure of document |\n| `read_section` | Read specific section by ID with context |\n| `read_lines` | Read specific line range |\n| `search_content` | Basic regex search (no LODA optimization) |\n\n---\n\n## Staging Directory\n\nBy default, LODA looks for documents in the `staging/` subdirectory:\n\n```\nloda-mcp-server/\n├── staging/              ← Put documents here\n│   ├── api-docs.md\n│   ├── architecture.md\n│   └── user-guide.md\n└── document_access_mcp_server.js\n```\n\nYou can also use absolute paths to search any document on your system.\n\n---\n\n## HTTP Mode (Development/Testing)\n\nFor testing without Claude, run the server in HTTP mode:\n\n```bash\nnode document_access_mcp_server.js --mode=http --port=49400\n```\n\nThen test with curl:\n\n```bash\n# Health check\ncurl http://localhost:49400/health\n\n# List tools\ncurl http://localhost:49400/tools\n\n# Search\ncurl -X POST http://localhost:49400/tools/loda_search \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"documentPath\": \"api-docs.md\", \"query\": \"authentication\"}'\n```\n\n---\n\n## Performance\n\n| Metric | Target | Achieved |\n|--------|--------|----------|\n| Search latency (cached) | <10ms | **1-5ms** |\n| Search latency (cold) | <100ms | **20-50ms** |\n| Token savings | >70% | **70-95%** |\n| Bloom filter effectiveness | >80% | **~85%** |\n| Cache hit rate | >80% | **~90%** |\n\n---\n\n## Testing\n\n```bash\n# Run all LODA tests\nnpm test\n\n# Run specific component tests\nnpm test -- tests/loda_search_handler.test.js\n\n# Run with coverage\nnpm test -- --coverage\n```\n\n**Test Results: 46/46 Passing**\n\n| Component | Tests | Status |\n|-----------|-------|--------|\n| token_estimator | 6 | ✅ |\n| relevance_scorer | 8 | ✅ |\n| budget_manager | 6 | ✅ |\n| bloom_filter | 10 | ✅ |\n| loda_index | 8 | ✅ |\n| loda_search_handler | 8 | ✅ |\n\n---\n\n## Architecture\n\n```\nloda/\n├── token_estimator.js      # Pure token estimation (~4 chars/token)\n├── relevance_scorer.js     # Section relevance scoring\n├── budget_manager.js       # Token budget selection\n├── loda_index.js           # Cached document structure (TTL + LRU)\n├── bloom_filter.js         # O(1) section elimination\n├── loda_search_handler.js  # Main orchestrator\n└── index.js                # Module entry\n\ndocument_access_mcp_server.js  # MCP server with 5 tools\n```\n\n---\n\n## Research & Development\n\nThis project was built using the **Continuum Development Process (CDP)**, a 13-phase methodology that emphasizes traceability and quality gates.\n\n### Why We Built This\n\nWe tried several approaches before arriving at LODA:\n\n| Approach | Why It Failed |\n|----------|---------------|\n| **Semantic Chunking** | Arbitrary boundaries split logical units |\n| **RAG + Vector Search** | Too much infrastructure for single-doc access |\n| **JIT-Steg Retrieval** | \"Gap zone\" at 25-35% where overhead exceeded brute-force |\n| **Simple Grep** | No relevance ranking, no token awareness |\n\nLODA combines the best of each: section awareness, fast elimination, budget control, and zero external dependencies.\n\n### Research Documents\n\n- [ULTRATHINK Analysis](warehouse/blueprints/cdp-loda-decomposition/loda-mcp-server/00-ultrathink/) - Problem analysis from 5+ perspectives\n- [Research Notes](warehouse/blueprints/cdp-loda-decomposition/loda-mcp-server/01-research-notes/) - Literature review and approach comparison\n- [Implementation Plan](warehouse/blueprints/cdp-loda-decomposition/loda-mcp-server/02-plan/) - Technical architecture\n- [Testing Plan](warehouse/blueprints/cdp-loda-decomposition/loda-mcp-server/04-testing-plan/) - 61 test cases specified\n\n---\n\n## Configuration Examples\n\n### Claude Desktop (Windows)\n\n`%APPDATA%\\Claude\\claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"loda\": {\n      \"command\": \"node\",\n      \"args\": [\"C:/Users/YourName/loda-mcp-server/document_access_mcp_server.js\", \"--mode=stdio\"]\n    }\n  }\n}\n```\n\n### Claude Desktop (macOS/Linux)\n\n`~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"loda\": {\n      \"command\": \"node\",\n      \"args\": [\"/home/yourname/loda-mcp-server/document_access_mcp_server.js\", \"--mode=stdio\"]\n    }\n  }\n}\n```\n\n### Claude Code (Project-level)\n\n`.claude/settings.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"loda\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/loda-mcp-server/document_access_mcp_server.js\", \"--mode=stdio\"]\n    }\n  }\n}\n```\n\n---\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Write tests for new functionality\n4. Submit a PR with documentation\n\n---\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n## Acknowledgments\n\n- Built for [Model Context Protocol](https://modelcontextprotocol.io/)\n- Developed using [Continuum Development Process](https://github.com/continuum-persistence/continuum)\n- Inspired by information retrieval research on probabilistic data structures\n\n---\n\n**Made with 🧠 for LLMs that need to read documents efficiently.**\n"}