FreeloMCP

Freelo MCP 服务（非官方）

**注意：**这是一个非官方社区项目，Freelo 公司不直接提供支持。

用于 Freelo API v1 的 MCP 服务——完整实现了 Model Context Protocol 服务，可与 Freelo API 通信。Freelo 是一款捷克项目管理和任务管理服务。

✨ 特性

• 🚀 104 个 MCP 工具，覆盖 100% 的 Freelo API v1
• ✅ 经过全面测试——207 个单元测试 + 82 个真实 API 测试
• 🔧 可用于生产环境——所有已知错误均已修复
• 📊 智能筛选——支持分页和高级筛选器
• 🔒 安全——使用 API 密钥进行 HTTP Basic Authentication
• 🎯 经过优化——修复大型数据集的令牌限制问题
• 📝 完整文档——详细介绍所有工具
• 🏷️ MCP 注解——自动添加行为提示（readOnly、destructive、idempotent）
• 📋 OutputSchema——使用 Zod schemas 验证所有 API 响应
• 🧩 模块化架构——工具分布在 19 个模块中

📊 项目状态

指标	值
MCP 工具总数	104
可用工具	100%
已修复错误	16/16（100%）
API 覆盖率	100% Freelo API v1
单元测试	207（205 通过，2 跳过）
真实 API 测试	82 通过，0 失败
测试状态	✅ 已完成全面验证

🚀 快速开始

通过 NPX 安装（推荐）

开始使用 Freelo MCP 最简单的方法是通过 npx——无需安装任何内容！

1️⃣ 用于 Claude Desktop（Anthropic Desktop）

1. 找到配置文件：

   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
   • Linux：~/.config/Claude/claude_desktop_config.json

2. 将 Freelo MCP 服务添加到配置中：

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}

3. 重启 Claude Desktop

4. 验证：

   • 在 Claude Desktop 中，你应该能在底部面板看到 🔌 图标
   • 试着说：“显示我的 Freelo 项目”

2️⃣ 用于 Claude Code（CLI）

1. 通过一条命令添加 MCP 服务：

claude mcp add freelo-mcp \
  --env [email protected] \
  --env FREELO_API_KEY=VAS_API_KLIC \
  --env FREELO_USER_AGENT="FreeloMCP/3.0.0 ([email protected])" \
  -- npx -y freelo-mcp

重要：-- 分隔符用于分隔 Claude CLI 选项和 MCP 服务命令！

2. 刷新连接：

/mcp

3. 验证：

在 Claude Code 中试着说：“显示我的 Freelo 项目”

其他安装方式——Git clone

用于开发，或在需要修改代码时使用：

# Klonování repozitáře
git clone https://github.com/karlost/FreeloMCP.git
cd FreeloMCP

# Instalace závislostí
npm install

# Vytvoření .env souboru
cat > .env << EOF
[email protected]
FREELO_API_KEY=VAS_API_KLIC
FREELO_USER_AGENT=FreeloMCP/3.0.0 ([email protected])
EOF

# Spuštění MCP serveru
node mcp-server.js

使用本地安装的 Claude Desktop 配置：

{
  "mcpServers": {
    "freelo": {
      "command": "node",
      "args": ["/absolutni/cesta/k/FreeloMCP/mcp-server.js"],
      "env": {
        "FREELO_EMAIL": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}

使用本地安装的 Claude Code 配置：

claude mcp add freelo-mcp \
  --env [email protected] \
  --env FREELO_API_KEY=VAS_API_KLIC \
  --env FREELO_USER_AGENT="FreeloMCP/3.0.0 ([email protected])" \
  -- node /absolutni/cesta/k/FreeloMCP/mcp-server.js

🚀 传输选项

Freelo MCP 服务支持三种传输协议：

1. Stdio 传输（默认——CLI 工具）

适用于 Claude Desktop、Claude Code、Cline 和其他基于 CLI 的 MCP 客户端。

用法：

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0"
      }
    }
  }
}

