Genvoy MCP
Genvoy是用于fal.ai媒体工作流程的生产级MCP服务器。
它为AI代理提供了一个安全、结构化的接口，用于：
- 发现fal.ai模型，
- 估算成本，
- 生成媒体，
- 比较不同模型的输出，
- 将输出保存到本地磁盘，并可选择复制到repo路径中。
Genvoy首先是为本地MCP使用而构建的（BYOK：自带密钥）。
Genvoy做什么
核心工具：
search_models-在生成之前查找模型ID（示例：搜索flux).get_schema-在调用模型之前，确切地查看模型接受哪些输入。estimate_cost-首先检查可能的成本，这样你就可以决定是否继续。generate-从一个提示符创建一个输出，并将其保存到文件路径。generate_batch-在一次调用中为同一模型创建多个变体。generate_compare-跨多个模型运行一个提示以比较结果。get_job_status-检查以前提交的异步请求的进度。cancel_job-停止您不再需要的排队/正在运行的请求。
资源：
genvoy://models-模型元数据的快速只读快照。genvoy://recent-最近使用情况的快速只读快照（需要管理员密钥）。
兼容性桥接工具（由FastMCP添加 ResourcesAsTools 转换）：
list_resources-即使没有本机资源UI，也可以让客户端发现资源。read_resource-直接通过URI获取资源内容。
安装模式
模式A：本地来源（开发）
直接从此仓库运行：
uv run python -m genvoy.server模式B：本地安装包（仍为本地）
在本地安装软件包：
uv tool install .然后运行：
genvoy模式C：通过PyPI发布包（默认情况下仍为本地）
发布后，用户可以在本地安装和运行(uvx genvoy 或本地安装）。
重要提示：发布到PyPI 不 指共享托管服务器。 它仍然在每个用户的计算机上运行，除非您自己部署和托管中央服务器。
本地模式与托管模式
本地MCP（当前项目重点）
- 每个用户在本地运行Genvoy，
- 每个用户都设置自己的
FAL_KEY, - 账单由每个用户的fal帐户支付。
托管共享MCP（可选的未来架构）
- 一个集中式服务器为许多用户服务，
- 服务器密钥由您管理，
- 计费和多租户身份验证成为您的运营责任。
Genvoy目前的目标是本地MCP。
需求
- python
>=3.11 uv- 环境中的fal.ai API密钥
可选：
- fal.ai管理员API密钥范围（如果需要）
genvoy://recent/使用历史。
配置
创建 .env 在repo根目录中：
FAL_KEY="Key your_fal_key_here"如果您提供的密钥没有 Key 前缀，Genvoy会自动对其进行规范化。
MCP客户端配置
使用客户端的MCP配置在本地运行已发布的包：
{
"mcpServers": {
"genvoy": {
"command": "uvx",
"args": ["genvoy"],
"env": {
"FAL_KEY": "Key your_fal_key_here"
}
}
}
}对于贡献者（直接从克隆仓库中的源代码运行），请使用：
{
"mcpServers": {
"genvoy-dev": {
"command": "
\\.venv\\Scripts\\python.exe",
"args": ["-m", "genvoy.server"],
"cwd": "
",
"env": {
"FAL_KEY": "Key your_fal_key_here"
}
}
}
}输出路径行为（重要）
Genvoy解析MCP进程工作目录中的相对输出路径(cwd).
这意味着：
- 在一些IDE中相对输出可能落在IDE工件/工作空间文件夹中，
- 不会自动出现在项目repo根目录中。
当您想要确定性放置时，请使用以下模式之一：
- 设置MCP
cwd到你的项目根， - 传递显式绝对值
output_path/repo_path, - 传递相对
repo_path只有当cwd是您的repo根。
安全行为：
- 在允许的根之外的路径遍历被阻止
PATH_TRAVERSAL_BLOCKED.
跨IDE放置提示：
- 如果IDE阻止直接写入目标文件夹，请先生成到IDE的默认工作区输出位置，然后将输出复制/移动到所需的项目文件夹中。
快速验证流程
在启用MCP的IDE中，运行：
search_models为了fluxget_schema为了fal-ai/flux/devestimate_cost为了计数1generate带着一个output_pathlist_resources然后read_resource为了genvoy://models
如果使用管理员范围键： 6\. read_resource 为了 genvoy://recent
型号可用性说明：
- 返回的一些模型
search_models运行时仍可能失败（例如HTTP405)由于提供商端的门控/弃用/访问控制。 - 为了进行可靠的比较运行，对每个模型进行烟雾测试
get_schema+单身generate使用前generate_compare.
工具合同快照
search_models
- 输入：
query，可选category，可选cursor - 兼容性别名：可选
page（映射到cursor)
get_schema
- 输入：
model_id
estimate_cost
- 输入：
model_id，可选count（默认值1)
generate
- 输入：
model_id,prompt,output_path，可选repo_path，可选params - 输出：包括
output_path,repo_path,media_type,cost_usd,duration_ms
generate_batch
- 输入：
model_id,prompt,count,output_dir，可选repo_dir，可选params - 输出：
files[]和failed[]
generate_compare
- 输入：
model_ids[],prompt,output_dir，可选repo_dir，可选params - 输出：
files[]和failed[]
get_job_status
- 输入：
request_id,model_id
cancel_job
- 输入：
request_id,model_id
可靠性和安全性
- 队列优先fal.ai执行(
queue.fal.run) - 带轮询回退的SSE状态流
- 速率限制映射(
RATE_LIMITED) - 队列启动超时映射(
QUEUE_START_TIMEOUT) - 使用范围映射(
ADMIN_KEY_REQUIRED) - 非阻塞I/O(
httpx异步+aiofiles) - 输出文件名冲突处理(
_1,_2, ...)
开发命令
uv run ruff check .
uv run mypy genvoy
uv run pytest --cov --cov-report=term-missing文档地图
- 系统架构：
docs/architecture.md - 构建/测试/发布阶段：
docs/setup.md - 产品级行为概述：
docs/overview.md
许可证
麻省理工学院