MCP Local RAG - Maintenance Guide

Copy

• Copy for LLM

  Copy page as Markdown for LLMs
• View as Markdown

  Open this page as Markdown
• Open in ChatGPT

  Get insights from ChatGPT
• Open in Claude

  Get insights from Claude
• Connect to Cursor

  Install MCP server on Cursor
• Connect to VS Code

  Install MCP server on VS Code

Purpose: This document tracks the deployment and maintenance of the MCP Local RAG standard across repositories.

Repository Tracking

Status Key:

• Active: Fully configured and in use
• In Progress: Being set up
• Outdated: Needs update from canonical source
• Deprecated: No longer maintained

Standard Files

All repositories using MCP Local RAG should have these files:

Required Files (mcp-docs/claude-code/)

1. MCP_STANDARD_RULES.md

   • Universal MCP workflow documentation
   • Referenced by all context files
   • Should be identical across all repos

2. ROOT_CONTEXT_TEMPLATE.md

   • Template for repository root CLAUDE_CONTEXT.md
   • Contains bootstrap instructions
   • Generic with auto-detection logic

3. CLAUDE_CONTEXT_TEMPLATE.md

   • Template for module-specific contexts
   • Auto-detection instructions
   • Generic across all codebases

4. setup.sh

   • Generic MCP Local RAG setup script
   • Installs Node.js, mcp-local-rag
   • Configures ~/.claude.json

5. ingest-docs.sh

   • Helper for generating ingestion commands
   • Generic across all repos

Optional Files (mcp-docs/claude-code/)

6. BOOTSTRAP_EXAMPLE.md

   • Shows complete bootstrap process
   • Useful for onboarding
   • Generic example

7. MCP_MAINTENANCE.md (this file)

   • Tracks standard deployment
   • Update propagation workflow
   • Can be customized per organization

Update Propagation Workflow

When standards are updated in your canonical source repository:

1. Identify Changes

cd canonical-source-repo/mcp-docs/claude-code
git log --since="YYYY-MM-DD" -- .

Review what changed in:

• MCP_STANDARD_RULES.md
• Templates (ROOT_CONTEXT_TEMPLATE.md, CLAUDE_CONTEXT_TEMPLATE.md)
• Scripts (setup.sh, ingest-docs.sh)

2. Determine Impact

Types of changes:

• Critical (propagate immediately):

  • MCP workflow changes
  • Security fixes in setup scripts
  • Breaking changes in templates

• Enhancement (propagate when convenient):

  • Documentation improvements
  • New optional features
  • Example updates

• Repository-specific (do not propagate):

  • Customizations in CLAUDE_CONTEXT.md files
  • Repository-specific documentation

3. Propagate Updates

For each target repository:

# Option A: Copy updated files directly
cd target-repo
cp ~/canonical-source-repo/mcp-docs/claude-code/MCP_STANDARD_RULES.md \
   mcp-docs/claude-code/MCP_STANDARD_RULES.md

# Option B: Use the bootstrap package
# (If major version update or full refresh needed)
cp ~/canonical-source-repo/MCP_BOOTSTRAP_PACKAGE.md .
# Then in Claude Code: "Please extract all files from MCP_BOOTSTRAP_PACKAGE.md"

4. Verify After Update

# Check file existence
ls -la mcp-docs/claude-code/

# Verify MCP configuration
cat ~/.claude.json | grep "local-rag"

# Test a documentation query
# (In Claude Code): "Query the documentation for [topic]"

5. Update Tracking

Update the "Repository Tracking" table above with:

• Last Updated date
• Status
• Any issues encountered

New Repository Setup

When adding MCP Local RAG to a new repository:

Step 1: Copy Bootstrap Package

# Copy to new repo root
cp ~/canonical-source-repo/MCP_BOOTSTRAP_PACKAGE.md /path/to/new-repo/
cd /path/to/new-repo

Step 2: (Optional) Add Documentation

# Add your documentation files
mkdir -p mcp-docs
cp /path/to/docs/* mcp-docs/
# Supports: PDF, DOCX, TXT, Markdown, HTML

Step 3: Bootstrap

In Claude Code:

Please bootstrap from MCP_BOOTSTRAP_PACKAGE.md

Claude will:

• Extract all 7 files
• Run setup.sh
• Auto-detect repository structure
• Create root CLAUDE_CONTEXT.md
• Create 3-5 module contexts
• Ingest documentation files
• Report completion

Step 4: Restart and Verify

1. Restart Claude Code
2. Test documentation query
3. Verify contexts are correct
4. Update tracking table in this file

Customization Guidelines

What to Customize

Per-Repository (in CLAUDE_CONTEXT.md files):

• Repository name and purpose
• Module structure
• Technology stack
• Documentation type ({{DOC_TYPE}})
• Specific documentation files

Per-Organization (in MCP_MAINTENANCE.md):

• Repository tracking table
• Organization-specific workflows
• Custom deployment procedures

What NOT to Customize

Keep Generic (in templates and rules):

• MCP_STANDARD_RULES.md (universal workflow)
• ROOT_CONTEXT_TEMPLATE.md (auto-detection logic)
• CLAUDE_CONTEXT_TEMPLATE.md (module template)
• setup.sh (generic setup script)
• ingest-docs.sh (generic helper)

Reason: These files should remain identical across repos for consistent behavior.

Auto-Detection Capabilities

The bootstrap system can auto-detect:

Items that may need user input:

• Purpose (if no README)
• Documentation type (if ambiguous from filenames)
• Complex processing flows
• Non-standard build processes

Troubleshooting

Issue: MCP Server Not Found

Symptoms: "MCP server not found" error in Claude Code

Solution:

1. Check ~/.claude.json has local-rag configuration
2. Verify mcp-local-rag is installed: npm list -g mcp-local-rag
3. Re-run setup: cd mcp-docs && ./claude-code/setup.sh
4. Restart Claude Code

Issue: Documentation Queries Return No Results

Symptoms: mcp__local-rag__query_documents returns empty results

Solution:

1. Check if files are ingested: mcp__local-rag__list_files
2. If not ingested, ingest files: mcp__local-rag__ingest_file("/absolute/path/to/file.pdf")
3. Verify documentation files exist: ls -la mcp-docs/
4. Try alternate query phrasing

Issue: Bootstrap Creates Wrong Module Contexts

Symptoms: Claude creates contexts for wrong directories

Solution:

1. Delete incorrect contexts
2. Update exclusion list in ROOT_CONTEXT_TEMPLATE.md
3. Re-run bootstrap
4. Or manually specify modules: "Create context for api/ module only"

Issue: Template Placeholders Not Replaced

Symptoms: Final CLAUDE_CONTEXT.md contains {{PLACEHOLDER}} text

Solution:

1. This indicates auto-detection failed
2. Manually edit the file to fill in placeholders
3. Report the detection failure for template improvement

Version History

Contact

For questions or issues with the MCP Local RAG standard:

• Documentation: See MCP_STANDARD_RULES.md
• Issues: Report via repository issues
• Updates: Pull from canonical source repository