2. Streamable HTTP 传输（⭐ 推荐用于 HTTP 客户端）

适用于 Web 应用、n8n、ElevenLabs Agents 和远程访问的现代 MCP 兼容 HTTP 传输。

启动 HTTP 服务：

# Základní použití
npm run mcp:http

# S vlastním portem
PORT=8080 npm run mcp:http

# Nebo přes npx
PORT=8080 npx -y freelo-mcp-http

端点： http://localhost:3000/mcp/v1/endpoint

所需 HTTP 标头：

• MCP-Protocol-Version: 2025-03-26
• Accept: text/event-stream（用于 GET 请求）
• Mcp-Session-Id: <session-id>（初始化后）

健康检查： GET http://localhost:3000/health

环境配置：

PORT=3000
[email protected]
FREELO_API_KEY=VAS_API_KLIC
FREELO_USER_AGENT=FreeloMCP/3.0.0

3. SSE 传输（⚠️ 已弃用）

旧版 Server-Sent Events 传输。请改用 Streamable HTTP。

npm run mcp:sse

Endpoint： http://localhost:3000/sse

⚠️ 注意： 自 MCP 规范 2025-03-26 起，SSE 传输已弃用。请迁移到 Streamable HTTP 传输。参见 MIGRATION_HTTP.md。

📡 传输方式对比

功能	Stdio	Streamable HTTP	SSE（旧版）
使用场景	CLI 工具	HTTP/网页客户端	旧版支持
状态	✅ 活跃	✅ 推荐	⚠️ 已弃用
会话管理	不适用	✅ 是	✅ 是
MCP 标准	✅ 是	✅ 是（2025-03-26）	❌ 旧版规范
Endpoint	stdio	/mcp/v1/endpoint	/sse
协议	stdin/stdout	HTTP GET/POST	Server-Sent Events
适用对象	桌面应用	n8n、网页应用、远程	从旧版迁移

其他 MCP 客户端的配置

3️⃣ Cline（VS Code 扩展）

1. 打开已安装 Cline 的 VS Code
2. 打开 Cline 中的 MCP 设置（汉堡菜单图标 → MCP Settings）
3. 编辑配置文件：

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}

4. 重启 VS Code 或重新加载窗口（Cmd/Ctrl + Shift + P → "Reload Window"）
5. **验证：**在 Cline 聊天中尝试输入“显示我的 Freelo 项目”

4️⃣ Windsurf（Codeium）

Windsurf 通过与 Claude Desktop 相同的格式支持 MCP：

1. 找到配置文件：

   • macOS：~/Library/Application Support/Windsurf/settings/mcp_config.json
   • Windows：%APPDATA%\Windsurf\settings\mcp_config.json
   • Linux：~/.config/Windsurf/settings/mcp_config.json

2. 添加配置：

{
  "mcpServers": {
    "freelo": {
      "command": "npx",
      "args": ["-y", "freelo-mcp"],
      "env": {
        "FREELO_EMAIL": "[email protected]",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
      }
    }
  }
}

3. 重启 Windsurf

5️⃣ Zed Editor

1. 打开 Zed 设置（Cmd/Ctrl + ,）
2. 前往“Language Models” → “Configure MCP Servers”
3. 添加配置：

{
  "freelo": {
    "command": "npx",
    "args": ["-y", "freelo-mcp"],
    "env": {
      "FREELO_EMAIL": "[email protected]",
      "FREELO_API_KEY": "VAS_API_KLIC",
      "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
    }
  }
}

4. 重启 Zed

6️⃣ Continue.dev（VS Code/JetBrains）

1. 打开 Continue 配置文件：

   • VS Code：主目录中的 .continue/config.json
   • JetBrains：相同位置

2. 添加 MCP 服务：

{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "name": "freelo",
        "command": "npx",
        "args": ["-y", "freelo-mcp"],
        "env": {
          "FREELO_EMAIL": "[email protected]",
          "FREELO_API_KEY": "VAS_API_KLIC",
          "FREELO_USER_AGENT": "FreeloMCP/3.0.0 ([email protected])"
        }
      }
    ]
  }
}

