Skip to main content
Glama
README.md
# RBI Regulatory Model Context Protocol (rbi-doc-mcp)

[![CI Test Suite](https://github.com/imsovikde/rbi-doc-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/imsovikde/rbi-doc-mcp/actions/workflows/ci.yml)
[![MCP Integrity & Edge Parity Audit](https://github.com/imsovikde/rbi-doc-mcp/actions/workflows/mcp_integrity.yml/badge.svg)](https://github.com/imsovikde/rbi-doc-mcp/actions/workflows/mcp_integrity.yml)
[![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
[![Node: 22](https://img.shields.io/badge/Node-22-green.svg)](package.json)
[![Cloudflare Workers](https://img.shields.io/badge/Cloudflare-Workers-orange.svg)](cloudflare.config.ts)
[![MCP Version: 2024-11-05](https://img.shields.io/badge/MCP-2024--11--05-purple.svg)](src/index.ts)

Model Context Protocol (MCP) server providing access to the Reserve Bank of India (RBI) Regulatory Archive (1991 to 2026). The server allows language models and developer applications to search, retrieve, verify, and cite Indian central banking regulations.

- Canonical MCP Endpoint: `https://rbi-doc-mcp.imsovikde.workers.dev/mcp`
- Root URL (`/`): Reserved for future portal homepage.
- Upstream Document Repository: [imsovikde/rbi-regulatory-archive-1991-2026](https://github.com/imsovikde/rbi-regulatory-archive-1991-2026)
- Upstream Dataset Vault: [Hugging Face Dataset (88,236 Documents)](https://huggingface.co/datasets/imsovikde/rbi-regulatory-archive-1991-2026)

---

## Capabilities

The server operates two complementary planes:

### Plane 1: Cloudflare Code Mode
- `rbi_doc_search_api`: Discovers methods and types in the virtual SDK with a payload footprint under 600 tokens (constrained to <900 tokens).
- `rbi_doc_execute_code`: Executes sandboxed JavaScript inside edge nodes to filter, join, and aggregate regulatory records in a single network round-trip.

### Plane 2: Canonical MCP Tools
- `resolve_rbi_doc`: Resolves circular identifiers, notification numbers, numeric IDs (`?Id=13143`), and title fragments.
- `search_rbi_regulations`: Fast full-text search using SQLite FTS5 with department, year, entity, and statutory filters.
- `fetch_rbi_markdown`: Downloads the markdown source text of any regulation with optional section extraction.
- `trace_statutory_consequences`: Traverses the causal amendment graph, parent Master Directions, and Section 47A penalty records.
- `verify_circular_validity`: Evaluates whether a regulation was in force on a given calendar date, returning `ACTIVE`, `SUPERSEDED`, or `REPEALED`.
- `format_court_citation`: Generates Indian court citations with SHA-256 verification hashes for legal filings.

---

## Quickstart

### Claude Code CLI (Instant Public Access)

Connect without authentication under the public rate limit (60 requests/minute):

```bash
claude mcp add rbi-doc-mcp https://rbi-doc-mcp.imsovikde.workers.dev/mcp
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "rbi-doc-mcp": {
      "command": "npx",
      "args": ["-y", "rbi-doc-mcp"],
      "env": {
        "RBI_DOC_MCP_URL": "https://rbi-doc-mcp.imsovikde.workers.dev/mcp"
      }
    }
  }
}
```

### Cursor IDE

Add to `.cursor/mcp.json` in your workspace root:

```json
{
  "mcpServers": {
    "rbi-doc-mcp": {
      "command": "npx",
      "args": ["-y", "rbi-doc-mcp"],
      "env": {
        "RBI_DOC_MCP_URL": "https://rbi-doc-mcp.imsovikde.workers.dev/mcp"
      }
    }
  }
}
```

### Python Direct Client

```python
import json
import urllib.request

payload = {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
        "name": "verify_circular_validity",
        "arguments": {"doc_id": "13143", "as_of_date": "2026-11-15"}
    }
}

req = urllib.request.Request(
    "https://rbi-doc-mcp.imsovikde.workers.dev/mcp",
    data=json.dumps(payload).encode("utf-8"),
    headers={"Content-Type": "application/json", "User-Agent": "rbi-client/1.0"}
)

with urllib.request.urlopen(req) as resp:
    data = json.loads(resp.read().decode("utf-8"))
    print(data["result"]["content"][0]["text"])
```

---

## Architecture and Formal Invariants

The server relies on the libRbiKernel Computational Kernel, a deterministic mathematical framework ensuring sub-50ms lookups and causal consistency:

1. Perfect Minimal Hash Arena (CHD): Resolves 88,236 keys with 0 collisions and $O(1)$ time complexity using prime modulus $n = 88,237$.
2. Elias-Fano Bitvectors: Stores document states in a 22.0 KB quasisuccinct structure with $O(1)$ broadword `select1`.
3. Nilpotent Causal DAG: Models regulatory amendments with strictly lower-triangular adjacency matrix where $A^3 = 0$. Resolves transitive dependencies via finite Neumann series $(I - A)^{-1} = I + A + A^2$.
4. Content-Defined Chunking: Splits markdown files using a 64-bit Gear rolling hash with Poisson-distributed boundaries ($[4 \text{ KB}, 64 \text{ KB}]$ window).
5. BM25F Search Router: Modulates keyword relevance by point-in-time regulatory validity factor $0.2 + 0.8 v_D(T)$.
6. Token Bucket Rate Limiting: Enforces continuous refill rates across public, authenticated, and zero-trust enterprise tiers.

Read the complete mathematical proofs and derivations in the [libRbiKernel Mathematical Architecture Document](docs/MATHEMATICAL_KERNEL_ARCHITECTURE.md).

---

## Documentation

- [Complete Setup and Integration Guide](docs/COMPLETE_SETUP_GUIDE.md): Covers zero-setup public usage, Claude Code, OAuth 2.1 PKCE login flow, Cloudflare Access Service Tokens, and client backoff logic.
- [libRbiKernel Mathematical Architecture and Invariants](docs/MATHEMATICAL_KERNEL_ARCHITECTURE.md): Exhaustive public derivation of all algorithms, formulas, byte structures, and proofs.
- [Full-Stack Verification Report](docs/EXECUTION_AND_MATHEMATICAL_VERIFICATION_REPORT.md): Empirical test logs, live latencies, and component inventory.

---

## Local Development and Testing

```bash
# Install dependencies
npm ci

# Run unit test suite
npm test

# Run live edge verification against production endpoint
python test/live_backtest.py

# Build project with Cloudflare CLI
cf build

# Deploy to Cloudflare edge
cf deploy
```

---

## Repository Structure

```
rbi-doc-mcp/
├── .github/
│   ├── workflows/
│   │   ├── ci.yml                 # Node 22 test suite and live edge audit
│   │   └── deploy.yml             # Cloudflare worker deployment workflow
│   ├── ISSUE_TEMPLATE/            # Bug report and feature request templates
│   ├── PULL_REQUEST_TEMPLATE.md   # Pull request checklist
│   ├── CODEOWNERS                 # Code ownership declarations
│   └── dependabot.yml             # Automated dependency updates
├── docs/
│   ├── COMPLETE_SETUP_GUIDE.md    # Exhaustive setup and authentication guide
│   └── MATHEMATICAL_KERNEL_ARCHITECTURE.md # Public mathematical proofs and formulas
├── src/
│   ├── index.ts                   # Edge router (/mcp, /health, / schema)
│   ├── auth.ts                    # Four-tier token bucket rate limiter
│   ├── code_mode.ts               # Plane 1 dynamic discovery and sandbox engine
│   ├── db.ts                      # Cloudflare D1 query abstractions
│   ├── mcp_tools.ts               # Plane 2 canonical MCP tool handlers
│   ├── r2_corpus.ts               # Cloudflare R2 binary index reader
│   └── types.ts                   # TypeScript interfaces
├── test/
│   ├── auth.test.ts               # Authentication and rate limiting tests
│   ├── code_mode.test.ts          # Code mode budget and execution tests
│   ├── mcp_tools.test.ts          # Tool validation and citation format tests
│   └── live_backtest.py           # Live edge verification suite
├── cloudflare.config.ts           # Cloudflare CLI configuration
├── package.json                   # Package manifest
└── wrangler.json                  # Wrangler fallback configuration
```

---

## License

Apache License 2.0. Copyright 2026 Souvik Dey (imsovikde).