Banking RAG MCP Server!

Cloud-ready MCP server for retrieving banking document evidence from Supabase pgvector. It uses Gemini embeddings and does not generate RCA conclusions. It also supports explicit single-file ingestion from GitHub.

Verified embedding contract

The official Gemini embeddings documentation lists gemini-embedding-2 as stable. It supports configurable 768, 1536, or 3072 dimensions. This project explicitly uses 1536 dimensions for both query and document embeddings. EMBEDDING_DIMENSION is validated accordingly, and the SQL migration uses vector(1536). Existing vectors must be re-embedded when changing models because embedding spaces are incompatible.

Related MCP server: MCP Knowledge Base Server

Setup

npm install
copy .env.example .env
npm run build
npm test

Fill .env with real credentials, apply supabase/migrations/001_banking_rag.sql, then run:

npm start
curl http://localhost:3000/health
npm run test:integration

test:integration generates a real Gemini embedding, checks Supabase connectivity, and performs a real vector search. With an empty database it reports zero results and never fabricates evidence.

Deployment

Configure these environment variables in the deployment platform's service settings before using /mcp:

SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key
GEMINI_API_KEY=your-gemini-api-key

The server binds to 0.0.0.0 and uses the platform-provided PORT value. It can start without secrets so platform health checks succeed; /mcp returns 503 and identifies the missing variables until the service is configured.

Apply supabase/migrations/002_retrieval_filters.sql after the original migration before using document-type filters or exact requirement lookup. It preserves the 0.70 similarity threshold and cosine/HNSW retrieval, adds server-side BRD/RCA filtering, and adds the exact get_requirement_chunks RPC.

Apply supabase/migrations/003_uat_observations.sql for UAT ingestion. It creates dedicated uat_observations and uat_observation_evaluations tables; UAT rows remain structured and are not embedded into the BRD/RCA vector index.

GitHub ingestion

Add these variables to .env:

GITHUB_TOKEN=your-github-token
GITHUB_OWNER=your-github-owner
GITHUB_REPO=your-github-repository
GITHUB_BRANCH=main
EXPECTED_GITHUB_PATH=documents/BRD/transaction-reference.md

Index one Markdown file:

npm run ingest -- documents/BRD/transaction-reference.md

The command fetches the file through GitHub's Contents API, detects BRD or RCA, computes a SHA-256 content hash, creates Markdown-aware chunks, generates one 1536-dimensional Gemini embedding per chunk, upserts the document, replaces old chunks when content changes, and verifies the stored chunk count and vector dimensions. Running it again with unchanged content skips duplicate insertion.

To verify semantic retrieval against the indexed source, set EXPECTED_GITHUB_PATH and run:

npm run test:integration

GitHub Webhook

POST /webhook/github automatically re-indexes changed Markdown documents and ingests changed UAT workbooks from the configured GitHub documentation repository. It verifies the GitHub HMAC SHA-256 signature, repository, and branch before calling the existing ingestion pipeline.

Required variables:

GITHUB_WEBHOOK_SECRET=your-github-webhook-secret
GITHUB_OWNER=your-github-owner
GITHUB_REPO=your-github-repository
GITHUB_BRANCH=main

Supported: documents/**/*.md under documents/BRD/ or documents/RCA/, plus .xlsx workbooks under documents/UAT/.

Store QA workbooks using a predictable path such as documents/UAT/2026/login/UAT_Observation_Report_TC-LOGIN-001.xlsx. The workbook parser discovers sheets and header rows, skips blank rows, validates observation ID/expected behavior/actual behavior, preserves sheet and source row metadata, and stores historical outcome columns separately as evaluation metadata. Repeated unchanged rows are skipped; changed rows are updated by source path and observation ID.

Ignored for now: .csv, .docx, and .pdf. Removed files are reported as deletion_not_supported because the current Supabase layer does not provide safe deletion.

MCP

The Streamable HTTP endpoint is POST /mcp. It exposes exactly three business-facing tools:

• search_banking_knowledge: semantic evidence search with query, optional topK (1-10), and optional documentType (BRD or RCA).

• get_banking_requirement: exact lookup by requirementId, using the Supabase requirement RPC.

• search_previous_rca: semantic RCA-only search with query and optional topK (1-10).

Responses contain grounded evidence only. API keys, the service-role key, and the GitHub token are never included in MCP responses or ingestion logs. test:mcp independently starts the server and verifies health, tool discovery, all three tools, filtering, missing requirements, and invalid inputs over Streamable HTTP.

MCP Integration

Endpoint: POST /mcp

Health: GET /health

The server binds to 0.0.0.0 with the configurable PORT value and can be consumed by an external MCP client using Streamable HTTP. Clients should send an MCP initialize request, call tools/list, then invoke only the three business tools above. The MCP layer returns grounded retrieval evidence and does not generate RCA conclusions.

Retrieval evaluation

After indexing the test BRD/RCA documents and applying migration 002, run:

npm run test:evaluation

The suite runs eight realistic queries, applies document-type filters, reports actual Supabase similarity scores, and verifies TRX-REF-001 plus a clean not-found result for NONEXISTENT-999.

Next steps

Automatic webhooks, scheduled synchronization, bulk repository indexing, Multica Cloud integration, remote MCP authentication, cloud deployment, and final RCA generation remain out of scope. The current ingestion command intentionally indexes one explicit Markdown path at a time.