MCP Server¶
AIMage SDK 提供可选的 Search MCP server，让支持 Model Context Protocol 的客户端通过工具调用访问 AI-Mage Search。
MCP 官方 Python SDK 的稳定 v1 使用 FastMCP 创建 server，并支持 stdio、SSE 和 Streamable HTTP transport。AIMage SDK 将 MCP 依赖放在 optional extra 中，普通 SDK 安装不会额外安装 MCP 运行时。
安装¶
本地开发时：
认证与服务环境¶
MCP server 使用与 SearchClient 相同的环境变量：
| 环境变量 | 说明 |
|---|---|
AIMAGE_API_KEY |
API Key，优先级高于 token |
AIMAGE_SEARCH_TOKEN |
Bearer Token |
AIMAGE_SEARCH_SERVICE |
PROD、DEV、STAGING、LOCAL 或自定义 URL |
AIMAGE_SEARCH_BASE_URL |
自定义 API origin，优先级高于 service |
AIMAGE_MCP_TIMEOUT |
请求超时秒数，默认 30 |
AIMAGE_MCP_TRANSPORT |
默认 transport，默认 stdio |
AIMAGE_MCP_ENABLE_WRITE / AIMAGE_MCP_ENABLE_WRITES |
设为 1 / true 时暴露写入工具 |
AIMAGE_MCP_ENABLE_DELETE / AIMAGE_MCP_ENABLE_DELETES |
设为 1 / true 时暴露删除工具，需要同时开启写入 |
AIMAGE_MCP_ENABLE_RAW_RPC |
设为 1 / true 时暴露 raw ORPC passthrough |
运行¶
默认使用 stdio，适合被 MCP 客户端拉起：
也可以显式指定环境：
需要远程/本地 HTTP 调试时：
需要暴露写入接口时必须显式开启：
删除接口需要再开启一层：
raw ORPC 默认不暴露；确实需要调试底层 procedure 时再开启：
客户端配置示例¶
stdio 客户端通常配置为：
{
"mcpServers": {
"aimage-search": {
"command": "aimage-mcp-search",
"env": {
"AIMAGE_API_KEY": "your_api_key",
"AIMAGE_SEARCH_SERVICE": "DEV"
}
}
}
}
写入模式：
{
"mcpServers": {
"aimage-search": {
"command": "aimage-mcp-search",
"args": ["--enable-write"],
"env": {
"AIMAGE_API_KEY": "your_api_key"
}
}
}
}
工具范围¶
只读模式默认暴露：
| 工具 | 说明 |
|---|---|
aimage_search_health |
检查 Search 服务健康状态 |
aimage_search_list_projects / aimage_search_get_project |
项目列表与详情 |
aimage_search_list_videos / aimage_search_get_video / aimage_search_video_processed_files |
视频与处理产物 |
aimage_search_text_search_clips / aimage_search_get_clip |
Clip 搜索与详情 |
aimage_search_list_characters |
角色列表 |
aimage_search_list_resources |
资源/其他材料列表 |
aimage_search_list_reference_images |
参考图像列表 |
aimage_search_list_translation_tables / aimage_search_list_translation_table_entries |
翻译表和条目 |
aimage_search_query_novels |
小说检索 |
aimage_search_agent_read_project_context / aimage_search_agent_read_tag_options / aimage_search_agent_read_characters |
Agent 项目上下文读取 |
aimage_search_agent_search_clips / aimage_search_agent_search_novels / aimage_search_agent_hydrate_clips |
Agent 检索与补全 |
开启写入后额外暴露：
| 工具 | 说明 |
|---|---|
aimage_search_update_project_settings |
更新 agent model 与功能开关 |
aimage_search_update_clip* |
更新 Clip、字幕、标签、角色 |
aimage_search_create_character / aimage_search_update_character |
角色创建与更新 |
aimage_search_create_resource / aimage_search_update_resource |
其他材料创建与更新 |
aimage_search_create_reference_image / aimage_search_update_reference_image |
参考图像创建与更新 |
aimage_search_create_translation_table* / aimage_search_update_translation_table* |
翻译表与条目创建与更新 |
aimage_search_agent_save_generated_image |
保存 Agent 生成图 |
aimage_search_create_conversation / aimage_search_add_conversation_message / aimage_search_switch_conversation_branch |
Chatbot 对话与分支 |
删除工具只有同时开启 --enable-write --enable-delete 时才注册，包括 aimage_search_delete_character、aimage_search_delete_resource、aimage_search_delete_reference_image、aimage_search_delete_translation_table 和 aimage_search_delete_translation_table_entry。raw ORPC passthrough 只有开启 --enable-raw-rpc 时才注册；不开启写入时，它会拒绝明显写入类 procedure，不开启删除时会拒绝 delete procedure。
写入权限
MCP 客户端会把工具暴露给 agent。默认不注册写入工具；只有确认当前客户端、账号和项目权限都适合自动化写入时再开启 --enable-write。