Fusional

🚀 FusionAL — 可自托管 MCP 治理网关

你的团队连接了 10 个 MCP 服务。接下来呢？
🌐 fusional.dev • 📧 [email protected] • 🗓️ 预约通话

MCP 功能强大。企业级 MCP 部署则是完全不同的问题。

你连接的每个服务，都会在处理请求的第一个 token 之前，将其完整的工具清单加载到 Claude 的上下文窗口中。当多个服务共计提供 84 个工具时，会话开始时就会消耗 15,540 个 token——此时你的团队还什么都没问。在大规模部署时，这意味着成本、延迟，以及一个没人能向法务解释清楚的审计范围。

FusionAL 是一个可自托管的 MCP 治理网关，位于 AI 客户端和工具服务之间。一个端点。集中式身份验证。工具级策略执行。完整审计跟踪。只需一条 Docker 命令即可部署——包括 Windows；MCP 在 Windows 上有 6 种已记录的故障模式，官方文档却没有提及。

专为已决定采用 MCP、现在需要安全运行 MCP 的团队打造：

• Token 控制 — 按客户端过滤工具暴露范围，避免上下文膨胀随服务数量同步增长
• 满足审计要求的运维 — 记录每次工具调用的调用者、输入、延迟和响应状态
• 策略执行 — 控制运行哪些工具、由谁运行，以及在什么条件下运行
• 针对 Windows 加固 — 解决了 6 种已记录的故障模式，而这些问题在官方 MCP 文档中均未提及
• AI 驱动的服务生成 — 用通俗的语言描述工具，FusionAL 就会构建并注册它
• 省心托管选项 — 我们为你部署、治理和管理

问题不在于是否采用 MCP，而在于你的部署能否经受住安全团队的审查。

---

⚡ 快速开始（5 分钟）

前置条件

• Docker Desktop（已安装并运行）
• Claude Desktop
• Python 3.11+
• Git

步骤 1：克隆并安装

git clone https://github.com/JRM-FusionAL/FusionAL.git
cd FusionAL

python -m venv venv
source venv/bin/activate        # macOS/Linux
# venv\Scripts\activate         # Windows

pip install -r core/requirements.txt

步骤 2：启动 FusionAL

cd core
python -m uvicorn main:app --reload --port 8009

确认服务正在运行：

curl http://localhost:8009/health

步骤 3：配置 Claude Desktop

找到配置文件：

• Windows： C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

⚠️ **Windows 用户：**请勿在路径中使用 %APPDATA%——Claude Desktop 不会展开它。 请使用完整路径。示例：C:\Users\YourName\AppData\Roaming\Claude\claude_desktop_config.json

将 FusionAL 添加为 MCP 服务：

{
  "mcpServers": {
    "fusional-gateway": {
      "url": "http://localhost:8009/sse"
    }
  }
}

步骤 4：重启 Claude Desktop 并测试

完全退出并重新打开 Claude Desktop。打开新聊天并尝试：

“生成一个 Python MCP 服务，用于获取指定城市的当前天气。”

FusionAL 会自动生成、注册并运行它。

---

🐳 Docker 部署

在 Docker 中构建并运行完整网关：

docker build -t fusional .
docker run -d -p 8089:8009 --name fusional fusional

或使用 Docker Compose：

docker compose up -d

网关可通过 http://localhost:8089 访问。

---

🏗️ 架构

Claude Desktop / Any MCP Client
         │
         ▼  (SSE or Streamable HTTP)
  FusionAL Gateway  (:8009)
         │
   ┌─────┴──────┐
   ▼            ▼
FastAPI      MCP Transport (/mcp)
REST API     ├── execute_code
             ├── generate_and_execute
             └── generate_mcp_project
         │
         ▼
  Docker Sandbox Executor
  (network isolated, memory capped)
         │
         ▼
  MCP Server Registry (JSON)
  ├── business-intelligence-mcp  (:8101)
  ├── api-integration-hub        (:8102)
  └── content-automation-mcp     (:8103)

MCP 工具（通过 /mcp）

工具	说明
execute_code	在隔离的子进程沙箱中运行 Python
generate_and_execute	用通俗语言编写提示词 → Claude 编写代码 → 运行代码
generate_mcp_project	描述 MCP 服务 → Claude 构建完整项目

REST API

Endpoint	Method	Description
/health	GET	健康检查
/execute	POST	执行 Python（可选 Docker 沙箱）
/register	POST	在注册表中注册 MCP 服务
/catalog	GET	列出所有已注册的服务
/generate	POST	根据提示词生成并启动新服务

---

🛠️ 展示服务

这些服务随 mcp-consulting-kit 一同提供， 并已预先注册到 FusionAL 网关中：

Server	Port	Tools
business-intelligence-mcp	8101	自然语言 → SQL（PostgreSQL、MySQL、SQLite）
api-integration-hub	8102	Slack、GitHub Issues、Stripe 客户查询
content-automation-mcp	8103	网页抓取、链接提取、表格解析、RSS 订阅源

启动完整的展示服务栈：

cd ../mcp-consulting-kit
docker compose up -d

---

🔒 安全模型

Docker 沙箱

每次代码执行都在以下条件下运行：

• ✅ 网络隔离（--network none）
• ✅ 内存限制（默认为 128 MB，可配置）
• ✅ 进程限制（最多 64 个进程）
• ✅ 只读文件系统（/tmp 除外）
• ✅ 禁止权限提升
• ✅ 以非 root 用户身份执行

