xrey167/meshmcp

MCP server 通常是本地 stdio 进程或开放的 HTTP 端口。跨机器安全共享意味着需要 VPN、反向代理、身份验证层、审计流水线（pipeline），并且还要期盼连接保持稳定。**meshmcp 将所有这些压缩成一个库**，包裹在你已有的任何 MCP server 外围 — 将连接、身份、策略和证明作为五个可组合的层： ``` clients / agents / IDEs ── meshmcp call · connect · your MCP client │ ════════════▼════════════ WireGuard mesh · no public ports · nmap finds nothing │ │ │ UNDERSTAND insight │ policy from behavior: profile · recommend · simulate · detect │ PROVE audit │ Ed25519-signed, hash-chained log · dashboard · replay │ ENFORCE firewall │ policy engine: rate · window · taint · data-flow labels · co-sign │ CONNECT mesh │ cryptographic identity · resumable + migratable sessions │ │ ════════════▼════════════ any MCP server (stdio or HTTP), unmodified · fs · fetch · db · your tools ``` 可以通过聚合 **router**、托管的 **control plane** 以及跨组织的 **federation** 来进行扩展。 ## 独特之处 许多 MCP gateway 基于调用者提供的 application-layer header 或 bearer token 进行授权。而 meshmcp 则以**传输层证明的 WireGuard 公钥**作为策略、审计和路由的基准 — 身份在每个强制执行点均派生自已验证的传输层，而不是从调用者提供的 header、`_meta` 或请求体中读取。调用者无法出示其不持有私钥的身份。这是身份验证和工作负载身份（workload identity）；它本身**并不**等于授权 — 每个特权表面还额外强制执行默认拒绝（default-deny）策略（关于此边界的适用范围及不适用情形，例如被入侵的 mesh 内 peer 或持有密钥的内部人员，请参阅威胁模型）。 | | | |---|---| | 🔒 **零暴露** | 后端仅监听 mesh 接口。没有公共端口可供扫描、钓鱼或 DDoS。 | | 🪪 **加密身份** | 每个请求都会解析为调用者的 WireGuard 公钥 + mesh FQDN — 这是策略和审计的根源，而非一项主张。 | | 🔁 **持久会话** | 通过有限、带流控的缓冲区在重连时按顺序交付帧并抑制重复；支持客户端漫游。跨 gateway 的故障转移和端到端幂等性目前处于实验阶段 — meshmcp **并不**保证严格的单次*工具执行*（请参阅威胁模型中的交付与执行保证对比）。 | | 🧱 **agent 防火墙** | 按身份对每个工具和方法进行允许/拒绝，**速率限制**，**时间窗口**，**人工共同签名（co-sign）**，以及**数据流标签** — 在越狱（jailbreak）无法触及的地方强制执行。 | | 🧾 **网关签名审计** | 每个决策都是由 **Ed25519 签名的 Merkle 检查点**封存的哈希链记录。`audit verify` 会报告四种真实状态之一 — 无效、有效但不受信任的密钥、有效但未封存的尾部，或完全封存 — 只有根据**固定（pinned）**的预期密钥验证的**已封存**日志才是完整且受信任的。它对文件编辑器具有防篡改可见性，但并不能证明现实世界中的每一个操作都确实发生过；持有密钥的内部人员需要外部锚定。 | | 🧠 **源于行为的策略** | `insight` 分析 agent 的实际行为，**生成**最小权限策略，针对真实流量**模拟**变更（CI gate），并**检测**偏移。 | | 🔑 **凭证代理** | Agent 按名称引用 secret (`{{secret:stripe_key}}`)；gateway 根据身份将其注入到声明的 backend 参数中，审计其使用情况（仅限名称，绝不包含值），并拒绝将其注入到受污染的会话中。此保证是**凭证隔离** — agent 不会从 gateway 接收到 secret — 而不是绝对保证该值永远不会被观察到：恶意 backend 仍处于 secret 的暴露边界内（参见威胁模型）。 | | 🎟️ **签名能力** | 短期、绑定主体的 Ed25519 授权可**升级策略默认拒绝**而无需编辑配置 — 固定信任根，绑定到调用者的 WireGuard 密钥，在到达 backend 前剥离，失败即关闭。绝不会覆盖明确的拒绝或共同签名。 | | 🌐 **扩展与联合** | 聚合 router（LB · 故障转移 · 发现 · 双向 MCP）、托管的 control plane 以及身份映射的跨组织 federation。 | ## 一个平面，多个 MCP server meshmcp 本身不是 server — 它是位于你的 server **前面**的层。文件系统、web-fetcher、支付 API、客户数据库、部署流水线：每一个都是**不同**的 MCP server，未经修改地封装起来。对**其中任何一个**的每次调用都会获得相同的身份、策略、审计和 secret 注入 — router 可以将它们联合为一个命名空间的 endpoint。 ``` flowchart LR subgraph clients ["callers"] A1["agent A · read-only"] A2["agent B · billing"] A3["IDE / CLI · you"] end subgraph plane ["meshmcp — one control plane"] direction TB P1["identity"] ~~~ P2["policy"] ~~~ P3["audit"] ~~~ P4["secrets"] ~~~ P5["router"] end subgraph servers ["many different MCP servers (unmodified)"] S1["fs · stdio
read_*"] S2["web · stdio
taint_source"] S3["payments · stdio
🔑 secret · co-sign"] S4["customer-db · stdio
emit pii"] S5["deploy · stdio
⏰ window · co-sign"] S6["github · http
🔑 secret"] S7["slack · http
block pii"] S8["vectors · stdio
rate-limited"] end A1 & A2 & A3 --> plane plane --> S1 & S2 & S3 & S4 & S5 & S6 & S7 & S8 ``` 每个 server 都保持其原有特性 — 不同的工具、传输和风险。该平面为它们提供了**共享**的主干：每个调用者一个 WireGuard 身份、一种策略语言、一个防篡改账本、一个凭证代理。有关封装每一个 server 的详细示例，请参阅[ cookbook](docs/COOKBOOK.md)。 ## 快速开始 — 60 秒 ``` go build -o meshmcp . go build -o cmd/mcpserver/mcpserver.exe ./cmd/mcpserver/prompt_mcp # the demo MCP server the config runs export NB_SETUP_KEY= # 在 mesh 上提供 demo MCP server — 打印其 mesh IP（例如 100.x.y.z） meshmcp serve --config examples/demo-backends.yaml ``` 从** mesh 上的任何其他机器** — 不会向互联网暴露任何内容： ``` meshmcp ls 100.x.y.z:9101 # list tools / resources / prompts meshmcp call 100.x.y.z:9101 add --arg a=2 --arg b=40 ``` 使用 stdio 桥接将 mesh MCP server 接入 Claude Code（或任何 MCP client）： ``` { "mcpServers": { "home-tools": { "command": "meshmcp", "args": ["connect", "--resumable", "100.x.y.z:9101"], "env": { "NB_SETUP_KEY": "" } } } } ``` ## 一览 agent 防火墙 策略是声明式的，并以加密身份为基准。这是完整的语言： ``` policy: default_allow: false # deny by default rules: - peers: ["*"] # rate-limited read access for everyone tools: ["read_*", "search"] allow: true rate: { max: 30, per: "1m" } - peers: ["pubkey:"] # deploys only in business hours, one identity tools: ["deploy"] allow: true when: { days: [mon,tue,wed,thu,fri], hours: "09:00-17:00", tz: "UTC" } - peers: ["*"] # fetch brings untrusted data in … tools: ["fetch"] allow: true taint_source: true - peers: ["*"] # … so writes are blocked once tainted tools: ["write_file"] # (prompt-injection defense, network-layer) allow: true taint_guard: true - peers: ["*"] # PII may never reach an egress tool tools: ["read_customer"] allow: true emit_labels: ["pii"] - peers: ["*"] tools: ["post_external"] allow: true block_labels: ["pii"] - peers: ["*"] # money movement needs a human co-sign tools: ["transfer_funds"] allow: true require_cosign: true ``` 被拒绝的调用会收到内联的 JSON-RPC 错误；`require_cosign` 调用在人工批准之前会被挂起（`meshmcp approve …`）。不想手动编写这些内容？**从真实流量中生成它：** ``` meshmcp insight recommend audit.jsonl > policy.yaml # least-privilege policy from behavior meshmcp insight simulate audit.jsonl --policy policy.yaml # CI gate: exit ≠ 0 on regressions ``` ## 证明发生了什么 审计日志是一个防篡改的哈希链，由签名的 Merkle 检查点封存： ``` $ meshmcp audit verify audit.jsonl --checkpoints cps.jsonl --pubkey OK 1240 records, 10 signed checkpoint(s), 1240 records covered [sealed] signer SEALED & TRUSTED: gateway-signed tamper-evident decision log — every record is covered by a checkpoint signed with the pinned key. A holder of the file cannot edit a covered record without the signing key. (Anchor a checkpoint externally to also defend against a key-holding insider who rolls the log and checkpoints back together.) ``` 如果没有 `--pubkey`，签名者的身份将未经验证 (`untrusted_key`)；如果存在未封存的尾部，结果为 `unsealed`；这两种情况均以非零状态退出。只有根据预期密钥固定且**已封存**的结果才是完整且受信任的。 修改哪怕一条记录 — 即使是重新链接整个链 — 验证也会在确切的序列号处失败。具有该文件写入权限的内部人员如果缺少密钥，仍然无法伪造它。 使用 `meshmcp dash --audit audit.jsonl` 实时查看；使用 `meshmcp replay` 重放过去的会话。 ## 命令 | 命令 | 功能 | |---|---| | `serve --config ` | 加入 mesh；在 mesh 端口上暴露配置的 backend。 | | `router --config ` | 将上游聚合为一个命名空间的 endpoint（LB · 故障转移 · 发现 · 双向 MCP）。 | | `orchestrate --config ` | 提供一个通过 mesh 调用其他 server 工具的工具。 | | `control [flags]` | 托管的 control plane：节点注册（NetBird 密钥颁发）、注册表、策略分发。 | | `federate --config ` | 跨组织边界：在 mesh 间桥接授权的工具，具有身份映射和审计。 | | `connect [flags] ` | 用于 MCP client 配置的 Stdio ⇄ 远程 stdio 桥接 (`--resumable`)。 | | `forward ` | 将本地 TCP 端口转发到 mesh peer（用于 HTTP backend）。 | | `drop ` | **AirDrop** 按身份将文件投递给 mesh peer — 可恢复、E2E 加密、受策略控制、可审计（`--config` 运行接收器）。 | | `peers` | 列出可达的 mesh 身份 — “我可以向谁投递”视图。 | | `fetch ` | 通过内容哈希从 peer 的内容寻址存储中拉取 blob。 | | `push ` | 通过可恢复通道将 stdin 的 payload（剪贴板 / 任务）推送到 peer 的收件箱。 | | `air ` | **Air · Steer**：列出/引导 gateway 的实时会话、引导运行中的 agent、启动 agent、运行声明式工作流，或提供实时 Air 网页 — 所有操作均受治理和审计。 | | `pubsub --config ` · `publish` · `subscribe ` | mesh 上具有身份控制和审计功能的 **event bus** — 持久化且可恢复；`publish`/`subscribe` 代理主题（参见 [docs/PUBSUB.md](docs/PUBSUB.md)）。 | | `graphrag --config ` | 提供 `graph_search`：通过 mesh 进行向量检索 + 知识图谱实体扩展。 | | `ls · call · read · prompt ` | 从终端驱动工具 / 资源 / prompt。 | | `insight profile·recommend·simulate·detect` | 将审计流转化为策略；检测偏移。 | | `mcp [flags]` | 将 meshmcp **作为 MCP server** 运行 — 将其添加到 Claude Code / Codex 以操作 mesh（网络、调用工具、运行、批准）。 | | `hook --client --config ` | **Client-hook 防火墙** (F33)：通过策略 + DLP + 污点 + 审计来治理 Claude Code / Cursor / Codex 中的*每一个*本地工具调用 — `hook install` 会打印配置代码片段。 | | `audit verify [--checkpoints --pubkey]` | 验证日志：哈希链，或签名 + Merkle。 | | `audit keygen [--out f]` | 生成 gateway 的 Ed25519 签名密钥。 | | `audit export --in ` · `audit receipt --in ` · `audit attest --audit ` | 将账本导出为 CSV；发出可验证的来源凭证（会话工具生成了什么）；构建一个自描述、可独立验证的合规/证明包 (F32)。 | | `capability keygen [--out f]` | 生成 backend 作为信任根固定的 Ed25519 授权密钥。 | | `capability issue --subject --audience --tool [--ttl]` | 签署短期、绑定到主体的工具授权（使用 `call --capability @file` 出示）。 | | `capability revoke·list --store ` | 撤销某个能力 id（在任何地方均失败即关闭） / 列出已撤销的 id。 | | `approve --store ` | 从 CLI 对挂起的 `require_cosign` 调用进行人工共同签名。 | | `approvals --store [--approver ] [--devices --notify-webhook ]` | 通过 mesh 提供适合手机操作的共同签名批准器（`--approver` 限制可批准的人员；`--devices` 启用推送唤醒 token 注册，`--notify-webhook` 将每个新的待处理请求 POST 到一个中继器，该中继器将其分发到 APNs/FCM）。 | | `secrets check --config ` | 验证凭证代理的配置（绝不打印值）。 | | `status --audit ` · `budget --audit ` | 汇总账本（每个 peer/tool/backend + 链结论）；按身份汇总的总成本/配额（FinOps）。 | | `config validate --config ` · `doctor --config ` |验证配置（globs/windows/enums/DLP） / 运行预检就绪检查。 | | `plugins` | 列出编译进当前构建版本的扩展 (F13)。 | | `spotlight [flags] ` | **Mesh Spotlight** (F19)：联邦语义搜索 — 一个查询被分发到你的身份可以访问的搜索 backend 中，经过合并、排名并添加来源标签。 | | `market ` | **受治理的插件市场** (F14)：发布/发现 Ed25519 签名的 bundle manifest；安装时会针对固定的授权密钥 + bundle 哈希进行验证，并记录经过计量的、经审计的授权 — 不进行动态加载。 | | `dash --audit ` | 提供实时控制仪表板。 | | `room --audit ` | 提供交互式 **Control Room** — 实时网络（server、agent、决策流）**外加一个控制台**：通过 mesh 列出/调用工具，一个受治理的 `run_command` 终端，以及（可选启用 `--local-shell`）一个原始 shell。 | | `agent --role ` | 运行带有自身 mesh 身份的演示 agent 应用（reader/fetcher/billing/analyst）。 | | `replay [--fork N] ` | 重新发起被追踪的会话并对比每个响应。 | | `probe [--full\|--task] ` | 进程内 MCP 握手诊断。 | _{共享的 mesh 标志：`--setup-key` (`$NB_SETUP_KEY`) · `--management-url` · `--device-name` · `--nb-config` · `--wg-port`} ## 设计不变式 1. **永远不开放端口** — 后端仅监听 mesh 接口。 2. **身份是加密的，绝非自称** — 授权基于传输层证明的 WireGuard 密钥，而不是调用者发送的 header。 3. **拒绝是安全的默认设置** — 策略即为白名单；无法写入的审计接收器属于严重错误。 4. **在可能的情况下保持纯传输** — gateway 解析 MCP 仅供授权之用；任何 MCP server 均可未经修改直接运行。 ## 项目结构 ``` session/ resumable + migratable session layer (Mars-STN-style reliability · store · lease · flock) policy/ the agent firewall (enforce): policy engine, signed tamper-evident audit, trace, replay insight/ the firewall's read side (understand): profile · recommend · simulate · detect secrets/ credential broker: inject secrets by identity (credential isolation; agent does not receive the value) control/ managed control plane: enrollment (NetBird key issuance) · registry · policy distribution federation/ cross-org boundary: per-org tool grants · identity mapping · audited crossings mcp/ dependency-free MCP server framework (tools · resources · prompts · tasks · HTTP) mcpclient/ MCP client over any transport (used by the router, orchestrator, CLI) protocol/ granular Go models for the MCP wire protocol — one package per domain (2025-06-18 base · draft · extensions · client helpers) registry/ file-based discovery registry embed/ local, deterministic text embedder (shared by RAG + semantic policy) mobile/ gomobile-bindable Mesh/Conn/Approvals surface for an iOS/Android app cmd/ mcpserver (demo) · mcpecho · mcphttp · kg (provenance knowledge graph) · vectors (zero-exposure RAG) · memory (agent-memory fabric) *.go the meshmcp binary: serve · router · orchestrate · control · federate · insight · … · CLI Air · Steer: air.go · airserve.go · airworkflow.go · aircontrol.go · steerinbox.go · pushwake.go examples/ ready-to-adapt configs docs/ design docs + open specs ``` ## 文档与规范 - **[docs/MCP-APP.md](docs/MCP-APP.md)** — 将 meshmcp 作为 MCP 应用添加到 Claude Code / Codex 中，并从助手中操作 mesh。 - **[docs/DEMO.md](docs/DEMO.md)** — 实时 mesh 演示：一个 gateway，四个 MCP server，四个 agent 应用，在 Control Room 中进行监控。 - **[docs/COOKBOOK.md](docs/COOKBOOK.md)** — 10 个深入的“探索可能”场景，每个都附带可直接粘贴的配置和图表。 - **[examples/](examples/)** — 每个场景的带注释配置（从 `agent-firewall.yaml` 开始）。 - **[docs/AGENT-FIREWALL.md](docs/AGENT-FIREWALL.md)** — 策略引擎、签名审计、仪表板、重放、control plane、federation。 - **[docs/INSIGHT.md](docs/INSIGHT.md)** — 防火墙的读取端：观察 → 推荐 → 模拟 → 检测。 - **[docs/SECRETS.md](docs/SECRETS.md)** — 凭证代理：身份控制的 secret 注入（凭证隔离；agent 不会接收到值；恶意 backend 停留在暴露边界内）。 - **[docs/EXTENSIONS.md](docs/EXTENSIONS.md)** — 签名能力（短期的、绑定主体的工具授权）、server middleware 以及类型化的函数/任务 client。 - **[docs/MARKETPLACE.md](docs/MARKETPLACE.md)** — **受治理的插件市场** (F14)：Ed25519 签名的 bundle manifest，固定密钥 + 内容哈希验证，以及经过计量和审计的安装 — 无动态加载。 - **[protocol/README.md](protocol/README.md)** — 针对完整 MCP wire protocol 的细粒度 Go 模型：2025-06-18 基础 schema、草案修订版（server/discover、MRTR、订阅、错误目录、采样工具使用、form/url 引导、streamable-HTTP + stdio 传输、OAuth 2.1 授权）以及 Server Card / Tasks / Apps 扩展 — 外加一个客户端响应缓存。每个域一个包，均带有往返测试。 - **[docs/spec/](docs/spec/)** — 开放规范：[audit-record 格式](docs/spec/AUDIT-RECORD.md) 和 [policy DSL](docs/spec/POLICY-DSL.md)，各自均包含 JSON Schema。 - **[docs/AIR.md](docs/AIR.md)** — **Air**：meshmcp 的 AirDrop 原生门面 — 发现 · 投递 · 推送 · 获取 · 引导 · 启动 · 批准，横跨移动优先的 Web 应用、助手和原生移动端（参见[视觉模型](https://xrey167.github.io/meshmcp/air.html)）。 - **[docs/AIR-STEER.md](docs/AIR-STEER.md)** — Air · **Steer**：向 / 取消 / 推送指令到 agent、会话或任务，并启动新的 agent/工作流。四个原语均已交付 — agent 引导收件箱、会话枚举 + 行安全的会话引导、`tasks/steer` 以及启动/工作流 — 外加 gateway 控制 endpoint、`air_*` 助手工具和 `meshmcp air` CLI。 - **[docs/PUBSUB.md](docs/PUBSUB.md)** — 身份原生的 **event bus**：mesh 上的发布/订阅代理（持久化事件日志、可恢复订阅者、签名检查点、能力授权、跨代理 federation）以及用于发布策略决策的 gateway 钩子。 - **[docs/MOBILE.md](docs/MOBILE.md)** — 整个技术栈如何延伸至手机（手机是 mesh 上的人类身份 — 天然的共同签名批准者）。 - **[examples/hitl/](examples/hitl/)** — 将任何 agent 框架的批准钩子（例如 OpenAI Agents SDK 的 `ShellTool.on_approval`）路由到 mesh 批准器 — 从手机批准，具备身份属性和可审计性。 - **[docs/HA-TOOLMESH.md](docs/HA-TOOLMESH.md)** · **[docs/reference.md](docs/reference.md)** · **[docs/VISION.md](docs/VISION.md)** — HA 设计、完整参考、路线图。 - **[docs/IDEAS.md](docs/IDEAS.md)** — payload 层：一个溯源原生的知识图谱 (`cmd/kg`)、零暴露的 RAG (`cmd/vectors`)、一个 agent 记忆结构 (`cmd/memory`)、`meshmcp drop`（跨实例的 AirDrop）+ 内容寻址的 `fetch`、污点隔离检索、签名凭证等 — 22 项基于现有原语的增强功能（参见 `examples/knowledge.yaml`、`drop.yaml`、`rag-firewall.yaml`）。 - **[docs/ROADMAP-HARDENING.md](docs/ROADMAP-HARDENING.md)** — 第二波路线图：编译时**插件平台**（工具 · 决策 · sink · 子命令接缝）、受治理的插件市场、HTTP-backend 策略对齐、联邦 Mesh Spotlight、新的暗 backend（vault · scheduler · event bus）、失败即关闭的审计 + 身份绑定会话，以及 30 项安全发现审查 — **20 个旗舰 (F13–F32) + 50 个次要功能 (S11–S60)**，每一项都根植于现有的原语。 - **[docs/CLIENT-HOOKS.md](docs/CLIENT-HOOKS.md)** — 将防火墙**固化到 LLM client 自身的工具循环中** (F33)：`meshmcp hook` 是 Claude Code 的 `PreToolUse`、Cursor 的 `beforeShellExecution`/`beforeMCPExecution` 以及 Codex 的 `PermissionRequest` 背后的决策引擎 — 使得*每一个*本地工具调用（Bash、Edit、原生 MCP）都受策略治理、进行 DLP 扫描，并记录在防篡改账本中，而不仅仅是 mesh 流量。 ## 构建与测试 ``` go build ./... && go vet ./... && go test ./... -race ``` ## 许可证 **专有 — 保留所有权利。** 源代码公开仅供阅读。 任何使用 — 运行、部署、复制、修改或再分发 — 均需 事先获得版权持有人 **Rey Darius** 的书面许可。请先询问。 参见 [LICENSE](LICENSE)。

_{构建基于腾讯 Mars STN 背后的可靠性理念、caddy-netbird 的嵌入模式，以及 NetBird 的 userspace WireGuard。}

标签：EVTX分析, 日志审计