内容
# @fidacy/mcp
适用于AI代理的行动防火墙。 一个可直接使用的MCP服务器，在资金流动之前，根据加密签名的授权 **阻止** 或 **允许** 支付行动。
非托管：Fidacy授权并证明，但从不持有资金。
只需安装一次，即可在任何与MCP兼容的代理中使用：Claude Code、Claude Desktop、Hermes、OpenClaw以及其他支持MCP的代理。
[](https://www.npmjs.com/package/@fidacy/mcp)
[](https://www.npmjs.com/package/@fidacy/mcp)
**支持：** Claude Code · Claude Desktop · OpenClaw · Hermes · Brex CrabTrap
> **您的代理可能正在向诈骗者支付款项。** 如果提示注入到错误的收款人、膨胀的金额或重复的发票 - 而您的日志不是证据。Fidacy在资金流动之前 **阻止** 支付，并返回一个签名判决，**任何人都可以验证** 该判决的真实性。
## 快速开始（免费，本地优先，无需账户）
```json
{
"mcpServers": {
"fidacy": { "command": "npx", "args": ["-y", "@fidacy/mcp"] }
}
}
```
在您的机器上运行，离线，默认拒绝。 在`~/.fidacy/config.json`中添加受信任的收款人和上限。 通过[`/.well-known/jwks.json`](https://api.fidacy.com/.well-known/jwks.json)验证任何判决。
## 为什么
代理可能会幻觉或被提示注入支付：错误的收款人、错误的金额、伪造的发票。提示级别的防护是概率性的，可以绕过。`@fidacy/mcp`是代理意图和执行器之间的确定性门槛：除非行动根据签名授权验证，否则该行动将被阻止，并且每个决定都会记录在不可篡改的哈希链审计跟踪中。
## 强制执行模型
1. 将`@fidacy/mcp`注册为代理 **唯一** 的具有支付能力的工具。 不要给代理原始支付工具。 工具清单是运行时防火墙。
2. 代理调用`request_payment`。 Fidacy根据授权（收款人白名单、每笔交易上限、总上限、货币、时间窗口、吊销）检查它。
3. ALLOW返回一个短期的Ed25519 **授权令牌**。 DENY返回不授予令牌和违反的规则。下游执行器必须要求授权令牌，因此拒绝的行动不能继续。
4. 每个决定都追加到哈希链日志中。 `get_audit_proof`返回可移植的、可验证的证明。
## 一个安装，两个后端
`@fidacy/mcp`提供两个互补的功能：
- **判决层（建议）**：`assess_action`调用实时Fidacy引擎并返回 **签名信任判决**。 它不移动资金；它返回一个可以通过`@fidacy/verify`针对引擎JWKS在`/.well-known/jwks.json`验证的证明。
- **支付防火墙（强制执行）**：`request_payment` / `verify_mandate` / `get_audit_proof`通过核心根据签名授权阻止和证明支付，返回短期Ed25519授权令牌。
思维模型：`assess_action` -> **引擎**（签名判决）；`request_payment`和朋友 -> **核心**（支付防火墙）。
## 工具
| 工具 | 后端 | 目的 |
|---|---|---|
| `assess_action` | 引擎 | 为提议的行动提供签名的Fidacy信任判决。 建议。 |
| `request_payment` | 核心 | 授权支付行动。 ALLOW + 授权令牌，或DENY + 规则。 |
| `verify_mandate` | 核心 | 读取授权信封 + Fidacy公钥。 |
| `get_audit_proof` | 核心 | 决策ID的哈希链证明。 |
### `assess_action`
从实时引擎为提议的行动返回签名的Fidacy信任判决。 签名证明是`riskPayloadJws` + `signingKeyId`，可以通过`@fidacy/verify`针对`{engineUrl}/.well-known/jwks.json`验证。
输入：
- `kind`（可选，默认`ap2_payment`）：`ap2_payment`、`message_send`、`voice_call`、`custom`、`claim_document`之一。
- `mandate`（必填）：该`kind`的行动/授权对象。
- `mandateType`、`spendingMandate`、`idempotencyKey`、`a2a.task_id`（可选）。
环境：
| 变量 | 默认值 | 目的 |
|---|---|---|
| `FIDACY_ENGINE_URL` | `https://api.fidacy.com` | Fidacy引擎的基本URL。 |
| `FIDACY_ENGINE_API_KEY` | （无） | 具有范围`assess:write`的`fky_live_` / `fky_test_`密钥。 |
服务器在没有`FIDACY_ENGINE_API_KEY`的情况下启动；该工具始终注册。只有**调用** `assess_action`而没有密钥时，才会返回一个有帮助的错误，提示您设置它。 密钥从不记录、回显或附加到任何错误。
## 安装
```bash
npm install -g @fidacy/mcp # 或使用npx运行，无需安装
```
### Claude Code
```bash
claude mcp add fidacy -- npx -y @fidacy/mcp
```
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"fidacy": { "command": "npx", "args": ["-y", "@fidacy/mcp"] }
}
}
```
### Hermes (`config.yaml`)
```yaml
mcp_servers:
fidacy:
command: npx
args: ["-y", "@fidacy/mcp"]
```
### OpenClaw
通过工具面板或代理配置中的`mcpServers`块添加相同的服务器。 任何MCP兼容的主机都使用相同的命令。
## 连接真实的核心（生产）
MCP层通过一个接口（`FidacyCore`）与您的核心通信。 您的存储库保持私有。 设置`FIDACY_MODE=http`并实现三个端点：
- `POST /v1/mandate/get` -> `Mandate`
- `POST /v1/decide` -> `Decision`（运行您的Ed25519/AP2验证 + 审计追加）
- `POST /v1/audit/proof` -> `AuditProof`
MCP层无需更改。
## 开发
```bash
npm install
npm run build
npm start # 标准输入输出服务器，内存演示授权
```
