meridian-mcp 0.5.4

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.

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.

---

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 — 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:

"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:

pip install meridian-mcp

To enable beautiful PDF reporting using Playwright, install with the pdf extra:

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:

{
  "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:

{
  "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:

{
  "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:

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:

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!):

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:

# .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:

# 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

---

License

Apache 2.0 — see LICENSE.

---