Skip to content

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:

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:

# 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:

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:

## 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:

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:

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.