EasyProject-MCP-Server by hnizdiljan - MCP Server

🚀 EasyProject MCP Server

Model Context Protocol server pro integraci s EasyProject API - umožňuje použití EasyProject nástrojů přímo v Cursor AI editoru.

📋 Obsah

Funkce
Rychlé spuštění
Instalace
Konfigurace
Dostupné nástroje
Příklady použití
Deployment
Vývoj
Troubleshooting

✨ Funkce

Základní funkcionality

MCP protokol: Plná implementace Model Context Protocol
Správa projektů: Vytváření, aktualizace, mazání a seznam projektů
Správa úkolů: Komplexní správa issues včetně přiřazování a označování jako dokončené
Správa uživatelů: Seznam uživatelů a analýza pracovního vytížení
Časové sledování: Záznam a správa časových záznamů
Reporting: Generování sestav projektů a dashboard dat

Pokročilé funkce

Caching: In-memory cache s konfigurovatelným TTL
Rate limiting: Ochrana před přetížením API
Retry logika: Automatické opakování neúspěšných požadavků
Strukturované logování: JSON formát pro monitoring
Konfigurovatelnost: Rozsáhlé možnosti konfigurace

🚀 Rychlé spuštění

Předpoklady

Rust 1.70+
Aktivní EasyProject instance
API klíč pro EasyProject

Základní spuštění

Klonování repozitáře:

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

Konfigurace:

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

Nastavení environment proměnných:

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

Spuštění:

cargo run

📦 Instalace

Pomocí Cargo

cargo install easyproject-mcp-server

Pomocí 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

Sestavení ze zdrojového kódu

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

⚙️ Konfigurace

Server používá TOML konfigurační soubor. Příklad kompletní konfigurace:

[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

Environment proměnné

Proměnná	Popis	Povinná
`EASYPROJECT_API_KEY`	API klíč pro EasyProject	Ano
`EASYPROJECT_BASE_URL`	URL EasyProject instance	Ano
`MCP_LOG_LEVEL`	Úroveň logování (trace, debug, info, warn, error)	Ne

🛠️ Dostupné nástroje

Správa projektů

Nástroj	Popis
`list_projects`	Seznam všech projektů s filtrováním
`get_project`	Detail konkrétního projektu
`create_project`	Vytvoření nového projektu
`update_project`	Aktualizace existujícího projektu
`delete_project`	Smazání projektu

Správa úkolů

Nástroj	Popis
`list_issues`	Seznam úkolů s filtrováním
`get_issue`	Detail konkrétního úkolu
`create_issue`	Vytvoření nového úkolu
`update_issue`	Aktualizace úkolu
`assign_issue`	Přiřazení úkolu uživateli
`complete_task`	Označení úkolu jako dokončený

Správa uživatelů

Nástroj	Popis
`list_users`	Seznam všech uživatelů
`get_user`	Detail konkrétního uživatele
`get_user_workload`	Pracovní vytížení uživatele

Časové sledování

Nástroj	Popis
`list_time_entries`	Seznam časových záznamů
`get_time_entry`	Detail časového záznamu
`log_time`	Záznam odpracovaného času
`update_time_entry`	Aktualizace časového záznamu

Reporting

Nástroj	Popis
`generate_project_report`	Detailní sestava projektu
`get_dashboard_data`	Agregovaná data pro dashboard

📖 Příklady použití

Získání seznamu projektů

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

Vytvoření nového úkolu

{
  "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
    }
  }
}

Přiřazení úkolu

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

Označení úkolu jako dokončený

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

Generování sestavy projektu

{
  "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
    }
  }
}

Získání pracovního vytížení

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

🚢 Deployment

Docker

Vytvoření Docker image:

docker build -t easyproject-mcp-server .

Spuštění kontejneru:

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)

Kopírování binárky:

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

Vytvoření systemd service:

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

Spuštění služby:

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

🔧 Vývoj

Sestavení vývojové verze

cargo build

Spuštění testů

