JinDaGe - mcp-planfix MCP Details

article

README

🚀 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 密钥：

进入设置 → API。
创建新的 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 年第一季度活动"

📚 详细文档

配置说明

命令行参数

服务器支持以下命令行参数： | 参数 | 描述 | 示例 | |------|------|------| | --account | Planfix 账户名称 | --account mycompany | | --api-key | Planfix API 密钥 | --api-key abc123xyz | | --debug | 启用调试日志 | --debug | | --help | 显示帮助信息 | --help | | --version | 显示版本信息 | --version |

示例用法：

# 通过命令行参数进行完整配置
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

环境变量

| 变量 | 描述 | 是否必需 | |------|------|------| | PLANFIX_ACCOUNT | Planfix 账户名称 | ✅ | | PLANFIX_API_KEY | API 密钥 | ✅ | | PLANFIX_BASE_URL | 基础 URL（默认：https://{account}.planfix.ru） | ❌ | | DEBUG | 启用调试日志 | ❌ |

在 Cursor 中配置

Cursor 从 0.42 版本及以上开始支持 MCP 服务器。要进行连接：

打开 Cursor 设置：使用 Cmd/Ctrl + ,。
找到 "MCP Servers" 部分：或者将配置添加到设置文件中。
添加服务器配置：使用 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"
      }
    }
  }
}

通过 .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.

重启 Cursor 使更改生效。
检查连接：在 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 分析功能。
支持联系人管理。