claude-rag-mcp: Instructions file for Claude Code

CLAUDE.md

Last Updated: 2026-02-02 (v1.0.0 - Initial Release)

Project Overview

Repository: /home/olivier/dev/claude-rag-mcp Branch: main Version: 1.0.0 Purpose: MCP server providing RAG context and failure capture for Claude Code

Architecture

MCP Server (src/mcp/server.ts)
  ↓
┌─────────────────────────────────────────────────────┐
│ Context (RAG)                                        │
│   src/context/ - semantic search, knowledge store   │
│   Providers: memory, chromadb                       │
└─────────────────────────────────────────────────────┘
  ↓
┌─────────────────────────────────────────────────────┐
│ Learning (Capture)                                   │
│   src/learning/ - failure storage (SQLite)          │
│   Types: test, review, quality_gate, timeout, error │
└─────────────────────────────────────────────────────┘

MCP Tools (11 total)

• Context (7): context_status, context_search, context_list, context_get, context_add, context_delete, context_prune
• Learning (4): learning_status, learning_list_failures, learning_get_failure, learning_prune

Technical Stack

• Language: TypeScript 5.7 (strict mode) with NodeNext module resolution
• Module System: ESM ("type": "module")
• Testing: Vitest 4.0 with colocated __tests__/ directories
• MCP: @modelcontextprotocol/sdk 1.0

Key Files

• src/mcp/server.ts - MCP server with 11 tools
• src/mcp/context-tools.ts - 7 RAG tools
• src/mcp/learning-tools.ts - 4 failure capture tools
• src/context/ - Global context module (RAG system)
• src/learning/ - Failure capture service
• src/cli.ts - CLI entry point (serve command)
• src/config/config-loader.ts - YAML config loader

Commands

npm run build          # Compile TypeScript
npm test               # Run all tests
npm run test:watch     # Watch mode
npm run serve          # Start MCP server

Conventions

• ESM with NodeNext module resolution
• Strict TypeScript throughout
• Tests colocated in __tests__/ directories
• Use import { randomUUID } from 'node:crypto' (Node 18+)
• Zod for config validation with safeParse