3. 重启 IDE

7️⃣ LibreChat

在 LibreChat（可自托管的 ChatGPT 替代方案）中：

1. 编辑 librechat.yaml：

mcpServers:
  - name: freelo
    command: npx
    args:
      - "-y"
      - "freelo-mcp"
    env:
      FREELO_EMAIL: [email protected]
      FREELO_API_KEY: VAS_API_KLIC
      FREELO_USER_AGENT: "FreeloMCP/3.0.0 ([email protected])"

2. 重启 LibreChat 容器

8️⃣ n8n（工作流自动化）

n8n 需要使用 SSE（Server-Sent Events）传输，而不是 stdio。Freelo MCP 提供专用的 SSE 服务：

1. 启动 SSE 服务：

通过 npx 在本地启动：

npx -y freelo-mcp-sse

或者在 git clone 后使用 npm 脚本：

npm run mcp:sse

或者使用自定义端口：

PORT=8080 npx -y freelo-mcp-sse

2. 在 n8n 中配置：

1. 在 n8n 工作流中添加 MCP Client Tool 节点

2. 在 MCP Client 设置中创建新的凭据：

   • 传输类型： SSE
   • SSE Endpoint URL： http://localhost:3000/sse
   • 消息 Endpoint URL： http://localhost:3000/message

3. 连接后，即可访问全部 104 个 Freelo 工具

3. 健康检查：

验证服务是否正在运行：

curl http://localhost:3000/health

响应：

{
  "status": "ok",
  "service": "freelo-mcp-sse",
  "version": "3.0.0",
  "activeConnections": 0,
  "endpoints": {
    "sse": "/sse",
    "messages": "/message",
    "health": "/health"
  }
}

4. Docker 部署：

生产环境中可以创建 Docker 容器：

FROM node:18-alpine
WORKDIR /app
RUN npm install -g freelo-mcp
ENV [email protected]
ENV FREELO_API_KEY=VAS_API_KLIC
ENV FREELO_USER_AGENT="FreeloMCP/3.0.0 ([email protected])"
ENV PORT=3000
EXPOSE 3000
CMD ["freelo-mcp-sse"]

docker build -t freelo-mcp-sse .
docker run -p 3000:3000 freelo-mcp-sse

注意事项：

• SSE 服务支持多个并发连接
• 每个连接都有自己的会话 ID
• 客户端断开连接时，会话会自动清理
• 允许来自所有来源的 CORS 请求

📚 可用的 MCP 工具

分类概览（104 个工具）

类别	数量	描述
Tasks	22	任务 CRUD、提醒、公开链接、预估
Projects	13	项目管理、模板、归档
Custom Fields	14	自定义字段、枚举选项、值
Labels	9	创建、编辑和管理标签
Users	9	用户管理、离开办公室、邀请
Invoices	6	开票、报告、标记
Tasklists	6	任务列表、工作人员、模板管理
Work Reports	5	工作报告 CRUD
Notes	5	项目笔记 CRUD
Time Tracking	4	开始／停止跟踪、编辑
Files	3	上传、下载、列出文件
Comments	3	任务和文件评论
Notifications	3	获取和管理通知
Pinned Items	3	项目中的固定条目
Subtasks	3	创建和管理子任务
Filters	3	任务自定义筛选器
Search	1	Elasticsearch 全文搜索
Events	1	事件历史记录
States	1	获取状态（active、archived 等）

🔥 最常用工具

Projects（18 个工具）

