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

1. Klonování repozitáře:

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

2. Konfigurace:

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

3. Nastavení environment proměnných:

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

4. 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

1. Vytvoření Docker image:

docker build -t easyproject-mcp-server .

2. 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)

1. Kopírování binárky:

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

2. 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

3. 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 LICENSE soubor pro detaily.

🤝 Přispívání

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

📞 Podpora

• Issues: GitHub Issues
• Diskuze: GitHub Discussions
• Email: support@your-org.com

🗺️ Roadmap

• [ ] WebSocket real-time notifikace
• [ ] Plugin systém
• [ ] Batch operace
• [ ] Prometheus metrics
• [ ] GraphQL endpoint
• [ ] Webhooks podpora

---

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

• DEPLOYMENT.md - Kompletní deployment guide
• API Reference - Dokumentace jednotlivých nástrojů
• Swagger API - 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 LICENSE soubor.

🤝 Přispívání

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

📞 Podpora

• 🐛 Issues: GitHub Issues
• 📖 Dokumentace: DEPLOYMENT.md
• 💬 Diskuze: GitHub Discussions

---

Vyvinuto s ❤️ pro EasyProject komunitu