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 分析功能。
• 支持联系人管理。