• get_projects - 获取自己的活跃项目
• get_all_projects - 所有项目（自己的和共享的），支持分页
• get_project_details - 项目详情，包括工作人员和任务列表
• get_invited_projects - 我受邀加入的项目
• get_archived_projects - 已归档项目
• get_template_projects - 可按筛选条件查看的模板项目
• get_user_projects - 特定用户的项目
• get_project_workers - 项目工作人员列表
• get_project_manager_of - 我担任 PM 的项目
• get_project_tasklists - 项目中的所有任务列表
• create_project - 创建新项目
• create_project_from_template - 从模板创建
• archive_project - 归档项目
• activate_project - 激活项目
• delete_project - 删除项目
• invite_users_by_email - 通过电子邮件邀请用户
• invite_users_by_ids - 根据 ID 邀请用户
• remove_workers - 从项目中移除工作人员

Tasks（19 个工具）- 支持高级筛选

列表和详情：

• get_all_tasks - 所有任务，支持 14 个筛选条件：

  • search_query - 全文搜索
  • state_id - 按状态筛选（active、finished）
  • projects_ids - 按项目筛选（数组）
  • tasklists_ids - 按任务列表筛选（数组）
  • order_by - 排序字段（priority、name、date_add、date_edited_at）
  • order - 排序方向（asc、desc）
  • with_label / without_label - 按标签筛选
  • no_due_date - 无截止日期
  • due_date_range - 截止日期范围
  • finished_overdue - 逾期完成
  • finished_date_range - 完成日期范围
  • worker_id - 按工作人员筛选
  • p - 分页（从 0 开始）

• get_tasklist_tasks - 特定任务列表中的任务

• get_finished_tasks - 已完成的任务

• get_task_details - 完整的任务详情

• get_task_description - 任务描述

CRUD 操作：

• create_task - 创建任务
• create_task_from_template - 从模板创建
• edit_task - 编辑任务
• update_task_description - 更新描述
• move_task - 移至其他任务列表
• finish_task - 完成任务
• activate_task - 激活任务
• delete_task - 删除任务

高级功能：

• create_task_reminder - 添加提醒（✅ 已修复）
• delete_task_reminder - 删除提醒
• get_public_link - 获取公开链接
• delete_public_link - 删除链接
• set_total_time_estimate - 设置时间预估（Premium - 未测试）
• delete_total_time_estimate - 删除时间预估（Premium - 未测试）
• set_user_time_estimate - 设置用户预估（Premium - 未测试）
• delete_user_time_estimate - 删除用户预估（Premium - 未测试）

Files（3 个工具）- 上传和下载

- `get_all_files` - 按筛选条件列出文件： - `projects_ids` - 按项目筛选 - `type` - 类型（directory、link、file、document） - `p` - 分页

• upload_file - 上传文件（最大 100MB）

  • 参数 filePath - 本地文件路径（大文件优先使用）
  • 参数 fileData - Base64 编码的文件（适用于小文件或内存中的数据）
  • 参数 fileName - 文件名（使用 fileData 时必填，使用 filePath 时可选）

• download_file - 根据 UUID 下载文件

时间跟踪与工作报告（7 个工具）

时间跟踪：

• start_time_tracking - 开始跟踪
• stop_time_tracking - 停止跟踪
• edit_time_tracking - 编辑活动跟踪

工作报告：

• get_work_reports - 按筛选条件获取工作报告：

  • projects_ids - 按项目筛选
  • users_ids - 按用户筛选
  • tasks_labels - 按标签筛选
  • date_reported_range - 日期范围

• create_work_report - 创建报告

• update_work_report - 更新报告

• delete_work_report - 删除报告

自定义字段（11 个工具）- 高级功能

⚠️ 注意： 自定义字段是 Freelo 的高级功能（402 Payment Required）。由于套餐限制，这些工具尚未经过完整测试。

• get_custom_field_types - 字段类型（text、number、date、bool、enum、link）
• get_custom_fields_by_project - 项目中的字段
• create_custom_field - 创建字段（✅ 已修复 - enum 验证）
• rename_custom_field - 重命名
• delete_custom_field - 删除
• restore_custom_field - 恢复
• add_or_edit_field_value - 字段值
• add_or_edit_enum_value - Enum 值
• delete_field_value - 删除值
• get_enum_options - Enum 选项
• create_enum_option - 新建 enum 选项

