LODA MCP Server

LLM-Optimized Document Access - A Model Context Protocol server for token-efficient document search in Claude Desktop and Claude Code.

What is LODA?

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.

The Problem

When LLMs work with large documents, they face a fundamental challenge:

Traditional Approach	Problem
Load entire document	Exceeds context limits
Keyword search	No relevance ranking, returns too much
RAG/Vector search	Requires infrastructure, 200-500ms latency
Chunk-based retrieval	Arbitrary boundaries break coherence

We discovered a "gap zone" at 25-35% document positions where traditional smart retrieval actually performed worse than brute-force loading.

The Solution

LODA combines lightweight techniques to achieve vector search quality at grep-like speeds:

┌─────────────────┐     ┌──────────────────────┐     ┌─────────────────┐
│  Large Document │────▶│  LODA Search Engine  │────▶│ Relevant Sections│
│   (5000+ lines) │     │  • Bloom Filters     │     │  within budget   │
│                 │     │  • Token Budget      │     │  (~200 tokens)   │
│                 │     │  • Relevance Scoring │     │                  │
└─────────────────┘     │  • Smart Caching     │     └─────────────────┘
                        └──────────────────────┘

Results:

70-95% token savings compared to loading full document
1-5ms search latency (cached) vs 200-500ms for RAG
Zero external dependencies - no vector database needed

Quick Start

1. Installation

git clone https://github.com/patrickkarle/loda-mcp-server.git
cd loda-mcp-server
npm install

2. Configure Claude Desktop

Find your config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Add this to the file:

{
  "mcpServers": {
    "loda": {
      "command": "node",
      "args": ["/full/path/to/loda-mcp-server/document_access_mcp_server.js", "--mode=stdio"]
    }
  }
}

3. Configure Claude Code

Add to your project's .claude/settings.json or global ~/.claude/settings.json:

{
  "mcpServers": {
    "loda": {
      "command": "node",
      "args": ["/full/path/to/loda-mcp-server/document_access_mcp_server.js", "--mode=stdio"]
    }
  }
}

4. Use It!

Ask Claude:

"Use loda_search to find the authentication section in api-docs.md"

"Search architecture.md for deployment instructions with a 500 token budget"

How LODA Works

1. Bloom Filter Elimination

Before scoring, LODA uses Bloom filters to instantly eliminate sections that definitely don't contain your search terms. This O(1) operation typically eliminates 80%+ of sections.

2. Section-Aware Parsing

LODA respects your document's structure. It understands markdown headings and returns complete logical sections, not arbitrary text chunks.

3. Relevance Scoring

Each candidate section is scored based on:

Query term presence in content (0.8 base score)
Header match bonus (+0.2 for header matches)
Multi-term coverage (all terms weighted equally)

4. Token Budget Selection

You specify a token budget, LODA returns the best sections that fit:

// "I need info about auth, but only have 500 tokens of context"
{
  query: "authentication",
  contextBudget: 500
}

5. Aggressive Caching

Document structures and Bloom filters are cached with TTL (60s default). Repeated searches on the same document are 10x+ faster.

API Reference

loda_search

The main search tool.

Parameters:

Parameter	Type	Required	Default	Description
`documentPath`	string	Yes	-	Path to document (relative to staging or absolute)
`query`	string	Yes	-	Search keywords or phrase
`contextBudget`	number	No	null	Maximum tokens to return (null = unlimited)
`maxSections`	number	No	5	Maximum sections to return

Example Request:

{
  "documentPath": "api-docs.md",
  "query": "authentication oauth",
  "contextBudget": 500,
  "maxSections": 3
}

Example Response:

{
  "query": "authentication oauth",
  "documentPath": "/path/to/api-docs.md",
  "sections": [
    {
      "id": "section-5",
      "header": "OAuth 2.0 Authentication",
      "level": 3,
      "score": 1.0,
      "lineRange": [27, 41],
      "tokenEstimate": 88
    },
    {
      "id": "section-4",
      "header": "API Key Authentication",
      "level": 3,
      "score": 0.8,
      "lineRange": [15, 26],
      "tokenEstimate": 66
    }
  ],
  "metadata": {
    "totalSections": 21,
    "candidatesAfterBloom": 5,
    "scoredAboveZero": 3,
    "returnedSections": 2,
    "totalTokens": 154,
    "budgetStatus": "SAFE",
    "truncated": false,
    "cacheHit": true
  }
}

Budget Status Values

