# mcp-redact

中文 | [English](#english)

本地优先的 CLI 和 MCP Server，用于在把日志、配置、报错等文本分享给 AI 工具之前，先自动脱敏敏感信息。

`mcp-redact` 只做一件事：在你把内容粘贴给 Claude Code、Cursor 或其他 AI 工具之前，先把 secret 和敏感数据脱敏。

## 为什么要做这个

开发者经常会把日志、`.env` 文件、请求头、报错堆栈、配置片段直接贴给 AI 工具。这些内容里很可能包含 API Key、Bearer Token、Cookie、邮箱地址等敏感值。

`mcp-redact` 的设计目标是让这件事更安全：
- 本地优先
- 基于正则、确定性的脱敏
- CLI 和 MCP 共用一套核心引擎
- 输出稳定、可解释，例如 `[REDACTED_EMAIL]`

## 脱敏前 / 脱敏后

### 脱敏前

```text
Authorization: Bearer abcdefghijklmnop123456
user_email=user@example.com
callback=https://example.com/callback?token=secret123&lang=en
Cookie: session=abcdef123456; theme=dark
```

### 脱敏后

```text
Authorization: Bearer [REDACTED_AUTHORIZATION_HEADER]
user_email=[REDACTED_EMAIL]
callback=https://example.com/callback?token=[REDACTED_SENSITIVE_URL]&lang=en
Cookie: session=[REDACTED_COOKIE_HEADER]; theme=dark
```

## 快速开始

环境要求：
- Node.js 20+
- pnpm

安装依赖：

```bash
pnpm install
```

使用示例文件运行：

```bash
pnpm dev -- --file ./examples/sample.log
```

通过 stdin 管道输入：

```bash
pnpm dev -- < ./examples/sample.log
```

## 示例文件

仓库内提供了可用于本地测试和演示的样例文件：

- `examples/sample.log`
- `examples/sample.env`
- `examples/sample.json`
- `examples/sample.yaml`
- `examples/mcp-redact.config.json`

所有样例值均为伪造数据。

## CLI 用法

### 从 stdin 读取

```bash
pnpm dev -- < ./examples/sample.log
```

### 从文件读取

```bash
pnpm dev -- --file ./examples/sample.log
```

```bash
pnpm dev -- --file ./examples/sample.env
```

### 写入输出文件

```bash
pnpm dev -- --file ./examples/sample.env --output ./sanitized.env
```

### JSON 输出

```bash
pnpm dev -- --file ./examples/sample.log --format json
```

示例输出：

```json
{
  "redactedText": "Authorization: Bearer [REDACTED_AUTHORIZATION_HEADER]\nuser_email=[REDACTED_EMAIL]\ncallback=https://example.com/callback?token=[REDACTED_SENSITIVE_URL]&lang=en\nCookie: session=[REDACTED_COOKIE_HEADER]; theme=dark\n",
  "summary": {
    "totalMatches": 4,
    "byType": {
      "authorization_header": 1,
      "email": 1,
      "sensitive_url": 1,
      "cookie_header": 1
    }
  }
}
```

### 只输出摘要

```bash
pnpm dev -- --file ./examples/sample.log --summary-only
```

示例输出：

```text
Total matches: 4
By type:
- authorization_header: 1
- cookie_header: 1
- email: 1
- sensitive_url: 1
```

### 限制启用的规则组

只启用 personal 规则：

```bash
pnpm dev -- --file ./examples/sample.log --only personal
```

运行时禁用某个规则组：

```bash
pnpm dev -- --file ./examples/sample.log --disable http
```

### 使用配置文件

```bash
pnpm dev -- --file ./examples/sample.log --config ./examples/mcp-redact.config.json
```

示例配置只启用 `personal` 和 `custom` 组，禁用内置 `email` detector，并新增一条 `internal-ticket` 自定义规则。由于 `sample.log` 里没有匹配的 ticket 且 email 脱敏被关闭，因此这个示例下文件内容不会发生变化。

## MCP 用法

### 启动 MCP Server

开发模式：

```bash
pnpm mcp:dev
```

构建后运行：

```bash
pnpm build
pnpm mcp:start
```

### MCP 工具

#### `redact_text`

输入：

```json
{
  "text": "Authorization: Bearer abcdefghijklmnop123456",
  "groups": ["http"],
  "configPath": "./examples/mcp-redact.config.json"
}
```

#### `redact_file`

输入：

```json
{
  "filePath": "./examples/sample.log",
  "groups": ["http"],
  "configPath": "./examples/mcp-redact.config.json"
}
```

两个工具都会返回同样的结构：

```json
{
  "redactedText": "...",
  "summary": {
    "totalMatches": 4,
    "byType": {
      "authorization_header": 1,
      "email": 1
    }
  }
}
```

### 从 MCP 客户端连接

根据你的环境选择对应的 server 命令：

- 开发模式：`pnpm mcp:dev`
- 构建产物：`pnpm mcp:start`

如果你的 MCP 客户端要求填写命令和参数，请指向本地项目并通过 stdio 启动服务。当前服务暴露两个工具：`redact_text` 和 `redact_file`。

## 配置

默认配置文件名：

```text
mcp-redact.config.json
```

如果没有显式传入配置路径，`mcp-redact` 会尝试从当前工作目录读取这个默认文件。若默认文件不存在，程序会继续正常执行；如果你显式传入了一个不存在的配置路径，则命令会报错。

示例配置：

```json
{
  "enabledGroups": ["personal", "custom"],
  "disabledDetectors": ["email"],
  "customRules": [
    {
      "name": "internal-ticket",
      "pattern": "TICKET-[0-9]{6}",
      "placeholder": "[REDACTED_TICKET]"
    }
  ]
}
```

### 配置字段

- `enabledGroups`：限制只启用列出的内置或自定义规则组
- `disabledDetectors`：按名称禁用 detector，例如 `email` 或 `github-token`
- `customRules`：添加本地正则规则，并复用与内置规则相同的处理流水线

## 支持的内置 detector

### `secrets`

- Bearer Token
- JWT
- GitHub Token
- OpenAI 风格 API Key
- Anthropic 风格 API Key
- AWS Access Key ID
- `password=`、`token=`、`secret=`、`api_key=` 这类键值形式 secret
- 多行私钥块

### `personal`

- 邮箱地址
- 手机号
- IPv4 地址

### `http`

- Authorization Header 中的 Bearer 值
- Cookie Header 中的敏感值
- URL 中敏感 query 参数，例如 `token=`

## 本地开发

常用命令：

```bash
pnpm install
pnpm test
pnpm lint
pnpm typecheck
pnpm build
pnpm mcp:dev
```

## 路线图

- 增加更多 token 和 API key 模式
- 进一步降低误报
- 提供更多真实风格的日志和配置示例
- 提供更多端到端 MCP 客户端示例

---

## English

Local-first CLI and MCP server for redacting sensitive text before sharing logs, configs, and errors with AI tools.

`mcp-redact` helps you do one thing before pasting text into Claude Code, Cursor, or other AI tools: redact secrets and sensitive data first.

## Why this exists

Developers often paste logs, `.env` files, request headers, stack traces, and config snippets into AI tools. Those snippets can contain API keys, bearer tokens, cookies, emails, and other sensitive values.

`mcp-redact` is built to make that flow safer:
- local-first
- deterministic regex-based redaction
- shared engine for both CLI and MCP
- readable placeholders like `[REDACTED_EMAIL]`

## Before / After

### Before

```text
Authorization: Bearer abcdefghijklmnop123456
user_email=user@example.com
callback=https://example.com/callback?token=secret123&lang=en
Cookie: session=abcdef123456; theme=dark
```

### After

```text
Authorization: Bearer [REDACTED_AUTHORIZATION_HEADER]
user_email=[REDACTED_EMAIL]
callback=https://example.com/callback?token=[REDACTED_SENSITIVE_URL]&lang=en
Cookie: session=[REDACTED_COOKIE_HEADER]; theme=dark
```

## Quick start

Requirements:
- Node.js 20+
- pnpm

Install dependencies:

```bash
pnpm install
```

Run on a sample file:

```bash
pnpm dev -- --file ./examples/sample.log
```

Pipe text through stdin:

```bash
pnpm dev -- < ./examples/sample.log
```

## Example files

This repository includes sample inputs you can use for local testing and demos:

- `examples/sample.log`
- `examples/sample.env`
- `examples/sample.json`
- `examples/sample.yaml`
- `examples/mcp-redact.config.json`

All sample values are fake.

## CLI usage

### Read from stdin

```bash
pnpm dev -- < ./examples/sample.log
```

### Read from a file

```bash
pnpm dev -- --file ./examples/sample.log
```

```bash
pnpm dev -- --file ./examples/sample.env
```

### Write output to a file

```bash
pnpm dev -- --file ./examples/sample.env --output ./sanitized.env
```

### JSON output

```bash
pnpm dev -- --file ./examples/sample.log --format json
```

Example output:

```json
{
  "redactedText": "Authorization: Bearer [REDACTED_AUTHORIZATION_HEADER]\nuser_email=[REDACTED_EMAIL]\ncallback=https://example.com/callback?token=[REDACTED_SENSITIVE_URL]&lang=en\nCookie: session=[REDACTED_COOKIE_HEADER]; theme=dark\n",
  "summary": {
    "totalMatches": 4,
    "byType": {
      "authorization_header": 1,
      "email": 1,
      "sensitive_url": 1,
      "cookie_header": 1
    }
  }
}
```

### Summary-only output

```bash
pnpm dev -- --file ./examples/sample.log --summary-only
```

Example output:

```text
Total matches: 4
By type:
- authorization_header: 1
- cookie_header: 1
- email: 1
- sensitive_url: 1
```

### Limit enabled groups

Only run personal detectors:

```bash
pnpm dev -- --file ./examples/sample.log --only personal
```

Disable one group at runtime:

```bash
pnpm dev -- --file ./examples/sample.log --disable http
```

### Use a config file

```bash
pnpm dev -- --file ./examples/sample.log --config ./examples/mcp-redact.config.json
```

The example config enables only `personal` and `custom` groups, disables the built-in `email` detector, and adds a custom `internal-ticket` rule. With that config, `sample.log` is left unchanged because it does not contain any custom ticket value and email redaction is disabled.

## MCP usage

### Start the MCP server

Development mode:

```bash
pnpm mcp:dev
```

Build and run:

```bash
pnpm build
pnpm mcp:start
```

### MCP tools

#### `redact_text`

Input:

```json
{
  "text": "Authorization: Bearer abcdefghijklmnop123456",
  "groups": ["http"],
  "configPath": "./examples/mcp-redact.config.json"
}
```

#### `redact_file`

Input:

```json
{
  "filePath": "./examples/sample.log",
  "groups": ["http"],
  "configPath": "./examples/mcp-redact.config.json"
}
```

Both tools return the same structured shape:

```json
{
  "redactedText": "...",
  "summary": {
    "totalMatches": 4,
    "byType": {
      "authorization_header": 1,
      "email": 1
    }
  }
}
```

### Connecting from an MCP client

Use the server command that fits your environment:

- development: `pnpm mcp:dev`
- built output: `pnpm mcp:start`

If your MCP client expects a command plus arguments, point it at the local project and run the server over stdio. The server exposes two tools: `redact_text` and `redact_file`.

## Configuration

Default config file name:

```text
mcp-redact.config.json
```

If no explicit config path is provided, `mcp-redact` will try to read that file from the current working directory. If the default file is missing, execution continues normally. If you explicitly pass a missing config path, the command fails.

Example config:

```json
{
  "enabledGroups": ["personal", "custom"],
  "disabledDetectors": ["email"],
  "customRules": [
    {
      "name": "internal-ticket",
      "pattern": "TICKET-[0-9]{6}",
      "placeholder": "[REDACTED_TICKET]"
    }
  ]
}
```

### Config fields

- `enabledGroups`: restricts built-in and custom detectors to the listed groups
- `disabledDetectors`: disables detectors by name, such as `email` or `github-token`
- `customRules`: adds local regex-based detectors that use the same pipeline as built-in rules

## Supported detectors

### `secrets`

- Bearer token
- JWT
- GitHub token
- OpenAI-style API key
- Anthropic-style API key
- AWS access key id
- Key-value secrets like `password=`, `token=`, `secret=`, `api_key=`
- Private key blocks

### `personal`

- Email
- Phone
- IPv4

### `http`

- Authorization header bearer value
- Cookie header sensitive value
- Sensitive URL query value like `token=`

## Local development

Common commands:

```bash
pnpm install
pnpm test
pnpm lint
pnpm typecheck
pnpm build
pnpm mcp:dev
```

## Roadmap

- More token and API key patterns
- Better false-positive suppression
- More real-world log and config examples
- More end-to-end MCP client examples