其他类别

任务列表（5 个）：

• get_project_tasklists、get_tasklist_details、get_assignable_workers
• create_tasklist、create_tasklist_from_template（✅ 已修复）

用户（6 个）：

• get_users、get_out_of_office、set_out_of_office（✅ 已修复）
• delete_out_of_office、invite_users_by_email、invite_users_by_ids（✅ 已修复）

子任务（2 个）：

• create_subtask、get_subtasks

评论（3 个）：

• create_comment、edit_comment、get_all_comments（支持筛选和分页）

标签（9 个）：

• create_task_labels、add_labels_to_task、remove_labels_from_task、find_available_labels
• edit_label、delete_label、add_label_to_project、remove_label_from_project

发票（4 个）：

• get_issued_invoices、get_invoice_detail、download_invoice_reports、mark_as_invoiced

通知（3 个）：

• get_all_notifications（支持分页）、mark_notification_read、mark_notification_unread

备注（4 个）：

• create_note、get_note、update_note、delete_note

置顶项目（3 个）：

• get_pinned_items、pin_item（✅ 已修复）、delete_pinned_item

事件（1 个）：

• get_events - 支持高级筛选（7 个参数及分页）的历史记录

筛选器（3 个）：

• get_custom_filters、get_tasks_by_filter_uuid、get_tasks_by_filter_name

状态（1 个）：

• get_all_states - 获取所有状态（active、archived、template、finished）

搜索（1 个）：

• search_elasticsearch - 跨实体全文搜索

🤖 AI Agent 指南

如需了解如何将 Freelo MCP 与 AI Agent（Claude、ChatGPT 等）高效配合使用，请阅读 AI_GUIDE.md。

指南包含：

• ✅ 快速入门工作流 - 最常用的工作流程
• 🔄 数据流模式 - 如何正确连接工具
• 🎯 工具选择指南 - 何时使用哪个工具
• 💡 最佳实践 - 面向 AI Agent 的优化建议和技巧
• 📊 常见工作流 - 常见任务的现成模板
• ⚠️ 错误处理 - 常见问题的解决方法

面向 AI Agent： AI_GUIDE.md 提供结构化说明、代码示例和工作流模式，帮助通过 MCP 使用 Freelo API 时实现最高效率。

---

🔧 已修复的错误与改进

版本 2.0.0 - 全面验证与修复

Token 限制修复（4 个工具）：

• ✅ get_all_tasks - 新增 14 个筛选参数和分页
• ✅ get_events - 新增 7 个筛选参数和分页
• ✅ get_all_comments - 新增 5 个筛选参数和分页
• ✅ get_all_files - 新增 3 个筛选参数和分页

API 集成修复（修复了 16 个 bug）：

1. ✅ create_task_reminder - 将 date 转换为 remind_at
2. ✅ invite_users_by_ids - 将 project_id 改为 projects_ids（数组）
3. ✅ set_out_of_office - 数据包装在 {out_of_office: {...}} 中
4. ✅ pin_item - 默认链接值设为 '#'，而不是 null
5. ✅ create_tasklist_from_template - 使用扁平结构，而不是嵌套对象
6. ✅ upload_file - 新增从 'form-data' package 导入 FormData
7. ✅ create_custom_field - is_required 使用 enum('yes','no')，而不是 boolean
8. ✅ create_comment - 将参数 'description' 更正为 'content'
9. ✅ edit_comment - 修正 API 所需的数据结构
10. ✅ create_subtask - 更正 assignedTo 参数
11. ✅ create_task - 全面验证参数

v3.0.0 中的新修复： 12. ✅ add_labels_to_task - API 使用 { id }，而不是 { uuid } 13. ✅ remove_labels_from_task - 同样的修复 14. ✅ create_comment - 附件通过 files: [{ uuid }] 传递，而不是 attachments 15. ✅ edit_comment - 附件通过 files: [{ uuid }] 传递，而不是 { download_url } 16. ✅ remove_workers - users_ids 使用整数数组，并使用 users_emails 键

