MCP Planfix

🚀 Planfix MCP 服務器

Planfix MCP 服務器實現了商業流程管理系統 Planfix 與模型上下文協議（Model Context Protocol，MCP）的集成，可與 Claude 等 AI 助手配合使用。

🚀 快速開始

本集成系統可幫助用戶在利用 Planfix 系統進行業務流程管理的同時，藉助 MCP 協議與 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

搜索信息

查找項目 "網站開發" 下的所有任務

獲取分析數據

顯示上個月的時間報告

項目管理

創建項目 "新的營銷活動"，描述為 "2024 年第一季度活動"

📚 詳細文檔

配置說明

命令行參數

服務器支持以下命令行參數：

示例用法：

# 通過命令行參數進行完整配置
uv run python -m src.planfix_server --account mycompany --api-key abc123

# 調試模式運行
uv run python -m src.planfix_server --debug

# 與環境變量結合使用
export PLANFIX_ACCOUNT=mycompany
uv run python -m src.planfix_server --api-key abc123

環境變量

在 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/

高級用法

自動化工作流

# 創建每週規劃
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} 項目")

API 參考

所有可用工具、資源和提示模板的詳細文檔請參考 docs/api_reference.md。

故障排除

常見問題及解決方案請參考 docs/troubleshooting.md。

📄 許可證

本項目採用 MIT 許可證，請參閱 LICENSE 文件獲取詳細信息。

支持

• GitHub 問題：用於報告錯誤和提出功能請求。
• 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）。
• 更新了 Cursor 配置，使用 uvx 和 git+repo@main。
• 從文檔中移除了 Claude Desktop 部分。

v1.0.0 (2024-12-23)

• 首次發佈。
• 支持基本的任務和項目操作。
• 集成 Planfix 分析功能。
• 支持聯繫人管理。