Content
# 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
