使用说明

补救与合规MCP服务器

生产就绪版 |版本2.0

此存储库包含等级实施a 补救与合规模型上下文协议（MCP） 服务器。它提供了一个 飞行前/飞行后防火墙 对于具有全面检测、分类、策略执行的LLM呼叫，可逆编校、选择性去标记、输出安全和不可变审计日志。

✨ 特性

🎯 核心能力

🔄 流媒体支持：OpenAI、Claude和Gemini的实时流媒体，逐块去标记
🛡️ 索赔验证：基于研究的幻觉检测，带有内联警告（支持本地模型）
🚀 透明代理：零代码集成-只需更改API基础URL
📊 等级：NGINX、HTTPS、SIEM集成、Redis后端、systemd服务

🔍 超前预报

多云凭据：AWS（AKID，机密）、Azure（存储密钥、SAS令牌、连接字符串）、GCP（API密钥、OAuth）
OAuth和承载令牌：JWT检测、OAuth访问令牌
加密密钥：PEM（RSA、DSA、EC）、PKCS#12、Kubernetes配置/令牌
PII验证:
- 信用卡 Luhn校验和验证
- SSN与 格式验证 （拒绝无效的区号000、666、900-999）
- 电子邮件地址和电话号码
内部基础设施：Joby航空领域(*.na.joby.aero, *.az.joby.aero)、IP地址、主机名
出口管制：航空关键词（eVTOL、ITAR、FAA认证、飞行控制系统、推进）

🛡️ 策略引擎

地理/区域限制：美国、欧盟、亚太地区、限制地区（CN、RU、IR、KP、SY）
基于呼叫者的路由：受信任的呼叫者列表，每个呼叫者的去标记权限
数据驻留：欧盟GDPR合规性，区域特定模型路由
类别操作: block, redact, internal_only, allow
版本跟踪：所有决策中都嵌入了政策版本

🔐 代币商店

在存储器中：快速、无状态、用于开发/测试
带AES-GCM的Redis：生产级，静态加密
- AES-256-GCM加密
- PBKDF2密钥推导
- 自动TTL管理
确定性占位符: «token:TYPE:HASH4» 在对话范围内稳定

⚠️ 输出安全

50+危险命令模式：文件系统销毁、系统控制、K8s/Docker、数据库、云基础设施、网络/防火墙
外部配置支持：基于JSON的自定义模式加载
3种模式: warning （注释）， block （编辑）， silent （通过）

📊 审计与合规

仅附加JSONL：不可变的审计跟踪
完整上下文捕获：呼叫者、地区、类别、决定、编辑计数
查询API：搜索和检索审计记录
SIEM集成：实时发送到Splunk、Elasticsearch、Datadog、Syslog
缓冲运输：<5%的开销，批量生产模式

🚀 生产安装（5分钟）

使用NGINX、HTTPS和客户端SDK的自动安装程序：

# On your Linux server (Ubuntu 20.04+ or RHEL 8+)
wget https://raw.githubusercontent.com/sunkencity999/redaction-compliance-MCP/main/install.sh
chmod +x install.sh
sudo ./install.sh

它的作用：

✅ 安装所有依赖项（Python 3.11、Redis、NGINX）
✅ 生成加密密钥（您备份它们）
✅ 配置SIEM集成（Splunk/Eelasticsearch/Datadog）
✅ 使用HTTPS设置NGINX反向代理（Let's Encrypt或自签名）
✅ 创建systemd服务（启动时自动启动）
✅ 安装Python客户端SDK
✅ 创建集成示例
✅ 运行完整的测试套件（186+个测试）

手动安装： 看 QUICKSTART.md

📦 客户端SDK

开发包

Python/后端应用程序的无缝集成：

# Install SDK (included in automated installer)
pip install -e .

用途：

from mcp_client import MCPClient, MCPConfig

# Configure once
mcp = MCPClient(MCPConfig(
    server_url="https://mcp.yourcompany.com",
    caller="your-app-name"
))

# Protect LLM calls automatically
user_input = "My AWS key is AKIAIOSFODNN7EXAMPLE, help me debug"

# Redact before sending to LLM
sanitized, handle = mcp.redact(user_input)
# sanitized: "My AWS key is «token:SECRET:a3f9», help me debug"

# Send sanitized version to OpenAI/Claude/etc
llm_response = your_llm_function(sanitized)

# Restore non-secret tokens
final = mcp.detokenize(llm_response, handle)

# Secrets stay tokenized, PII/ops_sensitive restored!

或者使用便利包装：

from mcp_client import MCPClient, MCPConfig

mcp = MCPClient(MCPConfig.from_env())

# One-line protection
response = mcp.safe_llm_call(
    user_input,
    lambda text: openai.ChatCompletion.create(
        model="gpt-4",
        messages=[{"role": "user", "content": text}]
    ).choices[0].message.content
)

示例： 看 examples/ 安装后的目录

JavaScript/浏览器SDK

对于web应用程序，React、Vue、Angular：

<!-- Include SDK -->
<script src="mcp_client_js/mcp-client.js"></script>

<script>
// Initialize client
const mcp = new MCPClient({
    serverUrl: 'https://mcp.yourcompany.com',
    caller: 'web-app'
});

// Protect browser-based LLM calls
async function safeChatCompletion(userInput) {
    const response = await mcp.safeLLMCall(
        userInput,
        async (sanitized) => {
            // Call OpenAI/Claude from browser
            return await callYourLLM(sanitized);
        }
    );
    return response;
}
</script>

反应示例：

import { MCPClient } from './mcp-client.js';

