Skip to main content
Glama

mcp-rag-showcase

One retrieval contract. Two MCP servers — C# and Python. Same answers, proven by a test.

A minimal, fully free reference implementation of a RAG tool surface over the Model Context Protocol, written twice against one frozen spec and one shared corpus. No API keys, no model downloads, no vector database, no cloud spend.

CI .NET Python MCP License

What it proves

Claim

How you check it

The tool contract is language-agnostic

Three tools, implemented independently in C# and Python

Retrieval is reproducible

BM25 with frozen constants, no model, no randomness

Both implementations agree

parity_runner.py replays 10 golden queries and compares docId sequences

It runs in a container

compose.yaml, smoke-tested in CI over MCP

It costs nothing

No secret, no paid dependency; Render free tier

Related MCP server: neonrecall

Quick start

git clone https://github.com/Steinantonio/mcp-rag-showcase.git
cd mcp-rag-showcase

./scripts/bootstrap.ps1   # .venv + pip + dotnet restore
./scripts/test.ps1        # 72 pytest + 26 xunit + 10/10 parity
./scripts/serve.ps1       # Python on :8080 (REST + MCP)

Both services, side by side over MCP:

./scripts/up.ps1          # docker compose up, both containers
./scripts/smoke.ps1       # same query, both servers, citations compared

Surfaces

Surface

Python

.NET

MCP (streamable HTTP)

:8080/mcp

:8081/mcp

REST + OpenAPI

:8080/docs

—

Health

:8080/health

:8081/health

Tools in both: search(query, k), get_document(docId), answer(query, k). Answers are extractive — source sentences with citations, no generator model.

Real output

$ ./scripts/smoke.ps1
query: restore a database backup
  python  ops-backups#00  ops-data-retention#01  ops-faq#01
  dotnet  ops-backups#00  ops-data-retention#01  ops-faq#01
  MATCH

5/5 queries matched

Full transcript: docs/demo.md.

Repository map

corpus/                 15 authored docs + 10 golden queries (frozen)
src/mcp_rag_py/         core/ (pure) · adapters/ (REST, MCP, filesystem) · apps/
src/Mcp.Rag.Dotnet/     Core/ (tokenizer, chunker, BM25, engine) · Adapters/
tests/                  unit · conformance · integration · arch · fixtures
specs/ agents/          spec-driven delivery and the six agent roles
docs/                   concepts · tool contract · ADRs · demo · deploy · OpenAPI
infra/                  Dockerfile x2 · main.bicep (validated, never deployed)

Design decisions

ADR

Decision

0001

BM25 and extractive answers instead of embeddings + LLM

0002

Freeze the spec; prove parity with hand-derived vectors

0003

MCP + REST facade; one free service

0004

Ports and adapters with a pure core

Architecture in four analogies: docs/concepts.md.

Honest limitations

  • Lexical retrieval only. No synonyms, no paraphrase. "how long do we keep backups" ranks a monitoring document first because of shared words — measured, documented, not hidden.

  • Extractive answers. Stitched quotes, not prose.

  • 15 documents. Demonstrates the shape of a pipeline, not retrieval quality.

  • Cold start. The deployed free instance sleeps after 15 idle minutes and takes ~1 minute to wake.

  • No auth. The corpus is authored for this repo and is public on purpose.

Docs

Concepts · Tool contract · Demo · Deploy · Methodology · Build plan · OpenAPI

License

MIT — see LICENSE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP clients to connect document sources, prepare searchable documents, and run RAG-ready lexical, vector, or hybrid search with account-scoped document access.
      31 PyPI
      BSD 3-Clause
    • A
      license
      A
      quality
      C
      maintenance
      Enables MCP clients to search and retrieve approved, role-filtered internal knowledge with PII redaction, citations, content-integrity checks, and tamper-evident audit logging.
      3
      1
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to query a document knowledge base with permission-aware hybrid retrieval, listing sources, searching snippets, and fetching document context while reporting confidence for each result.
      3
      Apache 2.0