Freelo MCP 服务器 (非官方)

警告: 这是一个非官方的社区项目，不由 Freelo 直接支持。

<p align="center"> <a href="https://www.freelo.io/cs"> <img src="logo.png" alt="Freelo Logo" width="300"> </a> </p>

用于 Freelo API v1 的 MCP 服务器 - 使用模型上下文协议 (MCP) 与 Freelo API 通信的代理服务器的实现。 Freelo 是一个捷克项目管理和任务管理服务。

关于项目

Freelo MCP 服务器提供了一个使用模型上下文协议 (MCP) 与 Freelo API 通信的接口。 它允许将 Freelo 集成到支持 MCP 协议的 AI 助手，如 Cline、Claude 等。

该项目包含两个主要组件：

1. REST API 服务器 - 用于与 Freelo API 通信的传统 REST API
2. MCP 服务器 - 实现模型上下文协议的服务器，用于 AI 助手

安装

本地安装

# 克隆存储库
git clone https://github.com/karlost/FreeloMCP.git
cd FreeloMCP

# 安装依赖项
npm install

作为 npm 包安装

# 全局安装
npm install -g freelo-mcp

# 或者无需安装即可使用
npx freelo-mcp

配置

在使用之前，需要设置环境变量以进行 Freelo API 身份验证。 有两种配置选项：

1. 使用 .env 文件

在项目根目录中创建一个 .env 文件，内容如下：

# 可选的服务器设置
PORT=3000
NODE_ENV=development

# Freelo API 的必需身份验证凭据
FREELO_EMAIL=vas@email.cz
FREELO_API_KEY=VAS_API_KLIC
FREELO_USER_AGENT=freelo-mcp

2. 直接使用环境变量

您也可以在启动时直接设置环境变量：

FREELO_EMAIL=vas@email.cz FREELO_API_KEY=VAS_API_KLIC FREELO_USER_AGENT=freelo-mcp node mcp-server.js

系统要求

• Node.js 版本 18.0.0 或更高版本

启动

REST API 服务器

# 开发环境
npm run dev

# 生产环境
npm start

MCP 服务器

# 开发环境
npm run mcp:dev

# 生产环境
npm run mcp

# 使用 npx (安装包后)
freelo-mcp

# 使用 npx (无需安装)
npx freelo-mcp

# 本地运行
node bin/freelo-mcp.js

与 Cline 集成

为了与 Cline (支持 MCP 的 AI 助手) 集成，在您的主目录中创建一个 cline_mcp_settings.json 文件，内容如下：

{
  "mcpServers": {
    "freelo-mcp": {
      "command": "node",
      "args": ["bin/freelo-mcp.js"],
      "env": {
        "NODE_ENV": "production",
        "FREELO_EMAIL": "vas@email.cz",
        "FREELO_API_KEY": "VAS_API_KLIC",
        "FREELO_USER_AGENT": "freelo-mcp"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

请确保：

1. bin/freelo-mcp.js 文件的路径正确（可能因安装方式而异）
2. 身份验证凭据 (FREELO_EMAIL, FREELO_API_KEY) 正确
3. 设置后重启 Cline 以使更改生效

测试

该项目包含自动化测试，用于验证 MCP 工具的功能。 测试使用 nock 库模拟 API，不需要真实的登录凭据。

运行所有测试

npm test

运行特定测试

npm test -- tests/mcp-tools-simple.test.js

运行带有代码覆盖率的测试

npm test -- --coverage

身份验证

REST API

身份验证使用 HTTP Basic Authentication。 用户名是用于登录 Freelo 的电子邮件，密码是 API 密钥。

每个请求都必须包含 User-Agent 标头。

MCP 中的身份验证

使用 MCP 服务器时，身份验证完全通过环境变量进行：

• 在 .env 文件或 cline_mcp_settings.json 中设置环境变量 FREELO_EMAIL、FREELO_API_KEY 和 FREELO_USER_AGENT
• 所有 MCP 工具都会自动使用这些值来验证 Freelo API
• 无需在每个请求中传递身份验证凭据

可用的 MCP 工具

下表显示了基于最新测试的各个 MCP 工具的实现状态：

类别	工具	描述	状态	备注
项目	get_projects	获取自己的项目	✅
	get_all_projects	获取所有项目	✅
	create_project	创建新项目	✅
	get_project_details	获取项目详情	✅
	archive_project	存档项目	✅
	activate_project	激活项目	✅
	delete_project	删除项目	✅
任务	get_all_tasks	获取所有任务（全局，带过滤器）	⚠️	即使使用 projectId 过滤器，也会返回所有项目中的任务。
	create_task	在任务列表中创建新任务	✅
	get_task_details	获取特定任务的详情	✅
	edit_task	编辑现有任务	✅
	delete_task	删除任务	✅
	finish_task	完成任务	✅
	activate_task	激活任务	✅
任务列表	get_project_tasklists	获取项目的任务列表	✅
	create_tasklist	在项目中创建新的任务列表	✅
	get_tasklist_tasks	获取任务列表中的任务	✅
用户	get_users	获取所有用户列表	✅
	remove_workers	从项目中删除工作人员	❌	失败，出现 404 错误。
文件	get_all_files	获取所有文件和文档的列表	✅
	upload_file	上传文件	❌	失败，出现 TypeError 错误（期望 Blob 而不是 Base64）。
	download_file	下载文件	❓	未测试（取决于 upload_file）。
子任务	create_subtask	为任务创建新的子任务	⚠️	在响应中返回不正确的 task_id。
	get_subtasks	获取任务的子任务列表	⚠️	返回整个项目中的子任务，而不是根据 taskId 进行过滤。
评论	create_comment	向任务添加评论	✅
	edit_comment	编辑评论	✅
标签	add_labels_to_task	向任务添加标签	✅
	remove_labels_from_task	从任务中删除标签	✅

图例:

• ✅: 功能正常
• ⚠️: 功能正常，但存在问题/意外行为
• ❌: 功能不正常
• ❓: 未测试

贡献和进一步开发

如果您想为该项目的开发做出贡献，您可以创建一个 pull request 或在 GitHub 上打开一个 issue。

进一步开发的建议：

• 实现更多 MCP 工具以覆盖 Freelo API 的所有功能
• 改进文档和使用示例
• 添加对 Freelo API 其他功能的支持（通知、标签等）

许可证

该项目根据 MIT 许可证获得许可。

作者

Chodeec (karlost)