const mcp = new MCPClient({
    serverUrl: process.env.REACT_APP_MCP_SERVER,
    caller: 'react-app'
});

function ChatComponent() {
    const handleSubmit = async (input) => {
        try {
            const response = await mcp.safeLLMCall(input, callOpenAI);
            setMessages(prev => [...prev, response]);
        } catch (error) {
            if (error instanceof MCPBlockedError) {
                alert('Request blocked: contains sensitive data');
            }
        }
    };
    // ... rest of component
}

支持的TypeScript： 看 mcp_client_js/mcp-client.d.ts

示例： 看 mcp_client_js/examples/ 用于浏览器和React演示

🔄 透明代理模式（新增！）

现有OpenAI/Claude/Gemini应用程序的零代码集成：

只需更改API基本URL，MCP就会自动保护所有呼叫！

import openai

# Change this one line:
openai.api_base = "https://mcp.yourcompany.com/v1"

# Your existing code works unchanged!
response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "My AWS key is AKIA..."}]
)
# MCP automatically redacts before OpenAI sees it!

支持的提供商：

✅ 开放人工智能 (/v1/chat/completions)-支持流媒体
✅ 克劳德 (/v1/messages)-支持流媒体
✅ 双子座 (/v1/models/{model}:generateContent)-支持流媒体

特征：

✅ 逐块去标记实时流媒体
✅ 可选索赔验证（幻觉检测）
✅ 本地模型支持（vLLM、Ollama、FastAPI）
✅ 自动编校+去标记
✅ SIEM中的完整审计跟踪

设置：

# In .env file
PROXY_MODE_ENABLED=true
CLAIM_VERIFICATION_ENABLED=false  # Optional
DETOKENIZE_TRUSTED_CALLERS=openai-proxy,claude-proxy,gemini-proxy

完整指南：

TRANSPARENT_PROXY.md -代理模式文档
CLAIM_VERIFICATION.md -幻觉检测指南

🛡️ 索赔验证（幻觉检测）

可选的后处理层，用于验证LLM响应的事实准确性：

该功能使用基于研究的方法，通过4级管道分析LLM反应，以检测和标记潜在的幻觉和虚假声明。

# Enable in .env
CLAIM_VERIFICATION_ENABLED=true
CLAIM_VERIFICATION_MODEL=gpt-4o-mini  # Or local model

# Use any LLM normally via transparent proxy
response = openai.ChatCompletion.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What was Argentina's inflation in 2023?"}]
)

# If LLM hallucinates a wrong number, you'll see:
print(response.choices[0].message.content)
# "Argentina's inflation reached 300% in 2023."
# ⚠️ **[CLAIM FLAGGED - HIGH CONFIDENCE]**: This claim is likely false. 
# Evidence suggests Argentina's inflation was approximately 211% in 2023.

四阶段验证流程：

句子拆分 -根据上下文将反应分解为句子
选择 -筛选可验证的事实主张
消歧 -解决或标记歧义语句
分解 -提取原子独立声明
验证 -用置信度分数对每项索赔进行事实核查

输出模式：

内联警告: 🚨 高，⚠️ 中等，ℹ️ 文本中添加了低置信度标志
元数据：详细验证信息请参见 mcp_verification 响应字段
无阻塞：用户总是看到完整的响应+警告（通知，不要审查）

本地模型支持：

# Use vLLM, Ollama, or FastAPI locally (no API fees, full privacy)
CLAIM_VERIFICATION_BASE_URL=http://localhost:8000/v1
CLAIM_VERIFICATION_MODEL=meta-llama/Meta-Llama-3.1-8B-Instruct
CLAIM_VERIFICATION_REQUIRE_AUTH=false  # No authentication needed

使用案例：

✅ 技术/工程 -验证计算、公式、规格
✅ 科学的 -事实核查研究声明、数据、常数
✅ 金融的 -验证统计数据、市场数据、经济声明
✅ 医学的 -验证剂量、症状、治疗（严格模式）

演出

延迟：每个响应约500-1000ms（云）或约300ms（本地）
成本：约0.0003美元/gpt-4o-mini响应，本地型号为0美元
缓存：约80%的命中率降低了延迟和成本

完整指南： 看 CLAIM_VERIFICATION.md 有关完整的设置、配置和示例。

🌐 API端点（REST）

核心MCP端点：

GET /health → 服务器健康检查
POST /classify → 对有效载荷灵敏度进行分类
POST /redact → 清理有效负载，返回token_map_handle
POST /detokenize → 重新注入允许的令牌（仅限受信任的客户端）
POST /route → 制定执行计划（内部/外部，编辑步骤）
POST /audit/query → 简单审计搜索

透明代理端点 （当 PROXY_MODE_ENABLED=true):

POST /v1/chat/completions → OpenAI兼容代理
POST /v1/messages → 克劳德兼容代理
POST /v1/models/{model}:generateContent → Gemini兼容代理

API完整文档： 看 mcp_redaction/models.py 用于请求/响应模式。

政策

编辑 mcp_redaction/sample_policies/default.yaml。支持更改时的热重新加载（观察器可选）。

标准/JSON-RPC（MCP）适配器

看 mcp_redaction/stdio_adapter.py 对于最小的适配器骨架，您可以在代理运行时下挂载。

测试

pytest -q

生产硬化

运行在mTLS和身份感知代理后面
使用Redis（或带信封加密的KV）进行令牌映射
将审核日志发送到SIEM（Splunk/ELK）；旋转JSONL文件
添加OPA/看门人检查脱酮分类
扩展检测器（NER、出口管制分类器），为附件添加OCR
在中强制执行地理路由和模型允许列表 policy.yaml