使用说明
ResourceSpace MCP 服务器
一个全面的模型上下文协议(MCP)服务器,提供对ResourceSpace数字资产管理(DAM)API的全面访问。该服务器将100多个ResourceSpace API端点作为MCP工具公开,同时还提供可浏览的资源和工作流提示。
🎯 多服务器架构
为了达到最佳性能,ResourceSpace MCP被划分为 4台模块化服务器:
- 主服务器 (44种工具) - 核心数字资产管理(DAM)操作
- 管理服务器 (18种工具) - 用户与系统管理
- IIIF服务器 (5种工具) - IIIF图像协议
- 同意管理服务器 (8种工具) - 同意管理插件
总计:75个工具 (所有服务器均在Cursor IDE推荐的80个工具限制之内)
👉 看 MULTI_SERVER_GUIDE.md 翻译为中文是:“多服务器指南.md” 完整的设置说明
特性/特点
-
75个MCP工具资源空间API的整合与高效覆盖
- **主服务器(44个工具)**资源(8),搜索(7),集合(8),元数据(12),批量(9)
- **管理服务器(18种工具)**用户(8),系统操作(10)
- **IIIF 服务器(5种工具)**支持IIIF协议
- **同意服务器(8种工具)**同意管理
- 使用操作参数整合CRUD操作以实现最佳性能
-
**MCP Resources(公司名,可译为“MCP资源公司”或根据具体语境调整)**基于URI的可浏览资产和集合访问
resource://assets/{id}- 资产详情resource://assets/search?query={q}- 搜索结果resource://collections/{id}- 收藏内容- 以及更多。。。
-
MCP 提示常见任务的工作流模板
- 资产上传工作流
- 搜索与筛选工作流程
- 藏品管理
- 元数据丰富化
- 用户入职/引导(或“用户上手”)
- 系统健康检查
从GitHub安装
先决条件
- Node.js 18+ 和 npm
- 一个具有API访问权限的ResourceSpace实例
- 资源空间API凭证(用户和API密钥)
快速安装
# Clone the repository
git clone https://github.com/Magnolia-Tech-Services-LLC/ressourcespaceMCP.git
cd ressourcespaceMCP
# Install dependencies and build (auto-builds via postinstall)
npm install
# Install globally to make commands available everywhere
npm link
搞定!服务器现在可以作为全局命令使用了。
可用命令
安装后,您将可以访问4台MCP服务器:
resourcespace-mcp-server- 主服务器 (44种工具) - 核心数字资产管理(DAM)操作resourcespace-admin-mcp- 管理服务器 (18种工具) - 用户与系统管理resourcespace-iiif-mcp- IIIF 服务器 (5种工具)- IIIF图像协议resourcespace-consent-mcp- 同意管理器 (8种工具) - 同意插件
配置
Cursor IDE 配置
添加到你的Cursor MCP配置文件中(~/.cursor/mcp.json 或者 .cursor/mcp.json (在你的项目中):
{
"mcpServers": {
"resourcespace": {
"command": "resourcespace-mcp-server",
"env": {
"RESOURCESPACE_URL": "https://your-instance.com",
"RESOURCESPACE_USER": "your-email@example.com",
"RESOURCESPACE_API_KEY": "your-api-key-here"
}
},
"resourcespace-admin": {
"command": "resourcespace-admin-mcp",
"env": {
"RESOURCESPACE_URL": "https://your-instance.com",
"RESOURCESPACE_USER": "your-email@example.com",
"RESOURCESPACE_API_KEY": "your-api-key-here"
}
}
}
}
Claude 桌面配置
在您的Claude桌面配置文件中添加:
macOS(发音:/ˈmæk θiː əs/): ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"resourcespace": {
"command": "resourcespace-mcp-server",
"env": {
"RESOURCESPACE_URL": "https://your-instance.com",
"RESOURCESPACE_USER": "your-email@example.com",
"RESOURCESPACE_API_KEY": "your-api-key-here"
}
}
}
}
注: 您可以启用这4台服务器中的任意组合。大多数用户仅需要主服务器。
获取您的API密钥
- 登录到您的ResourceSpace实例
- 首选 用户偏好 → API密钥
- 生成一个新的API密钥
- 复制密钥并在您的配置中使用它
看 MULTI_SERVER_GUIDE.md 翻译为中文是:“多服务器指南.md” 以下是每台服务器的详细设置说明和使用案例。
API覆盖率
资源管理工具
| 工具 | 描述 |
|---|---|
get_resource_data |
获取资源的全面数据 |
get_resource_field_data |
获取特定字段数据 |
get_resource_path 获取资源的文件路径/URL |
|
create_resource |
创建新资源 |
update_field |
更新元数据字段值 |
delete_resource |
删除资源 |
get_resource_types |
获取所有资源类型 |
get_alternative_files |
获取资源的替代文件 |
add_alternative_file |
添加替代文件 |
delete_alternative_file |
移除备用文件 |
get_resource_access |
获取访问级别 |
upload_file |
将文件上传到资源 |
copy_resource |
复制资源 |
get_resource_type_fields |
获取资源类型的字段 |
revert_resource_to_alternative |
用替代文件替换 |
get_related_resources |
获取相关资源 |
add_resource_nodes |
添加关键词/类别 |
delete_resource_nodes |
移除关键词/分类 |
get_resource_log |
获取活动日志 |
resource_download |
日志下载事件 |
搜索与发现工具
| 工具 | 描述 |
|---|---|
do_search |
执行资源搜索 |
get_search_results |
获取带选项的搜索结果 |
search_get_previews |
获取预览信息 |
get_recent_resources |
获取最近添加的资源 |
search_public_collections |
搜索公共收藏 |
get_search_filter_nodes |
获取可用过滤器 |
get_resource_collections |
获取资源的集合 |
get_themes |
获取搜索主题 |
search_advanced |
高级专业领域搜索 |
get_facets |
获取分面搜索选项 |
get_keywords |
获取关键词建议 |
get_smart_themes |
获取智能主题集锦 |
get_featured_collections |
获取精选集合 |
收藏管理工具
| 工具 | 描述 |
|---|---|
get_collections |
获取所有集合 |
get_collection |
获取收藏详情 |
get_collection_resources |
获取集合中的资源 |
create_collection |
创建新收藏夹 |
delete_collection |
删除收藏集 |
add_resource_to_collection |
将资源添加到集合中 |
remove_resource_from_collection |
从集合中移除资源 |
update_collection |
更新集合属性 |
get_public_collections |
获取公共收藏集 |
share_collection |
通过电子邮件分享 |
get_collection_external_access |
获取外部访问密钥 |
create_collection_external_access |
创建外部访问 |
delete_collection_external_access |
删除外部访问 |
collection_email |
电子邮件收集详情 |
get_collection_log |
获取活动日志 |
copy_collection |
重复集合 |
add_collection_smart_search |
转换为智能集合 |
get_theme_category_collections |
获取主题分类集合 |
order_collection_resources |
设置自定义订单 |
元数据与字段工具
| 工具 | 描述 |
|---|---|
get_resource_type_fields |
获取元数据字段 |
get_resource_field_data |
获取现场数据 |
update_field |
更新字段值 |
copy_field |
在资源之间复制字段 |
get_field_data |
获取字段信息 |
create_resource_field |
创建新字段 |
update_resource_field |
更新字段配置 |
delete_resource_field |
删除字段 |
get_nodes |
获取字段节点/选项 |
get_node |
获取节点详细信息 |
create_node |
创建下拉选项 |
update_node |
更新节点值 |
delete_node |
删除节点 |
get_resource_nodes |
获取资源的节点 |
add_resource_nodes |
向资源中添加节点 |
delete_resource_nodes |
移除节点 |
get_field_options |
获取下拉选项 |
copy_resource_metadata |
复制所有元数据 |
get_exif_data |
获取EXIF元数据 |
extract_exif_comment 解析EXIF注释 |
|
update_resource_type |
更改资源类型 |
get_field_values |
获取字段的唯一值 |
validate_field_value |
验证字段值 |
用户管理工具
| 工具 | 描述 |
|---|---|
get_users |
获取所有用户 |
get_user |
获取用户详细信息 |
create_user |
创建新用户 |
update_user |
更新用户账户 |
delete_user |
删除用户 |
get_usergroups |
获取用户组 |
get_usergroup |
获取群组详情 |
create_usergroup |
创建用户组 |
update_usergroup |
更新用户组 |
delete_usergroup |
删除用户组 |
get_user_preferences |
获取用户偏好 |
save_user_preferences |
保存偏好设置 |
get_user_activity |
获取活动日志 |
get_user_collections |
获取用户的收藏集 |
approve_user |
审批待处理用户 |
系统操作工具
| 工具 | 描述 |
|---|---|
get_system_info |
获取系统信息 |
get_config_options |
获取配置选项 |
set_config_option |
设置配置 |
get_plugins |
获取已安装插件 |
get_plugin_config |
获取插件配置 |
set_plugin_config |
设置插件配置 |
get_job_queue |
获取作业队列状态 |
clear_job_queue |
清除作业队列 |
get_resource_stats |
获取资源统计信息 |
get_system_status |
获取系统健康状况 |
clear_cache |
清除系统缓存 |
reindex_resources |
重新索引元数据 |
get_activity_log |
获取系统活动日志 |
批处理操作工具
| 工具 | 描述 |
|---|---|
batch_update_field |
更新多个资源的字段 |
batch_add_to_collection |
向集合中添加多个资源 |
batch_remove_from_collection |
从集合中移除多个项 |
batch_delete_resources |
删除多个资源 |
batch_update_archive_status |
更新存档状态 |
batch_copy_field |
将字段复制到多个资源 |
batch_add_nodes |
向多个资源添加节点 |
batch_delete_nodes |
从多个节点中移除节点 |
batch_download_resources |
准备批量下载 |
batch_email_resources |
向多个资源发送电子邮件 |
示例用法
搜索资产
// Using the do_search tool
{
"search": "landscape mountains",
"restypes": "1,2",
"archive": 0,
"per_page": 20,
"order_by": "relevance"
}
创建并填充集合
// 1. Create collection
{
"name": "Marketing Campaign 2024",
"public": false,
"allow_changes": true
}
// 2. Add resources
{
"resource_ids": [101, 102, 103],
"collection_id": 42
}
批量更新元数据
// Update copyright field for multiple resources
{
"resource_ids": [101, 102, 103, 104],
"field_id": 5,
"value": "© 2024 Company Name"
}
认证
ResourceSpace 使用 MD5 签名认证。服务器会自动:
- 构建包含用户和参数的查询字符串
- 生成MD5哈希值:
md5(API_KEY + query_string) - 在请求中附加签名
示例认证流程:
Query: user=admin&function=get_resource_data¶m1=123
Sign: md5(YOUR_API_KEY + query_string)
URL: /api/?user=admin&function=get_resource_data¶m1=123&sign=abc123...
错误处理
该服务器包含全面的错误处理机制:
- 网络错误自动重试,采用指数退避策略
- API错误带有详细信息的结构化错误响应
- 验证错误对所有输入进行Zod模式验证
- 超时处理可配置的请求超时时间
配置选项
所有配置均通过环境变量进行:
| 变量 | 必需 | 默认值 | 描述 |
|---|---|---|---|
RESOURCESPACE_URL |
是 | - | 您的ResourceSpace实例URL |
RESOURCESPACE_USER 是 |
- | API用户名 | |
RESOURCESPACE_API_KEY 是 |
- | API密钥/私钥 | |
LOG_LEVEL |
序号 | info |
日志级别(调试/信息/警告/错误) |
REQUEST_TIMEOUT |
编号 | 30000 |
请求超时时间(毫秒) |
MAX_RETRIES |
编号 | 3 |
最大重试次数 |
RETRY_DELAY |
不(No) | 1000 |
重试之间的延迟(毫秒) |
发展
项目结构
ressourcespaceMCP/
├── src/
│ ├── index.ts # Main MCP server
│ ├── config.ts # Configuration management
│ ├── client/
│ │ └── resourcespace.ts # API client
│ ├── tools/ # MCP tools
│ │ ├── resources.ts
│ │ ├── search.ts
│ │ ├── collections.ts
│ │ ├── metadata.ts
│ │ ├── users.ts
│ │ ├── system.ts
│ │ └── batch.ts
│ ├── resources/ # MCP resources
│ │ ├── asset-browser.ts
│ │ └── collection-browser.ts
│ ├── prompts/ # MCP prompts
│ │ └── templates.ts
│ └── types/
│ └── resourcespace.ts # TypeScript types
├── package.json
├── tsconfig.json
└── README.md
建筑
npm run build
在开发中运行
npm run dev
故障排除
连接问题
- 验证凭据请检查URL、用户名和API密钥
.env - 直接测试API使用ResourceSpace内置的API测试工具
- 检查网络确保服务器能够访问ResourceSpace实例
- 审查日志检查控制台输出以获取详细的错误信息
API 错误
- **“无效的签名”**API密钥不正确
- **“函数未找到”**ResourceSpace版本可能不支持该端点
- **“权限被拒绝”**用户缺少所需的权限
- 超时错误增加
REQUEST_TIMEOUT价值
资源空间API文档
如需有关特定API端点的详细信息,请参阅官方ResourceSpace API文档: https://www.resourcespace.com/knowledge-base/api/ 的中文翻译是:“https://www.resourcespace.com/知识库/API/”。不过,通常在实际使用中,我们可能会简化为“资源空间API知识库”或类似表述,以更符合中文表达习惯。但直接翻译网址时,保留原格式更为常见
许可证
麻省理工学院(MIT)
贡献;助力
欢迎贡献!请在(项目/仓库)上提出问题或提交拉取请求 GitHub 仓库。
支持
对于此MCP服务器的相关问题,请 打开一个问题(或议题) 在GitHub上。
如需有关ResourceSpace API的问题,请参阅官方ResourceSpace文档。