内容
# fal-mpc
> 一个通用的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，将 **[fal.ai](https://fal.ai)** 的全部功能融入任何MCP客户端。
[fal.ai](https://fal.ai) 是一个生成式媒体强国 — **600+ 个图像、视频、音频和文本模型**（FLUX、Kontext、Veo、Kling、Suno-style 音频等）通过一些最快的推理基础设施提供服务。该服务器通过一组小而精的工具将整个目录交给MCP客户端（Claude Code、Claude Desktop、Cursor等）：通过ID运行任何模型，管理异步作业队列，浏览和搜索模型目录，并在调用模型之前检查模型的确切输入模式。
## 为什么选择 fal.ai
- **难以超越的广度。** 一个 API 密钥解锁了 600+ 个跨所有生成模态的生产模型 — 无需每个供应商的集成，也无需管理多个 SDK。
- **为速度而设计。** fal 的推理栈旨在实现低延迟生成，因此快速模型在几秒内返回，而繁重作业则通过强大的异步队列流式传输。
- **始终保持最新。** 新的尖端模型不断在 fal 上发布 — 只需将此服务器指向新的 `model_id` 即可使用它们。
- **基于模式，杜绝猜测。** 每个模型都发布一个 OpenAPI 模式，因此 `fal_get_model_schema` 允许您的代理在调用模型之前发现确切的输入和默认值。
- **专为代理设计。** 可预测的 REST 接口和干净的队列模型使 fal 成为自主、多步骤生成工作流的自然选择。
该MCP服务器是一个薄而忠实的桥梁，通往该平台 — 它不会碍事，让 fal.ai 展现其全部实力。
## 工具
| 工具 | 用途 |
|---|---|
| `fal_run_model` | 同步运行模型并阻塞以获取结果（适用于快速模型，<2 分钟） |
| `fal_submit_request` | 向异步队列提交作业并立即获取 `request_id` （适用于视频/训练） |
| `fal_check_status` | 轮询队列请求的 状态（`IN_QUEUE` / `IN_PROGRESS` / `COMPLETED`） |
| `fal_get_result` | 获取已完成队列请求的最终输出 |
| `fal_cancel_request` | 取消仍处于 `IN_QUEUE` 的请求 |
| `fal_list_models` | 搜索/浏览 fal.ai 模型目录以查找合适的模型 ID |
| `fal_get_model_schema` | 获取模型的 OpenAPI 模式 — 确切的输入字段、类型、默认值 |
| `fal_encode_file_as_data_uri` | 在本地将文件 base64 编码，以便在无需单独上传步骤的情况下作为 `image_url` 样式参数传递 |
## 设置
1. 从 [fal.ai/dashboard/keys](https://fal.ai/dashboard/keys) 获取 API 密钥。
2. 构建服务器：
```bash
npm install
npm run build
```
3. 将其添加到您的MCP客户端配置中（例如Claude Code的 `.mcp.json` 或Claude Desktop的配置），指向 `dist/index.js` 并设置 `FAL_KEY`：
```json
{
"mcpServers": {
"fal": {
"command": "node",
"args": ["/absolute/path/to/fal-mpc/dist/index.js"],
"env": {
"FAL_KEY": "your-fal-api-key"
}
}
}
}
```
## 典型工作流程
**快速图像生成：**
```
fal_run_model(model_id="fal-ai/flux/dev", arguments={"prompt": "a sunset over mountains"})
```
**不确定模型接受什么？**
```
fal_get_model_schema(model_id="fal-ai/flux-pro/kontext")
```
**慢速模型（视频）— 先运行后检查：**
```
fal_submit_request(model_id="fal-ai/minimax/video-01", arguments={"prompt": "a rocket launch"})
-> fal_check_status(model_id=..., request_id=...)
-> fal_get_result(model_id=..., request_id=...) # once COMPLETED
```
**使用本地图像作为输入：**
```
fal_encode_file_as_data_uri(file_path="/path/to/photo.jpg")
-> 将返回的数据 URI 作为 image_url 传递给 fal_run_model / fal_submit_request
```
**为任务查找模型：**
```
fal_list_models(query="background removal")
```
## 注意事项
- Base64 数据 URI 直接作为文件输入在 fal 预期 URL 的任何地方工作 — `fal_encode_file_as_data_uri` 在本地处理此操作（无需 fal 上传 API 调用）。对于已经公开托管的文件，只需直接传递 URL。
- `fal_run_model` 有 5 分钟超时；任何较慢的操作都应通过 `fal_submit_request` 进行。
- 所有工具都支持 `response_format: "json"` 以获取结构化输出或 `"markdown"` （默认）以获取可读性。
## 评估
`evaluation.xml` 包含 10 个只读 QA 对，它们使用已知的模型默认值测试 `fal_get_model_schema`。请使用 mcp-builder 技能的评估指南中描述的测试框架运行。由于 fal.ai 模型模式可能会随着模型的更新而变化，请在依赖它们之前先检查这些模式与实时 API 的一致性。
