resourcespace-mcp-server

v1.1.1

Published

2 months ago

Model Context Protocol server for ResourceSpace API integration

0High
0Medium
0Low

greerso

mcp model-context-protocol resourcespace api dam digital-asset-management ai claude cursor llm typescript

ResourceSpace MCP Server

A comprehensive Model Context Protocol (MCP) server that provides full access to the ResourceSpace Digital Asset Management (DAM) API. This server exposes 100+ ResourceSpace API endpoints as MCP tools, along with browsable resources and workflow prompts.

🎯 Multi-Server Architecture

For optimal performance, the ResourceSpace MCP is split into 4 modular servers:

Main Server (44 tools) - Core DAM operations
Admin Server (18 tools) - User & system management
IIIF Server (5 tools) - IIIF image protocol
Consent Manager Server (8 tools) - Consent management plugin

Total: 75 tools (all servers under the recommended 80-tool limit for Cursor IDE)

👉 See MULTI_SERVER_GUIDE.md for complete setup instructions

Features

75 MCP Tools: Consolidated, efficient coverage of ResourceSpace API
- Main Server (44 tools): Resources (8), Search (7), Collections (8), Metadata (12), Batch (9)
- Admin Server (18 tools): Users (8), System Operations (10)
- IIIF Server (5 tools): IIIF protocol support
- Consent Server (8 tools): Consent management
- CRUD operations consolidated using action parameters for optimal performance
MCP Resources: Browsable URI-based access to assets and collections
- resource://assets/{id} - Asset details
- resource://assets/search?query={q} - Search results
- resource://collections/{id} - Collection contents
- And more...
MCP Prompts: Workflow templates for common tasks
- Asset Upload Workflow
- Search & Filter Workflow
- Collection Management
- Metadata Enrichment
- User Onboarding
- System Health Check

Installation from GitHub

Prerequisites

Node.js 18+ and npm
A ResourceSpace instance with API access
ResourceSpace API credentials (user and API key)

Quick Install

# 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

That's it! The servers are now available as global commands.

Available Commands

After installation, you have access to 4 MCP servers:

resourcespace-mcp-server - Main Server (44 tools) - Core DAM operations
resourcespace-admin-mcp - Admin Server (18 tools) - User & system management
resourcespace-iiif-mcp - IIIF Server (5 tools) - IIIF image protocol
resourcespace-consent-mcp - Consent Manager (8 tools) - Consent plugin

Configuration

Cursor IDE Configuration

Add to your Cursor MCP config file (~/.cursor/mcp.json or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "resourcespace": {
      "command": "resourcespace-mcp-server",
      "env": {
        "RESOURCESPACE_URL": "https://your-instance.com",
        "RESOURCESPACE_USER": "[email protected]",
        "RESOURCESPACE_API_KEY": "your-api-key-here"
      }
    },
    "resourcespace-admin": {
      "command": "resourcespace-admin-mcp",
      "env": {
        "RESOURCESPACE_URL": "https://your-instance.com",
        "RESOURCESPACE_USER": "[email protected]",
        "RESOURCESPACE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Claude Desktop Configuration

Add to your Claude Desktop config file:

macOS: ~/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": "[email protected]",
        "RESOURCESPACE_API_KEY": "your-api-key-here"
      }
    }
  }
}

Note: You can enable any combination of the 4 servers. Most users only need the main server.

Getting Your API Key

Log into your ResourceSpace instance
Go to User Preferences → API Keys
Generate a new API key
Copy the key and use it in your configuration

See MULTI_SERVER_GUIDE.md for detailed setup instructions and use cases for each server.

API Coverage

Resource Management Tools

| Tool | Description | |------|-------------| | get_resource_data | Get comprehensive data for a resource | | get_resource_field_data | Get specific field data | | get_resource_path | Get file path/URL for a resource | | create_resource | Create a new resource | | update_field | Update metadata field value | | delete_resource | Delete a resource | | get_resource_types | Get all resource types | | get_alternative_files | Get alternative files for a resource | | add_alternative_file | Add alternative file | | delete_alternative_file | Remove alternative file | | get_resource_access | Get access level | | upload_file | Upload file to resource | | copy_resource | Duplicate a resource | | get_resource_type_fields | Get fields for resource type | | revert_resource_to_alternative | Replace with alternative file | | get_related_resources | Get related resources | | add_resource_nodes | Add keywords/categories | | delete_resource_nodes | Remove keywords/categories | | get_resource_log | Get activity log | | resource_download | Log download event |

Search & Discovery Tools

| Tool | Description | |------|-------------| | do_search | Perform resource search | | get_search_results | Get search results with options | | search_get_previews | Get preview information | | get_recent_resources | Get recently added resources | | search_public_collections | Search public collections | | get_search_filter_nodes | Get available filters | | get_resource_collections | Get collections for resource | | get_themes | Get search themes | | search_advanced | Advanced field-specific search | | get_facets | Get faceted search options | | get_keywords | Get keyword suggestions | | get_smart_themes | Get smart theme collections | | get_featured_collections | Get featured collections |

Collections Management Tools

| Tool | Description | |------|-------------| | get_collections | Get all collections | | get_collection | Get collection details | | get_collection_resources | Get resources in collection | | create_collection | Create new collection | | delete_collection | Delete collection | | add_resource_to_collection | Add resource to collection | | remove_resource_from_collection | Remove resource from collection | | update_collection | Update collection properties | | get_public_collections | Get public collections | | share_collection | Share via email | | get_collection_external_access | Get external access keys | | create_collection_external_access | Create external access | | delete_collection_external_access | Delete external access | | collection_email | Email collection details | | get_collection_log | Get activity log | | copy_collection | Duplicate collection | | add_collection_smart_search | Convert to smart collection | | get_theme_category_collections | Get theme category collections | | order_collection_resources | Set custom order |

