# MCP Local RAG - Standard Documentation Access Rules

**This is the canonical standard for accessing documentation via MCP Local RAG.**

Every repository context file should reference this document rather than duplicating these rules.

## CRITICAL RULES - READ THIS FIRST

### Rule #1: NEVER Read Documentation Files Directly

**NEVER EVER use the Read tool on documentation files (PDF, DOCX, etc.)**

If you find yourself about to use Read tool on a file in `mcp-docs/`, **STOP** and follow this workflow instead:

1. Check if MCP is configured: `cat ~/.claude.json | grep "local-rag"`
2. If NOT configured → Run `cd mcp-docs/claude-code && ./setup.sh` and tell user to restart
3. If configured → Use `mcp__local-rag__query_documents` instead


### Rule #2: Check MCP Configuration FIRST

**BEFORE attempting to answer questions about specifications/documentation:**


```bash
cat ~/.claude.json | grep "local-rag"
```

If this returns empty, run setup automatically (see Step 5 below).

## Configuration Variables

Each repository's root `CLAUDE_CONTEXT.md` defines these variables:

- **`{{REPO_ROOT}}`**: Absolute path to repository root (e.g., `/Users/username/repos/my-repo`)
- **`{{DOCS_DIR}}`**: Relative path to documentation directory from repo root (e.g., `mcp-docs/`)
- **`{{DOC_TYPE}}`**: Type of documentation (e.g., "API specifications", "Technical manuals")
- **`{{SETUP_SCRIPT}}`**: Path to setup script (typically `mcp-docs/claude-code/setup.sh`)
- **`{{MCP_EXTERNAL_PATH}}`**: (Optional) External documentation path if docs are stored outside the repository


**Example substitution**:


```
When docs say: {{REPO_ROOT}}/{{DOCS_DIR}}/filename.pdf
You use: /Users/username/repos/my-repo/mcp-docs/filename.pdf
```

## CRITICAL RULE: Never Read Documentation Files Directly

**NEVER** use the Read tool on documentation files (PDF, DOCX, etc.). **ALWAYS** use MCP Local RAG tools instead.

❌ **WRONG**:


```
Read tool: /path/to/documentation.pdf
Read tool: /path/to/specification.docx
```

✅ **CORRECT**:


```
mcp__local-rag__query_documents: "query about specific topic"
```

**Why?**

- Binary files (PDF, DOCX) - Read tool cannot parse them properly
- Text files (TXT, MD, HTML) - MCP Local RAG provides better semantic search
- MCP Local RAG provides semantic search across all ingested documentation
- Query results are context-aware and return relevant excerpts
- Ingestion preprocesses files into searchable chunks with embeddings


## Standard Workflow: Accessing Documentation

### Step 1: Check if MCP is Configured

Before attempting to access documentation, verify MCP Local RAG is set up:


```bash
# Check if MCP server is configured
cat ~/.claude.json | grep "local-rag"
```

If not configured, proceed to Step 5 (Setup).

### Step 2: Evaluate If Documentation is Needed

Ask yourself:

- Does the user's question require authoritative {{DOC_TYPE}} information?
- Is this information likely to be in the documentation (not in code)?
- Can I answer from code/context alone?


**Examples that need documentation:**

- "What are the field definitions for [specific format]?"
- "What are the requirements for [specific specification]?"
- "Explain the [technical standard] implementation"


**Examples that don't need documentation:**

- "How does this function work?" (read the code)
- "What's the bug in this code?" (analyze the code)
- "Refactor this module" (pure code task)


### Step 3: Query the Documentation

Use `mcp__local-rag__query_documents` with a specific, well-formed query:


```
mcp__local-rag__query_documents(
  query: "specific topic or question",
  limit: 10  # Adjust based on expected result size: 5 for precision, 10 for balance, 20 for broad exploration
)
```

**Query Best Practices:**

- Be specific: "record format fields" not "file format"
- Include relevant identifiers: "authentication flow requirements"
- Use technical terms from the domain
- If results are poor, try alternate phrasing


**Interpreting Results:**

- **score < 0.3**: Highly relevant, use with confidence
- **score 0.3-0.5**: Moderately relevant, verify context
- **score > 0.5**: Low relevance, may not be useful
- **No results**: Documentation may not cover this topic, or it's not ingested yet


### Step 4: If Documentation is Missing

If you get no relevant results (or user reports documentation is missing):

**A. Check what's currently ingested**:


```
mcp__local-rag__list_files
```

**B. Check what documentation exists in the repository**:


```bash
find {{DOCS_DIR}} -type f \( -name "*.pdf" -o -name "*.docx" -o -name "*.txt" -o -name "*.md" -o -name "*.html" \) -not -path "*/claude-code/*"
```

**C. If documentation exists but isn't ingested**:

**Automatic ingestion** (proactive):


```
mcp__local-rag__ingest_file(
  filePath: "{{REPO_ROOT}}/{{DOCS_DIR}}/filename.pdf"
)
```

