使用说明

EPR-MCP-Python

概述

EPR MCP Python 是一个用于事件溯源注册表（Event Provenance Registry）服务器的 Python MCP 服务器。

发展

本地开发

git clone git@github.com:xbcsmith/epr-mcp-python.git
cd epr-mcp-python

python3 -m venv .venv/epr-mcp-python
source .venv/epr-mcp-python/bin/activate

pip install -e .

Docker 开发

选项1：Docker Compose（推荐）

git clone git@github.com:xbcsmith/epr-mcp-python.git
cd epr-mcp-python

# Copy and configure environment
cp .env.example .env
# Edit .env with your EPR_URL and EPR_TOKEN

# Start with Docker Compose
docker-compose up -d

# View logs
docker-compose logs -f epr-mcp-server

选项2：直接运行Docker

git clone git@github.com:xbcsmith/epr-mcp-python.git
cd epr-mcp-python

# Build the Docker image
docker build -t epr-mcp-server .

# Run with environment variables
docker run -d \
  --name epr-mcp-server \
  -p 8000:8000 \
  -e EPR_URL=http://host.docker.internal:8042 \
  -e EPR_TOKEN=your-epr-api-token \
  -e EPR_DEBUG=false \
  epr-mcp-server

# View logs
docker logs -f epr-mcp-server

# Stop the container
docker stop epr-mcp-server
docker rm epr-mcp-server

Docker 运行选项

基本运行：

docker run -p 8000:8000 \
  -e EPR_URL=http://host.docker.internal:8042 \
  -e EPR_TOKEN=your-token \
  epr-mcp-server

对于原木的体积：

docker run -p 8000:8000 \
  -v $(pwd)/logs:/app/logs \
  -e EPR_URL=http://host.docker.internal:8042 \
  -e EPR_TOKEN=your-token \
  epr-mcp-server

交互模式（用于调试）：

docker run -it --rm \
  -p 8000:8000 \
  -e EPR_URL=http://host.docker.internal:8042 \
  -e EPR_TOKEN=your-token \
  epr-mcp-server

重要提示： 在Docker中运行时，EPR_URL必须指向正确的地址：

如果EPR服务器运行在主机上： EPR_URL=http://host.docker.internal:8042
如果EPR服务器在容器中运行： EPR_URL=http://container-name:8042

看 docker_compose.md（文件名，可译为“docker_compose.md文档”或根据上下文简化为“docker_compose.md”）以获取详细的 Docker Compose 文档。

开发依赖项

pip install -e .[lint,test,build]

Makefile

install         Installs epr-mcp-python into a virtualenv called epr-mcp
lint            Run linter (requires ruff)
tests           Run tests
release         Run tox
wheel           Create an sdist bdist_wheel
clean           Cleanup everything

使用方法

EPR MCP服务器提供了MCP工具和OpenAPI端点，用于与事件溯源注册表进行交互。

MCP 工具

服务器根据OpenAPI规范自动生成MCP工具：

fetchEvent - 通过ID获取事件
fetchReceiver - 通过ID获取事件接收器
fetchGroup - 通过ID获取事件接收器组
createEvent - 创建一个新事件
createReceiver - 创建一个新的事件接收器
createGroup - 创建一个新的事件接收器组
searchEvents - 搜索活动
searchReceivers - 搜索事件接收器
searchGroups - 搜索事件接收器组
healthCheck - 健康检查端点

OpenAPI 端点

当服务器运行时，可访问以下OpenAPI端点：

开放API规范：
- YAML 格式： http://localhost:8000/openapi.yaml
- JSON 格式： http://localhost:8000/openapi.json
API 文档:
- Swagger UI： http://localhost:8000/docs
健康检查：
- http://localhost:8000/health

示例用法

# Using MCP tools
mcp.call_tool('fetchEvent', {'id': 'event-123'})

mcp.call_tool('searchEvents', {
    'name': 'deployment', 
    'version': '1.0.0'
})

mcp.call_tool('createEvent', {
    'name': 'test-event',
    'version': '1.0.0',
    'release': '1.0.0',
    'platform_id': 'linux',
    'package': 'test-package',
    'description': 'Test event',
    'event_receiver_id': 'receiver-123',
    'success': True,
    'payload': {'key': 'value'}
})

VSCode

HTTP传输配置

"mcp": {
	"servers": {
		"epr-mcp-server": {
			"type": "http",
			"url": "http://localhost:8000/mcp"
		}
	}
}

Docker 配置（备选方案）

如果通过Docker运行，您可以使用以下配置：

"mcp": {
	"servers": {
		"epr-mcp-server": {
			"command": "docker",
			"args": [
				"run",
				"-d",
				"--rm",
				"--network=host",
				"-e",
				"EPR_URL=${input:epr_url}",
				"-e",
				"EPR_TOKEN=${input:epr_token}",
				"epr-mcp-python:latest"
			],
			"type": "http",
			"url": "http://localhost:8000/mcp"
		}
	},
	"inputs": [
		{
			"type": "promptString",
			"id": "epr_token",
			"description": "EPR API Token",
			"password": true
		},
		{
			"type": "promptString",
			"id": "epr_url",
			"description": "EPR URL",
			"default": "http://localhost:8042",
			"password": false
		}
	]
}

本地开发配置

对于本地开发，请先启动服务器，然后使用以下配置：

"mcp": {
	"servers": {
		"epr-mcp-server": {
			"type": "http",
			"url": "http://localhost:8000/mcp",
			"env": {
				"EPR_URL": "${input:epr_url}",
				"EPR_TOKEN": "${input:epr_token}"
			}
		}
	},
	"inputs": [
		{
			"type": "promptString",
			"id": "epr_token",
			"description": "EPR API Token",
			"password": true
		},
		{
			"type": "promptString",
			"id": "epr_url",
			"description": "EPR URL",
			"default": "http://localhost:8042",
			"password": false
		}
	]
}

启动服务器

在使用VSCode集成之前，请先启动EPR MCP服务器：

# Set environment variables
export EPR_URL="http://your-epr-server:8042"
export EPR_TOKEN="your-api-token"

# Start the server
python -m epr_mcp.main start

服务器将在 http://localhost:8000/mcp 用于MCP连接和 http://localhost:8000/docs 为API文档。

运行MCP检查器

npx @modelcontextprotocol/inspector

故障排除

遇到连接问题？请参阅故障排除指南以获取常见问题的详细解决方案。

Docker的快速修复方案：

连接失败错误：请使用 EPR_URL=http://host.docker.internal:8042 在你的 .env 文件
检查EPR服务器是否正在运行： curl http://localhost:8042/health
查看日志： docker-compose logs -f epr-mcp-server

文档

Docker 设置指南 - Docker Compose 和直接使用 Docker
Docker 快速参考指南 - 常用的Docker命令及示例
故障排除指南 - 常见问题的解决方案
OpenAPI 实现
模式验证