# Unit testy
cargo test

# Integration testy
cargo test --test integration_tests

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

Spuštění s debug logováním

RUST_LOG=debug cargo run

Linting a formátování

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

# Linting
cargo clippy -- -D warnings

# Kontrola bezpečnosti
cargo audit

Generování dokumentace

cargo doc --open

🔍 Troubleshooting

Časté problémy

"Connection refused" chyba

Chyba: Connection refused (os error 61)

Řešení: Zkontrolujte, že:

EasyProject instance je dostupná
URL v konfiguraci je správná
Firewall neblokuje připojení

"Unauthorized" chyba

Chyba: 401 Unauthorized

Řešení: Zkontrolujte, že:

API klíč je správný
API klíč má dostatečná oprávnění
API klíč není expirovaný

"Rate limit exceeded"

Chyba: 429 Too Many Requests

Řešení:

Snižte requests_per_minute v konfiguraci
Zvýšte retry_delay_seconds
Kontaktujte správce EasyProject instance

Cache problémy

Pro vymazání cache restartujte server nebo nastavte cache.enabled = false.

Debug režim

Pro detailní diagnostiku spusťte server s debug logováním:

RUST_LOG=debug ./easyproject-mcp-server

Logování

Server podporuje strukturované logování. Pro analýzu logů můžete použít nástroje jako jq:

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

Health check

Server poskytuje health check endpoint (pokud je spuštěn v WebSocket módu):

curl http://localhost:8080/health

📝 Licence

MIT License. Viz soubor pro detaily.

🤝 Přispívání

Forkněte repozitář
Vytvořte feature branch (git checkout -b feature/amazing-feature)
Commitněte změny (git commit -m 'Add amazing feature')
Pushněte do branch (git push origin feature/amazing-feature)
Otevřete Pull Request

📞 Podpora

Issues: GitHub Issues
Diskuze: GitHub Discussions
Email:

🗺️ Roadmap

Vytvořeno s ❤️ pro EasyProject komunitu

⚡ Rychlý Start

1. Deployment

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

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

# Rychlý deployment
.\quick-deploy.ps1

2. Konfigurace Cursor

Zkopírujte deployment/easyproject-mcp-server.exe kamkoliv a nastavte v 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. Testování

V Cursor můžete použít:

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

🔧 Deployment Skripty

Skript	Použití	Popis
`deploy.ps1`	Hlavní deployment	Inteligentní build + kompletní balíček
`quick-deploy.ps1`	Rychlý deployment	Pouze kopírování EXE
`setup-build-tools.ps1`	Setup prostředí	Instalace build nástrojů

Troubleshooting Build Problémů

Pokud build selhává s chybou ring crate nebo 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

🎯 Single-File Deployment

EXE soubor (15.29 MB) je kompletně samostatný:

✅ Všechny Rust dependencies zabudované
✅ TLS support (rust-native, bez OpenSSL)
✅ Žádné externí DLL dependencies
✅ Portable - zkopírujte kamkoliv a spusťte

Systémové požadavky:

Windows 10/11 x64
Visual C++ Redistributable 2019+ (obvykle již nainstalován)

📚 Dokumentace

- Kompletní deployment guide
- Dokumentace jednotlivých nástrojů
- EasyProject API dokumentace

🛠 Vývoj

Build z sources:

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

Testování:

cargo test
cargo check

Lokální deployment:

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

🔍 Architektura

Projekt dodržuje principy SOLID, KISS a 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ů

📄 Licence

MIT License - viz soubor.

🤝 Přispívání

Fork projektu
Vytvořte feature branch (git checkout -b feature/amazing-feature)
Commit změny (git commit -m 'Add amazing feature')
Push do branch (git push origin feature/amazing-feature)
Otevřete Pull Request

📞 Podpora

🐛 Issues: GitHub Issues
📖 Dokumentace:
💬 Diskuze: GitHub Discussions

Vyvinuto s ❤️ pro EasyProject komunitu