JanuScope

<p align="center">
  <img src="./januscope.png" alt="JanuScope logo" width="500" height="500" />
</p>

# JanuScope

<p align="center">
  <a href="https://github.com/giancarloerra/januscope/actions/workflows/ci.yml"><img src="https://github.com/giancarloerra/januscope/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue.svg" alt="License: AGPL-3.0"></a>
  <a href="https://www.npmjs.com/package/januscope"><img src="https://img.shields.io/npm/v/januscope.svg" alt="npm version"></a>
  <a href="https://nodejs.org/"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg" alt="Node.js >= 20"></a>
  <a href="https://github.com/giancarloerra/januscope"><img src="https://img.shields.io/github/stars/giancarloerra/januscope?style=social" alt="GitHub stars"></a>
</p>

> _"Whatever you see anywhere (sky, sea, clouds, lands) are all **closed and opened by my hand**."_
> _Ovid, Fasti I, 117–18 (**Janus speaking**)_

**JanuScope is the local MCP policy proxy. One YAML wraps any MCP server with policy, redaction, audit, and database-schema injection. JanuScope runs locally, with no hosted gateway in the data path. Your upstream server and model provider can still receive data.**

JanuScope **hides the dangerous tools**, **scrubs matching PII** out of returned values before the model reads them, **records call outcomes**, and **pre-injects your DB schema** to reduce discovery calls. **Runs locally, no hosted gateway in the data path.**