Metadata & Fields Tools

| Tool | Description | |------|-------------| | get_resource_type_fields | Get metadata fields | | get_resource_field_data | Get field data | | update_field | Update field value | | copy_field | Copy field between resources | | get_field_data | Get field information | | create_resource_field | Create new field | | update_resource_field | Update field configuration | | delete_resource_field | Delete field | | get_nodes | Get field nodes/options | | get_node | Get node details | | create_node | Create dropdown option | | update_node | Update node value | | delete_node | Delete node | | get_resource_nodes | Get resource's nodes | | add_resource_nodes | Add nodes to resource | | delete_resource_nodes | Remove nodes | | get_field_options | Get dropdown options | | copy_resource_metadata | Copy all metadata | | get_exif_data | Get EXIF metadata | | extract_exif_comment | Parse EXIF comments | | update_resource_type | Change resource type | | get_field_values | Get distinct field values | | validate_field_value | Validate field value |

User Management Tools

| Tool | Description | |------|-------------| | get_users | Get all users | | get_user | Get user details | | create_user | Create new user | | update_user | Update user account | | delete_user | Delete user | | get_usergroups | Get user groups | | get_usergroup | Get group details | | create_usergroup | Create user group | | update_usergroup | Update user group | | delete_usergroup | Delete user group | | get_user_preferences | Get user preferences | | save_user_preferences | Save preferences | | get_user_activity | Get activity log | | get_user_collections | Get user's collections | | approve_user | Approve pending user |

System Operations Tools

| Tool | Description | |------|-------------| | get_system_info | Get system information | | get_config_options | Get configuration options | | set_config_option | Set configuration | | get_plugins | Get installed plugins | | get_plugin_config | Get plugin configuration | | set_plugin_config | Set plugin configuration | | get_job_queue | Get job queue status | | clear_job_queue | Clear job queue | | get_resource_stats | Get resource statistics | | get_system_status | Get system health | | clear_cache | Clear system cache | | reindex_resources | Reindex metadata | | get_activity_log | Get system activity log |

Batch Operations Tools

| Tool | Description | |------|-------------| | batch_update_field | Update field for multiple resources | | batch_add_to_collection | Add multiple resources to collection | | batch_remove_from_collection | Remove multiple from collection | | batch_delete_resources | Delete multiple resources | | batch_update_archive_status | Update archive status | | batch_copy_field | Copy field to multiple resources | | batch_add_nodes | Add nodes to multiple resources | | batch_delete_nodes | Remove nodes from multiple | | batch_download_resources | Prepare batch download | | batch_email_resources | Email multiple resources |

Example Usage

Searching for Assets

// Using the do_search tool
{
  "search": "landscape mountains",
  "restypes": "1,2",
  "archive": 0,
  "per_page": 20,
  "order_by": "relevance"
}

Creating and Populating a Collection

// 1. Create collection
{
  "name": "Marketing Campaign 2024",
  "public": false,
  "allow_changes": true
}

// 2. Add resources
{
  "resource_ids": [101, 102, 103],
  "collection_id": 42
}

Batch Updating Metadata

// Update copyright field for multiple resources
{
  "resource_ids": [101, 102, 103, 104],
  "field_id": 5,
  "value": "© 2024 Company Name"
}

Authentication

ResourceSpace uses MD5 signature authentication. The server automatically:

Constructs query string with user and parameters
Generates MD5 hash: md5(API_KEY + query_string)
Appends signature to request

Example authentication flow:

Query: user=admin&function=get_resource_data&param1=123
Sign: md5(YOUR_API_KEY + query_string)
URL: /api/?user=admin&function=get_resource_data&param1=123&sign=abc123...

Error Handling

The server includes comprehensive error handling:

Network errors: Automatic retry with exponential backoff
API errors: Structured error responses with details
Validation errors: Zod schema validation for all inputs
Timeout handling: Configurable request timeouts

Configuration Options

All configuration via environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | RESOURCESPACE_URL | Yes | - | Your ResourceSpace instance URL | | RESOURCESPACE_USER | Yes | - | API username | | RESOURCESPACE_API_KEY | Yes | - | API key/private key | | LOG_LEVEL | No | info | Logging level (debug/info/warn/error) | | REQUEST_TIMEOUT | No | 30000 | Request timeout in ms | | MAX_RETRIES | No | 3 | Max retry attempts | | RETRY_DELAY | No | 1000 | Delay between retries in ms |

Development

Project Structure

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

Building

npm run build

Running in Development

npm run dev

Troubleshooting

Connection Issues

Verify credentials: Check URL, username, and API key in .env
Test API directly: Use ResourceSpace's built-in API test tool
Check network: Ensure server can reach ResourceSpace instance
Review logs: Check console output for detailed error messages

API Errors

"Invalid signature": API key is incorrect
"Function not found": ResourceSpace version may not support that endpoint
"Permission denied": User lacks required permissions
Timeout errors: Increase REQUEST_TIMEOUT value

ResourceSpace API Documentation

For detailed information about specific API endpoints, refer to the official ResourceSpace API documentation: https://www.resourcespace.com/knowledge-base/api/

License

MIT

Contributing

Contributions welcome! Please open issues or pull requests on the GitHub repository.

Support

For issues with this MCP server, please open an issue on GitHub.

For ResourceSpace API questions, consult the official ResourceSpace documentation.