Metadata-Version: 2.4
Name: meridian-mcp
Version: 0.5.2
Summary: Meridian — Local-first AI compliance scanner. DPDPA 2023 · RBI FREE-AI · SEBI AI/ML · EU AI Act. Works with any LLM provider. AST-level code analysis across Python, TypeScript, Go, Java.
Project-URL: Homepage, https://meridiancompliance.framer.website
Project-URL: Repository, https://github.com/KNambiarDJsc/Meridian
Project-URL: Issues, https://github.com/KNambiarDJsc/Meridian/issues
License: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: fastmcp>=2.0
Requires-Dist: jinja2>=3.1
Requires-Dist: litellm>=1.40
Requires-Dist: pydantic>=2.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich-argparse>=1.4.0
Requires-Dist: tenacity>=8.0
Requires-Dist: tree-sitter-go>=0.23
Requires-Dist: tree-sitter-java>=0.23
Requires-Dist: tree-sitter-javascript>=0.23
Requires-Dist: tree-sitter-python>=0.23
Requires-Dist: tree-sitter-typescript>=0.23
Requires-Dist: tree-sitter>=0.23
Provides-Extra: all-providers
Requires-Dist: anthropic>=0.40; extra == 'all-providers'
Requires-Dist: boto3>=1.34; extra == 'all-providers'
Requires-Dist: groq>=0.9; extra == 'all-providers'
Requires-Dist: openai>=1.40; extra == 'all-providers'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40; extra == 'anthropic'
Provides-Extra: bedrock
Requires-Dist: boto3>=1.34; extra == 'bedrock'
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: groq
Requires-Dist: groq>=0.9; extra == 'groq'
Provides-Extra: openai
Requires-Dist: openai>=1.40; extra == 'openai'
Provides-Extra: pdf
Requires-Dist: playwright>=1.40; extra == 'pdf'
Description-Content-Type: text/markdown

<p align="center">
  <img src=".github/brand/logo-full.svg" alt="Meridian — AI Compliance Intelligence" width="720">
</p>

# Meridian

**Local-first AI compliance scanner via Model Context Protocol.**  
Scan your codebase for violations of DPDPA 2023, RBI FREE-AI, SEBI AI/ML, and the EU AI Act — directly inside Cursor, Claude Desktop, Windsurf, or Antigravity.

