Eva MCP Server

Eva MCP服务器

   

用于Eva-project API集成的MCP（模型上下文协议）服务器。该服务器允许Claude和Cursor等AI助手与Eva项目任务、项目、文档等进行交互。

快速入门： 看 GETTING_STARTED.md 有关分步设置说明。

特性

• 任务管理：搜索、查看、创建和更新任务
• 项目管理：列出并查看项目详细信息
• 用户管理：列出并查看用户信息
• 文档管理：搜索和查看文档
• 评论：查看任务/文档并添加注释
• Sprint管理：列出和查看冲刺/列表
• 审计日志：查看审核历史记录
• 只读模式：防止写入操作的可选安全模式（为方便起见，默认禁用）
• JSON-RPC 2.0：全面支持Eva API协议

安装

先决条件

• Python 3.10或更高版本
• Eva API访问令牌

从源代码安装

# Clone the repository
git clone https://github.com/knrerikh/eva-mcp-server.git
cd eva-mcp-server

# Install dependencies
pip install -r requirements.txt

# Or install in development mode
pip install -e .

配置

环境变量

创建 .env 项目根目录中的文件（使用 .env.example 作为模板）：

# Eva API Configuration
EVA_API_URL=https://your-eva-instance.com/api
EVA_API_TOKEN=your_token_here

# Optional: Enable read-only mode (default: false - write operations allowed)
# Set to "true" to prevent write operations
EVA_READ_ONLY=false

# Optional: Request timeout in seconds (default: 30)
EVA_TIMEOUT=30

获取API令牌

1. 登录到您的Eva项目实例
2. 导航到您的个人资料设置
3. 生成API令牌
4. 将令牌复制到您的 .env 文件

用法

运行服务器

# Using Python
python -m eva_mcp_server.server

# Or if installed as package
eva-mcp-server

与Cursor集成

1. 打开光标设置
2. 导航到MCP服务器配置
3. 添加以下配置：

{
  "Eva": {
    "command": "python",
    "args": ["/path/to/eva-mcp-server/src/server.py"],
    "env": {
      "EVA_API_URL": "https://your-eva-instance.com/api",
      "EVA_API_TOKEN": "your_token_here"
    }
  }
}

1. 重新启动游标
2. Eva MCP服务器现在应该可用

可选：启用只读模式以确保安全

默认情况下，写入操作为 允许。如果您想保护您的Eva实例免受意外修改（例如，用于生产环境或分析），可以启用只读模式：

1. 打开光标设置（Ctrl+Shift+P→ “首选项：打开设置（JSON）”）
2. 在中查找Eva MCP服务器配置 mcpServers 章节
3. 添加 "EVA_READ_ONLY": "true" 在 env 章节：

{
  "mcpServers": {
    "Eva Project MCP": {
      "command": "python",
      "args": ["C:\\Users\\YourUser\\Repos\\eva-mcp-server\\src\\server.py"],
      "env": {
        "EVA_API_URL": "https://your-eva-instance.com/api",
        "EVA_API_TOKEN": "your_token",
        "EVA_READ_ONLY": "true"
      }
    }
  }
}

1. 保存配置文件
2. 重新启动游标
3. Eva MCP服务器现在将阻止所有写入操作

与Claude Desktop集成

添加到您的Claude Desktop配置文件(claude_desktop_config.json):

{
  "mcpServers": {
    "Eva": {
      "command": "python",
      "args": ["/path/to/eva-mcp-server/src/server.py"],
      "env": {
        "EVA_API_URL": "https://your-eva-instance.com/api",
        "EVA_API_TOKEN": "your_token_here"
      }
    }
  }
}

可用工具

任务工具

• eva_search_tasks：使用筛选器搜索和列出任务

- 参数： query, project, responsible, status, limit

• eval_get_task：获取详细的任务信息

- 参数： task_code

• eva_count_tasks：计数与筛选器匹配的任务

- 参数： project, responsible, status

• eva_create_task：创建新任务（需要 read_only=false)

- 参数： name, project_code （可选）， lists （可选）， description, responsible, priority - 重要: - 对于项目中的任务：仅指定 project_code - 对于sprint中的任务：指定 两者 project_code （sprint的母项目）和 lists （冲刺代码） - 要是…就好了 lists 如果提供，任务将被创建，但不会正确链接到项目

• eva_update_task：更新现有任务（需要 read_only=false)

- 参数： task_code, name, description, responsible, status, priority

项目工具

• eval_list_项目：列出所有项目

- 参数： limit

• eva_get-project：获取详细的项目信息

- 参数： project_code

用户工具

• eval_list_users：列出所有用户

- 参数： limit

• eva_get_user：获取详细的用户信息

- 参数： user_code

文档工具

• eva_search_文档：搜索和列出文档

- 参数： query, project, limit

• eval_get-document：获取详细的文档信息

- 参数： document_code

评论工具

• eval_get_注释：获取任务或文档的注释

- 参数： parent_code, limit

• eva_add_注释：添加评论（需要 read_only=false)

- 参数： parent_code, text

Sprint/列表工具

• eval_list_sprints：列出所有冲刺/列表

- 参数： limit

• eva_get_sprint：获取详细的冲刺/列表信息

