内容
# 魔术小时 MCP 服务器
基于 OpenAPI 的 MCP 服务器，用于魔术小时的图像、视频和音频生成。
启动时，该服务器读取 `docs/openapi.json` 并使用 `FastMCP.from_openapi()` 构建 MCP 工具。OpenAPI 规范提供了端点覆盖，而魔术小时 MCP 策略为异步轮询、上传和项目下载提供了面向代理的指导。
用户指南详见：`user.md`
## 当前支持
- 本地 MCP 检查器
- Claude 代码
- Codex CLI 带有远程 HTTP MCP
- 手动 Claude 桌面样式配置，允许自定义标头
- 后端安装的 HTTP MCP，位于 `/mcp`
- 通过独立的 `fastmcp` 进行运行时 OpenAPI 工具生成
## 本仓库不包含
- OAuth 或 Web 连接器身份验证
- 聊天原生文件上传 UI
- 用于 Web 聊天客户端的服务器端上传桥
核心文档：
- `user.md` - 主机端点用户指南
- `integration-handoff.md` - FastAPI 安装和烟雾测试指南
- `docs/detailed-step-by-step-integration.md` - 分步后端集成指南
- `docs/ai-agent-go-live-instructions.md` - 为另一个 AI 代理提供产品集成说明
## 设置
```sh
pip install -e .
```
## 在本地运行
```sh
python main.py
```
本地 MCP 端点：
```text
http://127.0.0.1:8000/
```
此本地开发服务器在 `/` 处运行，而不是 `/mcp`。主机应用程序在安装服务器时添加 `/mcp`。
默认情况下，它调用位于：
```text
https://api.magichour.ai
```
的真实魔术小时 API
每个 MCP 请求都必须包含您的魔术小时 API 密钥：
```text
Authorization: Bearer <magic_hour_api_key>
```
可选环境变量：
```sh
MAGIC_HOUR_API_BASE_URL=https://api.magichour.ai
MAGIC_HOUR_OPENAPI_PATH=docs/openapi.json
```
您仍然可以通过覆盖 `MAGIC_HOUR_API_BASE_URL` 来指向模拟或替代 API 基址：
```sh
MAGIC_HOUR_API_BASE_URL=https://api.sideko.dev/v1/mock/magichour/magic-hour/latest python main.py
```
## 使用 MCP 检查器进行测试
1. 启动服务器。
2. 运行：
```sh
npx @modelcontextprotocol/inspector
```
3. 在检查器中：
- 传输：`Streamable HTTP`
- URL：`http://127.0.0.1:8000/`
- 标头：`Authorization: Bearer <magic_hour_api_key>`
4. 调用 `ping`。
5. 调用生成的 OpenAPI 工具，例如 `videoAssets_generatePresignedUrl` 或 `textToVideo_createVideo`，或自定义的 `wait_for_*_project` 工具。
注意：
- 运行时 OpenAPI 服务器不再手动注册每个端点。
- 生成的创建工具立即返回，带有 `id` 和 `credits_charged`。
- 我们故意不维护每个端点的友好别名。FastMCP 从 OpenAPI `operationId` 派生工具名称，例如 `textToVideo_createVideo` 和 `imageProjects_getDetails`。
- 共享的 `/v1/files/upload-urls` 端点当前作为 `videoAssets_generatePresignedUrl` 公开，因为这是上游 OpenAPI `operationId`；它接受 `video`、`audio` 和 `image` 项。
- 使用匹配的生成的项目详细信息工具或自定义的 `wait_for_*_project` 助手来检索完成的 `downloads`。
- `wait_for_video_project`、`wait_for_image_project` 和 `wait_for_audio_project` 返回净化的下载字段，以便签名 URL 与过期元数据保持分离。
- `wait_for_image_project` 和 `wait_for_audio_project` 还尝试在同一响应中内联完成媒体，同时返回完整的项目 JSON。
- `fetch_image_download` 和 `fetch_audio_download` 仍然可用作备用工具，如果您想重试特定的 `downloads[n].url`。
## 使用 Claude 代码进行测试
为当前仓库/项目注册本地 HTTP MCP 服务器：
```sh
claude mcp add --scope project --transport http magic-hour http://127.0.0.1:8000/ --header "Authorization: Bearer API_KEY"
```
然后在此仓库中启动新的 Claude 代码会话。
## 使用 Codex CLI 进行测试
Codex 支持流式 HTTP MCP 服务器和 bearer token 身份验证。
1. 启动服务器：
```sh
python main.py
```
2. 设置临时 API 密钥环境变量：
```sh
export MAGIC_HOUR_API_KEY=test-key
```
在 PowerShell 上：
```powershell
$env:MAGIC_HOUR_API_KEY = "test-key"
```
3. 注册 MCP 服务器：
```sh
codex mcp add magic-hour --url http://127.0.0.1:8000/ --bearer-token-env-var MAGIC_HOUR_API_KEY
```
4. 验证配置：
```sh
codex mcp get magic-hour --json
```
5. 在此仓库中启动新的 Codex 会话，并要求它调用 `ping`。
注意：
- 这适用于当前的 API 密钥直通模型。OAuth 对于 Codex CLI 不必填。
- 真实 API 调用可能会花费魔术小时积分。
- 从设置 `MAGIC_HOUR_API_KEY` 的同一 shell 启动 Codex。Codex 必须继承该环境，以便 MCP 服务器出现并正确身份验证。
## 文件上传
魔术小时不接受工具参数中的原始文件字节。流程如下：
1. 调用生成的共享上传 URL 工具，目前为 `videoAssets_generatePresignedUrl`
2. 将文件字节上传到返回的 `upload_url`
3. 将返回的 `file_path` 传递到生成的创建工具中
直接公共媒体 URL 在稳定且可获取时可能有效，但上传流程是本地文件、热链接资产或可能无法一致返回原始文件字节的任何内容的可靠路径。
Claude 代码可以处理这一点，因为它具有 shell 访问权限。普通的聊天附件不能干净地映射到此 API。
## 上传示例，供未来聊天 UI 使用
对于基于上传的工具，例如 `imageToVideo_createVideo`：
1. 为 `image` 调用 `videoAssets_generatePresignedUrl`；同一工具也接受 `video` 和 `audio`
2. 将本地文件字节上传到返回的 `upload_url`
3. 将返回的 `file_path` 传递到 `imageToVideo_createVideo.assets.image_file_path`
生成的上传 URL 工具在步骤 1 处停止。对于本地 CLI 测试，自定义 `upload_file_to_presigned_url` 助手可以执行步骤 2，如果 MCP 服务器可以读取本地文件路径。对于远程/网络聊天，调用者或主机应用程序仍然需要处理上传桥。
## 内联媒体和签名 URL
在项目完成后进行检查器测试：
1. 调用 `wait_for_video_project`、`wait_for_image_project` 或 `wait_for_audio_project`
2. 使用 `exact_download_urls[n]` 作为确切的链接来共享或打开
3. 对于图像/音频项目，请在同一响应中查找内联媒体块
4. 如果特定的图像/音频下载没有干净地内联，请使用 `fetch_image_download` 或 `fetch_audio_download` 重试它
图像/音频等待助手现在尝试下载并返回生成的媒体作为 MCP 图像/音频内容，而不是让您在快乐路径中操作第二个工具。
在共享链接时，仅使用 `exact_download_urls[n]` 或确切的 `downloads[n].url` 值。不要将 `expires_at` 或 `download_expiration_metadata` 值附加到 URL。
有关未来的 Web 聊天工作，请参见 `docs/future-chat-ui-handoff.md`。
