内容
# EDC MCP 服务器
用于Eclipse Dataspace Components（EDC）的模型上下文协议（MCP）服务器，启用Claude等AI助手与EDC连接器交互，进行数据空间操作。
## 概述
该项目提供基于FastMCP的服务器，通过MCP工具公开EDC管理API功能。它允许AI助手执行数据空间操作，如管理资产、策略、目录、合同谈判和数据传输。
### 什么是EDC？
[Eclipse Dataspace Components（EDC）](https://github.com/eclipse-edc/Connector) 是一个用于主权组织间数据交换的框架。它实现了数据空间协议，并提供了用于以去中心化方式管理数据资产、访问策略、合同谈判和数据传输的API。
### 什么是MCP？
[模型上下文协议（MCP）](https://modelcontextprotocol.io/) 是一个开放协议，用于标准化应用程序如何为大型语言模型（LLM）提供上下文。该服务器实现了MCP，使EDC功能可供AI助手访问。
## 功能
- **资产管理**：创建、读取、更新和删除数据资产
- **策略定义**：管理资产的访问控制策略
- **合同定义**：定义数据访问的合同条款
- **目录操作**：浏览和搜索数据目录
- **联邦目录**：使用SPARQL查询多个数据空间
- **合同谈判**：发起和管理合同协议
- **传输过程**：执行数据传输（HTTP拉取/推送）
- **数据集操作**：检索数据集元数据和事物描述
- **后台刷新**：自动联邦目录更新
## 安装
### 先决条件
- Python 3.11 或更高版本
- 访问EDC连接器实例
### 从源码构建
```bash
# 克隆仓库
git clone https://github.com/soofi-project/edc-mcp.git
cd edc-mcp
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # 在Windows上：.venv\Scripts\activate
# 安装包
pip install -e .
```
### 使用Docker
```bash
# 拉取已发布的跨架构镜像
docker pull ghcr.io/soofi-project/edc-mcp:latest
# 运行容器
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
```
将 `host.docker.internal` 替换为容器可访问的主机名或服务名。
对于本地镜像开发：
```bash
# 构建镜像
docker build -t edc-mcp .
# 运行容器
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
```
## 配置
在启动服务器之前，设置以下环境变量：
- `EDC_MANAGEMENT_URL`：EDC管理API端点（默认：`http://localhost:5173/api/management`）
- `EDC_CATALOG_URL`：用于联邦目录刷新的EDC目录API端点（默认：`http://localhost:5173/api/catalog`）
- `CATALOG_REFRESH_INTERVAL`：联邦目录刷新间隔（秒）（默认：`300`）
- `CATALOG_BASE_URI`：解析目录JSON-LD为RDF时使用的基准URI（默认：`urn:edc:catalog/`）
- `LOG_LEVEL`：此服务器的Python日志级别（默认：`INFO`）
示例：
```bash
export EDC_MANAGEMENT_URL=http://localhost:5173/api/management
export EDC_CATALOG_URL=http://localhost:5173/api/catalog
```
## 使用
### 启动服务器
```bash
# 直接运行
python -m edc_mcp.main
# 或使用已安装的命令
edc-mcp
```
服务器将默认启动在 `http://0.0.0.0:8081`。
### 与Claude Desktop一起使用
将以下内容添加到您的Claude Desktop配置（`claude_desktop_config.json`）：
```json
{
"mcpServers": {
"edc": {
"url": "http://localhost:8081/mcp"
}
}
}
```
## 可用工具
### 资产管理
- `create_asset` - 创建具有属性和数据地址的新资产
- `list_assets` - 列出所有资产，支持分页
- `find_assets` - 使用筛选表达式搜索资产
- `get_asset` - 通过ID检索特定资产
- `update_asset_properties` - 更新资产元数据
- `update_asset_private_properties` - 更新私有资产属性
- `update_asset_data_address` - 更新资产数据地址配置
- `delete_asset` - 删除资产
### 策略定义
- `create_policy_definition` - 创建新的访问策略
- `list_policy_definitions` - 列出所有策略定义
- `get_policy_definition` - 通过ID检索特定策略
- `delete_policy_definition` - 删除策略定义
### 合同定义
- `create_contract_definition` - 创建合同定义
- `list_contract_definitions` - 列出所有合同定义
- `find_contract_definitions_by_name` - 按名称搜索合同定义
- `get_contract_definition` - 检索特定合同定义
- `delete_contract_definition` - 删除合同定义
### 目录操作
- `get_catalog` - 从提供者连接器检索目录
- `get_dataset_from_catalog` - 从目录获取数据集详情
### 联邦目录
- `query_federated_catalog_sparql` - 在联邦目录上执行SPARQL查询
- `get_federated_catalog_stats` - 获取缓存目录数据的统计信息
- `get_federated_catalog_example_queries` - 获取SPARQL查询示例
### 数据集操作
- `get_policies_for_dataset` - 提取特定数据集的策略
- `get_policy_for_dataset` - 从数据集获取特定策略
- `get_thing_description_for_dataset` - 检索数据集的事物描述（WoT）
### 合同谈判
- `create_contract_negotiation` - 发起合同谈判
- `list_contract_negotiations` - 列出所有谈判
- `get_contract_negotiation` - 通过ID获取谈判详情
- `get_contract_negotiation_by_agreement` - 通过协议ID查找谈判
### 合同协议
- `list_contract_agreements` - 列出所有已达成的协议
- `get_contract_agreement` - 通过ID获取协议详情
- `get_contract_agreement_by_negotiation` - 通过谈判ID获取协议
### 传输过程
- `create_transfer_process_http_pull` - 启动HTTP拉取传输
- `create_transfer_process_http_push` - 启动HTTP推送传输
- `list_transfer_processes` - 列出所有传输过程
- `get_transfer_process` - 获取传输过程详情
- `get_data_address_for_http_pull_transfer_process` - 获取拉取传输的EDR
- `perform_http_pull_request` - 执行HTTP拉取数据请求
## 示例用例
1. **浏览可用数据**：查询目录和联邦目录以发现数据集
2. **谈判合同**：与数据提供者发起和跟踪合同谈判
3. **传输数据**：在成功谈判后执行HTTP拉取或推送传输
4. **管理资产**：创建和配置数据资产以共享
5. **定义策略**：设置访问控制策略和合同条款
6. **SPARQL查询**：对联邦数据空间目录执行高级查询
## 资源
- [Eclipse Dataspace Components](https://github.com/eclipse-edc/Connector)
- [模型上下文协议](https://modelcontextprotocol.io/)
- [FastMCP 文档](https://gofastmcp.com/)