Status	Meaning
`UNLIMITED`	No budget was specified
`SAFE`	Total tokens under 80% of budget
`WARNING`	Total tokens between 80-100% of budget
`EXCEEDED`	Over budget (first section always returned)

Other Tools

Tool	Description
`list_document_sections`	Get hierarchical structure of document
`read_section`	Read specific section by ID with context
`read_lines`	Read specific line range
`search_content`	Basic regex search (no LODA optimization)

Staging Directory

By default, LODA looks for documents in the staging/ subdirectory:

loda-mcp-server/
├── staging/              ← Put documents here
│   ├── api-docs.md
│   ├── architecture.md
│   └── user-guide.md
└── document_access_mcp_server.js

You can also use absolute paths to search any document on your system.

HTTP Mode (Development/Testing)

For testing without Claude, run the server in HTTP mode:

node document_access_mcp_server.js --mode=http --port=49400

Then test with curl:

# Health check
curl http://localhost:49400/health

# List tools
curl http://localhost:49400/tools

# Search
curl -X POST http://localhost:49400/tools/loda_search \
  -H "Content-Type: application/json" \
  -d '{"documentPath": "api-docs.md", "query": "authentication"}'

Performance

Metric	Target	Achieved
Search latency (cached)	<10ms	1-5ms
Search latency (cold)	<100ms	20-50ms
Token savings	>70%	70-95%
Bloom filter effectiveness	>80%	~85%
Cache hit rate	>80%	~90%

Testing

# Run all LODA tests
npm test

# Run specific component tests
npm test -- tests/loda_search_handler.test.js

# Run with coverage
npm test -- --coverage

Test Results: 46/46 Passing

Component	Tests	Status
token_estimator	6	✅
relevance_scorer	8	✅
budget_manager	6	✅
bloom_filter	10	✅
loda_index	8	✅
loda_search_handler	8	✅

Architecture

loda/
├── token_estimator.js      # Pure token estimation (~4 chars/token)
├── relevance_scorer.js     # Section relevance scoring
├── budget_manager.js       # Token budget selection
├── loda_index.js           # Cached document structure (TTL + LRU)
├── bloom_filter.js         # O(1) section elimination
├── loda_search_handler.js  # Main orchestrator
└── index.js                # Module entry

document_access_mcp_server.js  # MCP server with 5 tools

Research & Development

This project was built using the Continuum Development Process (CDP), a 13-phase methodology that emphasizes traceability and quality gates.

Why We Built This

We tried several approaches before arriving at LODA:

Approach	Why It Failed
Semantic Chunking	Arbitrary boundaries split logical units
RAG + Vector Search	Too much infrastructure for single-doc access
JIT-Steg Retrieval	"Gap zone" at 25-35% where overhead exceeded brute-force
Simple Grep	No relevance ranking, no token awareness

LODA combines the best of each: section awareness, fast elimination, budget control, and zero external dependencies.

Research Documents

ULTRATHINK Analysis - Problem analysis from 5+ perspectives
Research Notes - Literature review and approach comparison
Implementation Plan - Technical architecture
Testing Plan - 61 test cases specified

Configuration Examples

Claude Desktop (Windows)

%APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "loda": {
      "command": "node",
      "args": ["C:/Users/YourName/loda-mcp-server/document_access_mcp_server.js", "--mode=stdio"]
    }
  }
}

Claude Desktop (macOS/Linux)

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "loda": {
      "command": "node",
      "args": ["/home/yourname/loda-mcp-server/document_access_mcp_server.js", "--mode=stdio"]
    }
  }
}

Claude Code (Project-level)

.claude/settings.json:

{
  "mcpServers": {
    "loda": {
      "command": "node",
      "args": ["/path/to/loda-mcp-server/document_access_mcp_server.js", "--mode=stdio"]
    }
  }
}

Contributing

Fork the repository
Create a feature branch
Write tests for new functionality
Submit a PR with documentation

License

MIT License - see LICENSE for details.

Acknowledgments

Built for Model Context Protocol
Developed using Continuum Development Process
Inspired by information retrieval research on probabilistic data structures

Made with 🧠 for LLMs that need to read documents efficiently.

Name		Name	Last commit message	Last commit date
config-templates		config-templates
loda		loda
staging		staging
tests		tests
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
USER_GUIDE.md		USER_GUIDE.md
document_access_mcp_server.js		document_access_mcp_server.js
package.json		package.json

Latest commit

History

Folders and files

Repository files navigation