API 安全（可选）

当 mcp-consulting-kit/showcase-servers/common/security.py 存在时，网关会启用：

• 在 /execute、/register、/generate 上进行 API 密钥身份验证
• 速率限制
• CORS 配置

---

🪟 Windows 特定修复

FusionAL 记录并解决了官方文档未涵盖的 6 种 Windows MCP 故障模式：

1. 60 秒静默 — Claude Desktop 超时且不显示任何错误。由 Docker 套接字初始化延迟导致。
   查看修复方法 →

2. BOM 陷阱 — Notepad/VS Code 会在 JSON 配置中插入字节顺序标记，导致 MCP 静默故障。
   修复方法：[System.IO.File]::WriteAllText(path, content, New-Object System.Text.UTF8Encoding($false))

3. 反斜杠陷阱 — claude_desktop_config.json 中的 Windows 路径分隔符会导致启动静默失败。
   使用正斜杠或转义后的双反斜杠。

4. %USERPROFILE% 展开 — Claude Desktop 不会展开配置路径中的环境变量。请使用硬编码路径。

5. Docker 命名管道故障 — Docker 的命名管道传输在 WSL2 上会失败。请使用 /var/run/docker.sock。

6. 8 个以上服务时注册表超时 — 在性能较低的硬件上，Claude Desktop 会达到超时阈值。
   在 i5/i7 第 7 代及更早的设备上，将注册表中的服务数量限制为 8 个。

---

🧰 构建你自己的 MCP 服务

使用 AI 构建器（通过 Claude Desktop）

连接 FusionAL 后，向 Claude 提出请求：

“生成一个使用自然语言查询我们 PostgreSQL 数据库的 MCP 服务。”

FusionAL 会自动生成完整项目、完成构建，并将其注册到网关中。

手动服务结构

my-server/
├── Dockerfile
├── requirements.txt
├── my_server.py       ← FastMCP tools go here
└── .env

关键规则

1. 在异步函数上使用 @mcp.tool() 装饰器
2. 仅使用单行文档字符串（多行文档字符串会导致部分 MCP 客户端出错）
3. 所有工具都返回格式化字符串
4. 默认参数使用 "" 而不是 None
5. 将日志写入 sys.stderr
6. 在 Docker 中以非 root 用户身份运行

from mcp.server.fastmcp import FastMCP
import sys

mcp = FastMCP("my-server")

@mcp.tool()
async def my_tool(query: str = "") -> str:
    """What this tool does in one line."""
    return f"✅ Result for: {query}"

if __name__ == "__main__":
    mcp.run(transport='stdio')

---

📚 示例

Example	Path	What it demonstrates
骰子工具	examples/dice-roller/	D&D 骰子（8 个工具）、骰子表示法解析
天气 API	examples/weather-api/	外部 API 集成、错误处理
文件工具	examples/file-utils/	安全的文件系统访问、分页

---

🚀 交付式咨询服务

不想自行管理？FusionAL 提供交付式 MCP 部署服务：

套餐	范围	价格
入门安装	单一环境、核心服务、Windows 加固	$2,500–$3,500
核心安装	完整技术栈、自定义服务、治理层、团队入职培训	$5,000–$9,000
顾问服务	持续运维、事件响应、新服务构建	$1,500–$4,000/mo

预约免费的 15 分钟 MCP 安全审计 →

---

🤝 参与贡献

欢迎贡献。优先方向：

• 新示例服务
• Windows 兼容性修复
• 文档改进
• 测试覆盖

---

📄 许可证

MIT — 参见 LICENSE

---

🙏 致谢

• Anthropic — Claude AI + MCP 协议
• FastAPI — API 框架
• FastMCP — MCP 服务框架
• Docker — 容器基础设施

---

由一位自学成才的开发者打造，他解决了那些无人记录的 MCP 问题。
🌐 fusional.dev • ⭐ 如果这个仓库为你节省了数小时，请给它点个星

---

🙌 起源与灵感

FusionAL 始于 NetworkChuck 的一段视频。

如果你还没看过 "you need to learn MCP RIGHT NOW!!"，先去看吧。Chuck 对基础知识的讲解胜过任何人，他的 docker-mcp-tutorial 仓库 是了解 MCP 服务如何与 Docker 配合工作的最佳起点。

本仓库中的掷骰子示例和快速入门结构改编自该教程（采用 MIT 许可证）。

FusionAL 更进一步之处：

Chuck 的教程展示了如何手动构建 MCP 服务——编辑提示词模板，将其粘贴到 Claude 中，再自行实现结果。

FusionAL 则完全将人工从这一流程中移除。无需复制粘贴提示词文件，generate_mcp_project 是一次实时工具调用——Claude 描述想要构建的内容，FusionAL 生成并注册，然后运行。无需剪贴板，也无需手动操作。

更重要的是，Chuck 的视频介绍了 Docker 的 MCP 目录，其中有 300 多个可一键启用的服务。这只是第一步。当 CTO 问：

“很好——但我们如何审计这些工具正在做什么？如何强制执行策略？如何确保这不会演变成安全事件？”

FusionAL 正是为填补这个缺口而打造的：为大规模部署 MCP 的团队提供治理、可审计性和运营控制——尤其是在 Windows 上，因为仅靠目录并不足够。