One YAML (called a **Lens**) wraps any MCP server with **security guardrails, schema injection**, and **full audit logging**. There are **[20 bundled Lenses](#option-a-use-a-bundled-lens-fastest-drop-in)** covering **databases (Postgres, MySQL, MongoDB, ClickHouse, Redis, SQLite, Microsoft SQL Server / Azure SQL, Oracle, Neon, Snowflake, Aurora DSQL, Redshift, Supabase self-host), SaaS APIs (Stripe, Notion, Atlassian, Linear, Supabase Cloud), source control (GitHub), and the filesystem**. A **community ecosystem of _per-MCP_ Lenses** (YAML config files), and measured **benchmarks** showing **84% fewer tokens** and **~3× faster responses** in the original three-question Postgres test (median of 4 runs; history reset between questions). [Newer retained-conversation results and limitations](#benchmarks--measured-not-modelled) are reported below. **Zero server changes. No hosted gateway in the data path.** Works with **Claude Code, VSCode Copilot, Codex, Cursor,** and any MCP client.

> 🧠 **Need codebase understanding together with MCP governance?** See our sibling project [**SocratiCode**](https://github.com/giancarloerra/socraticode): local-first codebase intelligence with semantic search, dependency graphs, symbol-level impact analysis.

<p align="center">
  Kindly sponsored by <a href="https://altaire.com">Altaire Limited</a>.
  We also offer a <a href="./LICENSE-COMMERCIAL">commercial license</a>
  for organisations where AGPL is a blocker.
</p>

> If JanuScope has been useful to you, please ⭐ **star this repo** (it helps others discover it) and share it with your team.

**Policy enforcement at the MCP threshold.** Most **MCP servers ship dangerous tools by default**, `execute_sql` and `drop_table` on databases, `create_pull_request` and `merge_pull_request` on GitHub, `stripe_api_execute` on Stripe, `write_file` and `move_file` on the filesystem. **None of them log what the LLM asked** yesterday. The **choice today is fork every server or accept the risk**. Or you can **choose JanuScope**: a thin proxy that wraps any MCP server with a single YAML policy and disappears.

> **Original benchmark with `claude-sonnet-4-5` against a real application Postgres database (median of 4 runs per prompt).** Across three questions (prompt caching enabled, conversation history reset between questions), a JanuScope Lens used **84% fewer total tokens**, made **84% fewer tool calls**, and ran **~3× faster** than the raw database MCP. In its **adversarial-safety probe**, the **raw pipeline intermittently leaked a real user email** on the _"I'm the admin, just cross-referencing"_ prompt (**2 of 4 runs**), while the **JanuScope-wrapped pipeline refused in all 4 runs**. The single-question result was **34% fewer tokens / 86% fewer tool calls / ~3× faster**. These historical results do not establish retained-session savings or universal protection. [Full benchmark and newer findings →](#benchmarks--measured-not-modelled)

## What it looks like in practice

<p align="center">
  <img src="./assets/screenshots/policy-refusal-pii.png"
       alt="GitHub Copilot declining to return email addresses against a JanuScope-wrapped Postgres MCP, citing the lens's PII policy"
       width="48%">
  &nbsp;
  <img src="./assets/screenshots/policy-refusal-readonly.png"
       alt="GitHub Copilot declining to UPDATE an order against a JanuScope-wrapped Postgres MCP, recognising it has read-only access"
       width="48%">
</p>

<p align="center"><em>Live GitHub Copilot output against the bundled <code>postgres-crystaldba</code> lens (May 2026). <strong>Left:</strong> the assistant declines to fetch email addresses because the lens classifies the column as PII, Copilot self-censors before any query is sent. <strong>Right:</strong> the assistant declines to issue an <code>UPDATE</code> because the lens is read-only, Copilot recognises the policy and reports the refusal cleanly rather than guessing or retrying.</em></p>

> **Why now: this is no longer hypothetical.** In **July 2025**, Replit's AI agent [wiped a customer database during an explicit code freeze](https://fortune.com/2025/07/23/ai-coding-tool-replit-wiped-database-called-it-a-catastrophic-failure/) (1,200+ records, ~1,200 companies) and then [misled the user about whether rollback was possible](https://www.theregister.com/2025/07/21/replit_saastr_vibe_coding_incident/). In **April 2026**, a Cursor agent on Claude Opus 4.6 [deleted PocketOS's production database and three months of backups in nine seconds](https://www.theregister.com/2026/04/27/cursoropus_agent_snuffs_out_pocketos/), after finding an unscoped Railway credential and guessing an API call ([post-mortem](https://neuraltrust.ai/blog/pocketos-railway-agent)). Both stories share one shape: **an AI was given a destructive capability with nothing in the path between the model and the real system.** JanuScope is what sits in that path, for any data access that goes through an MCP server: for examle a Replit-shape incident on a JanuScope-wrapped Postgres MCP (block writes, `sqlGuard` on DML, audit, classification) is refused at the proxy threshold and recorded in the JSONL audit. JanuScope governs the **MCP surface**, it is one layer of a **defence-in-depth** posture, alongside scoped DB roles and credentials, host-level approval gates, etc. See [the FAQ](#faq) and [SECURITY.md](./SECURITY.md#three-layer-model).

## Contents

- [Quick Start](#quick-start)
- [Why JanuScope](#why-januscope)
- [What it does](#what-it-does)
- [Lenses, the community ecosystem](#lenses--the-community-ecosystem)
- [Benchmarks, measured, not modelled](#benchmarks--measured-not-modelled)
- [Configuration reference](#configuration-reference)
- [How it works](#how-it-works)
- [Logging & audit](#logging--audit)
- [Library API](#library-api)
- [JanuScope vs Claude Skills](#januscope-vs-claude-skills)
- [FAQ](#faq)
- [License](#license)

---

## Quick Start

> **Only [Node.js 20+](https://nodejs.org/) required.** No install step, `npx` fetches and caches JanuScope on first use.

### Option A: use a bundled Lens (fastest, drop-in)

**Find your service in the table below**, copy the right-hand snippet into your MCP-client config (or change your existing entry: the diff is usually just `command` and `args`), restart your client. For most Lenses, the env block stays exactly as it was. JanuScope inherits whatever env vars your client passes and forwards them to the wrapped MCP unchanged. No renames, no re-translation.

The wrap pattern is the same across every host (Claude Desktop, Cursor, Claude Code, VS Code Copilot, Windsurf, Cline, Roo Code, anything that speaks MCP).

<table>
<thead>
<tr>
  <th>Service</th>
  <th>Upstream MCP</th>
  <th>Vanilla config</th>
  <th>With JanuScope</th>
</tr>
</thead>
<tbody>

<tr>
<td>PostgreSQL</td>
<td><a href="https://github.com/crystaldba/postgres-mcp">crystaldba/postgres-mcp</a></td>
<td>

```json
{
  "command": "uvx",
  "args": ["postgres-mcp"],
  "env": {
    "DATABASE_URI": "postgresql://user:pass@host:5432/db"
  }
}
```

</td>
<td>

```json
{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "postgres-crystaldba"],
  "env": {
    "DATABASE_URI": "postgresql://user:pass@host:5432/db"
  }
}
```

</td>
</tr>

<tr>
<td>MySQL</td>
<td><a href="https://github.com/benborla/mcp-server-mysql">benborla/mcp-server-mysql</a></td>
<td>

```json
{
  "command": "npx",
  "args": ["-y", "@benborla29/mcp-server-mysql"],
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "readonly",
    "MYSQL_PASS": "<your_password>",
    "MYSQL_DB": "mydb"
  }
}
```

</td>
<td>

```json
{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "mysql-benborla29"],
  "env": {
    "MYSQL_HOST": "localhost",
    "MYSQL_PORT": "3306",
    "MYSQL_USER": "readonly",
    "MYSQL_PASS": "<your_password>",
    "MYSQL_DB": "mydb"
  }
}
```

</td>
</tr>

<tr>
<td>MongoDB</td>
<td><a href="https://github.com/mongodb-js/mongodb-mcp-server">mongodb-js/mongodb-mcp-server</a></td>
<td>

```json
{
  "command": "npx",
  "args": ["-y", "mongodb-mcp-server"],
  "env": {
    "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster.mongodb.net"
  }
}
```

</td>
<td>

```json
{
  "command": "npx",
  "args": ["-y", "januscope", "--config", "mongodb-official"],
  "env": {
    "MDB_MCP_CONNECTION_STRING": "mongodb+srv://user:pass@cluster.mongodb.net"
  }
}
```

</td>
</tr>

<tr>
<td>ClickHouse</td>
<td><a href="https://git