🚀

🚀 EasyProject MCP Server

Name: 🚀 EasyProject MCP Server
Author: hnizdiljan

本地服务

github.com/hnizdiljan生产力150 周前更新

代码仓库

关于 🚀 EasyProject MCP Server

EasyProject MCP Server 将 EasyProject 接入 MCP 客户端，包括 Cursor，可通过 EasyProject API 工具处理项目、问题、用户、工时和报告。

主要功能

01创建、更新、删除和列出项目
02管理并分配问题
03查看用户及工作负载
04记录和管理工时
05生成项目报告和仪表板数据
06缓存请求并重试失败操作

适用场景

01查看和更新项目详情
02创建并分配项目问题
03记录工时并查看用户工作负载
04生成项目报告

MCP 相关

将 EasyProject API 操作作为 MCP 工具提供给 Cursor 等客户端。支持 stdio 和 WebSocket 传输。

#easyproject #mcp-server #api-integration

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "EasyProject-MCP-Server": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "\\"
      ]
    }
  }
}

启动命令docker run -i --rm '\'

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

oci\stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

🚀 EasyProject MCP 服务

用于与 EasyProject API 集成的 Model Context Protocol 服务——可在 Cursor AI 编辑器中直接使用 EasyProject 工具。

✨ 功能

基本功能

MCP 协议：完整实现 Model Context Protocol
项目管理：创建、更新、删除和列出项目
任务管理：全面管理 issues，包括分配任务和标记任务为已完成
用户管理：列出用户并分析工作负载
时间跟踪：记录和管理时间条目
报告：生成项目报告和仪表板数据

高级功能

缓存：支持配置 TTL 的内存缓存
速率限制：防止 API 过载
重试逻辑：自动重试失败的请求
结构化日志记录：使用 JSON 格式进行监控
可配置性：提供丰富的配置选项

🚀 快速启动

前提条件

Rust 1.70+
可用的 EasyProject 实例
EasyProject API 密钥

基本启动

克隆代码库：

git clone https://github.com/your-org/easyproject-mcp-server.git
cd easyproject-mcp-server

配置：

cp config.toml.example config.toml
# Upravte config.toml s vašimi údaji

设置环境变量：

export EASYPROJECT_API_KEY="your-api-key"
export EASYPROJECT_BASE_URL="https://your-instance.easyproject.com"

启动：

cargo run

📦 安装

使用 Cargo

cargo install easyproject-mcp-server

使用 Docker

docker run -d \
  --name easyproject-mcp \
  -e EASYPROJECT_API_KEY="your-key" \
  -e EASYPROJECT_BASE_URL="https://your-instance.com" \
  easyproject/mcp-server:latest

从源代码构建

git clone https://github.com/your-org/easyproject-mcp-server.git
cd easyproject-mcp-server
cargo build --release

⚙️ 配置

服务使用 TOML 配置文件。完整配置示例如下：

[server]
name = "EasyProject MCP Server"
version = "1.0.0"
transport = "stdio"  # stdio nebo websocket
websocket_port = 8080

[easyproject]
base_url = "https://your-instance.easyproject.com"
api_version = "v1"
auth_type = "api_key"  # api_key, oauth2, session
api_key = ""  # Doporučujeme nastavit přes ENV
api_key_header = "X-Redmine-API-Key"

[http]
timeout_seconds = 30
max_retries = 3
retry_delay_seconds = 1
user_agent = "EasyProject-MCP-Server/1.0.0"

[rate_limiting]
enabled = true
requests_per_minute = 60
burst_size = 10

[cache]
enabled = true
ttl_seconds = 300
max_entries = 1000
project_ttl = 600
user_ttl = 1800
issue_ttl = 60
time_entry_ttl = 30

[logging]
level = "info"
format = "json"
target = "stdout"

[tools.projects]
enabled = true
include_archived = false
default_limit = 25

[tools.issues]
enabled = true
default_limit = 25
include_attachments = false
include_relations = false

[tools.users]
enabled = true
default_limit = 25

[tools.time_entries]
enabled = true
default_limit = 25

[tools.reports]
enabled = true
cache_ttl = 3600

环境变量

变量	描述	必填
`EASYPROJECT_API_KEY`	EasyProject API 密钥	是
`EASYPROJECT_BASE_URL`	EasyProject 实例的 URL	是
`MCP_LOG_LEVEL`	日志级别（trace、debug、info、warn、error）	否

🛠️ 可用工具

项目管理

工具	描述
`list_projects`	列出所有项目并支持筛选
`get_project`	获取特定项目的详情
`create_project`	创建新项目
`update_project`	更新现有项目
`delete_project`	删除项目

任务管理

工具	描述
`list_issues`	列出任务并支持筛选
`get_issue`	获取特定任务的详情
`create_issue`	创建新任务
`update_issue`	更新任务
`assign_issue`	将任务分配给用户
`complete_task`	将任务标记为已完成

用户管理

