内容
# ArtCraft MCP服务端
为[Hermes Agent](https://github.com/NousResearch/hermes-agent)构建的ArtCraft订阅MCP服务端。 它为Hermes提供了实时模型发现、成本估算、参考摄入、图像/视频生成、本地任务查找和可恢复结果检索等工具。
它也可以被任何支持stdio上本地MCP服务端的代理或客户端使用。
欢迎贡献。如果您发现错误、过时的ArtCraft参数或使适配器更安全或更有用的方法，请打开问题或提交拉取请求。帮助测试和优化工具在不同设置下的表现尤为宝贵。
该MCP**不**控制ArtCraft桌面应用程序或其界面。 它读取已安装的ArtCraft应用程序保存的身份验证会话，可选地读取ArtCraft的本地任务数据库，并直接调用ArtCraft的Storyteller订阅API。
⚠ 图像和视频生成会消耗ArtCraft订阅积分。 在生成前请发现实时参数，估算成本，并获得明确的批准。
## Hermes快速入门
### 1. 安装MCP
在Hermes配置文件目录之外克隆存储库：
```bash
git clone https://github.com/smoermeow/artcraft-mcp.git ~/src/artcraft-mcp
cd ~/src/artcraft-mcp
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m unittest -v
```
### 2. 添加到Hermes配置文件
```bash
./scripts/setup-hermes.sh PROFILE
```
将`PROFILE`替换为应接收ArtCraft工具的Hermes配置文件。 辅助程序注册此克隆的绝对Python和服务器路径，设置300秒的MCP超时时间，并测试工具发现。
### 3. 重新加载并验证
在Hermes中运行`/reload-mcp`或重启该配置文件的CLI/网关进程。从终端：
```bash
hermes --profile PROFILE mcp test artcraft
hermes --profile PROFILE mcp list
```
Hermes应该发现18个ArtCraft工具。 可粘贴的Hermes提示和模型调用示例在[docs/USAGE.md](docs/USAGE.md)中。
### 手动Hermes配置
```bash
ROOT="$HOME/src/artcraft-mcp"
hermes --profile PROFILE mcp add artcraft \
--command "$ROOT/.venv/bin/python" \
--connect-timeout 30 \
--args "$ROOT/server.py"
hermes --profile PROFILE config set mcp_servers.artcraft.timeout 300
hermes --profile PROFILE mcp test artcraft
```
等效的YAML可在[examples/hermes-mcp.yaml](examples/hermes-mcp.yaml)中找到。
## 工作原理
ArtCraft在macOS上将活动订阅会话存储在此处：
```text
~/Library/Caches/ai.artcraft.app/.cookies
```
服务器仅读取属于`api.storyteller.ai`的`visitor`和`session` cookie。 它从未返回MCP工具的这些值。 它使用这些凭据调用ArtCraft的订阅API，而不是操作桌面UI。 请参阅[SECURITY.md](SECURITY.md)。
Hermes将`server.py`作为本地子进程启动，并通过标准输入/输出（stdio）交换MCP消息。 不会打开本地端口或公共Web服务器。
## 要求
- 安装并登录了ArtCraft的macOS。
- Python 3.11+。
- Hermes Agent，或另一个支持本地stdio的MCP客户端。
## 查找模型和参数
不要猜测模型选项。 请求Hermes调用：
```text
artcraft_list_image_models
artcraft_list_video_models
```
实时记录公开了确切的模型ID和模型特定的分辨率、持续时间、宽高比、批次限制、引用限制和音频/关键帧支持。 接下来调用相应的免费支出估算器：
```text
artcraft_estimate_image_cost
artcraft_estimate_video_cost
```
有关发现、估算、引用、付费生成和结果检索的完整Hermes提示，请参见[docs/USAGE.md](docs/USAGE.md)。
## 工具
| 组 | 工具 |
| --- | --- |
| 健康/账户 | `artcraft_check_connection`, `artcraft_detect_installation`, `artcraft_credential_status`, `artcraft_get_user_status` |
| 模型/成本 | `artcraft_list_image_models`, `artcraft_list_video_models`, `artcraft_estimate_image_cost`, `artcraft_estimate_video_cost` |
| 任务/结果 | `artcraft_list_tasks`, `artcraft_get_task`, `artcraft_list_subscription_jobs`, `artcraft_get_task_result`, `artcraft_wait_for_result` |
| 引用 | `artcraft_upload_reference_image`, `artcraft_upload_reference_audio`, `artcraft_upload_reference_video` |
| 付费生成 | `artcraft_generate_image_subscription`, `artcraft_generate_video_subscription` |
## 其他MCP客户端
服务器是stdio上的标准MCP。 配置另一个兼容的代理/客户端以运行：
```text
/path/to/artcraft-mcp/.venv/bin/python /path/to/artcraft-mcp/server.py
```
工具行为和安全要求相同。 客户端特定的配置格式不同。
## 安全边界
- 只读发现和估算不会花费积分。
- 上传新引用会写入ArtCraft账户，需要明确批准。
- 付费生成在估算成本后需要明确批准。
- 永远不要提交cookie、ArtCraft数据库、日志、`.env`文件、订阅令牌、私有媒体或私有提示。
## 测试
```bash
.venv/bin/python -m unittest -v
```
GitHub Actions为推送和拉取请求运行相同的测试套件。
## 致谢
该适配器源自[ArtCraft PR #1649, “[BETA] 桌面应用MCP_stdio层”](https://github.com/storytold/artcraft/pull/1649)，由[tanish2k09](https://github.com/tanish2k09)编写。 有关此处独立实施的特定模式，请参见[NOTICE.md](NOTICE.md)。
## 许可证
[MIT](LICENSE)。 有关上游确认，请参见[NOTICE.md](NOTICE.md)。
