# LODA MCP Server - User Guide
> Complete runbook for installing, configuring, and using LODA with Claude Desktop and Claude Code.
---
## Table of Contents
1. [Prerequisites](#prerequisites)
2. [Installation](#installation)
3. [Claude Desktop Setup](#claude-desktop-setup)
4. [Claude Code Setup](#claude-code-setup)
5. [Using LODA Search](#using-loda-search)
6. [Working with Documents](#working-with-documents)
7. [Understanding Results](#understanding-results)
8. [Advanced Usage](#advanced-usage)
9. [Troubleshooting](#troubleshooting)
10. [FAQ](#faq)
---
## Prerequisites
Before starting, ensure you have:
- [ ] **Node.js 18+** installed
```bash
node --version # Should show v18.x.x or higher
```
- [ ] **Claude Desktop** or **Claude Code** installed
- [ ] Basic familiarity with JSON configuration files
---
## Installation
### Step 1: Clone the Repository
```bash
git clone https://github.com/patrickkarle/loda-mcp-server.git
cd loda-mcp-server
```
### Step 2: Install Dependencies
```bash
npm install
```
### Step 3: Verify Installation
```bash
# Run the test suite
npm test
# Or test the server directly
node document_access_mcp_server.js --help
```
You should see output showing available tools.
---
## Claude Desktop Setup
### Step 1: Locate Your Config File
| Operating System | Config File Location |
|-----------------|---------------------|
| **Windows** | `%APPDATA%\Claude\claude_desktop_config.json` |
| **macOS** | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| **Linux** | `~/.config/Claude/claude_desktop_config.json` |
**Tip**: On Windows, press `Win+R`, type `%APPDATA%\Claude`, and press Enter.
### Step 2: Create or Edit the Config File
If the file doesn't exist, create it. Add this content:
```json
{
"mcpServers": {
"loda": {
"command": "node",
"args": [
"REPLACE_WITH_FULL_PATH/document_access_mcp_server.js",
"--mode=stdio"
]
}
}
}
```
### Step 3: Replace the Path
**Windows example:**
```json
"args": ["C:/Users/Patrick/loda-mcp-server/document_access_mcp_server.js", "--mode=stdio"]
```
**macOS/Linux example:**
```json
"args": ["/home/patrick/loda-mcp-server/document_access_mcp_server.js", "--mode=stdio"]
```
⚠️ **Important**: Use forward slashes `/` even on Windows!
### Step 4: Restart Claude Desktop
1. Quit Claude Desktop completely (not just close the window)
2. Relaunch Claude Desktop
3. Wait for it to fully load
### Step 5: Verify MCP Server is Loaded
Ask Claude:
> "What MCP tools do you have available?"
You should see these tools listed:
- `loda_search`
- `list_document_sections`
- `read_section`
- `read_lines`
- `search_content`
---
## Claude Code Setup
### Option A: Project-Level Configuration (Recommended)
Add to your project's `.claude/settings.json`:
```json
{
"mcpServers": {
"loda": {
"command": "node",
"args": ["/full/path/to/document_access_mcp_server.js", "--mode=stdio"]
}
}
}
```
This configuration only applies to this specific project.
### Option B: Global Configuration
Add to `~/.claude/settings.json` (creates if doesn't exist):
```json
{
"mcpServers": {
"loda": {
"command": "node",
"args": ["/full/path/to/document_access_mcp_server.js", "--mode=stdio"]
}
}
}
```
This makes LODA available in all Claude Code sessions.
### Verify Installation
Start a new Claude Code session:
```bash
claude
```
Ask: "What MCP tools do you have?"
---
## Using LODA Search
### Basic Search
Ask Claude to search any document:
```
Use loda_search to find information about authentication in api-docs.md
```
### Search with Token Budget
When you're low on context or want concise results:
```
Search architecture.md for deployment instructions with a 500 token budget
```
### Search for Multiple Topics
LODA handles multi-word queries intelligently:
```
Use loda_search to find "error handling rate limiting" in the API documentation
```
### Limit Number of Sections
When you only want the top matches:
```
Find the top 2 sections about database configuration in config-guide.md
```
---
## Working with Documents
### Staging Directory
By default, LODA looks in the `staging/` folder:
```
loda-mcp-server/
└── staging/
├── your-doc.md
├── api-reference.md
└── user-manual.md
```
**To add a document:**
1. Copy it to the `staging/` folder
2. Search it by filename
### Absolute Paths
You can also search any document using its full path:
```
Use loda_search on /home/patrick/projects/docs/README.md to find setup instructions
```
### Supported Formats
LODA works best with:
- Markdown files (`.md`)
- Plain text files (`.txt`)
- Any text-based format
It recognizes markdown headings (`#`, `##`, etc.) to understand document structure.
---
## Understanding Results
### Response Structure
When LODA finds results, it returns:
```json
{
"sections": [
{
"id": "section-5",
"header": "Authentication",
"level": 2,
"score": 1.0,
"lineRange": [45, 78],
"tokenEstimate": 125
}
],
"metadata": {
"totalSections": 21,
"budgetStatus": "SAFE",
"totalTokens": 125
}
}
```
### Score Interpretation
| Score | Meaning |
|-------|---------|
| 1.0 | Perfect match (query in both header and content) |
| 0.8 | Good match (query in content, partial header match) |
| 0.6 | Partial match (some query terms found) |
| 0.0 | No match |
### Budget Status
| Status | What It Means |
|--------|---------------|
| `UNLIMITED` | No budget specified, all relevant sections returned |
| `SAFE` | Under 80% of your budget - plenty of room |
| `WARNING` | 80-100% of budget - approaching limit |
| `EXCEEDED` | Over budget, but at least one section always returned |
---
## Advanced Usage
### Follow-Up with Full Content
After LODA finds relevant sections, get full content:
```
1. "Use loda_search to find authentication in api.md"
→ Returns: section-5 (Authentication)
2. "Now read the full content of section-5"
→ Use read_section tool to get complete text
```
### Combine with Other Search
For comprehensive search:
```
1. "Use loda_search to find the auth module documentation"
2. "Now use grep to find all files that import AuthModule"
```
### Cache Behavior
- First search: Parses document, builds index (~20-50ms)
- Subsequent searches: Uses cache (~1-5ms)
- Cache expires after 60 seconds of inactivity
- Modified files automatically refresh on next search
### HTTP Mode for Testing
Test without Claude:
```bash
# Start server
node document_access_mcp_server.js --mode=http --port=49400
# In another terminal
curl -X POST http://localhost:49400/tools/loda_search \
-H "Content-Type: application/json" \
-d '{"documentPath": "test.md", "query": "setup"}'
```
---
## Troubleshooting
### "MCP tools not available"
**Symptoms**: Claude doesn't recognize loda_search command
**Solutions**:
1. Verify config file syntax is valid JSON
2. Check path uses forward slashes
3. Ensure Node.js is in your PATH
4. Restart Claude Desktop completely
### "Document not found"
**Symptoms**: Error when searching a document
**Solutions**:
1. Check document is in `staging/` folder
2. Use absolute path instead of relative
3. Verify file exists: `ls staging/`
### "Permission denied"
**Symptoms**: Server can't read documents
**Solutions**:
1. Check file permissions
2. Ensure the server has read access to staging directory
### Server Crashes
**Debug steps**:
```bash
# Run in HTTP mode to see errors
node document_access_mcp_server.js --mode=http --port=49400
# Check for errors in console output
```
### Config File Not Found
**Windows**: Create folder and file manually:
```
%APPDATA%\Claude\claude_desktop_config.json
```
**macOS**: Create if needed:
```bash
mkdir -p ~/Library/Application\ Support/Claude
touch ~/Library/Application\ Support/Claude/claude_desktop_config.json
```
---
## FAQ
### Q: What documents work best with LODA?
**A**: Documents with clear markdown headings (`#`, `##`, `###`). LODA uses these to understand structure. Plain text without headings will be treated as a single section.
### Q: How does LODA compare to RAG?
**A**: LODA is designed for single-document search, while RAG is for searching across many documents. LODA is much faster (1-5ms vs 200-500ms) but doesn't do semantic similarity - it uses exact term matching with smart relevance scoring.
### Q: Can I search multiple documents at once?
**A**: Currently, each search targets one document. For multi-document search, make separate calls or use a RAG solution.
### Q: Why use a token budget?
**A**: When your conversation is long and Claude is near its context limit, specifying a budget ensures LODA returns concise results that fit in the available context.
### Q: Does LODA modify my documents?
**A**: No. LODA is read-only. It never writes to or modifies your documents.
### Q: How is the token count estimated?
**A**: LODA uses ~4 characters per token, which is optimized for Claude's tokenizer. It's an estimate, not exact, but consistently accurate within 10%.
### Q: Can I use LODA with other LLMs?
**A**: The MCP server works with any MCP-compatible client. The LODA search algorithm itself is LLM-agnostic.
---
## Getting Help
- **GitHub Issues**: [Report bugs or request features](https://github.com/patrickkarle/loda-mcp-server/issues)
- **Documentation**: Check the README.md for technical details
- **Research**: See `warehouse/blueprints/cdp-loda-decomposition/` for design documents
---
## Version History
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2025-11-28 | Initial release with full LODA implementation |
---
**Happy searching!** 🔍
