🚀 EasyProject MCP Server

🚀 EasyProject MCP サーバー

EasyProject API と統合するための Model Context Protocol サーバーです。Cursor AI エディターで EasyProject のツールを直接使用できます。

📋 目次

• 機能
• クイックスタート
• インストール
• 設定
• 利用可能なツール
• 使用例
• デプロイ
• 開発
• トラブルシューティング

✨ 機能

基本機能

• MCP プロトコル：Model Context Protocol の完全な実装
• プロジェクト管理：プロジェクトの作成、更新、削除、一覧表示
• タスク管理：割り当てや完了済みとしてのマークを含む、課題の包括的な管理
• ユーザー管理：ユーザー一覧と作業負荷の分析
• 時間追跡：時間記録の登録と管理
• レポート作成：プロジェクトレポートとダッシュボードデータの生成

高度な機能

• キャッシュ：有効期限を設定できるインメモリーキャッシュ
• レート制限：API の過負荷を防止
• 再試行ロジック：失敗したリクエストを自動的に再試行
• 構造化ログ：監視用の JSON 形式
• 設定可能性：幅広い設定オプション

🚀 クイックスタート

前提条件

• Rust 1.70+
• 有効な EasyProject インスタンス
• EasyProject の API キー

基本的な起動方法

1. リポジトリのクローン：

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

2. 設定：

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

3. 環境変数の設定：

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

4. 起動：

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

1. Docker イメージの作成：

docker build -t easyproject-mcp-server .

2. コンテナーの起動：

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. バイナリーのコピー：

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

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

3. サービスの起動：

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 ファイルをご覧ください。

🤝 貢献

1. リポジトリをフォークします
2. feature ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. Pull Request を作成します

📞 サポート

• Issues：GitHub Issues
• ディスカッション：GitHub Discussions
• メール：[email protected]

🗺️ ロードマップ

• WebSocket によるリアルタイム通知
• プラグインシステム
• バッチ操作
• Prometheus メトリクス
• GraphQL エンドポイント
• Webhook 対応

---

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 リファレンス - 各ツールのドキュメント
• 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 ファイルをご覧ください。

🤝 貢献

1. プロジェクトをフォークします
2. feature ブランチを作成します（git checkout -b feature/amazing-feature）
3. 変更をコミットします（git commit -m 'Add amazing feature'）
4. ブランチにプッシュします（git push origin feature/amazing-feature）
5. Pull Request を作成します

📞 サポート

• 🐛 Issues： GitHub Issues
• 📖 ドキュメント： DEPLOYMENT.md
• 💬 ディスカッション： GitHub Discussions

---

EasyProject コミュニティのために ❤️ を込めて開発