工具	描述
`list_users`	列出所有用户
`get_user`	获取特定用户的详情
`get_user_workload`	获取用户的工作负载

时间跟踪

工具	描述
`list_time_entries`	列出时间条目
`get_time_entry`	获取时间条目的详情
`log_time`	记录已工作的时间
`update_time_entry`	更新时间条目

报告

工具	描述
`generate_project_report`	生成详细的项目报告
`get_dashboard_data`	获取仪表板的汇总数据

📖 使用示例

获取项目列表

{
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {
      "limit": 10,
      "include_archived": false
    }
  }
}

创建新任务

{
  "method": "tools/call",
  "params": {
    "name": "create_issue",
    "arguments": {
      "project_id": 1,
      "tracker_id": 1,
      "subject": "Nový úkol",
      "description": "Popis úkolu",
      "assigned_to_id": 5,
      "priority_id": 2
    }
  }
}

分配任务

{
  "method": "tools/call",
  "params": {
    "name": "assign_issue",
    "arguments": {
      "id": 123,
      "assigned_to_id": 5
    }
  }
}

将任务标记为已完成

{
  "method": "tools/call",
  "params": {
    "name": "complete_task",
    "arguments": {
      "id": 123,
      "done_ratio": 100
    }
  }
}

生成项目报告

{
  "method": "tools/call",
  "params": {
    "name": "generate_project_report",
    "arguments": {
      "project_id": 1,
      "from_date": "2023-01-01",
      "to_date": "2023-12-31",
      "include_time_entries": true,
      "include_issues": true
    }
  }
}

获取工作负载

{
  "method": "tools/call",
  "params": {
    "name": "get_user_workload",
    "arguments": {
      "id": 5,
      "from_date": "2023-11-01",
      "to_date": "2023-11-30"
    }
  }
}

🚢 部署

Docker

创建 Docker 镜像：

docker build -t easyproject-mcp-server .

启动容器：

docker run -d \
  --name easyproject-mcp \
  -e EASYPROJECT_API_KEY="your-key" \
  -e EASYPROJECT_BASE_URL="https://your-instance.com" \
  -p 8080:8080 \
  easyproject-mcp-server

systemd（Linux）

复制二进制文件：

sudo cp target/release/easyproject-mcp-server /usr/local/bin/

创建 systemd 服务：

sudo tee /etc/systemd/system/easyproject-mcp.service > /dev/null <<EOF
[Unit]
Description=EasyProject MCP Server
After=network.target

[Service]
Type=simple
User=easyproject
WorkingDirectory=/opt/easyproject-mcp
ExecStart=/usr/local/bin/easyproject-mcp-server
Restart=always
RestartSec=10
Environment=EASYPROJECT_API_KEY=your-key
Environment=EASYPROJECT_BASE_URL=https://your-instance.com

[Install]
WantedBy=multi-user.target
EOF

启动服务：

sudo systemctl daemon-reload
sudo systemctl enable easyproject-mcp
sudo systemctl start easyproject-mcp

🔧 开发

构建开发版本

cargo build

运行测试

# Unit testy
cargo test

# Integration testy
cargo test --test integration_tests

# Všechny testy s výstupem
cargo test -- --nocapture

启用调试日志运行

RUST_LOG=debug cargo run

代码检查与格式化

# Formátování kódu
cargo fmt

# Linting
cargo clippy -- -D warnings

# Kontrola bezpečnosti
cargo audit

文档生成

cargo doc --open

🔍 故障排除

常见问题

“Connection refused” 错误

Chyba: Connection refused (os error 61)

解决方案：请检查：

EasyProject 实例是否可用
配置中的 URL 是否正确
防火墙是否阻止了连接

“Unauthorized” 错误

Chyba: 401 Unauthorized

解决方案：请检查：

API 密钥是否正确
API 密钥是否具有足够的权限
API 密钥是否已过期

“Rate limit exceeded”

Chyba: 429 Too Many Requests

解决方案：

降低配置中的 requests_per_minute
增大 retry_delay_seconds
联系 EasyProject 实例的管理员

缓存问题

要清除缓存，请重启服务或设置 cache.enabled = false。

调试模式

如需详细诊断，请启用调试日志后运行服务：

RUST_LOG=debug ./easyproject-mcp-server

日志记录

服务支持结构化日志记录。你可以使用 jq 等工具分析日志：

./easyproject-mcp-server | jq '.level == "ERROR"'

健康检查

服务提供健康检查端点（如果以 WebSocket 模式运行）：

curl http://localhost:8080/health

📝 许可证

MIT License。详情请参阅 LICENSE 文件。

🤝 参与贡献

Fork 此仓库
创建功能分支（git checkout -b feature/amazing-feature）
提交更改（git commit -m 'Add amazing feature'）
推送到分支（git push origin feature/amazing-feature）
打开 Pull Request

📞 支持

Issues：GitHub Issues
讨论：GitHub Discussions
电子邮件：[email protected]

🗺️ 路线图