**Note**: Always use **absolute paths** for ingestion. Construct them as:


```
{{REPO_ROOT}}/{{DOCS_DIR}}/filename.ext
```

**Supported formats**: PDF, DOCX, TXT, Markdown (.md), HTML

**D. Ask user for module mapping**:
After ingesting, ask: "I've ingested [filename]. Which module(s) or code sections is this documentation relevant to?"

**E. Update module context(s)**:
Add an "External Documentation" section to relevant module `CLAUDE_CONTEXT.md` files:


```markdown
## External Documentation

> **Documentation Access**: See `mcp-docs/claude-code/MCP_STANDARD_RULES.md` for complete MCP workflow

**Available [topic] specifications** (listed for auto-ingestion):
- **[filename-without-extension]**: [Brief description of contents]

**Query examples:**
- "[Example query relevant to this module]"
- "[Another example query]"
```

**F. If documentation doesn't exist at all**:
Inform the user that the documentation needs to be added to `{{DOCS_DIR}}/` before it can be used.

### Step 5: Initial Setup (if MCP not configured)

If MCP Local RAG is not configured, **AUTOMATICALLY run the setup**:

**A. Inform the user and run setup**:
Tell the user: "MCP Local RAG is not configured. I'll run the setup script now."

Then run:


```bash
cd {{REPO_ROOT}}/mcp-docs/claude-code && ./setup.sh
```

**B. After setup completes, instruct the user**:
"Setup is complete! Please restart Claude Code completely (exit and relaunch) for the MCP server configuration to take effect. After restarting, ask your question again and I'll be able to query the documentation."

**C. DO NOT attempt to query documentation** until after restart - it will not work.

## Error Handling

### Error: "MCP server not found"

**Solution**: Run setup script and restart Claude Code (Step 5 above)

### Error: "File not found" during ingestion

**Solution**: Verify file path is absolute and file exists:


```bash
ls -la {{REPO_ROOT}}/{{DOCS_DIR}}/filename.pdf
```

### Error: "No results found" with high confidence query

**Solution**:

1. Check if file is ingested: `mcp__local-rag__list_files`
2. Try alternate query phrasing
3. Verify documentation actually contains the information


### Error: Low quality results (high scores)

**Solution**:

1. Refine query to be more specific
2. Check if correct documentation is ingested
3. May indicate information isn't in documentation


## Best Practices

### Query Formulation

- Start broad, then narrow: "authentication" → "OAuth token validation flow"
- Include context: "error code 400 handling for API requests"
- Use exact terminology from the domain
- Reference specific sections if known: "section 4.2 authentication flows"


### Result Interpretation

- Always check the `score` field
- Cross-reference multiple results for confirmation
- If unsure, query again with refined terms
- Don't assume low-score results are correct


### Ingestion Strategy

- Ingest documentation proactively when detected (don't wait for user request)
- Update module contexts after ingesting to create self-documenting system
- Re-ingest if documentation is updated (use same filePath to replace)
- Keep ingested documentation in sync with repository files


### Context Management

- Only mention documentation access in module contexts where it's truly needed
- Use the standard "External Documentation" format for consistency
- List 2-4 relevant query examples specific to each module
- Reference this file rather than duplicating rules


## Troubleshooting Decision Tree


```
User asks a question
    ├─ Can be answered from code? → Read code, answer directly
    │
    ├─ Requires {{DOC_TYPE}} info?
    │   ├─ MCP configured? (check ~/.claude.json)
    │   │   ├─ No → Run setup automatically (Step 5), then tell user to restart
    │   │   └─ Yes → Continue
    │   │
    │   ├─ Query documentation (Step 3)
    │   │   ├─ Good results (score < 0.3)? → Use results
    │   │   └─ No results / poor results?
    │   │       ├─ Check what's ingested (list_files)
    │   │       ├─ Check what exists (find files)
    │   │       ├─ Ingest if needed (Step 4)
    │   │       └─ Query again
    │   │
    │   └─ Documentation missing entirely? → Inform user
    │
    └─ General question? → Answer normally
```

## Summary

**Key Points**:

1. **Never Read files directly** - always use MCP Local RAG tools
2. **Check MCP setup first** - verify `~/.claude.json` has local-rag server
3. **Auto-run setup if missing** - run `setup.sh` automatically, then tell user to restart
4. **Query before ingesting** - documentation might already be loaded
5. **Use absolute paths** - construct as `{{REPO_ROOT}}/{{DOCS_DIR}}/filename.pdf`
6. **Interpret scores** - < 0.3 is good, > 0.5 is questionable
7. **Update module contexts** - create self-documenting system by adding External Documentation sections
8. **Be proactive** - detect new files and ingest automatically, then ask user for module mapping
9. **Reference this file** - don't duplicate these rules in module contexts


**When in doubt**: Query first, ingest if needed, setup if missing.