💡 使用示例

项目基本操作

// Získání všech projektů
await get_all_projects()

// Detail konkrétního projektu
await get_project_details({ projectId: "197352" })

// Vytvoření nového projektu
await create_project({
  projectData: {
    name: "Nový projekt",
    currency_iso: "CZK"
  }
})

任务与筛选器操作

// Všechny aktivní úkoly v projektu
await get_all_tasks({
  filters: {
    projects_ids: [197352],
    state_id: 1,
    order_by: "priority",
    order: "desc",
    p: 0
  }
})

// Hledání úkolů s konkrétním štítkem
await get_all_tasks({
  filters: {
    with_label: "urgent",
    no_due_date: false,
    p: 0
  }
})

// Úkoly dokončené po termínu
await get_all_tasks({
  filters: {
    finished_overdue: true,
    finished_date_range: {
      date_from: "2025-10-01",
      date_to: "2025-10-09"
    }
  }
})

Time Tracking 工作流

// 1. Spustit tracking na úkolu
await start_time_tracking({ taskId: "25368707" })

// 2. Upravit popis
await edit_time_tracking({
  trackingData: {
    description: "Práce na feature XYZ"
  }
})

// 3. Zastavit a vytvořit work report
await stop_time_tracking()

文件

// Upload souboru z disku (preferováno pro velké soubory)
await upload_file({
  filePath: "/cesta/k/dokument.pdf"
})

// Upload souboru z base64 (pro malé soubory / data v paměti)
const base64Data = Buffer.from("obsah souboru").toString('base64')
await upload_file({
  fileName: "dokument.pdf",
  fileData: base64Data
})

// Listing souborů v projektu
await get_all_files({
  filters: {
    projects_ids: [197352],
    type: "file",
    p: 0
  }
})

🔒 身份验证

获取 API 密钥

1. 登录 Freelo
2. 前往设置 → API
3. 生成新的 API 密钥
4. 复制密钥并妥善保存

安全

• ⚠️ 切勿公开分享你的 API 密钥
• ⚠️ 不要将 .env 文件提交到 git
• ✅ 使用 .gitignore 保护凭据
• ✅ 在生产环境中使用环境变量

🧪 测试

单元测试

# Spuštění všech testů (207 testů, 7 test suites)
npm test

# Konkrétní test suite
npm test -- tests/mcp-tools-simple.test.js

# S code coverage
npm test -- --coverage

真实 API 测试

针对 Freelo API 的完整测试，涵盖全部 104 个工具：

[email protected] \
FREELO_API_KEY=VAS_API_KLIC \
FREELO_USER_AGENT=freelo-mcp \
node tests/real-api-full-test.js

结果：82 项通过，0 项失败，33 项跳过（跳过项 = 高级功能、缺少数据）

🐛 故障排查

MCP 服务无法连接

解决方案：

1. 检查 Node.js 版本是否 ≥ 18.0.0：node --version
2. 检查配置中的环境变量
3. 重启 Claude Code：/mcp
4. 检查日志：ps aux | grep mcp-server

错误 "Payment required (402)"

部分功能为高级功能：

• 自定义字段操作
• 时间预估（设置/删除）

**解决方案：**升级 Freelo 方案或使用其他工具。

超出 Token 限制

对于大型数据集，请使用分页：

// Místo
await get_all_tasks()

// Použijte
await get_all_tasks({
  filters: {
    projects_ids: [specificProjectId],
    p: 0  // první stránka
  }
})

服务不断重启

**原因：**ES6 模块会缓存在 Node.js 进程中。

解决方案：

# Najděte proces
ps aux | grep "[n]ode.*mcp-server.js"

# Zabijte proces (nahraďte PID)
kill -9 PID

# Refresh v Claude Code
/mcp

📖 更多资源

• Freelo API 文档
• Model Context Protocol 规范
• Claude Code 文档

