Freedcamp MCP Server

🚀 增强型Freedcamp MCP服务器

全面 模型上下文协议（MCP）服务器 与无缝集成 Freedcamp API此服务器提供企业级项目管理功能，具有高级过滤、完整的CRUD操作和广泛的自定义选项。

✨ 特性

🏗️ 项目管理

• 列出项目 具有可选的最近项目跟踪功能
• 详细项目信息 包括用户、通知和功能
• 创建/更新/删除项目 用户管理
• 管理项目团队 （添加、更新、删除用户）
• 组管理 项目组织

📋 高级任务管理

• 全面的任务过滤 有15+个过滤器选项：

- 状态筛选（未开始、已完成、正在进行） - 用户分配过滤（分配给，由创建） - 日期范围筛选（截止日期、创建日期） - 基于优先级的过滤和排序 - 自定义字段和标签支持

• 完整的任务生命周期 -创建、读取、更新、删除
• 子任务支持 有亲子关系
• 文件附件 媒体管理
• 周期性任务 支持iCalendar格式
• 分页和排序 对于大型数据集

👥 用户管理

• 完整的用户资料 详细信息
• 当前用户管理 以及个人资料更新
• 用户任务分配 以及工作量跟踪
• 电子邮件和密码管理 具有安全令牌处理功能

💬 评论系统

• 添加/更新/删除评论 关于任务和项目
• 文件附件 在评论中
• 富文本支持 使用HTML格式
• 评论线程 以及用户归因

📁 文件管理

• 文件详细信息 元数据访问
• 文件删除 和清理
• 多格式支持 （图像、文档等）
• 临时文件处理 用于上传

🛠️ 安装和设置

先决条件

• Docker和Docker Compose
• Freedcamp API凭据（API密钥）

快速开始

1. 克隆存储库：

git clone https://github.com/BluePointDigital/freedcamp-mcp-server.git
cd freedcamp-mcp-server

1. 设置环境变量：

cp env-example.sh .env
# Edit .env and add your Freedcamp credentials

1. 启动服务：

docker-compose up -d

1. 访问API：

• MCP服务器: http://localhost:8000/mcp/
• OpenAPI代理: http://localhost:8111
• API文档: http://localhost:8111/docs

🔧 配置

环境变量

创建一个 .env 将您的Freedcamp凭据归档：

FREEDCAMP_API_KEY=your_api_key_here
FREEDCAMP_API_SECRET=your_api_secret_here  # Optional for some endpoints

Docker配置

包括 docker-compose.yml 提供：

• 健康检查 用于服务监控
• 重新启动策略 可靠性
• 资源限制 为了获得最佳性能
• 网络隔离 出于安全考虑

🔥 LLM工作流程说明

重要：此MCP服务器包括全面的工作流程指导，以确保正确使用：

1. 服务器描述：LLM首次连接时提供的内置说明
2. get_workflow_help() 工具：特定操作的上下文工作流程指南
3. 增强工具文档字符串：关键工具中的工作流提醒，如 create_task()
4. 工作流文档：参见 freedcamp-workflow-instructions.md 获取详细指导

关键规则：总是打电话 get_projects() 和 get_users() 在操作中使用ID之前，先查找ID！

📚 api参考

🏗️ 项目工具

📋 任务工具

👥 用户工具

💬 评论工具

📁 文件工具

🔍 使用示例

高级任务筛选

# Get overdue high-priority tasks assigned to specific users
await get_all_tasks(
    status_filter=["0", "2"],  # Not started or in progress
    assigned_to_ids=["123", "456"],
    due_date_to="2024-01-01",  # Overdue
    order_by="priority",
    order_direction="desc",
    limit=50
)

项目团队管理

# Add users to a project
await update_project(
    project_id="789",
    users_to_add=[
        {"email": "user@example.com", "first_name": "John", "last_name": "Doe"},
        {"email": "admin@example.com", "first_name": "Jane", "last_name": "Admin"}
    ]
)

使用子任务创建任务

# Create a parent task with subtasks and files
parent_task = await create_task(
    title="Main Project Phase",
    project_id="123",
    priority=3,  # High priority
    due_date="2024-12-31"
)

# Create subtask
await create_task(
    title="Subtask 1",
    project_id="123",
    parent_task_id=parent_task["task"]["id"],
    attached_file_ids=[456, 789]
)

🏗️ 建筑

组件

• FastMCP核心：高性能MCP服务器框架
• Freedcamp API客户端：安全、经过身份验证的API包装
• MCPO代理：OpenAPI生成和REST接口
• Docker环境：具有运行状况监控的容器化部署

主要特点

• 稳健的错误处理：全面的错误管理和日志记录
• 数据格式：所有端点的一致响应结构
• 安全：安全的凭据管理和API身份验证
• 演出：通过分页和过滤优化查询
• 可靠性：健康检查、重启策略和连接管理

🐳 部署

生产部署

1. 环境设置：

# Production environment file
FREEDCAMP_API_KEY=prod_api_key
FREEDCAMP_API_SECRET=prod_api_secret

1. 服务扩展：

docker-compose up -d --scale freedcamp-fastapi=3

1. 健康监测：

docker-compose ps  # Check service health
docker-compose logs -f  # Monitor logs

开发模式

# Start with hot-reload
docker-compose -f docker-compose.yml -f docker-compose.dev.yml up

🔧 发展

项目结构

freedcamp-mcp-server/
├── freedcamp_mcp.py          # Main MCP server implementation
├── docker-compose.yml        # Docker services configuration
├── Dockerfile               # Container definition
├── requirements.txt         # Python dependencies
├── healthcheck.py          # Health monitoring
├── .env                    # Environment variables
├── .gitignore             # Git ignore rules
└── README.md              # This file

添加新功能

1. 实施该方法 在……里面 FreedcampMCP 类
2. 添加工具装饰器 在……里面 _setup_tools()
3. 更新文档 以及示例
4. 使用Docker Compose进行测试

🤝 贡献

1. 分叉存储库
2. 创建要素分支(git checkout -b feature/amazing-feature)
3. 提交您的更改(git commit -m 'Add amazing feature')
4. 推到分支(git push origin feature/amazing-feature)
5. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🆘 支持

• 问题:
• 文档: Freedcamp API文档
• MCP协议: 模型上下文协议

🎯 路线图

• \[ \] 文件上传支持：直接文件上传功能
• \[ \] Webhook集成：实时通知
• \[ \] 高级报告：分析和报告工具
• \[ \] 批量操作：大规模任务和项目管理
• \[ \] 自定义字段模板：动态自定义字段管理
• \[ \] 集成测试：全面的测试套件
• \[ \] 性能优化：查询缓存和优化

______________________________________________________________________

⭐ 如果此存储库能帮助您更有效地管理Freedcamp项目，请将其标记为星号！

由以下材料制成❤️ Freedcamp和MCP社区。