MCP Planfix

🚀 Planfix MCP Server

ビジネスプロセス管理システム Planfix を Model Context Protocol (MCP) と統合し、Claude やその他の AI アシスタントと共に使用できるようにします。

✨ 主な機能

🛠️ ツール

• タスク管理：タスクの作成、検索、ステータスの更新
• プロジェクト管理：新しいプロジェクトの作成
• コンタクト管理：CRM に新しいコンタクトを追加
• 分析：時間、財務、タスクに関するレポートの取得
• コメント：タスクにコメントを追加

📊 リソース

• プロジェクトリスト：タスク数を含むアクティブなプロジェクト
• ダッシュボード概要：ワークスペースの現在の状態
• タスク詳細：特定のタスクの詳細情報
• 最近のコンタクト：最近追加されたコンタクト
• レポート：事前に作成されたレポート

💡 プロンプト

• プロジェクト分析：プロジェクトの状態を分析するためのテンプレート
• 週次レポート：レポートを作成するためのテンプレート
• スプリント計画：タスクを計画するためのテンプレート

📦 インストール

要件

• Python 3.8 以上
• uv (推奨) または pip
• API アクセスが有効な Planfix アカウント

1. リポジトリのクローンと依存関係のインストール

git clone <repository-url>
cd planfix-mcp-server

# uv を使用する場合 (推奨)
uv sync

# または pip を使用する場合
pip install -r requirements.txt

2. API キーの設定

Planfix アカウントで API キーを取得します：

1. 設定 → API に移動します。
2. 新しい API キーを作成します。

.env ファイルを作成します：

cp .env.example .env

.env ファイルを編集します：

PLANFIX_ACCOUNT=your-account-name
PLANFIX_API_KEY=your-api-key

3. テスト

# コマンドライン引数で実行
python -m src.planfix_server --account your-account --api-key your-api-key

# デバッグモードで実行
python -m src.planfix_server --debug

# ヘルプを表示
python -m src.planfix_server --help

# 環境変数を使用して実行 (.env ファイルから)
python -m src.planfix_server

💻 使用例

基本的な使用法

# タスクの作成
Создай задачу "Подготовить презентацию" с описанием "Презентация для клиента XYZ" и приоритетом HIGH

# 情報の検索
Найди все задачи по проекту "Разработка сайта"

# 分析情報の取得
Покажи отчёт по времени за последний месяц

# プロジェクトの管理
Создай проект "Новая маркетинговая кампания" с описанием "Q1 2024 кампания"

高度な使用法

# 自動化されたワークフローの例
tasks = await search_tasks(status="active", assignee_id=123)
report = await get_analytics_report("time", "2024-01-01", "2024-01-07")

# 他のシステムとの統合の例
contact = await add_contact("Новый клиент", "client@example.com")
project = await create_project(f"Проект для {contact.name}")

📚 ドキュメント

コマンドライン引数

サーバーは以下のコマンドライン引数をサポートしています：

環境変数

Cursor での設定

Cursor バージョン 0.42 以上で MCP サーバーをサポートしています。接続するには：

1. Cursor の設定を開きます：Cmd/Ctrl + ,
2. 「MCP Servers」セクションを見つけるか、設定ファイルに構成を追加します
3. サーバー構成を追加します

uvx を使用する場合：

{
  "mcp.servers": {
    "planfix": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/your-repo/planfix-mcp@main",
        "planfix-server",
        "--account", "your-account-name",
        "--api-key", "your-api-key"
      ]
    }
  }
}

環境変数を使用する場合：

{
  "mcp.servers": {
    "planfix": {
      "command": "uvx",
      "args": [
        "--from", "git+https://github.com/your-repo/planfix-mcp@main",
        "planfix-server"
      ],
      "env": {
        "PLANFIX_ACCOUNT": "your-account-name",
        "PLANFIX_API_KEY": "your-api-key"
      }
    }
  }
}

4. .cursorrules を使用する代替方法

プロジェクトのルートに .cursorrules ファイルを作成します：

MCP Server: Planfix Integration

This project uses a Planfix MCP server for task and project management.

Available tools:
- search_tasks: Find tasks by query, project, assignee, or status
- search_contacts: Search for contacts and companies  
- get_contact_details: Get detailed information about a contact
- list_employees: Get list of employees
- list_files: Get files associated with tasks/projects
- list_comments: Get comments for tasks/projects
- list_reports: Get available reports
- list_processes: Get business processes

Server configuration:
- Command: uvx --from git+https://github.com/your-repo/planfix-mcp@main planfix-server
- Requires PLANFIX_ACCOUNT, PLANFIX_API_KEY environment variables

Use these tools to help with project management, task tracking, and CRM operations.

5. Cursor を再起動して変更を適用します
6. 接続を確認します：Cursor のチャットに Planfix の利用可能なツールが表示されます。

Cursor での使用

設定後、Cursor のチャットで Planfix を直接使用できます：

Найди все активные задачи по проекту "Разработка сайта"

Покажи детали контакта с ID 123

Создай отчет по всем просроченным задачам

Cursor でのトラブルシューティング

• パスを確認します：ファイルへの絶対パスを使用します。
• 環境変数を確認します：すべての API キーが正しく指定されていることを確認します。
• ログを確認します：Cursor の開発者コンソール (Cmd/Ctrl + Shift + I) の出力を確認します。
• バージョンを確認します：Cursor バージョン 0.42 以上を使用していることを確認します。

🔧 技術詳細

プロジェクト構造

planfix-mcp-server/
├── src/
│   ├── planfix_server.py          # 主要な MCP サーバー
│   ├── planfix_api.py             # Planfix API クライアント
│   ├── config.py                  # 設定ファイル
│   └── utils.py                   # ユーティリティ関数
├── tests/
│   ├── test_server.py             # サーバーのテスト
│   ├── test_api.py                # API のテスト
│   └── conftest.py                # pytest の設定
├── examples/
│   ├── basic_usage.py             # 使用例
│   └── advanced_workflows.py     # 高度なワークフロー
├── docs/
│   ├── api_reference.md           # API リファレンス
│   └── troubleshooting.md         # トラブルシューティングガイド
├── .env.example                   # 設定例
├── requirements.txt               # 依存関係
├── pyproject.toml                # プロジェクト設定
└── README.md                      # ドキュメント

テストの実行

# すべてのテスト
uv run pytest

# コードカバレッジ付き
uv run pytest --cov=src

# 高速テストのみ
uv run pytest -m "not slow"

コードの整形とチェック

# コードの整形
uv run ruff format

# スタイルのチェック
uv run ruff check

# 型チェック
uv run mypy src/

📄 ライセンス

MIT License - LICENSE ファイルを参照してください。

サポート

• GitHub Issues: バグ報告や機能リクエスト用
• MCP ドキュメント: https://modelcontextprotocol.io/

変更履歴

v1.0.1 (2024-12-23)

• argparse を使用してコマンドライン引数の処理を改善
• --help、--version、--debug オプションを追加
• ツールの出力から絵文字と Markdown 形式を削除
• model_dump() を使用してデータの返却を簡素化し、統合を改善
• PLANFIX_USER_KEY の依存関係を削除 (PLANFIX_ACCOUNT と PLANFIX_API_KEY のみ)
• uvx と git+repo@main を使用して Cursor の設定を更新
• ドキュメントから Claude Desktop セクションを削除

v1.0.0 (2024-12-23)

• 最初のリリース
• タスクとプロジェクトの基本的な操作
• Planfix の分析機能との統合
• コンタクト管理のサポート