🤝 参与贡献

欢迎贡献！

1. Fork 仓库
2. 创建功能分支（git checkout -b feature/AmazingFeature）
3. 提交更改（git commit -m 'Add AmazingFeature'）
4. 推送分支（git push origin feature/AmazingFeature）
5. 发起 Pull Request

📝 更新日志

v3.0.0 (2026-03-09) - 重大重构与完整真实 API 验证！🎯🧪

模块化架构：

• 🧩 19 个工具模块 - 将工具从单体 mcp-server.js 重构为 tools/ 中的独立模块
• 📁 新结构：tools/tasks.js、tools/projects.js、tools/labels.js、tools/comments.js 等
• 🔧 共享实用工具：registerToolWithMetadata.js、paginationHelper.js、errorHandler.js

新增工具（98 → 104）：

• ➕ get_note - 获取备注详情
• ➕ change_enum_option - 编辑枚举选项
• ➕ force_delete_enum_option - 强制删除枚举选项
• ➕ get_invoice_reports_json - 以 JSON 格式获取发票报告
• ➕ get_assignable_workers - 获取可分配到任务列表的工作人员
• ➕ edit_label / delete_label / add_label_to_project / remove_label_from_project - 完整的标签管理

真实 API 测试发现的错误修复（新增 5 项修复）：

• 🐛 add_labels_to_task - API 使用 { id } 而不是 { uuid } 表示标签
• 🐛 remove_labels_from_task - 与 add_labels_to_task 相同的修复
• 🐛 create_comment - 通过 files: [{ uuid }] 而不是 attachments 添加附件
• 🐛 edit_comment - 通过 files: [{ uuid }] 而不是 { download_url } 添加附件
• 🐛 remove_workers - users_ids 使用整数数组，并使用 users_emails 键

测试：

• ✅ 207 个单元测试，分布在 7 个测试套件中（205 个通过，2 个跳过）
• ✅ 82 个真实 API 测试，针对在线 Freelo API（0 个失败）
• 🧪 新增 tests/real-api-full-test.js - 对全部 104 个工具进行完整真实 API 测试
• 🔄 API 速率限制（429）的重试逻辑
• ⏭️ 自动跳过高级功能（402）

v2.3.0 (2025-10-12) - 完整实现 MCP 元数据！🏷️📊

• ✨ 新功能： 为全部 98 个工具实现 MCP 工具注解和 outputSchema
• 🏷️ 行为提示： 每个工具都有自动注解：
  • readOnlyHint: true - 41 个工具仅读取数据（无需确认即可安全使用）
  • destructiveHint: true - 14 个工具可能删除数据（需要确认）
  • idempotentHint: true - 18 个工具可安全重复执行
  • openWorldHint: false - 所有工具仅使用 Freelo API
• 📊 OutputSchema： 全部 98 个工具都定义了用于验证输出的 Zod schema
  • 基于官方 freelo.apib API 文档
  • 帮助 AI Agent 更好地理解数据结构
  • 验证所有 API 响应的类型
• 📝 自动生成的标题： 每个工具都有易于理解的名称（例如，“获取所有任务”）
• 🔧 集中管理：
  • 新增 utils/toolAnnotations.js，用于管理行为提示
  • 新增 utils/schemas.js，用于存放完整的 Zod schema 库
  • 新增 utils/registerToolWithMetadata.js，用于自动应用元数据
• ✅ 100% 覆盖率： 所有工具均已重构，没有语法错误
• 🧪 全面测试： 新增的 test-annotations.js 会验证实现是否正确
• 📚 文档： 新增 ANNOTATIONS_IMPLEMENTATION.md 和 TOOL_DESCRIPTIONS_ANALYSIS.md 文件
• 🎯 用户优势：
  • 在 Claude Desktop 中获得更好的用户体验（破坏性操作会显示警告）
  • 对幂等工具进行更安全的自动重试
  • 加快工作流（只读工具无需额外确认）
  • 通过 schema 更准确地解析响应

