# MCP Local RAG - Maintenance Guide

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

## Repository Tracking

| Repository | Bootstrap Date | Last Updated | Status | Notes |
|  --- | --- | --- | --- | --- |
| finix-docs-redocly | 2026-02-02 | 2026-02-02 | Active | Documentation source repo |


**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/)

1. **BOOTSTRAP_EXAMPLE.md**
  - Shows complete bootstrap process
  - Useful for onboarding
  - Generic example
2. **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


```bash
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**:


```bash
# 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


```bash
# 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


```bash
# 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


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

| Item | Detection Method | Confidence |
|  --- | --- | --- |
| Repository name | Working directory basename | 100% |
| Main modules | `ls -la` + heuristics | 95% |
| Programming language | Build files (build.gradle, package.json, etc.) | 95% |
| Build tool | Build files presence | 95% |
| Framework | Annotations, imports | 90% |
| Purpose | README.md extraction | 80% |
| Documentation type | File patterns, directory names | 70% |
| Package structure | `find` + directory analysis | 90% |
| Key classes | File listing + grep | 85% |
| Configuration | Config file detection | 90% |


**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

| Version | Date | Changes | Repositories Updated |
|  --- | --- | --- | --- |
| 1.0 | 2026-02-02 | Initial release | finix-docs-redocly |


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