chartviewer/rag-mcp-server-cpp

RAG MCP Server (C++)

Status: ✅ Production Ready | Version: 0.1.0 | Tests: 24/24 Passing

C++ implementation of the RAG MCP Server, converted from Rust for integration with the alan-agent C++ ecosystem.

Quick Status

Ready for production deployment with full MCP support! 🚀

Overview

This is a complete C++ port of the Rust-based RAG (Retrieval-Augmented Generation) MCP server. It provides:

• Document ingestion (PDF, Markdown, Code, Text)
• Semantic chunking and embedding
• Vector similarity search
• MCP (Model Context Protocol) server over stdio
• SQLite-based storage with full-text search
• Built-in prompts for guided usage and best practices

Features

• 100% MCP Protocol Compliant - Full tool discovery and invocation support
• 100% API Compatible with Rust version
• Database Interoperability - Can read/write same SQLite databases as Rust version
• Three MCP Tools:
  • ingest: Process and store documents
  • search_knowledge_chunk: Search for relevant text chunks
  • search_knowledge_chapter: Search for relevant chapters/sections
• MCP Protocol Methods:
  • initialize: Server capability negotiation
  • tools/list: Tool discovery with schemas
  • tools/call: Standardized tool invocation
  • prompts/list: Discover available prompts
  • prompts/get: Retrieve prompt templates and guides
• Built-in Prompts:
  • rag_usage_guide: Comprehensive guide on using all 3 RAG tools with examples, parameters, and best practices

Building

Prerequisites

• CMake 3.20 or later
• C++20 compatible compiler (GCC 10+, Clang 12+, MSVC 2019+)
• vcpkg (optional, for dependency management)

Dependencies

• SQLite3
• nlohmann/json
• yaml-cpp
• OpenSSL
• Google Test (for testing)

Build Instructions

# Configure
cmake -B build -S .

# Build
cmake --build build --config Release

# Test
cd build && ctest --output-on-failure

# Install
cmake --install build --prefix ./install

With vcpkg

cmake -B build -S . -DCMAKE_TOOLCHAIN_FILE=[path-to-vcpkg]/scripts/buildsystems/vcpkg.cmake
cmake --build build --config Release

Configuration

The server uses a YAML configuration file (compatible with Rust version):

storage:
  data_dir: "./data"
  max_chunk_size: 512
  min_chunk_size: 100

chunking:
  overlap_tokens: 50
  semantic_threshold: 0.75

embedding:
  model_name: "sentence-transformers/all-MiniLM-L6-v2"
  dimension: 384

mcp:
  transport: "stdio"

Usage

# Set config file (optional, defaults to rag_config.yaml)
export RAG_CONFIG=path/to/config.yaml

# Run server
./rag-mcp-server-cpp

The server communicates via JSON-RPC 2.0 over stdin/stdout.

MCP Tools

1. Ingest Documents

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "ingest",
    "arguments": {
      "path": "/path/to/document.pdf",
      "doc_type": "pdf"
    }
  },
  "id": 1
}

Supported document types: pdf, markdown, text, code

2. Search Knowledge Chunks

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_knowledge_chunk",
    "arguments": {
      "query": "What are the main features?",
      "top_k": 5
    }
  },
  "id": 2
}

Returns individual text chunks with similarity scores.

3. Search Knowledge Chapters

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_knowledge_chapter",
    "arguments": {
      "query": "Machine learning fundamentals",
      "top_k": 3
    }
  },
  "id": 3
}

Returns grouped chapters/sections with aggregated relevance.

MCP Prompts

List Available Prompts

{
  "jsonrpc": "2.0",
  "method": "prompts/list",
  "params": {},
  "id": 4
}

Returns:

{
  "jsonrpc": "2.0",
  "result": {
    "prompts": [
      {
        "name": "rag_usage_guide",
        "description": "Guide on how to use the RAG (Retrieval Augmented Generation) system tools",
        "arguments": []
      }
    ]
  },
  "id": 4
}

Get RAG Usage Guide

{
  "jsonrpc": "2.0",
  "method": "prompts/get",
  "params": {
    "name": "rag_usage_guide"
  },
  "id": 5
}

Returns a comprehensive guide covering:

• Detailed documentation for all 3 tools (ingest, search_knowledge_chunk, search_knowledge_chapter)
• Parameters, types, and defaults for each tool
• Example JSON usage for each tool
• Use cases and best practices
• Workflow examples
• Tips for optimal results

Architecture

rag-mcp-server-cpp/
├── include/rag/           # Header files
│   ├── config.hpp
│   ├── error.hpp
│   ├── storage/          # Storage layer
│   ├── chunker/          # Document processing
│   ├── search/           # Search algorithms
│   ├── mcp/              # MCP protocol
│   └── graph/            # Graph relationships
├── src/                  # Implementation files
├── test/                 # Unit and integration tests
└── scripts/              # Build and test scripts

Compatibility

This C++ implementation is designed to be 100% compatible with the Rust version:

• Same configuration file format
• Same database schema
• Same JSON-RPC protocol
• Same API responses
• Interoperable databases (can read Rust DB, Rust can read C++ DB)

Testing

All tests passing! See VERIFICATION_RESULTS.md for complete results.

# Comprehensive test suite
./test_suite.sh               # All functional tests

# Verification tests
./scripts/test_embedding_compatibility.sh  # Embedding verification
./scripts/test_database_schema.sh          # Schema compatibility
./scripts/benchmark.sh                     # Performance benchmarks

# Quick demo
./demo.sh                     # Quick demonstration

Test Results:

• ✅ Functional tests: 15/15 passed (100%)
• ✅ MCP protocol tests: 18/18 passed (100%)
• ✅ Embedding tests: 4/4 passed (100%)
• ✅ Schema verification: 5/5 passed (100%)
• ✅ Performance: Excellent (meets all targets)
• ✅ Total: 42/42 tests passing

Performance

Verified Performance (Actual):

• Ingestion: ~1,833 chunks/second
• Search: ~6ms average query time (166 queries/second)
• Storage: ~5.45KB per chunk
• Startup: < 1 second

Target: Within 20% of Rust version Result: ✅ Excellent performance, meets all targets

See VERIFICATION_RESULTS.md for detailed benchmark results.

License

[Add license information]

Contributing

[Add contribution guidelines]

Conversion Notes

This is a direct conversion from Rust to C++, maintaining:

• Exact same chunking algorithm
• Identical embedding generation (deterministic)
• Byte-compatible database format
• Identical JSON-RPC responses

See the conversion documentation in the rag-mcp-server directory for detailed specifications.