vinkius-labs/mcpfusion

# MCP FUSION **用于构建安全 MCP 服务器的 TypeScript 框架。** [](https://www.npmjs.com/package/@mcpfusion/core) [](https://www.npmjs.com/package/@mcpfusion/core) [](https://www.typescriptlang.org/) [](https://modelcontextprotocol.io/) [](https://github.com/vinkius-labs/mcpfusion/blob/main/LICENSE) [](https://mcpfusion.vinkius.com/llms.txt) MCP Fusion 是一个 TypeScript 框架，在每个 MCP 服务器的架构层面强制实施安全性。原始数据必须经过类型化的出站防火墙（egress firewall），否则永远无法到达 LLM。当工作流状态禁止时，工具会从 agent 的命名空间中被物理移除。每个行为表面都经过哈希处理、锁定，并可在版本控制中进行审计。 该框架附带了一个 [SKILL.md](https://github.com/vinkius-labs/mcpfusion/blob/main/.claude/skills/mcpfusion-development/SKILL.md) —— 一份机器可读的架构契约。AI 编码 agent 阅读该 Skill 后，能够在首次尝试时就生成正确且受治理的服务器。 ## Skill —— AI 编写服务器 MCP Fusion 包含一个 SKILL.md，它将整个 MVA 架构、安全模式和治理规则编码为 AI 编码 agent 可直接消费的格式。 在 **Cursor**、**Claude Code**、**GitHub Copilot** 或 **Windsurf** 中打开你的项目，并描述你的需求： agent 会阅读该 Skill。它会生成带有 `m.hidden()`（用于敏感字段）的 `defineModel()` 声明，带有 `.redactPII(['*.ssn', '*.diagnosis'])`（用于 DLP 合规）的 `definePresenter()`，通过 `.bindState()` 进行 FSM 状态门控（用于工作流强制执行），以及位于 `src/tools/` 下的基于文件的路由。然后你只需审查 PR 即可。 Skill 不是文档。它是安全契约。AI 生成的每个服务器都会继承治理堆栈，因为 Skill 将 Presenters、状态机和 lockfile 生成编码为强制性的结构模式。 ## 安全架构 ### 出站防火墙 —— Presenter Presenter 通过从 `defineModel()` 编译的 Zod schema 验证每个响应。未声明的字段会在序列化之前于内存（RAM）中被剥离。PII 通过 V8 优化的 `fast-redact` 编译函数进行脱敏。规则随数据一起传输，而不是存在于 system prompt 中。Late Guillotine 模式在 UI 块渲染后应用脱敏 —— 图表和建议总是能看到完整数据，而网络传输永远不会。 ``` const PatientPresenter = createPresenter('Patient') .schema(PatientModel) .redactPII(['*.ssn', '*.diagnosis']) .rules((p) => [ p.status === 'critical' ? 'PRIORITY: Patient is critical.' : null, ]) .suggest((p) => p.status === 'admitted' ? [suggest('ward.discharge', 'Begin discharge protocol')] : []); ``` Presenter 还运行一个 **PromptFirewall** —— 这是一个 LLM-as-Judge，会在动态生成的系统规则到达 agent 之前评估其是否存在 prompt injection。默认实施故障关闭（Fail-closed）。 ### 状态门 —— FSM 当当前状态不匹配时，绑定到 FSM 状态的工具会从 `tools/list` 中被物理移除。LLM 无法调用其命名空间中不存在的内容。由 XState v5 提供支持，并在未安装 XState 时提供手动回退。 ``` const gate = f.fsm({ id: 'discharge', initial: 'admitted', states: { admitted: { on: { PHYSICIAN_SIGNOFF: 'approved' } }, approved: { on: { DISCHARGE: 'discharged' } }, discharged: { type: 'final' }, }, }); export default f.mutation('ward.discharge') .bindState('approved', 'DISCHARGE') .handle(async (input, ctx) => ctx.db.patients.discharge(input.id)); ``` | 状态 | 可见工具 | |---|---| | `admitted` | `ward.view`, `ward.update_vitals` | | `approved` | `ward.discharge`, `ward.view` | | `discharged` | `ward.view` | 兼容 Serverless：`FsmStateStore` 可跨请求边界将状态持久化到 Redis/KV。每个请求都会获得一个隔离的 `gate.clone()`。 ### 治理堆栈 八个内省模块，使行为变更可见且可审计： | 模块 | 功能 | |---|---| | **ToolContract** | 具象化每个工具的完整行为表面 | | **BehaviorDigest** | 行为表面的 SHA-256 哈希值 | | **CapabilityLockfile** | `mcpfusion.lock` — 可 git diff 的行为快照，通过 `fusion lock --check` 进行 CI 门控 | | **CryptoAttestation** | HMAC-SHA256 运行时验证 —— 若行为摘要发生偏移则快速失败 | | **ContractDiff** | lockfile 版本之间的逐字段差异对比 | | **EntitlementScanner** | 对 handler 源码进行静态分析以检查 I/O 能力（fs、network、subprocess、eval），并带有规避启发式检测 | | **SemanticProbe** | 基于 LLM-as-Judge 检测 handler 输出中的语义偏移 | | **TokenEconomics** | 上下文窗口膨胀风险分析 | ### Sandbox `SandboxEngine` 在密封的 V8 isolate 中执行 LLM 提供的 JavaScript。没有 `process`、`require`、`fs` 或网络访问权限。每个引擎对应一个 isolate，每次执行提供全新的空上下文。限制内存、强制超时、限制输出上限、兼容 abort-signal。 ## 三种途径 ### 1. YAML —— 零代码 ``` version: "1.0" server: name: "github-tools" connections: github: type: rest base_url: "https://api.github.com" auth: type: bearer token: "${SECRETS.GITHUB_TOKEN}" tools: - name: search_repos description: "Search GitHub repositories" instruction: "Use for finding projects by topic or keyword." rules: - "Max 10 results per query" parameters: query: { type: string, required: true } execute: connection: github method: GET path: "/search/repositories" query: { q: "{{query}}", per_page: "10" } response: extract: ["items[].{full_name, description, stargazers_count, html_url}"] ``` ``` mcpfusion yaml dev ``` ### 2. 类型化 MVA —— 完全控制 ``` export const InvoiceModel = defineModel('Invoice', m => { m.casts({ id: m.string(), amount_cents: m.number('CRITICAL: in CENTS. Divide by 100 for display.'), status: m.enum('Status', ['paid', 'pending', 'overdue']), }); m.hidden(['password_hash', 'internal_margin']); }); export const InvoicePresenter = definePresenter({ name: 'Invoice', schema: InvoiceModel, suggestActions: (inv) => inv.status === 'pending' ? [{ tool: 'billing.pay', reason: 'Process payment', args: { id: inv.id } }] : [], }); export default f.query('billing.get_invoice') .describe('Get an invoice by ID') .withString('id', 'Invoice ID') .returns(InvoicePresenter) .handle(async (input, ctx) => ctx.db.invoices.findUnique({ where: { id: input.id } })); ``` ### 3. FSM —— 确定性工作流强制执行 状态门控的工具发现。工具根据当前状态出现和消失。 ## 开始使用 ``` npx @mcpfusion/core create my-server cd my-server && npm run dev ``` 基于文件的路由 —— 拖入一个文件，重启，它就是一个生效的 MCP 工具： ``` src/tools/ ├── billing/ │ ├── get_invoice.ts → billing.get_invoice │ └── pay.ts → billing.pay └── users/ └── list.ts → users.list ``` ### 部署 ``` mcpfusion deploy # Vinkius Edge (V8 Isolate) vercel deploy # Vercel Functions wrangler deploy # Cloudflare Workers ``` ### 脚手架 ``` mcpfusion create my-server # Vanilla mcpfusion create my-api --vector prisma # Prisma + field-level security mcpfusion create ops-bridge --vector n8n # n8n workflow bridge mcpfusion create petstore --vector openapi # OpenAPI → MCP mcpfusion create my-server --target vercel --yes # Vercel Functions mcpfusion create my-server --target cloudflare --yes # Cloudflare Workers ``` ## 生态系统 ### 核心 | 包 | 用途 | |---|---| | [`@mcpfusion/core`](https://www.npmjs.com/package/@mcpfusion/core) | 框架核心 —— Presenters、Fluent API、中间件、路由、治理 | | [`@mcpfusion/yaml`](https://www.npmjs.com/package/@mcpfusion/yaml) | 声明式 YAML 引擎 | | [`@mcpfusion/swarm`](https://github.com/vinkius-labs/mcpfusion/tree/main/packages/swarm) | 多 agent 编排 —— HMAC-SHA256 委派、命名空间隔离、W3C 追踪 | | [`@mcpfusion/a2a`](https://github.com/vinkius-labs/mcpfusion/tree/main/packages/a2a) | A2A 协议桥接 —— Agent Cards、任务委派 | | [`@mcpfusion/skills`](https://mcpfusion.vinkius.com/skills) | 面向 agent 的渐进式 SKILL.md 披露 | | [`@mcpfusion/testing`](https://mcpfusion.vinkius.com/testing) | 内存级 MVA pipeline 测试 | | [`@mcpfusion/inspector`](https://mcpfusion.vinkius.com/inspector) | 实时 TUI 仪表板 | ### 适配器 | 包 | 目标 | |---|---| | [`@mcpfusion/vercel`](https://mcpfusion.vinkius.com/vercel-adapter) | Vercel Functions (Edge / Node.js) | | [`@mcpfusion/cloudflare`](https://mcpfusion.vinkius.com/cloudflare-adapter) | Cloudflare Workers | ### 生成器与连接器 | 包 | 用途 | |---|---| | [`@mcpfusion/openapi-gen`](https://mcpfusion.vinkius.com/openapi-gen) | OpenAPI 3.x / Swagger 2.0 → MCP 工具 | | [`@mcpfusion/prisma-gen`](https://mcpfusion.vinkius.com/prisma-gen) | Prisma schema → 带有字段级安全性的 CRUD 工具 | | [`@mcpfusion/n8n`](https://mcpfusion.vinkius.com/n8n-connector) | n8n 工作流 → MCP 工具 | | [`@mcpfusion/aws`](https://mcpfusion.vinkius.com/aws-connector) | AWS Lambda & Step Functions → MCP 工具 | ### 安全与认证 | 包 | 用途 | |---|---| | [`@mcpfusion/oauth`](https://mcpfusion.vinkius.com/oauth) | RFC 8628 Device Flow | | [`@mcpfusion/jwt`](https://mcpfusion.vinkius.com/jwt) | JWT 验证 —— HS256 / RS256 / ES256 + JWKS | | [`@mcpfusion/api-key`](https://mcpfusion.vinkius.com/api-key) | API 密钥验证（使用 timing-safe comparison） | ## 免费将你的 MCP 服务器部署到相同的基础设施上 你的服务器将与 Salesforce、Stripe、OpenAI 及其他 4,000+ 个应用并列运行。包含 V8 沙箱隔离、DLP、审计追踪和紧急开关（kill switch）。无需信用卡。 1. 在 [vinkius.com](https://vinkius.com) **注册** 2. 在仪表板中**创建一个 App Connector** 3. 从连接器设置中**复制你的部署 token** 4. 使用 MCP Fusion**构建你的 MCP 服务器** 5. **部署** ``` mcpfusion deploy ``` 你的 MCP 服务器现已上线。 ## 为 Vinkius 提供动力 —— 生产环境中的 4,000+ 个 MCP 服务器 **[vinkius.com](https://vinkius.com)** 上的每个 MCP 服务器都是使用 MCP Fusion 构建的。 Salesforce (12 个工具)、Slack (8 个工具)、Stripe、OpenAI、Gmail、WhatsApp Business、Instagram、PayPal、CrowdStrike Falcon、SAP S/4HANA、Workday、DocuSign、Zendesk、Okta、Twilio、Tableau、HubSpot、Shopify、WooCommerce、Airbnb、Tesla Fleet API、NVIDIA AI、Mistral AI、Anthropic、Box、Meta Ads、X Ads、Reddit、Notion、Supabase、Pinecone、Datadog、Sentry —— 还有数千个。 四大垂直领域。36+ 个子类别。全部受治理。 **AI 堆栈** —— 认知与 RAG、代码执行、数据库、可观测性、DevOps、AI 模型、Agent 协调、安全、支付与基础设施。 **企业** —— CRM、ERP、HR、法律与合规、客户支持、营销、BI 与分析、身份与 IAM、通信、电子商务、会计、项目管理。 **行业** —— 酒店、医疗保健、能源与大宗商品、建筑、房地产、农业、葡萄酒与烈酒、教育、物流、保险、健身、旅游。 **世界数据** —— 经济与金融、央行、证券与市场、天气与气候、人口统计、空间与天文、健康与医学、环境、能源、食品与营养、政府、贸易与劳工。 每个服务器都在 AWS 上的 V8 isolate 沙箱中运行。Ed25519 签名的审计链。低于 40ms 的冷启动。对每个响应进行 DLP 脱敏。配备用于即时关停的紧急开关（kill switch）。每个工具调用都被记录并可供审计。 **[vinkius.com/discover](https://vinkius.com/discover)** —— 浏览目录。**[vinkius.com/developers](https://vinkius.com/developers)** —— 使用 MCP Fusion 构建你自己的服务器。 ## 文档 **[mcpfusion.vinkius.com](https://mcpfusion.vinkius.com/)** · **[llms.txt](https://mcpfusion.vinkius.com/llms.txt)** · **[SKILL.md](https://github.com/vinkius-labs/mcpfusion/blob/main/.claude/skills/mcpfusion-development/SKILL.md)** ## 安全 如需报告漏洞，请参阅 [SECURITY.md](https://github.com/vinkius-labs/mcpfusion/blob/main/SECURITY.md)。 ## 许可证 [Apache 2.0](https://github.com/vinkius-labs/mcpfusion/blob/main/LICENSE)

标签：AI代理, MCP, TypeScript, XML 请求, 人工智能, 安全开发, 安全插件, 开发框架, 用户模式Hook绕过, 自动化攻击