Content
# EDC MCP Server
A Model Context Protocol (MCP) server for Eclipse Dataspace Components (EDC), enabling AI assistants like Claude to interact with EDC connectors for dataspace operations.
## Overview
This project provides a FastMCP-based server that exposes EDC Management API functionality through MCP tools. It allows AI assistants to perform dataspace operations such as managing assets, policies, catalogs, contract negotiations, and data transfers.
### What is EDC?
[Eclipse Dataspace Components (EDC)](https://github.com/eclipse-edc/Connector) is a framework for sovereign, inter-organizational data exchange. It implements the Dataspace Protocol and provides APIs for managing data assets, access policies, contract negotiations, and data transfers in a decentralized manner.
### What is MCP?
The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open protocol that standardizes how applications provide context to LLMs. This server implements MCP to make EDC functionality accessible to AI assistants.
## Features
- **Asset Management**: Create, read, update, and delete data assets
- **Policy Definitions**: Manage access control policies for assets
- **Contract Definitions**: Define contractual terms for data access
- **Catalog Operations**: Browse and search data catalogs
- **Federated Catalog**: Query across multiple dataspaces using SPARQL
- **Contract Negotiations**: Initiate and manage contract agreements
- **Transfer Processes**: Execute data transfers (HTTP pull/push)
- **Dataset Operations**: Retrieve dataset metadata and thing descriptions
- **Background Refresh**: Automatic federated catalog updates
## Installation
### Prerequisites
- Python 3.11 or higher
- Access to an EDC connector instance
### From Source
```bash
# Clone the repository
git clone https://github.com/soofi-project/edc-mcp.git
cd edc-mcp
# Create a virtual environment
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
# Install the package
pip install -e .
```
### Using Docker
```bash
# Pull the published multi-architecture image
docker pull ghcr.io/soofi-project/edc-mcp:latest
# Run the container
docker run --rm -p 8081:8081 \
-e EDC_MANAGEMENT_URL=http://host.docker.internal:5173/api/management \
-e EDC_CATALOG_URL=http://host.docker.internal:5173/api/catalog \
ghcr.io/soofi-project/edc-mcp:latest
```
Replace `host.docker.internal` with the hostname or service name that is reachable from the container.
For local image development:
```bash
# Build the image
docker build -t edc-mcp .
# Run the container
docker run --rm -p 8081:8081 \
-e EDC_MANAGEMENT_URL=http://host.docker.internal:5173/api/management \
-e EDC_CATALOG_URL=http://host.docker.internal:5173/api/catalog \
edc-mcp
```
## Configuration
Set the following environment variables before starting the server:
- `EDC_MANAGEMENT_URL`: EDC Management API endpoint (default: `http://localhost:5173/api/management`)
- `EDC_CATALOG_URL`: EDC catalog API endpoint used for federated catalog refreshes (default: `http://localhost:5173/api/catalog`)
- `CATALOG_REFRESH_INTERVAL`: Federated catalog refresh interval in seconds (default: `300`)
- `CATALOG_BASE_URI`: Base URI used when parsing catalog JSON-LD into RDF (default: `urn:edc:catalog/`)
- `LOG_LEVEL`: Python log level for this server (default: `INFO`)
Example:
```bash
export EDC_MANAGEMENT_URL=http://localhost:5173/api/management
export EDC_CATALOG_URL=http://localhost:5173/api/catalog
```
## Usage
### Starting the Server
```bash
# Run directly
python -m edc_mcp.main
# Or using the installed command
edc-mcp
```
The server will start on `http://0.0.0.0:8081` by default.
### Using with Claude Desktop
Add to your Claude Desktop configuration (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"edc": {
"url": "http://localhost:8081/mcp"
}
}
}
```
## Available Tools
### Asset Management
- `create_asset` - Create a new asset with properties and data address
- `list_assets` - List all assets with pagination
- `find_assets` - Search assets using filter expressions
- `get_asset` - Retrieve a specific asset by ID
- `update_asset_properties` - Update asset metadata
- `update_asset_private_properties` - Update private asset properties
- `update_asset_data_address` - Update asset data address configuration
- `delete_asset` - Remove an asset
### Policy Definitions
- `create_policy_definition` - Create a new access policy
- `list_policy_definitions` - List all policy definitions
- `get_policy_definition` - Retrieve a specific policy by ID
- `delete_policy_definition` - Remove a policy definition
### Contract Definitions
- `create_contract_definition` - Create a contract definition
- `list_contract_definitions` - List all contract definitions
- `find_contract_definitions_by_name` - Search contract definitions by name
- `get_contract_definition` - Retrieve a specific contract definition
- `delete_contract_definition` - Remove a contract definition
### Catalog Operations
- `get_catalog` - Retrieve catalog from a provider connector
- `get_dataset_from_catalog` - Get dataset details from catalog
### Federated Catalog
- `query_federated_catalog_sparql` - Execute SPARQL queries across federated catalogs
- `get_federated_catalog_stats` - Get statistics about cached catalog data
- `get_federated_catalog_example_queries` - Get example SPARQL queries
### Dataset Operations
- `get_policies_for_dataset` - Extract policies for a specific dataset
- `get_policy_for_dataset` - Get a specific policy from a dataset
- `get_thing_description_for_dataset` - Retrieve Thing Description (WoT) for a dataset
### Contract Negotiations
- `create_contract_negotiation` - Initiate a contract negotiation
- `list_contract_negotiations` - List all negotiations
- `get_contract_negotiation` - Get negotiation details by ID
- `get_contract_negotiation_by_agreement` - Find negotiation by agreement ID
### Contract Agreements
- `list_contract_agreements` - List all concluded agreements
- `get_contract_agreement` - Get agreement details by ID
- `get_contract_agreement_by_negotiation` - Get agreement by negotiation ID
### Transfer Processes
- `create_transfer_process_http_pull` - Start an HTTP pull transfer
- `create_transfer_process_http_push` - Start an HTTP push transfer
- `list_transfer_processes` - List all transfer processes
- `get_transfer_process` - Get transfer process details
- `get_data_address_for_http_pull_transfer_process` - Get EDR for pull transfers
- `perform_http_pull_request` - Execute HTTP pull data request
## Example Use Cases
1. **Browse Available Data**: Query catalogs and federated catalogs to discover datasets
2. **Negotiate Contracts**: Initiate and track contract negotiations with data providers
3. **Transfer Data**: Execute HTTP pull or push transfers after successful negotiations
4. **Manage Assets**: Create and configure data assets for sharing
5. **Define Policies**: Set up access control policies and contract terms
6. **SPARQL Queries**: Perform advanced queries across federated dataspace catalogs
## Resources
- [Eclipse Dataspace Components](https://github.com/eclipse-edc/Connector)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [FastMCP Documentation](https://gofastmcp.com/)
