FluidMCP CLI

🌀 FluidMCP CLI

通过单个配置文件编排多个 MCP 服务

---

⚡ 快速开始 - 运行多个 MCP 服务

FluidMCP 的核心优势是通过统一的 FastAPI 端点，从单个配置文件运行多个 MCP 服务。

1. 创建配置文件

创建一个包含 MCP 服务的 config.json 文件：

{
  "mcpServers": {
    "google-maps": {
      "command": "npx",
      "args": ["-y", "@google-maps/mcp-server"],
      "env": {
        "GOOGLE_MAPS_API_KEY": "your-api-key"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"],
      "env": {}
    }
  }
}

2. 启动所有服务

fluidmcp run config.json --file --start-server

这将：

• 安装并配置配置文件中列出的所有 MCP 服务
• 通过统一的 FastAPI 网关启动它们
• 在 http://localhost:8099 提供这些服务
• 在 http://localhost:8099/docs 自动提供 API 文档

---

🚀 功能

• 📁 多服务编排

  • 在单个 JSON 配置文件中定义多个 MCP 服务
  • 使用一条命令启动所有服务：fluidmcp run --file <config.json>
  • 通过统一的 FastAPI 网关提供所有 MCP 工具

• 📦 包管理

  • 使用 fluidmcp install author/package@version 安装 MCP 包
  • 自动解析依赖并设置环境
  • 支持 npm、Python 和自定义 MCP 服务

• 🚀 FastAPI 网关

  • 为所有 MCP 工具提供统一的 HTTP 端点
  • 支持服务器发送事件（SSE）流式传输
  • 在 /docs 提供 Swagger 文档

• 🔐 安全与身份验证

  • Bearer 令牌身份验证
  • 使用加密通信的安全模式
  • 加密 API 密钥的环境变量

---

📥 安装

pip install fluidmcp

---

🔧 其他使用方式

安装单个包

fluidmcp install author/package@version

列出已安装的包

fluidmcp list

运行单个包

fluidmcp run author/package@version --start-server

---

🔐 高级用法

使用身份验证的安全模式

使用 bearer 令牌身份验证运行：

fluidmcp run config.json --file --secure --token your_token --start-server

---

授权后

---

☁️ 从 S3 URL 运行

直接从 S3 运行配置：

fluidmcp run "https://bucket.s3.amazonaws.com/config.json" --s3

常用选项：

• --start-server – 启动 FastAPI 服务
• --master – 使用由 S3 驱动的配置
• --file – 从本地 config.json 运行
• --s3 – 从 S3 URL 运行
• --secure – 启用安全令牌模式
• --token <token> – 自定义 bearer 令牌
• --verbose – 启用详细日志记录（DEBUG 级别）

运行所有已安装的包

fluidmcp run all --start-server

---

📂 运行模式

🧠 主控模式（S3 集中管理）

fluidmcp install author/package@version --master
fluidmcp run all --master

---

🧩 环境变量

# S3 Credentials (used in --master mode)
export S3_BUCKET_NAME="..."
export S3_ACCESS_KEY="..."
export S3_SECRET_KEY="..."
export S3_REGION="..."


# Registry access
export MCP_FETCH_URL="https://registry.fluidmcp.com/fetch-mcp-package"
export MCP_TOKEN="..."

编辑环境

fluidmcp edit-env <author/package@version>

显示版本

fluidmcp --version

显示 FluidMCP 版本、Python 版本和安装路径。

验证配置

# Validate a local configuration file
fluidmcp validate config.json --file

# Validate an installed package
fluidmcp validate author/package@version

validate 命令会检查：

• 配置文件结构及解析结果
• 系统 PATH 中是否存在相应命令
• 必需的环境变量（标记为 required: true）
• 可选环境变量和令牌
• 已安装包是否存在 Metadata.json

注意： 环境变量查找不区分大小写。例如，如果配置中指定了 github_token，验证器会同时检查环境中的 github_token 和 GITHUB_TOKEN。

此命令会区分错误（致命问题）和警告（非致命问题）：

错误（退出代码 1）：

• PATH 中缺少命令
• 缺少必需的环境变量
• 配置解析失败

警告（退出代码 0）：

• 缺少可选环境变量
• 缺少未明确标记为必需项的 TOKEN 变量

输出示例：

成功：

✔ Configuration is valid with no issues found.

仅有警告：

⚠️  Configuration is valid with warnings:
  - Optional env var 'DEBUG_MODE' is not set (server: test-server)
  - Token env var 'GITHUB_TOKEN' is not set (server: github-server)

✔ No fatal errors found. You may proceed, but consider addressing the warnings above.

存在错误：

❌ Configuration validation failed with errors:
  - Command 'nonexistent-command' not found in PATH (server: test-server)
  - Missing required env var 'API_KEY' (server: test-server)

⚠️  Warnings:
  - Optional env var 'DEBUG_MODE' is not set (server: test-server)

---

📁 目录结构

.fmcp-packages/
└── Author/
    └── Package/
        └── Version/
            ├── metadata.json
            └── [tool files]

---

📑 metadata.json 示例

{
  "mcpServers": {
    "maps": {
      "command": "npx",
      "args": ["-y", "@package/server"],
      "env": {
        "API_KEY": "xxx"
      }
    }
  }
}

---

🧪 试用 MCP 服务

fluidmcp install Google_Maps/[email protected]
fluidmcp run all

然后通过以下方式调用：

import requests, json


url = "http://localhost:8099/google-maps/mcp"
payload = {
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "maps_search_places",
    "arguments": {
      "query": "coffee shops in San Francisco"
    }
  }
}
response = requests.post(url, json=payload)
print(json.dumps(response.json(), indent=2))

---

📡 使用 SSE 进行流式传输

curl -N -X POST http://localhost:8099/package/sse \
  -H "Content-Type: application/json" \
  -d @payload.json

• sse/start
• sse/stream
• sse/message
• sse/tools_call

适用于大模型、网页抓取或流式传输数据的 AI 工作流。

---

📸 演示

安装单个软件包

---

运行单个软件包

---

编辑软件包的环境变量

---

🤝 参与贡献

FluidMCP 欢迎合作，也欢迎社区成员贡献！

• 贡献指南：请参阅 CONTRIBUTING.md，了解开发环境设置和相关指南
• 报告问题：在 GitHub 上提交问题
• 提交 PR：按照我们的贡献指南提交拉取请求

---

📌 许可证

GNU 通用公共许可证 v3.0

---