- 参数： list_code

• eva_create_list：创建新列表/冲刺/发布（需要 read_only=false)

- 参数： name, project_code

审计工具

• eval_get_audit_log：获取审核日志条目

- 参数： entity_code, limit

最佳实践

创建任务

对于项目任务（无冲刺）：

{
  "name": "Task name",
  "project_code": "PROJ-123"
}

对于冲刺任务（推荐）：

{
  "name": "Task name",
  "project_code": "CmfProject:xxx",  // Sprint's parent project
  "lists": ["SPR-000929"]             // Sprint code
}

为什么两个参数？

• 仅使用 lists 将把任务添加到sprint中，但它不会链接到项目层次结构
• 两者都使用 project_code 和 lists 确保项目树和sprint板中的正确链接
• 这与Eva web界面的行为相匹配

例子

示例1：搜索任务

# In your AI assistant
"Search for tasks in project PROJ-123 assigned to user@example.com"

这将调用 eva_search_tasks 与：

{
  "project": "PROJ-123",
  "responsible": "user@example.com",
  "limit": 20
}

示例2：获取任务详细信息

"Show me details of task TASK-456"

这将调用 eva_get_task 与：

{
  "task_code": "TASK-456"
}

示例3：列出项目

"List all projects"

这将调用 eva_list_projects 使用默认参数。

示例4：创建任务（需要写入模式）

# First, disable read-only mode in configuration
"Create a new task named 'Implement feature X' in project PROJ-123"

这将调用 eva_create_task 与：

{
  "name": "Implement feature X",
  "project_code": "PROJ-123"
}

示例5：在sprint/list中创建任务（推荐方法）

"Create a new task named 'Fix bug in authentication' in sprint SPR-000929"

这将调用 eva_create_task 与：

{
  "name": "Fix bug in authentication",
  "project_code": "CmfProject:xxx",
  "lists": ["SPR-000929"]
}

备注：建议同时指定两者 project_code （sprint的父项目）和 lists 将任务与项目和冲刺正确地联系起来。如果 lists 如果提供了，任务将被添加到sprint中，但不会链接到项目层次结构。

安全和安保

只读模式

默认情况下，服务器允许写操作(EVA_READ_ONLY=false)为了使用方便。

要启用只读模式以确保安全（例如，用于生产环境）：

1. 集 EVA_READ_ONLY=true 在您的配置中
2. 这将防止：

- 创建任务 - 更新任务 - 添加评论 - 任何其他写入操作

推荐：当您只需要分析数据或多个用户共享同一配置时，请使用只读模式。

API代币安全

• 永远不要将API令牌提交到版本控制
• 将令牌存储在 .env 文件（被gitignored）
• 使用环境变量进行配置
• 定期旋转令牌

生产使用

与生产Eva实例一起使用时：

• 除非绝对必要，否则保持只读模式启用
• 首先对测试实例进行测试写入操作
• 监控API使用情况和日志
• 实施适当的错误处理

发展

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test file
pytest tests/test_eva_client.py

代码质量

# Format code
black src/ tests/

# Lint code
ruff check src/ tests/

项目结构

eva-mcp-server/
├── src/
│   ├── __init__.py
│   ├── server.py          # Main MCP server
│   ├── eva_client.py      # Eva API client
│   └── tools.py           # MCP tool implementations
├── tests/
│   ├── __init__.py
│   ├── test_eva_client.py # Client tests
│   └── test_tools.py      # Tools tests
├── .env.example           # Example configuration
├── .gitignore            # Git ignore rules
├── requirements.txt       # Python dependencies
├── pyproject.toml        # Project configuration
├── pytest.ini            # Pytest configuration
├── README.md             # This file
├── API_ANALYSIS.md       # API documentation
└── oas_evateam_v1_9_22.json  # OpenAPI specification

故障排除

服务器无法启动

1. 检查是否安装了Python 3.10+： python --version
2. 验证是否安装了所有依赖项： pip install -r requirements.txt
3. 检查 EVA_API_TOKEN 设定在 .env
4. 查看服务器日志中的特定错误

API调用失败

1. 验证API令牌是否有效
2. 检查与Eva API端点的网络连接
3. 确保API URL正确无误
4. 检查只读模式是否阻止写入操作
5. 查看Eva API文档以了解端点需求

工具未出现在Cursor/Claude中

1. 验证MCP服务器配置是否正确
2. 重新启动Cursor/Claude桌面
3. 检查服务器日志中的初始化错误
4. 确保服务器进程正在运行

API 文档

有关详细的API文档，请参阅Eva实例中的Eva-project API文档。

贡献

欢迎投稿！拜托：

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 添加新功能的测试
5. 确保所有测试通过
6. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

支持

对于问题和疑问：

• 在GitHub上打开一个问题
• 在您的Eva实例中检查Eva项目文档
• 查看中的API规范 oas_evateam_v1_9_22.json

更新日志

版本0.1.0（初始版本）

• Eva MCP服务器的初步实现
• 支持任务、项目、用户、文档、评论、冲刺和审计操作
• 安全操作的只读模式
• 全面的测试套件
• 完整文档

致谢

• API项目团队
• 模型上下文协议（MCP）规范
• Claude和MCP SDK的拟人化