{"id":50099925,"url":"https://github.com/vinkius-labs/mcpfusion","last_synced_at":"2026-05-23T07:00:48.677Z","repository":{"id":338057361,"uuid":"1156046366","full_name":"vinkius-labs/mcpfusion","owner":"vinkius-labs","description":"MCP Fusion - The TypeScript framework for secure MCP servers.","archived":false,"fork":false,"pushed_at":"2026-05-20T07:56:20.000Z","size":8213,"stargazers_count":251,"open_issues_count":7,"forks_count":22,"subscribers_count":2,"default_branch":"main","last_synced_at":"2026-05-20T09:48:23.748Z","etag":null,"topics":["mcp","mcp-framework","mcp-server","model-context-protocol"],"latest_commit_sha":null,"homepage":"https://vurb.vinkius.com/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/vinkius-labs.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":"docs/governance/blast-radius.md","roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-12T07:39:46.000Z","updated_at":"2026-05-20T07:56:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"6d643824-8932-4a0c-a40b-f7d45ee39cdc","html_url":"https://github.com/vinkius-labs/mcpfusion","commit_stats":null,"previous_names":["vinkius-labs/mcp-fusion","vinkius-labs/vurb.ts","vinkius-labs/mcpfusion"],"tags_count":162,"template":false,"template_full_name":null,"purl":"pkg:github/vinkius-labs/mcpfusion","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinkius-labs%2Fmcpfusion","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinkius-labs%2Fmcpfusion/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinkius-labs%2Fmcpfusion/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinkius-labs%2Fmcpfusion/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/vinkius-labs","download_url":"https://codeload.github.com/vinkius-labs/mcpfusion/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/vinkius-labs%2Fmcpfusion/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33386076,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-23T04:15:53.637Z","status":"ssl_error","status_checked_at":"2026-05-23T04:15:53.242Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["mcp","mcp-framework","mcp-server","model-context-protocol"],"created_at":"2026-05-23T07:00:35.332Z","updated_at":"2026-05-23T07:00:48.664Z","avatar_url":"https://github.com/vinkius-labs.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCP FUSION\n\n**The TypeScript framework for secure MCP servers.**\n\n[![npm version](https://img.shields.io/npm/v/@mcpfusion/core.svg?color=0ea5e9)](https://www.npmjs.com/package/@mcpfusion/core)\n[![Downloads](https://img.shields.io/npm/dw/@mcpfusion/core)](https://www.npmjs.com/package/@mcpfusion/core)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.7+-blue?logo=typescript\u0026logoColor=white)](https://www.typescriptlang.org/)\n[![MCP Standard](https://img.shields.io/badge/MCP-Standard-purple)](https://modelcontextprotocol.io/)\n[![License](https://img.shields.io/badge/License-Apache_2.0-green)](https://github.com/vinkius-labs/mcpfusion/blob/main/LICENSE)\n[![llms.txt](https://img.shields.io/badge/llms.txt-AI_Ready-8b5cf6)](https://mcpfusion.vinkius.com/llms.txt)\n\nMCP Fusion is a TypeScript framework that enforces security at the architectural level of every MCP server. Raw data never reaches the LLM without passing through a typed egress firewall. Tools are physically removed from the agent's namespace when the workflow state forbids them. Every behavioral surface is hashed, locked, and auditable in version control.\n\nThe framework ships with a [SKILL.md](.claude/skills/mcpfusion-development/SKILL.md) — a machine-readable architectural contract. AI coding agents read the Skill and produce correct, governed servers on the first pass.\n\n---\n\n## The Skill — AI Writes the Server\n\nMCP Fusion includes a SKILL.md that encodes the entire MVA architecture, security patterns, and governance rules into a format AI coding agents consume directly.\n\nOpen your project in **Cursor**, **Claude Code**, **GitHub Copilot**, or **Windsurf** and describe what you need:\n\n\u003e *\"Build an MCP server for patient records with Prisma. Redact SSN and diagnosis from LLM output. Gate discharge tools until attending physician signs off.\"*\n\nThe agent reads the Skill. It produces `defineModel()` declarations with `m.hidden()` for sensitive fields, `definePresenter()` with `.redactPII(['*.ssn', '*.diagnosis'])` for DLP compliance, FSM state gating via `.bindState()` for workflow enforcement, and file-based routing under `src/tools/`. You review the PR.\n\nThe Skill is not documentation. It is the security contract. Every server the AI produces inherits the governance stack because the Skill encodes Presenters, state machines, and lockfile generation as mandatory structural patterns.\n\n\u003e 📄 **[SKILL.md](.claude/skills/mcpfusion-development/SKILL.md)** · **[llms.txt](https://mcpfusion.vinkius.com/llms.txt)** *(complete API reference for LLM consumption)*\n\n---\n\n## Security Architecture\n\n### Egress Firewall — Presenter\n\nThe Presenter validates every response through a Zod schema compiled from `defineModel()`. Undeclared fields are stripped in RAM before serialization. PII is redacted via V8-optimized `fast-redact` compiled functions. Rules travel with data, not in the system prompt. The Late Guillotine pattern applies redaction after UI blocks render — charts and suggestions always see full data, the wire never does.\n\n```typescript\nconst PatientPresenter = createPresenter('Patient')\n    .schema(PatientModel)\n    .redactPII(['*.ssn', '*.diagnosis'])\n    .rules((p) =\u003e [\n        p.status === 'critical' ? 'PRIORITY: Patient is critical.' : null,\n    ])\n    .suggest((p) =\u003e p.status === 'admitted'\n        ? [suggest('ward.discharge', 'Begin discharge protocol')]\n        : []);\n```\n\nThe Presenter also runs a **PromptFirewall** — an LLM-as-Judge that evaluates dynamically generated system rules for prompt injection before they reach the agent. Fail-closed by default.\n\n### State Gate — FSM\n\nTools bound to FSM states are physically removed from `tools/list` when the current state does not match. The LLM cannot call what does not exist in its namespace. Powered by XState v5 with manual fallback when XState is not installed.\n\n```typescript\nconst gate = f.fsm({\n    id: 'discharge', initial: 'admitted',\n    states: {\n        admitted:    { on: { PHYSICIAN_SIGNOFF: 'approved' } },\n        approved:    { on: { DISCHARGE: 'discharged' } },\n        discharged:  { type: 'final' },\n    },\n});\n\nexport default f.mutation('ward.discharge')\n    .bindState('approved', 'DISCHARGE')\n    .handle(async (input, ctx) =\u003e ctx.db.patients.discharge(input.id));\n```\n\n| State | Visible tools |\n|---|---|\n| `admitted` | `ward.view`, `ward.update_vitals` |\n| `approved` | `ward.discharge`, `ward.view` |\n| `discharged` | `ward.view` |\n\nServerless-compatible: `FsmStateStore` persists state to Redis/KV across request boundaries. Each request gets an isolated `gate.clone()`.\n\n### Governance Stack\n\nEight introspection modules that make behavioral changes visible and auditable:\n\n| Module | What it does |\n|---|---|\n| **ToolContract** | Materializes the complete behavioral surface of each tool |\n| **BehaviorDigest** | SHA-256 hash of the behavioral surface |\n| **CapabilityLockfile** | `mcpfusion.lock` — git-diffable behavioral snapshot, CI gate via `fusion lock --check` |\n| **CryptoAttestation** | HMAC-SHA256 runtime verification — fail-fast if behavioral digest drifts |\n| **ContractDiff** | Per-field diff between lockfile versions |\n| **EntitlementScanner** | Static analysis of handler source for I/O capabilities (fs, network, subprocess, eval) with evasion heuristics |\n| **SemanticProbe** | LLM-as-Judge for detecting semantic drift in handler output |\n| **TokenEconomics** | Context window inflation risk profiling |\n\n### Sandbox\n\n`SandboxEngine` executes LLM-provided JavaScript in a sealed V8 isolate. No `process`, `require`, `fs`, or network access. One isolate per engine, fresh empty context per execution. Memory-limited, timeout-enforced, output-capped, abort-signal-compatible.\n\n---\n\n## Three Pathways\n\n### 1. YAML — Zero Code\n\n```yaml\nversion: \"1.0\"\nserver:\n  name: \"github-tools\"\n\nconnections:\n  github:\n    type: rest\n    base_url: \"https://api.github.com\"\n    auth:\n      type: bearer\n      token: \"${SECRETS.GITHUB_TOKEN}\"\n\ntools:\n  - name: search_repos\n    description: \"Search GitHub repositories\"\n    instruction: \"Use for finding projects by topic or keyword.\"\n    rules:\n      - \"Max 10 results per query\"\n    parameters:\n      query: { type: string, required: true }\n    execute:\n      connection: github\n      method: GET\n      path: \"/search/repositories\"\n      query: { q: \"{{query}}\", per_page: \"10\" }\n    response:\n      extract: [\"items[].{full_name, description, stargazers_count, html_url}\"]\n```\n\n```bash\nmcpfusion yaml dev\n```\n\n### 2. Typed MVA — Full Control\n\n```typescript\nexport const InvoiceModel = defineModel('Invoice', m =\u003e {\n    m.casts({\n        id:           m.string(),\n        amount_cents: m.number('CRITICAL: in CENTS. Divide by 100 for display.'),\n        status:       m.enum('Status', ['paid', 'pending', 'overdue']),\n    });\n    m.hidden(['password_hash', 'internal_margin']);\n});\n\nexport const InvoicePresenter = definePresenter({\n    name: 'Invoice',\n    schema: InvoiceModel,\n    suggestActions: (inv) =\u003e inv.status === 'pending'\n        ? [{ tool: 'billing.pay', reason: 'Process payment', args: { id: inv.id } }]\n        : [],\n});\n\nexport default f.query('billing.get_invoice')\n    .describe('Get an invoice by ID')\n    .withString('id', 'Invoice ID')\n    .returns(InvoicePresenter)\n    .handle(async (input, ctx) =\u003e ctx.db.invoices.findUnique({ where: { id: input.id } }));\n```\n\n### 3. FSM — Deterministic Workflow Enforcement\n\nState-gated tool discovery. Tools appear and disappear based on the current state.\n\n---\n\n## Get Started\n\n```bash\nnpx @mcpfusion/core create my-server\ncd my-server \u0026\u0026 npm run dev\n```\n\nFile-based routing — drop a file, restart, and it's a live MCP tool:\n\n```\nsrc/tools/\n├── billing/\n│   ├── get_invoice.ts  → billing.get_invoice\n│   └── pay.ts          → billing.pay\n└── users/\n    └── list.ts         → users.list\n```\n\n### Deploy\n\n```bash\nmcpfusion deploy                  # Vinkius Edge (V8 Isolate)\nvercel deploy                # Vercel Functions\nwrangler deploy              # Cloudflare Workers\n```\n\n### Scaffold\n\n```bash\nmcpfusion create my-server                           # Vanilla\nmcpfusion create my-api --vector prisma              # Prisma + field-level security\nmcpfusion create ops-bridge --vector n8n             # n8n workflow bridge\nmcpfusion create petstore --vector openapi           # OpenAPI → MCP\nmcpfusion create my-server --target vercel --yes     # Vercel Functions\nmcpfusion create my-server --target cloudflare --yes # Cloudflare Workers\n```\n\n---\n\n## Ecosystem\n\n### Core\n\n| Package | Purpose |\n|---|---|\n| [`@mcpfusion/core`](https://www.npmjs.com/package/@mcpfusion/core) | Framework core — Presenters, Fluent API, middleware, routing, governance |\n| [`@mcpfusion/yaml`](https://www.npmjs.com/package/@mcpfusion/yaml) | Declarative YAML engine |\n| [`@mcpfusion/swarm`](https://github.com/vinkius-labs/mcpfusion/tree/main/packages/swarm) | Multi-agent orchestration — HMAC-SHA256 delegation, namespace isolation, W3C tracing |\n| [`@mcpfusion/a2a`](https://github.com/vinkius-labs/mcpfusion/tree/main/packages/a2a) | A2A Protocol Bridge — Agent Cards, task delegation |\n| [`@mcpfusion/skills`](https://mcpfusion.vinkius.com/skills) | Progressive SKILL.md disclosure for agents |\n| [`@mcpfusion/testing`](https://mcpfusion.vinkius.com/testing) | In-memory MVA pipeline testing |\n| [`@mcpfusion/inspector`](https://mcpfusion.vinkius.com/inspector) | Real-time TUI dashboard |\n\n### Adapters\n\n| Package | Target |\n|---|---|\n| [`@mcpfusion/vercel`](https://mcpfusion.vinkius.com/vercel-adapter) | Vercel Functions (Edge / Node.js) |\n| [`@mcpfusion/cloudflare`](https://mcpfusion.vinkius.com/cloudflare-adapter) | Cloudflare Workers |\n\n### Generators \u0026 Connectors\n\n| Package | Purpose |\n|---|---|\n| [`@mcpfusion/openapi-gen`](https://mcpfusion.vinkius.com/openapi-gen) | OpenAPI 3.x / Swagger 2.0 → MCP tools |\n| [`@mcpfusion/prisma-gen`](https://mcpfusion.vinkius.com/prisma-gen) | Prisma schema → CRUD tools with field-level security |\n| [`@mcpfusion/n8n`](https://mcpfusion.vinkius.com/n8n-connector) | n8n workflows → MCP tools |\n| [`@mcpfusion/aws`](https://mcpfusion.vinkius.com/aws-connector) | AWS Lambda \u0026 Step Functions → MCP tools |\n\n### Security \u0026 Auth\n\n| Package | Purpose |\n|---|---|\n| [`@mcpfusion/oauth`](https://mcpfusion.vinkius.com/oauth) | RFC 8628 Device Flow |\n| [`@mcpfusion/jwt`](https://mcpfusion.vinkius.com/jwt) | JWT verification — HS256 / RS256 / ES256 + JWKS |\n| [`@mcpfusion/api-key`](https://mcpfusion.vinkius.com/api-key) | API key validation with timing-safe comparison |\n\n---\n\n\n## Ship Your MCP Server to the Same Infrastructure — Free\n\nYour server runs alongside Salesforce, Stripe, OpenAI, and 4,000+ others. V8 sandbox isolation, DLP, audit trails, and kill switch — all included. No credit card required.\n\n1. **Sign up** at [vinkius.com](https://vinkius.com)\n2. **Create an App Connector** in the dashboard\n3. **Copy your deploy token** from the connector settings\n4. **Build your MCP server** with MCP Fusion\n5. **Deploy**\n\n```bash\nmcpfusion deploy\n```\n\nYour MCP server is live.\n\n\n## Powering Vinkius — 4,000+ MCP Servers in Production\n\nEvery MCP server on **[vinkius.com](https://vinkius.com)** is built with MCP Fusion.\n\nSalesforce (12 tools), Slack (8 tools), 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 — and thousands more.\n\nFour verticals. 36+ subcategories. All governed.\n\n**AI Stack** — Cognition \u0026 RAG, Code Execution, Databases, Observability, DevOps, AI Models, Agent Coordination, Security, Payments \u0026 Infra.\n\n**Enterprise** — CRM, ERP, HR, Legal \u0026 Compliance, Customer Support, Marketing, BI \u0026 Analytics, Identity \u0026 IAM, Communications, E-Commerce, Accounting, Project Management.\n\n**Industries** — Hospitality, Healthcare, Energy \u0026 Commodities, Construction, Real Estate, Agriculture, Wine \u0026 Spirits, Education, Logistics, Insurance, Fitness, Travel.\n\n**World Data** — Economy \u0026 Finance, Central Banks, Securities \u0026 Markets, Weather \u0026 Climate, Demographics, Space \u0026 Astronomy, Health \u0026 Medicine, Environment, Energy, Food \u0026 Nutrition, Government, Trade \u0026 Labor.\n\nEvery server runs inside V8 isolate sandboxes on AWS. Ed25519 signed audit chains. Sub-40ms cold starts. DLP redaction on every response. Kill switch for instant shutdown. Every tool call logged and auditable.\n\n**[vinkius.com/discover](https://vinkius.com/discover)** — Browse the catalog. **[vinkius.com/developers](https://vinkius.com/developers)** — Build your own with MCP Fusion.\n\n\n## Documentation\n\n**[mcpfusion.vinkius.com](https://mcpfusion.vinkius.com/)** · **[llms.txt](https://mcpfusion.vinkius.com/llms.txt)** · **[SKILL.md](.claude/skills/mcpfusion-development/SKILL.md)**\n\n## Contributing\n\nSee [CONTRIBUTING.md](https://github.com/vinkius-labs/mcpfusion/blob/main/CONTRIBUTING.md) for development setup and guidelines.\n\n## Security\n\nSee [SECURITY.md](https://github.com/vinkius-labs/mcpfusion/blob/main/SECURITY.md) for reporting vulnerabilities.\n\n## License\n\n[Apache 2.0](https://github.com/vinkius-labs/mcpfusion/blob/main/LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvinkius-labs%2Fmcpfusion","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvinkius-labs%2Fmcpfusion","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvinkius-labs%2Fmcpfusion/lists"}