[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-0F2A4A.svg)](https://www.python.org/downloads/)
[![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-0F2A4A.svg)](LICENSE)
[![EU AI Act](https://img.shields.io/badge/EU%20AI%20Act-Article%209-F4A024.svg)](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX:32024R1689)
[![DPDPA 2023](https://img.shields.io/badge/India-DPDPA%202023-F4A024.svg)](https://www.meity.gov.in/dpdpa)
[![Zero telemetry](https://img.shields.io/badge/telemetry-zero-0B7A4B.svg)](#privacy)

---

## What it does

Meridian exposes six MCP tools that any AI coding assistant can call:

| Tool | Description |
|---|---|
| `scan_repository` | Scan a local repo for compliance violations — returns a Markdown report with line numbers, regulatory citations, and fixes |
| `evaluate_policy` | Check a privacy policy, DPA, or model card for compliance gaps |
| `explain_violation` | Get a plain-English explanation of any regulatory clause with exact penalties |
| `show_models` | List all supported LLM providers and configuration instructions |
| `cache_status` | Show or clear the local SQLite scan cache |
| `check_health` | Verify server config, detected API keys, and licence status |

### How scanning works

```
Your code → File Ranker → AST Slicer → Context Clusterer → Scan Pipeline (Rate Limiter) 
          → Stage 1 (Evaluator LLM) → candidate violations
          → Stage 2 (Critic LLM)    → confirmed violations
          → SHA-256 SQLite cache    → zero cost on re-scan
```

- **File Ranker**: Intelligently scores files by compliance risk (finding PII schemas) instead of blindly picking alphabetical files.
- **Context Clusterer**: Groups related files (same directory or name prefix) into 9,000-token bundles so the LLM can catch cross-file violations (e.g. data defined in `model.py` sent unencrypted in `routes.py`).
- **Adaptive Rate Limiter**: Implements token buckets (RPM/TPM) and dynamic concurrency scaling to handle thundering herd API constraints.
- **Stage 1** finds candidate violations across clusters concurrently.
- **Stage 2** runs a second LLM to disprove HIGH/CRITICAL findings, eliminating false positives.
- **Cache** skips re-evaluation of unchanged clusters — only new or modified code is sent to the API.
- **Async Artifact Factory**: Decouples slow I/O operations (PDF generation using headless Chromium/Playwright) from the main scan loop. PDFs are generated in a background thread, ensuring CI/CD pipelines don't block. The engine automatically injects cryptographic audit hashes into every PDF page footer for verifiable chain-of-custody.

### Supported frameworks

| Framework | Tier | Key penalties |
|---|---|---|
| `dpdpa` — DPDPA 2023 + Rules 2025 | **Free** | ₹250 Cr security failure · ₹200 Cr breach notification · ₹200 Cr children's data |
| `rbi` — RBI FREE-AI Aug 2025 | Pro | 7 Sutras — fairness, explainability, security, accountability |
| `eu` — EU AI Act Art. 9 | Pro | €30M / 6% global turnover for high-risk system failures |
| `sebi` — SEBI AI/ML Guidelines Jun 2025 | Pro | SEBI §5.1–§5.5 pillars |

---

## Supported LLM providers

Meridian uses [litellm](https://github.com/BerriAI/litellm) — **you bring your own API key, Meridian never touches your credentials.**

| Provider | Key env var | Example models |
|---|---|---|
| Anthropic | `ANTHROPIC_API_KEY` | `claude-opus-4-8`, `claude-haiku-4-5` |
| OpenAI | `OPENAI_API_KEY` | `gpt-5.4-pro`, `gpt-5.4-nano` |
| Gemini | `GEMINI_API_KEY` | `gemini/gemini-3.5-flash` |
| Groq | `GROQ_API_KEY` | `groq/meta-llama/llama-4-maverick-17b-128e-instruct` |
| OpenRouter | `OPENROUTER_API_KEY` | `openrouter/anthropic/claude-opus-4-8` |
| AWS Bedrock | `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY` + `AWS_REGION_NAME` | `bedrock/anthropic.claude-opus-4-8-20260501-v1:0` |
| Ollama (local) | *(none)* | `ollama/llama4:scout`, `ollama/mistral` |

You can mix providers — e.g. Anthropic for Stage 1 and Groq for Stage 2 (cheapest critic):

```
MERIDIAN_EVALUATOR_MODEL=claude-opus-4-8
MERIDIAN_CRITIC_MODEL=groq/llama-3.1-8b-instant
```

## Installation & Setup

Meridian can be run as a local CLI compliance scanner, or connected directly to an MCP-capable client like **Cursor**, **Claude Desktop**, **Windsurf**, or **Antigravity**.

### Option A: The quick way (no install, using `uvx`)
If you have `uv` installed, you don't even need to pre-install Meridian! You can run it instantly or register it as an MCP server using `uvx`:
```json
"meridian-compliance": {
  "command": "uvx",
  "args": ["meridian-mcp"],
  "env": {
    "GROQ_API_KEY": "gsk_...",
    "MERIDIAN_EVALUATOR_MODEL": "groq/llama3-8b-8192",
    "MERIDIAN_CRITIC_MODEL": "groq/llama3-8b-8192"
  }
}
```

### Option B: Installing via `pip` (PyPI)
Install the packages and binaries globally or to your active python environment:
```bash
pip install meridian-mcp
```
To enable beautiful PDF reporting using Playwright, install with the `pdf` extra:
```bash
pip install "meridian-mcp[pdf]"
```
This installs three executables on your system path:
1. `meridian-mcp`: The MCP Server command for AI assistants.
2. `meridian`: The interactive CLI (features `meridian init` and `meridian scan`).
3. `meridian-ci`: The CI/CD CLI command-line scanner (non-interactive).

---

## MCP Server Setup

Connect Meridian to your AI editor so your assistant can scan your repository and answer compliance questions.

### 1. Cursor (`~/.cursor/mcp.json` or GUI settings)
Add a new MCP server in **Cursor Settings -> Features -> MCP**:
- **Name**: `meridian-compliance`
- **Type**: `command`
- **Command**: `meridian-mcp` (use the absolute path to your Python env's `meridian-mcp` executable if it's not globally on your PATH)
- **Environment Variables**:
  - `GROQ_API_KEY`: `your-key-here` (or `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)

Or paste the following configuration directly into your `mcp.json` file:
```json
{
  "mcpServers": {
    "meridian-compliance": {
      "command": "meridian-mcp",
      "env": {
        "GROQ_API_KEY": "YOUR_GROQ_API_KEY"
      }
    }
  }
}
```

### 2. Claude Desktop (`%APPDATA%\Claude\claude_desktop_config.json`)
Add the following to your configuration:
```json
{
  "mcpServers": {
    "meridian-compliance": {
      "command": "meridian-mcp",
      "env": {
        "GROQ_API_KEY": "YOUR_GROQ_API_KEY"
      }
    }
  }
}
```

### 3. Antigravity (`~/.antigravity/mcp.json` or GUI settings)
Add a new MCP server in **Antigravity Settings -> Features -> MCP**:
- **Name**: `meridian-compliance`
- **Type**: `command`
- **Command**: `meridian-mcp` (use the absolute path to your Python env's `meridian-mcp` executable if it's not globally on your PATH)
- **Environment Variables**:
  - `GROQ_API_KEY`: `your-key-here` (or `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, etc.)

Or paste the following configuration directly into your `mcp.json` file:
```json
{
  "mcpServers": {
    "meridian-compliance": {
      "command": "meridian-mcp",
      "env": {
        "GROQ_API_KEY": "YOUR_GROQ_API_KEY"
      }
    }
  }
}
```

---

## Meridian Architecture

Below is a diagram illustrating the architecture of Meridian and its integration with various AI coding assistants:

```mermaid
flowchart TD
    subgraph Clients["AI Coding Assistants (MCP Clients)"]
        direction LR
        A1[Meridian CI/CD]
        A2[Cursor]
        A3[Windsurf]
        A4[Claude Desktop]
        A5[Antigravity]
    end

    subgraph Server["Meridian (MCP Server)"]
        B1[FastMCP Server]
        B2[Async Orchestrator]
        B3[Risk Ranker & Clusterer]
        B4[AST Parser]
        B5[Adaptive Rate Limiter]
        B6[Security Redactor]
        
        subgraph Scanning["Scanning Logic"]
            C1[Stage 1: Evaluator LLM]
            C2[Stage 2: Critic LLM]
        end
        
        B7[(SQLite Cache)]
        B8[Licensing Gate]
    end

    subgraph External["External Services"]
        direction LR
        D1[Anthropic/OpenAI/Groq/Gemini]
        D2[Regulatory Databases]
    end

    A1 -- Local CLI --> B2
    A2 -- MCP Protocol --> B1
    A3 -- MCP Protocol --> B1
    A4 -- MCP Protocol --> B1
    A5 -- MCP Protocol --> B1

    B1 --> B2
    B2 --> B3
    B3 --> B4
    B2 <--> B7
    B4 --> B5
    B5 --> B6
    B6 --> C1
    
    C1 --> C2
    C1 -- LiteLLM --> D1
    
    C2 -- LiteLLM --> D1
    C2 --> B8
    
    B8 -. Pro License .-> D2
```

---

## Local CLI Usage (`meridian`)

Meridian includes a polished, interactive CLI to scan local projects and generate PDF audit reports.

### 1. Initial Setup
Run the setup wizard to securely configure your LLM Provider and select your Evaluator and Critic models interactively:
```bash
meridian init
```

### 2. Run a Scan
Scan your local repository for compliance violations. Use the `--pdf` flag to automatically generate a beautiful, cross-platform PDF report (uses Playwright under the hood — no OS dependencies required!):
```bash
meridian scan --dir . --pdf
```

### CI/CD Pipeline Gate (`meridian-ci`)
Block PR merges on critical compliance violations by integrating the non-interactive `meridian-ci` as a step in your pipeline:

```yaml
# .github/workflows/compliance.yml
- name: Run Meridian compliance gate
  run: meridian-ci --dir . --frameworks dpdpa --fail-on critical
  env:
    GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
```

**Options:**
- `--dir`: Directory to scan (defaults to `.`)
- `--frameworks`: Frameworks to scan (`dpdpa`, `rbi`, `eu`, `sebi`)
- `--fail-on`: Block PRs/builds on violations at or above this severity (`low`, `medium`, `high`, `critical`)
- `--pdf`: Generates an A4 PDF report using headless Chromium.
- `--output`: Output format (`text`, `markdown`, `json`)
- `--max-files`: Maximum number of files to process

---

## Environment Variables

Configure these optional variables to adjust model defaults:

| Variable | Default | Description |
|---|---|---|
| `MERIDIAN_EVALUATOR_MODEL` | `claude-opus-4-8` | Stage 1 model — finds candidate violations |
| `MERIDIAN_CRITIC_MODEL` | `claude-haiku-4-5` | Stage 2 model — filters out false positives |
| `MERIDIAN_MAX_CONCURRENT` | `5` | Max concurrent LLM requests |
| `MERIDIAN_LICENSE_KEY` | *(none)* | Pro license key — unlocks RBI, EU, and SEBI rulesets |

---

## Quick start (inside your AI assistant)

Once the MCP server is connected:

```
check_health()                                 # verify setup and detected keys
show_models()                                  # see all providers and config options
scan_repository(path=".", frameworks="dpdpa")  # scan current repo
evaluate_policy(policy_text="...")             # check a privacy policy
explain_violation(statutory_clause="DPDPA §6(1)")  # plain-English explanation
cache_status()                                 # view cache stats
cache_status(clear=True)                       # wipe cache
```

---

## Project structure

```
src/meridian/
├── server.py        # MCP server — 6 tools exposed via FastMCP
├── scanner.py       # Async orchestrator with bounded producer-consumer queue
├── file_ranker.py   # Risk scoring & cross-file context clustering
├── ast_parser.py    # Language-aware code slicer (Python, JS/TS, SQL, YAML)
├── rate_limit.py    # Token bucket & dynamic semaphore adaptive rate limiter
├── evaluator.py     # Dual-stage litellm evaluator with cache and retry
├── config.py        # Multi-provider LLM config (load_config, validate_config)
├── prompts.py       # Regulatory prompts for all four frameworks
├── models.py        # Pydantic models — Violation, FileScanResult, ScanReport
├── ledger.py        # Compliance audit trail & PDF generation
├── report.py        # Terminal formatting & markdown reporting
├── cache.py         # SQLite SHA-256 scan cache (~/.meridian/cache.db)
├── security.py      # Secret redactor — strips API keys/JWTs before LLM calls
├── licensing.py     # Licence gate — free (DPDPA) vs Pro (RBI, EU, SEBI)
└── cli.py           # meridian-ci — CI/CD gate binary
```

---

## Contributing & Running Tests

If you want to contribute to Meridian or run the test suite locally:

```bash
# 1. Clone the repository
git clone https://github.com/KNambiarDJsc/Meridian.git
cd Meridian

# 2. Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
source .venv/bin/activate     # macOS / Linux

# 3. Install in editable mode with development dependencies
pip install -e ".[dev]"

# 4. Run the test suite
pytest tests/ -v
```

All 47 tests covering AST parsing, cache, prompts, and CLI logic pass locally without making any external API calls.

---

## Privacy

- **Zero telemetry.** Meridian sends no usage data anywhere.
- **Keys never leave your machine.** API keys are read from your environment and passed directly to the provider SDK — Meridian has no server, no proxy, no logging of credentials.
- **Code stays local until you call a tool.** The secret redactor (`security.py`) strips API keys, JWTs, and high-entropy strings from code slices before they are sent to any LLM.
- **Cache is local.** Scan results are stored in `~/.meridian/cache.db` on your machine only.

---

## Pricing / licence

| Tier | Frameworks | How to get |
|---|---|---|
| **Free** (Apache 2.0) | DPDPA 2023 | Use immediately, no key needed |
| **Pro** | DPDPA + RBI FREE-AI + EU AI Act + SEBI AI/ML | Set `MERIDIAN_LICENSE_KEY` — [meridian.so/pro](https://meridian.so/pro) |

---

## License

Apache 2.0 — see [LICENSE](LICENSE).

---
<!-- mcp-name: io.github.KNambiarDJsc/meridian-mcp -->
