# Boop MCP–RAG

**Boop MCP–RAG** is a source-independent foundation for a future Retrieval-Augmented Generation (RAG) and Model Context Protocol (MCP) system. It implements stable contracts and a deterministic local reference path without embedding a model provider, source system, credential, database, vector database, remote MCP server, or production identity service.

> The project is deliberately a structural foundation. It is **not** a production RAG service, autonomous agent, API gateway, vector search cluster, or remote tool executor.

## Runtime topology

```text
Consumer / MCP client
        |
        v
ContextRouter
   |                  |
   v                  v
QueryRetriever      MCPHost
   |                  |
   v                  v
ContextDocument     ToolResult
        \            /
         v          v
      ContextPayload
```

The orchestrator sees only normalized contracts. Retrieval storage, session persistence, tool transport, and telemetry export are selected behind interfaces at installation time.

| Boundary | Contract | Local reference adapter | Install-time extension point |
|---|---|---|---|
| Ingestion | `IngestionPipeline` | In-memory deterministic chunking | Document parser, embedding model, indexer |
| Retrieval | `QueryRetriever` | Keyword-overlap ranking | pgvector, Qdrant, hybrid search |
| Session state | `SessionStore` | Process memory | Redis, PostgreSQL |
| Tools | `MCPHost` | In-process Pydantic-validated host | MCP STDIO, HTTP/SSE, gRPC bridge |
| Telemetry | OpenTelemetry API spans | API instrumentation only | OTLP collector/exporter |
| Gateway | Configuration placeholder | None | Authentication, authorization, rate-limit adapters |

## Included behavior

The `ContextRouter` validates a request, retrieves context, discovers registered tools, and executes a tool **only** when the caller explicitly supplies `requested_tool`. It creates a normalized `ContextPayload` containing the user query, retrieved documents, tool definitions, session metadata, and optional tool result.

The reference knowledge adapter is deterministic keyword matching. It is provided to validate contracts and tests, **not** to claim semantic/vector retrieval. The local MCP host validates every tool input with Pydantic before invoking its handler.

## Install and validate

```bash
python3 -m pip install -e .
python3 -m unittest discover -s tests -p "test_*.py" -v
python3 -m compileall -q src tests server.py
boop-mcp-rag status
```

## Local MCP surface

Start the local MCP server:

```bash
mcp run server.py
```

It exposes four local-reference tools:

| Tool | Purpose |
|---|---|
| `rag_status` | Declares installed local adapters and uninstalled extension points. |
| `rag_ingest_text` | Indexes caller-provided text in process memory; it does not fetch external content. |
| `rag_orchestrate` | Retrieves context and optionally invokes an explicitly requested local tool. |
| `rag_list_tools` | Lists transport-neutral tool descriptors. |

## Installation boundary

Copy `config.example.json` and select real adapters only after the target runtime, data sources, access boundary, and operational requirements have been verified. Do not place secrets, service tokens, source dumps, or production connection strings in this repository.