# https://github.com/presidio-v/presidio-hardened-x402-mcp 项目说明书

生成时间：2026-06-17 23:16:45 UTC

## 目录

- [Project Overview & Architecture](#page-1)
- [MCP Tools & API Reference](#page-2)
- [Configuration, Modes & Deployment](#page-3)
- [Security, Composability & Operations](#page-4)

<a id='page-1'></a>

## Project Overview & Architecture

### 相关页面

相关主题：[MCP Tools & API Reference](#page-2), [Configuration, Modes & Deployment](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/README.md)
- [PRESIDIO-REQ.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PRESIDIO-REQ.md)
- [CHANGELOG.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/CHANGELOG.md)
- [SECURITY.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY.md)
- [PUBLISHING.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PUBLISHING.md)
- [SECURITY-AUDIT.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY-AUDIT.md)
- [server.json](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/server.json)
- [src/presidio_x402_mcp/server.py](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/src/presidio_x402_mcp/server.py)
- [src/presidio_x402_mcp/__init__.py](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/src/presidio_x402_mcp/__init__.py)
</details>

# Project Overview & Architecture

## 项目概述与定位

`presidio-hardened-x402-mcp` 是面向 x402 支付场景的**预签名 PII 筛查器**——一个通过 Model Context Protocol (MCP) 暴露给 AI agent 调用的 stdio 服务器。其核心职责是在 agent 签署 x402 支付之前，对 `resource_url`、`description`、`reason` 等支付元数据进行 PII 检测与脱敏，避免邮箱、SSN、电话号码、姓名等敏感数据落入商户侧。

资料来源：[README.md:1-15]() · [PRESIDIO-REQ.md:1-12]()

从架构层次看，本仓库是父库 [`presidio-hardened-x402`](https://github.com/presidio-v/presidio-hardened-x402) 的**薄适配层 (thin MCP adapter)**：所有安全原语——PII 检测准确率、策略引擎语义、重放防护加密、审计链 HMAC——均在父库实现并按 SemVer 演进；本仓库仅通过 stdio JSON-RPC 将这些能力暴露为 MCP 工具面，绝不重新推导父库逻辑。`SECURITY.md` 的 Scope 章节也明确将上述父库实现划为 out-of-scope。

资料来源：[PRESIDIO-REQ.md:1-12]() · [SECURITY.md:1-30]()

在 `presidio-hardened-*` 工具家族中，本包专注于**载荷安全 (payload safety)**，与 `x402station-mcp` 负责的端点安全 (endpoint safety)、Coinbase x402 MCP / MetaMask `mcp-x402` / Sardis 负责的**支付执行**形成互补。`CHANGELOG.md` 显示 `v0.1.1` 已加入与 `x402station-mcp` 的组合调用示例，体现 "composition over replacement" 的设计取舍。

资料来源：[PRESIDIO-REQ.md:80-100]() · [CHANGELOG.md:1-15]()

## 核心架构与执行模式

服务器通过 FastMCP 注册三个工具面，全部承载于同一 stdio JSON-RPC 通道：

| 工具 | 父库底层调用 | 副作用 |
|------|--------------|--------|
| `screen_payment_metadata(resource_url, description, reason, entities?)` | `PIIFilter.scan_payment_fields()` | 无（可重复调用） |
| `check_payment_policy(resource_url, amount_usd)` | `PolicyEngine.check_and_record()` | **有**（成功后扣减滚动窗口额度） |
| `check_payment_replay(resource_url, pay_to, amount, currency, deadline_seconds)` | `compute_fingerprint()` + `ReplayGuard.check_and_record()` | **有**（成功后记录指纹） |

资料来源：[README.md:30-60]() · [src/presidio_x402_mcp/server.py:30-80]() · [CHANGELOG.md:30-40]()

执行存在两种互斥模式，由环境变量 `PRESIDIO_X402_MCP_REMOTE_BASE_URL` + `PRESIDIO_X402_MCP_REMOTE_API_KEY` 是否同时设置决定：

- **In-process（默认）**：本地调用父库 `PIIFilter`/`PolicyEngine`/`ReplayGuard`，零网络、零 API key、零配额。
- **HTTP-proxy（opt-in）**：仅 `screen_payment_metadata` 走远端筛查服务，使用 `httpx.AsyncClient` 并设置 `httpx.Timeout(10.0, connect=3.0)`；**远端失败时不会静默回退到 in-process**，而是返回结构化 `{error, detail, mode: "remote"}`，由 agent 显式决策。

资料来源：[README.md:60-90]() · [SECURITY.md:40-55]() · [SECURITY-AUDIT.md:1-20]()

```mermaid
flowchart LR
    Agent[MCP Host / Agent] -->|stdio JSON-RPC| Server[presidio-hardened-x402-mcp<br/>FastMCP]
    Server -->|env vars unset| InProc[In-process 模式<br/>PIIFilter / PolicyEngine / ReplayGuard]
    Server -->|REMOTE_BASE_URL + API_KEY set| Proxy[HTTP-proxy 模式<br/>screen_payment_metadata only]
    Proxy -->|HTTPS / httpx| RemoteSvc[远端筛查服务<br/>screening-api v0.4.0]
    InProc --> Parent[父库 presidio-hardened-x402]
    Proxy -.wire-contract parity.-> Parent
```

## 传输、配置与契约对齐

服务器使用 [server.json](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/server.json) 声明的 stdio 传输，`runtimeHint` 为 `uvx`，意味着最终用户通过 `uvx presidio-hardened-x402-mcp` 拉起，无需手动管理虚拟环境。

资料来源：[server.json:1-20]()

所有配置通过 `PRESIDIO_X402_MCP_*` 前缀环境变量注入，文档明确要求用户在 MCP 客户端的 `env:` 块中设置，避免经由 shell 历史或全局可读文件泄露。其中 `PRESIDIO_X402_MCP_REMOTE_API_KEY` 在 `server.json` 中按 SECRET 类约定标识，允许客户端 UI 在日志中自动遮蔽。

资料来源：[README.md:90-110]() · [SECURITY.md:30-45]()

**Wire-contract parity** 是本包的核心设计原则：in-process 与 remote 两种模式接受完全相同的输入形态、字段长度上限（`resource_url ≤ 2048`、`description ≤ 4096`、`reason ≤ 4096`）以及实体发现结构，超长输入直接抛 `ValueError`。这确保一份被 in-process 接受的 payload 也可被远端 v0.4.0 screening-api 接受，反之亦然——模式只是传输细节，不是语义差异。

资料来源：[README.md:40-55]() · [PRESIDIO-REQ.md:50-65]()

## 设计原则与发布治理

`PRESIDIO-REQ.md` 总结的五条核心原则：**stdout 严格纪律**（JSON-RPC 帧不可被污染）、**绝不静默回退**（远端失败必须显式上报）、**组合优于替代**（不重复端点声誉与支付执行能力）、**零配置默认**（regex 模式、无策略、内存级重放、`NullAuditWriter`）、**线契约一致性**。这些原则共同塑造了一个"对失败可见、对配置可选、对组合开放"的安全工具。

资料来源：[PRESIDIO-REQ.md:90-110]() · [SECURITY-AUDIT.md:1-15]() · [SECURITY.md:25-40]()

发布流程采用 PyPI [Trusted Publishing (OIDC)](https://docs.pypi.org/trusted-publishers/)：无长期 API token，标签推送触发 `release.yml`，配合 `pypi` GitHub Environment 的强制审查者 (mandatory reviewer) 形成人工把关。`SECURITY-AUDIT.md` 进一步识别出若干可硬化项——CI 工作流缺少顶层 `permissions: contents: read` 块、GitHub Actions 仍以浮动 tag 而非 commit SHA 钉版、`PRESIDIO_X402_MCP_REMOTE_BASE_URL` 上未做 `https://` scheme 强制——这些均为当前版本 `0.1.1`（参见 `src/presidio_x402_mcp/__init__.py`）的硬化建议而非阻塞缺陷。

资料来源：[PUBLISHING.md:1-50]() · [SECURITY-AUDIT.md:1-60]() · [src/presidio_x402_mcp/__init__.py:1-5]()

## See Also

- 工具 API 详解与示例输出：参见 README.md 的 Tools 章节
- 完整需求与延期项：参见 [PRESIDIO-REQ.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PRESIDIO-REQ.md)
- 安全策略与 MCP-specific 注意事项：[SECURITY.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY.md)
- 安全审计与可硬化项：[SECURITY-AUDIT.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY-AUDIT.md)
- 发布流程：[PUBLISHING.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PUBLISHING.md)
- 父库能力：[presidio-hardened-x402](https://github.com/presidio-v/presidio-hardened-x402)
- 配套端点安全：[x402station-mcp](https://github.com/sF1nX/x402station-mcp)

---

<a id='page-2'></a>

## MCP Tools & API Reference

### 相关页面

相关主题：[Project Overview & Architecture](#page-1), [Configuration, Modes & Deployment](#page-3), [Security, Composability & Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/presidio_x402_mcp/server.py](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/src/presidio_x402_mcp/server.py)
- [src/presidio_x402_mcp/__init__.py](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/src/presidio_x402_mcp/__init__.py)
- [README.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/README.md)
- [PRESIDIO-REQ.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PRESIDIO-REQ.md)
- [SECURITY.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY.md)
- [server.json](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/server.json)
- [CHANGELOG.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/CHANGELOG.md)
- [PUBLISHING.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PUBLISHING.md)
- [SECURITY-AUDIT.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY-AUDIT.md)
</details>

# MCP Tools & API Reference

## 概述

`presidio-hardened-x402-mcp` 是一个**轻量级的 MCP（Model Context Protocol）适配器**，它通过 stdio JSON-RPC 传输协议，将父库 [`presidio-hardened-x402`](https://github.com/presidio-v/presidio-hardened-x402) 中的安全原语（PII 检测、支出策略、重放防护）暴露给自主智能体使用。该包是 [Presidio hardened 工具链](https://github.com/presidio-v) 的一部分，当前版本为 `0.1.1`（[`src/presidio_x402_mcp/__init__.py:3`](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/src/presidio_x402_mcp/__init__.py)）。

根据 v0.1.0 MVP 要求，该服务器必须暴露**三个强制 MCP 工具**，并在 stdio 上通过 `mcp.server.fastmcp.FastMCP` 运行（[PRESIDIO-REQ.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PRESIDIO-REQ.md)）。`server.json` 中声明的传输类型为 `stdio`，运行时提示为 `uvx`（[server.json:13-21](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/server.json)）。

## 工具详情

### Tool 1：`screen_payment_metadata`

封装父库的 `PIIFilter.scan_payment_fields()`，执行**预签名 PII 筛选**，捕获支付元数据中的邮箱、SSN、电话号码、姓名等敏感数据。该工具**无副作用**。

| 参数 | 类型 | 约束 | 说明 |
|------|------|------|------|
| `resource_url` | string | ≤ 2048 字符 | 资源 URL |
| `description` | string | ≤ 2048 字符 | 资源描述 |
| `reason` | string | ≤ 2048 字符 | 支付原因 |
| `entities` | list\<string\>? | 可选 | 允许的实体白名单 |

返回结构包含**脱敏后的字符串**与**每个字段的实体计数**。字段长度上限与 v0.4.0 screening-api 线协议完全一致（[PRESIDIO-REQ.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PRESIDIO-REQ.md)）。

### Tool 2：`check_payment_policy`

封装 `PolicyEngine.check_and_record()`，充当**支出策略网关**。调用者必须在实际支付前**立即**调用此工具。

- **输入**：`resource_url`、`amount_usd`
- **输出**：`{allowed: bool, ...}`
- **副作用**：成功时**记录支出**（调用即消耗网关预算）
- 抛出 `PolicyViolationError` 异常（[src/presidio_x402_mcp/server.py](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/src/presidio_x402_mcp/server.py)）

### Tool 3：`check_payment_replay`

封装 `compute_fingerprint()` 与 `ReplayGuard.check_and_record()`，执行**基于指纹的重放检测**。

```jsonc
// 输入
{
  "resource_url": "https://api.foo.com/x",
  "pay_to": "0xabc...",
  "amount": "1.50",
  "currency": "USDC",
  "deadline_seconds": 1700000000
}

// 输出（首次见到）
{ "is_replay": false, "fingerprint": "29aaf60f..." }
```

成功时**记录指纹**，TTL 默认 300 秒（`PRESIDIO_X402_MCP_REPLAY_TTL`）。可通过 `PRESIDIO_X402_MCP_REDIS_URL` 切换至 Redis 以实现跨进程状态共享（[README.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/README.md)）。

## 执行模式

服务器支持两种执行模式（[README.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/README.md)）：

| 模式 | 触发条件 | 行为 |
|------|----------|------|
| **In-process**（默认） | 无远程环境变量 | 包装本地库，无网络、无 API Key、无配额，PII 不离开智能体主机 |
| **HTTP-proxy** | 同时设置 `REMOTE_BASE_URL` + `REMOTE_API_KEY` | Tool 1 调用 `/v1/screen` 远程服务，**失败时返回结构化错误而非静默回退** |

Tool 2 与 Tool 3 始终在进程内执行，不受远程模式影响（[PRESIDIO-REQ.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PRESIDIO-REQ.md)）。

## 配置与环境变量

所有运行时参数均通过 `PRESIDIO_X402_MCP_*` 环境变量配置（[README.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/README.md)），在 MCP 宿主配置文件的 `env:` 块中传递。关键变量包括：

- `PRESIDIO_X402_MCP_LOG_LEVEL` — 默认 `INFO`，所有诊断输出通过 `logging` 写入 **stderr**
- `PRESIDIO_X402_MCP_AUDIT_PATH` — 可选的 JSON-L 审计日志路径
- `PRESIDIO_X402_FINGERPRINT_KEY` / `PRESIDIO_X402_CHAIN_KEY` — 跨进程密钥（使用 `openssl rand -hex 32` 生成）

## 安全注意事项

stdio MCP 服务器**严禁向 stdout 写入任何内容**，否则会破坏 JSON-RPC 帧结构。默认的 `NullAuditWriter` 与基于 `logging` 的日志配置即为此防护（[SECURITY.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY.md)）。Tool 2 与 Tool 3 每次调用都会**变更状态**（支出账本 / 指纹缓存），调用方文档中已明确警告此副作用（[PRESIDIO-REQ.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PRESIDIO-REQ.md)）。

## 发布与审计

该包通过 Trusted Publishing（OIDC）发布至 PyPI，无需 API Token（[PUBLISHING.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PUBLISHING.md)）。2026-06-03 的安全审计未发现严重漏洞，主要建议包括对 `PRESIDIO_X402_MCP_REMOTE_BASE_URL` 强制启用 `https://` 协议以及为 GitHub Actions 固定完整提交 SHA（[SECURITY-AUDIT.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY-AUDIT.md)）。

## See Also

- [README.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/README.md)
- [PRESIDIO-REQ.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PRESIDIO-REQ.md)
- [SECURITY.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY.md)
- [父库仓库](https://github.com/presidio-v/presidio-hardened-x402)
- [MCP 规范](https://modelcontextprotocol.io)
- [x402 协议](https://x402.org)

---

<a id='page-3'></a>

## Configuration, Modes & Deployment

### 相关页面

相关主题：[Project Overview & Architecture](#page-1), [MCP Tools & API Reference](#page-2), [Security, Composability & Operations](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/presidio_x402_mcp/server.py](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/src/presidio_x402_mcp/server.py)
- [src/presidio_x402_mcp/__init__.py](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/src/presidio_x402_mcp/__init__.py)
- [README.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/README.md)
- [server.json](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/server.json)
- [PUBLISHING.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PUBLISHING.md)
- [PRESIDIO-REQ.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PRESIDIO-REQ.md)
- [SECURITY.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY.md)
- [SECURITY-AUDIT.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY-AUDIT.md)
- [CHANGELOG.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/CHANGELOG.md)
- [pyproject.toml](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/pyproject.toml)
</details>

# Configuration, Modes & Deployment

## 概述

`presidio-hardened-x402-mcp` 是 `presidio-hardened-x402` 库的 Model Context Protocol (MCP) 适配层，在不重新实现任何安全原语的前提下，通过 stdio 把 PII 过滤、策略引擎和重放检测三项能力暴露给自主代理。`PRESIDIO-REQ.md` 把「Zero-config default」与「Mode is a transport detail, not a semantic difference」列为顶层设计准则——未设置环境变量时即开箱即用的进程内模式，需要集中审计或跨进程状态时再按需升级到 HTTP 代理模式。配置、模式与发布三者的关系由该原则贯穿。

## 环境变量配置

所有运行时配置都通过 `PRESIDIO_X402_MCP_*` 前缀的环境变量传入。`README.md` 的 Configuration 节列出了完整清单，汇总如下表（资料来源：[README.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/README.md)）：

| 变量 | 用途 | 默认值 |
|------|------|--------|
| `PRESIDIO_X402_MCP_ENTITIES` | 逗号分隔的 Presidio 实体类型白名单 | 未设置（检测全部已配置实体） |
| `PRESIDIO_X402_MCP_REMOTE_BASE_URL` | 远程筛查服务的基础 URL | 未设置（关闭代理模式） |
| `PRESIDIO_X402_MCP_REMOTE_API_KEY` | 远程服务 API 密钥，`server.json` 标记为 `isSecret: true` | 未设置 |
| `PRESIDIO_X402_MCP_AUDIT_PATH` | 审计记录输出文件路径 | 未设置（使用 `NullAuditWriter`） |
| `PRESIDIO_X402_REPLAY_KEY` | 32 字节 hex，跨进程重放检测密钥 | 未设置（per-process） |
| `PRESIDIO_X402_CHAIN_KEY` | 32 字节 hex，跨进程审计链 HMAC 密钥 | 未设置（per-process） |

`SECURITY.md` 指出：仅 `PRESIDIO_X402_MCP_REMOTE_API_KEY` 是真正的秘密类配置，运维时应通过 MCP 客户端配置文件的 `env:` 块注入，避免写入 shell 历史或全局可读文件。`README.md` 同时建议跨进程密钥用 `openssl rand -hex 32` 生成。

## 执行模式

服务器在 `src/presidio_x402_mcp/server.py` 中通过 `_REMOTE_ENABLED` 标志在两种模式间选择：

- **进程内模式（默认）**：当 `PRESIDIO_X402_MCP_REMOTE_BASE_URL` 未设置时启用，工具在调用线程内直接执行 `PIIFilter.scan_payment_fields()`，无网络、无 API 密钥、无配额，返回结果带 `"mode": "in_process"` 标记。
- **HTTP 代理模式（opt-in）**：仅当基础 URL 被设置时启用，对应 `_scan_remote()` 实现（资料来源：[src/presidio_x402_mcp/server.py:155-211](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/src/presidio_x402_mcp/server.py#L155-L211)）。该模式调用 `httpx.AsyncClient`，并使用 `httpx.Timeout(10.0, connect=3.0)` 防止远程服务挂起拖垮代理；TLS 校验默认开启。

`SECURITY-AUDIT.md` 把远程模式定义为有意的「大声失败」设计：失败时返回结构化 `{error, detail, ...}` 判别字段（`auth_error` / `rate_limit` / `unavailable`），**不会**静默回退到进程内模式——这保证了集中审计被旁路时调用方一定能察觉。该行为与 `PRESIDIO-REQ.md` 中的「No silent fallback」准则相对应。

## 部署

### MCP 宿主配置

`server.json` 声明运行提示为 `uvx`、传输类型为 stdio、当前版本 `0.1.1`（资料来源：[server.json](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/server.json)），与 `src/presidio_x402_mcp/__init__.py` 中的 `__version__` 保持一致（资料来源：[src/presidio_x402_mcp/__init__.py](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/src/presidio_x402_mcp/__init__.py)）。MCP 客户端应在其 `mcpServers` 块中通过 `env` 字段声明上述环境变量，并以 `command: ["uvx", "presidio-hardened-x402-mcp"]` 启动。

### PyPI 发布流程

`PUBLISHING.md` 描述了基于 PyPI Trusted Publishing（OIDC）的零密钥发布链（资料来源：[PUBLISHING.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PUBLISHING.md)）：

1. 一次性在 PyPI 注册 pending publisher：Owner = `presidio-v`，Workflow = `release.yml`，Environment = `pypi`
2. 一次性在 GitHub 创建同名 `pypi` 环境，并**强制设置 required reviewers**——这是唯一阻止被攻陷的 `v*.*.*` tag push 直接发布到 PyPI 的人工关卡
3. 打标签并推送后 `release.yml` 自动 `uv build` 出 sdist + wheel，再以 OIDC token 推送到 PyPI

`pyproject.toml` 把 `mcp[cli]` 锁在 `<2.0.0` 但对父库 `presidio-hardened-x402` 没有上限（资料来源：[pyproject.toml:29-32](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/pyproject.toml)）。`SECURITY-AUDIT.md` Finding 4 提醒：`uvx` 运行时不会读取本仓库的 `uv.lock`，端用户实际收到的是 PyPI 上的最新版——发布前需严格把关上游版本，必要时锁定具体版本。

## 部署安全注意事项

- **stdout 纪律**：`SECURITY.md` 与 `SECURITY-AUDIT.md` 均强调 stdio MCP 服务器不能向 stdout 写入任何内容，否则会破坏 JSON-RPC 帧；所有日志走 `logging`（stderr），审计默认走 `NullAuditWriter`
- **HTTPS 强制缺失**：`SECURITY-AUDIT.md` Finding 1 指出 `PRESIDIO_X402_MCP_REMOTE_BASE_URL` 未对 `https://` 做强制校验，运维侧应在入口校验或前置网关中补齐
- **CI 权限收敛**：`SECURITY-AUDIT.md` Finding 2 建议在 `.github/workflows/*.yml` 顶部加 `permissions: contents: read`，把默认 token 权限收敛到最小
- **版本一致性**：根据 `CHANGELOG.md` v0.1.0 → v0.1.1 的变更纪律，`server.json` 的 `version`、`__init__.py` 的 `__version__` 与 `pyproject.toml` 的 `version` 三者必须同步更新（资料来源：[CHANGELOG.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/CHANGELOG.md)）

## See Also

- [README.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/README.md) — 工具说明与配置表
- [PRESIDIO-REQ.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PRESIDIO-REQ.md) — 设计准则与威胁模型
- [SECURITY-AUDIT.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY-AUDIT.md) — 审计发现与缓解建议
- [PUBLISHING.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PUBLISHING.md) — Trusted Publishing 详细配置
- [CHANGELOG.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/CHANGELOG.md) — 版本演进与发布纪律

---

<a id='page-4'></a>

## Security, Composability & Operations

### 相关页面

相关主题：[Project Overview & Architecture](#page-1), [MCP Tools & API Reference](#page-2), [Configuration, Modes & Deployment](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [SECURITY.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY.md)
- [SECURITY-AUDIT.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/SECURITY-AUDIT.md)
- [README.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/README.md)
- [CHANGELOG.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/CHANGELOG.md)
- [PUBLISHING.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PUBLISHING.md)
- [PRESIDIO-REQ.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/PRESIDIO-REQ.md)
- [server.json](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/server.json)
</details>

# Security, Composability & Operations

本页聚焦于 `presidio-hardened-x402-mcp` 的安全模型、与其他 MCP 服务器的可组合性，以及发布/运维/供应链层面的关键设计。

## 1. 安全模型与 MCP 专项威胁缓解

本仓库是一个**薄适配器**（thin adapter），所有安全原语——PII 识别准确度、策略引擎语义、重放保护加密、审计链 HMAC——均由上游库 `presidio-hardened-x402` 实现，并由其 `SECURITY.md` 单独负责威胁建模；本仓库只承担 MCP 适配层相关的安全职责 资料来源：[SECURITY.md:30-50]()。

### 1.1 信任边界

- **stdin/stdout JSON-RPC 帧保护**：stdio MCP 服务器严禁向 stdout 写入任何内容，否则会破坏 JSON-RPC 帧。默认审计写入器为 `NullAuditWriter`，所有诊断信息经 `logging` 模块输出到 stderr 资料来源：[SECURITY.md:32-40]()。
- **环境变量注入防护**：所有配置通过 `PRESIDIO_X402_MCP_*` 前缀环境变量注入；其中 `PRESIDIO_X402_MCP_REMOTE_API_KEY` 被声明为 secret 类，MCP 客户端 UI 可在日志中自动脱敏 资料来源：[PRESIDIO-REQ.md]()`。
- **HTTP 代理模式信任外移**：当同时设置 `PRESIDIO_X402_MCP_REMOTE_BASE_URL` 与 `..._REMOTE_API_KEY` 时，支付元数据离开 agent 主机；远程筛查服务成为新的信任边界，部署前需校验其 TLS 与审计策略 资料来源：[SECURITY.md:42-50]()`。

### 1.2 威胁与缓解策略

| 威胁 | 缓解策略 |
|---|---|
| stdout 污染破坏 JSON-RPC 帧 | 生产代码路径不调用 `print()`；默认 `NullAuditWriter`；日志全部经 `logging` 走 stderr |
| 环境变量注入的密钥经进程列表泄露 | 仅 `REMOTE_API_KEY` 属于 secret 类；通过 MCP 客户端 `env:` 块注入并以合适文件系统权限保护 |
| HTTP 代理模式下中央审计旁路的静默回退 | 远程失败返回结构化 `{error: ...}` 判别符，由 agent 显式决策而非静默降级到进程内 |
| `check_payment_policy` / `check_payment_replay` 状态副作用被误用 | 工具 docstring、README、`server.json` 中显式声明副作用；调用者必须明确知晓其会写入消费账本与指纹缓存 |

资料来源：[PRESIDIO-REQ.md]()、[README.md]()`。

## 2. 与其他 MCP 服务器的可组合性

本仓库明确**不重复**生态已有能力，而是通过组合形成分层防护：

- **端点安全（preflight）**：由 `x402station-mcp` 负责（decoy、dead endpoint、price trap 等信誉信号）。其网络级护城河（每 10 分钟探测 `agentic.market` 全部 listing）非本项目可复制 资料来源：[PRESIDIO-REQ.md]()`。
- **支付执行**：由 Coinbase x402 MCP、MetaMask `mcp-x402`、`Sardis` 等执行类 MCP 负责；本项目只做载荷筛查，**不签名、不发送** 资料来源：[PRESIDIO-REQ.md]()`。
- **本项目定位**：在 preflight 之后、签名之前，对 `resource_url` / `description` / `reason` 做 PII 筛查（载荷层安全），与 `x402station-mcp` 串联形成 preflight → screen → pay 的两段式防护 资料来源：[CHANGELOG.md:7-10]()`。

```mermaid
flowchart LR
    A[Agent Host] -->|preflight| B[x402station-mCP<br/>端点信誉]
    B -->|endpoint safe| C[presidio-hardened-x402-mCP<br/>载荷 PII 筛查]
    C -->|payload safe| D[Payment Execution MCP<br/>签名/发送]
    D -->|paid| E[Merchant]
```

## 3. 运维：发布流水线与供应链

### 3.1 Trusted Publishing

发布至 PyPI 使用 Trusted Publishing（OIDC），不涉及长期 API token 或仓库 secret 资料来源：[PUBLISHING.md:1-5]()`。首次发布前需在 PyPI 注册 pending publisher，关键字段包括：PyPI Project Name `presidio-hardened-x402-mcp`、Owner `presidio-v`、Workflow name `release.yml`、Environment name `pypi` 资料来源：[PUBLISHING.md:9-21]()`。

### 3.2 GitHub 环境保护

必须在 GitHub 端创建 `pypi` 环境并**强制设置 Required reviewers**；此审核门是 push tag 与真实 PyPI 发布之间的唯一隔离层，对安全工具类包应视为非可选 资料来源：[PUBLISHING.md:26-33]()`。

### 3.3 锁文件与依赖

依赖通过 `uv.lock` 锁定；CI 强制检查 lockfile drift；`pip-audit` 在每个 PR 上运行，中危及以上 CVE 在无书面豁免时阻断合并 资料来源：[SECURITY.md:55-60]()`。需要注意的是，`mcp[cli]>=1.27.2,<2.0.0` 设定了主版本上限，但 `presidio-hardened-x402>=0.4.0` 无上限；运行时通过 `uvx` 解析不查询本仓库 lockfile，端到端用户实际获取的是 PyPI 上最新版 资料来源：[SECURITY-AUDIT.md:1-50]()`、`server.json`()`。

## 4. 已知风险与硬化建议（来自 SECURITY-AUDIT）

- **中危**：`PRESIDIO_X402_MCP_REMOTE_BASE_URL` 未强制 `https://` scheme，可能导致 PII 与 API key 经明文 HTTP 泄露 资料来源：[SECURITY-AUDIT.md]()`。
- **低-中危**：CI 工作流缺少顶层 `permissions:` 块，继承默认 `GITHUB_TOKEN` 读写权限；建议显式声明 `permissions: contents: read` 并按需覆盖 资料来源：[SECURITY-AUDIT.md]()`。
- **低-中危**：GitHub Actions 通过浮动 tag 引用（如 `actions/checkout@v6`、`pypa/gh-action-pypi-publish@release/v1`），存在供应链标签漂移风险；建议改用完整 commit SHA 钉死 资料来源：[SECURITY-AUDIT.md]()`。

## 5. 部署注意事项

- `PRESIDIO_X402_FINGERPRINT_KEY` 与 `PRESIDIO_X402_CHAIN_KEY` 未设置时回退到进程内内存存储；跨进程部署必须显式提供 32 字节十六进制 key（可用 `openssl rand -hex 32` 生成）资料来源：[README.md]()`、`SECURITY-AUDIT.md:1-80]()`。
- 默认审计关闭（`NullAuditWriter`），需通过 `PRESIDIO_X402_MCP_AUDIT_PATH` 显式开启 资料来源：[SECURITY-AUDIT.md:1-80]()`。
- `check_payment_policy` 与 `check_payment_replay` 每次成功调用都会写入状态（消费账本/指纹缓存），重复调用等于重复扣费或重复登记重放 资料来源：[SECURITY.md:50-55]()`。

## See Also

- 父库威胁建模：[presidio-hardened-x402 SECURITY.md](https://github.com/presidio-v/presidio-hardened-x402/blob/main/SECURITY.md)
- 端点信誉层：[x402station-mcp](https://github.com/sF1nX/x402station-mcp)
- 家族 SDLC 规范：[presidio-hardened-docs/sdlc](https://github.com/presidio-v/presidio-hardened-docs/blob/main/sdlc/sdlc-report.md)
- 版本变更历史：[CHANGELOG.md](https://github.com/presidio-v/presidio-hardened-x402-mcp/blob/main/CHANGELOG.md)

---

<!-- evidence_pipeline_checked: true -->

---

## Doramagic 踩坑日志

项目：presidio-v/presidio-hardened-x402-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

## 1. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/presidio-v/presidio-hardened-x402-mcp | host_targets=mcp_host, claude_code, claude, cursor

## 2. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/presidio-v/presidio-hardened-x402-mcp | README/documentation is current enough for a first validation pass.

## 3. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/presidio-v/presidio-hardened-x402-mcp | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/presidio-v/presidio-hardened-x402-mcp | no_demo; severity=medium

## 5. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/presidio-v/presidio-hardened-x402-mcp | no_demo; severity=medium

## 6. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/presidio-v/presidio-hardened-x402-mcp | issue_or_pr_quality=unknown

## 7. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/presidio-v/presidio-hardened-x402-mcp | release_recency=unknown

<!-- canonical_name: presidio-v/presidio-hardened-x402-mcp; human_manual_source: deepwiki_human_wiki -->