v2.2.0 (2025-10-11) - AI 易用性升级！🤖

• ✨ 重大更新： 所有 98 个工具均已改进，更适合与 AI Agent 搭配使用
• 📝 工具描述： 每个工具现在都有详细说明，包括：
  • 工具的功能及适用场景
  • 与其他工具的关联（工作流衔接）
  • 破坏性操作警告
  • 高级功能标记
• 🔧 参数描述： 所有参数的说明均已改进，包括：
  • 格式和值示例（例如，“197352”、“2025-10-11”）
  • 源工具的引用（从哪里获取所需 ID）
  • 区分必填参数和可选参数
• 📚 新增 AI_GUIDE.md： 面向 AI Agent 的完整指南，包括：
  • 常见任务的快速入门工作流
  • 数据流模式（如何正确串联工具）
  • 工具选择指南（何时使用哪个工具）
  • 常见工作流及代码示例
  • 最佳实践和性能提示
  • 常见问题解答和故障排除
• 🎯 结果： AI Agent 现在能更好地理解如何以及何时使用各个工具
• ✅ 覆盖范围： 100% 的工具均已升级（项目、任务、自定义字段、时间跟踪等）

v2.1.0 (2025-10-09) - 为 n8n 提供 SSE 传输！🚀

• ✨ 新功能： 新增 SSE（服务器发送事件）传输，支持 n8n 和其他 HTTP 客户端
• 🌐 新增 bin 命令：freelo-mcp-sse，用于启动 HTTP 服务
• 📡 SSE 端点：/sse、/message、/health
• 🔄 支持多个并发连接，并提供会话管理
• 🐳 支持使用环境变量进行 Docker 部署
• 🔧 重构 mcp-server.js，导出 initializeMcpServer() 函数
• 📚 扩展文档，新增 n8n 配置和 Docker 部署说明
• ✅ 已完成全面测试，SSE 服务运行稳定

v2.0.5 (2025-10-09) - NPX 安装已可正常使用！🎉

• 🐛 严重修复： 移除了阻止 npx 启动的 isMainModule 检查
• ✅ NPX 安装完全可用：npx -y freelo-mcp
• ✅ 精简 bin 文件（611B → 144B）
• ✅ 移除了 MCP 服务中的所有 console.log/warn（这些输出违反了 stdio 协议）
• ✅ 模块加载时自动启动
• ✅ 既可通过 npx 运行，也可直接启动
• 📝 更新文档，说明在 Claude Code 中使用 -- 分隔符

v2.0.0-2.0.4 (2025-10-09)

• ✅ 完成对 98 个 MCP 工具的全面测试
• ✅ 修复 API 集成中的 11 个错误
• ✅ 添加令牌限制修复（4 个工具支持分页）
• ✅ 修复 upload_file 的 FormData
• ✅ 修复自定义字段枚举验证
• ✅ 修复基于模板创建任务列表
• ✅ 所有功能的覆盖率达到 97% 以上
• ✅ 发布可用于生产环境的版本
• 📚 扩展针对 7 个 MCP 客户端的文档

v1.0.0

• 🎉 首次发布
• 📦 98 个 MCP 工具
• 🔧 REST API 服务
• 📚 基础文档

📄 许可证

本项目采用 MIT 许可证。

👤 作者

Chodeec (karlost)

• GitHub：@karlost
• NPM：freelo-mcp

⚠️ 免责声明

本项目未经 Freelo 官方支持。这是一个社区项目，旨在通过 Model Context Protocol 将 Freelo 与 AI 助手集成。

🌟 支持项目

如果本项目对您有所帮助，欢迎：

• ⭐ 在 GitHub 上为项目加星
• 🐛 报告错误
• 💡 提出改进建议
• 🤝 提交包含新功能的拉取请求

---

为 Freelo 社区倾情打造 ❤️

_{在 Anthropic 的 Claude Code 协助下创建并维护}