为 EasyProject 社区倾心打造 ❤️

⚡ 快速开始

1. 部署

# Použije existující EXE (nejrychlejší)
.\deploy.ps1 -SkipBuild

# Nebo vynutí nový build
.\deploy.ps1 -Force

# Rychlý deployment
.\quick-deploy.ps1

2. 配置 Cursor

将 deployment/easyproject-mcp-server.exe 复制到任意位置，并在 Cursor 中进行设置：

{
  "mcpServers": {
    "easyproject": {
      "command": "C:\\path\\to\\easyproject-mcp-server.exe",
      "args": [],
      "env": {
        "EASYPROJECT_API_KEY": "your-api-key",
        "EASYPROJECT_BASE_URL": "https://your-instance.easyproject.com"
      }
    }
  }
}

3. 测试

在 Cursor 中可以使用：

@easyproject list_projects    # Seznam projektů
@easyproject create_issue     # Nový úkol  
@easyproject log_time         # Logování času

🔧 部署脚本

脚本	用途	描述
`deploy.ps1`	主要部署	智能构建 + 完整软件包
`quick-deploy.ps1`	快速部署	仅复制 EXE
`setup-build-tools.ps1`	环境设置	安装构建工具

构建问题故障排除

如果构建因 ring crate 或 gcc.exe 错误而失败：

# Rychlé řešení - použije existující EXE
.\deploy.ps1 -SkipBuild

# Oprava build prostředí
.\setup-build-tools.ps1

# Manuální oprava
rustup toolchain install stable-x86_64-pc-windows-msvc
winget install Microsoft.VisualStudio.2022.BuildTools

🎯 单文件部署

EXE 文件（15.29 MB）完全独立：

✅ 已包含所有 Rust 依赖项
✅ 支持 TLS（rust-native，无需 OpenSSL）
✅ 无外部 DLL 依赖项
✅ 可移植——复制到任意位置即可运行

系统要求：

Windows 10/11 x64
Visual C++ Redistributable 2019+（通常已安装）

📚 文档

DEPLOYMENT.md - 完整部署指南
API Reference - 各工具的文档
Swagger API - EasyProject API 文档

🛠 开发

从源代码构建：

git clone https://github.com/your-repo/easyproject-mcp-server
cd easyproject-mcp-server
cargo build --release

测试：

cargo test
cargo check

本地部署：

cargo build --release
.\quick-deploy.ps1

🔍 架构

项目遵循 SOLID、KISS 和 CLEAN Code 原则：

src/
├── main.rs              # Entry point
├── api/
│   ├── client.rs        # HTTP klient pro EasyProject API
│   └── models.rs        # Datové modely
├── tools/               # MCP nástroje
│   ├── project_tools.rs # Správa projektů
│   ├── issue_tools.rs   # Správa úkolů
│   └── time_tools.rs    # Časové záznamy
└── utils/
    └── formatting.rs    # Formátování výstupů

📄 许可证

MIT License——请参阅 LICENSE 文件。

🤝 参与贡献

Fork 项目
创建功能分支（git checkout -b feature/amazing-feature）
提交更改（git commit -m 'Add amazing feature'）
推送到分支（git push origin feature/amazing-feature）
打开 Pull Request

📞 支持

🐛 Issues：GitHub Issues
📖 文档：DEPLOYMENT.md
💬 讨论：GitHub Discussions

为 EasyProject 社区倾心开发 ❤️

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

🚀 EasyProject MCP Server

关于 🚀 EasyProject MCP Server

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

🚀 EasyProject MCP 服务

📋 目录

✨ 功能

基本功能

高级功能

🚀 快速启动

前提条件

基本启动

📦 安装

使用 Cargo

使用 Docker

从源代码构建

⚙️ 配置

环境变量

🛠️ 可用工具

项目管理

任务管理

用户管理

时间跟踪

报告

📖 使用示例

获取项目列表

创建新任务

分配任务

将任务标记为已完成

生成项目报告

获取工作负载

🚢 部署

Docker

systemd（Linux）

🔧 开发

构建开发版本

运行测试

启用调试日志运行

代码检查与格式化

文档生成

🔍 故障排除

常见问题

“Connection refused” 错误

“Unauthorized” 错误

“Rate limit exceeded”

缓存问题

调试模式

日志记录

健康检查

📝 许可证

🤝 参与贡献

📞 支持

🗺️ 路线图

⚡ 快速开始

1. 部署

2. 配置 Cursor

3. 测试

🔧 部署脚本

构建问题故障排除

🎯 单文件部署

📚 文档

🛠 开发

从源代码构建：

测试：

本地部署：

🔍 架构

📄 许可证

🤝 参与贡献

📞 支持

评论

第一次接触 MCP？

MCP（Model Context Protocol）是什么？

MCP 服务和客户端有什么区别？

本地服务与远程服务怎么选？

如何在 Claude、Cursor 等客户端中安装服务？

收录的项目经过审核吗？“认证”标识代表什么？