项目概述与定位

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 的薄适配层 (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 通道：

资料来源：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

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 声明的 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)：无长期 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
• 安全策略与 MCP-specific 注意事项：SECURITY.md
• 安全审计与可硬化项：SECURITY-AUDIT.md
• 发布流程：PUBLISHING.md
• 父库能力：presidio-hardened-x402
• 配套端点安全：x402station-mcp

概述

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

根据 v0.1.0 MVP 要求，该服务器必须暴露三个强制 MCP 工具，并在 stdio 上通过 mcp.server.fastmcp.FastMCP 运行（PRESIDIO-REQ.md）。server.json 中声明的传输类型为 stdio，运行时提示为 uvx（server.json:13-21）。

工具详情

Tool 1：`screen_payment_metadata`

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

返回结构包含脱敏后的字符串与每个字段的实体计数。字段长度上限与 v0.4.0 screening-api 线协议完全一致（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）

Tool 3：`check_payment_replay`

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

// 输入
{
  "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）。

执行模式

服务器支持两种执行模式（README.md）：

Tool 2 与 Tool 3 始终在进程内执行，不受远程模式影响（PRESIDIO-REQ.md）。

配置与环境变量

所有运行时参数均通过 PRESIDIO_X402_MCP_* 环境变量配置（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）。Tool 2 与 Tool 3 每次调用都会变更状态（支出账本 / 指纹缓存），调用方文档中已明确警告此副作用（PRESIDIO-REQ.md）。

发布与审计

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

See Also

• README.md
• PRESIDIO-REQ.md
• SECURITY.md
• 父库仓库
• MCP 规范
• x402 协议

概述

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）：

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）。该模式调用 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），与 src/presidio_x402_mcp/__init__.py 中的 __version__ 保持一致（资料来源：src/presidio_x402_mcp/__init__.py）。MCP 客户端应在其 mcpServers 块中通过 env 字段声明上述环境变量，并以 command: ["uvx", "presidio-hardened-x402-mcp"] 启动。

PyPI 发布流程

PUBLISHING.md 描述了基于 PyPI Trusted Publishing（OIDC）的零密钥发布链（资料来源：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）。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）

See Also

• README.md — 工具说明与配置表
• PRESIDIO-REQ.md — 设计准则与威胁模型
• SECURITY-AUDIT.md — 审计发现与缓解建议
• PUBLISHING.md — Trusted Publishing 详细配置
• CHANGELOG.md — 版本演进与发布纪律

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 威胁与缓解策略

资料来源：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`。

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
• 端点信誉层：x402station-mcp
• 家族 SDLC 规范：presidio-hardened-docs/sdlc
• 版本变更历史：CHANGELOG.md

Pitfall Log / 踩坑日志

项目：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