Teamwork MCP

一个连接到 Teamwork API 的 MCP服务器，提供一个简化的接口来与 Teamwork 项目和任务进行交互。

特性

• 连接到 Teamwork API
• 检索项目和任务
• 创建、更新和删除任务
• RESTful API 端点
• 错误处理和日志记录
• MCP 服务器，用于与 Cursor 和其他应用程序集成

前提条件

• Node.js (v14.17 或更高版本，推荐 18+ 甚至更好的最新 LTS 版本)
• npm 或 yarn
• 具有 API 访问权限的 Teamwork 帐户

可用的 Teamwork MCP 工具

以下工具可通过 MCP 服务器获得：

项目工具

• getProjects - 从 Teamwork 获取所有项目
• getCurrentProject - 获取有关当前项目的详细信息
• createProject - 在 Teamwork 中创建一个新项目

任务工具

• getTasks - 从 Teamwork 获取所有任务
• getTasksByProjectId - 从 Teamwork 中特定项目获取所有任务
• getTaskListsByProjectId - 从 Teamwork 中特定项目获取所有任务列表
• getTaskById - 从 Teamwork 中按 ID 获取特定任务
• createTask - 在 Teamwork 中创建一个新任务
• createSubTask - 在 Teamwork 中父任务下创建一个新的子任务
• updateTask - 更新 Teamwork 中现有任务
• deleteTask - 从 Teamwork 中删除任务
• getTasksMetricsComplete - 获取 Teamwork 中已完成任务的总数
• getTasksMetricsLate - 获取 Teamwork 中延迟任务的总数
• getTaskSubtasks - 获取 Teamwork 中特定任务的所有子任务
• getTaskComments - 从 Teamwork 获取特定任务的评论

人员工具

• getPeople - 从 Teamwork 获取所有人
• getPersonById - 从 Teamwork 中按 ID 获取特定人员
• getProjectPeople - 从 Teamwork 中获取分配给特定项目的所有人员
• addPeopleToProject - 将人员添加到 Teamwork 中的特定项目
• deletePerson - 从 Teamwork 中删除人员
• getProjectsPeopleMetricsPerformance - 获取人员指标绩效
• getProjectsPeopleUtilization - 获取人员利用率
• getProjectPerson - 获取项目中的特定人员

报告工具

• getProjectsReportingUserTaskCompletion - 获取用户任务完成报告
• getProjectsReportingUtilization - 获取各种格式（CSV 和 HTML）的利用率报告

时间工具

• getTime - 获取所有时间条目
• getProjectsAllocationsTime - 获取项目分配时间

安装

1. 克隆存储库：

   git clone https://github.com/readingdancer/teamwork-mcp.git
   cd teamwork-mcp
   

2. 安装依赖项：

   npm install
   

3. 基于 .env.example 文件创建一个 .env 文件：

   cp .env.example .env
   

4. 使用您的 Teamwork 凭据更新 .env 文件。

配置

编辑 .env 文件以配置应用程序：

• PORT: 服务器将运行的端口（默认值：3000）
• NODE_ENV: 环境（开发、生产、测试）
• LOG_LEVEL: 日志记录级别（info、error、debug）
• TEAMWORK_DOMAIN: 您的 Teamwork 域名（例如，对于 https://your-company.teamwork.com，则为 "your-company"）
• TEAMWORK_USERNAME: 您的 Teamwork 用户名（电子邮件）
• TEAMWORK_PASSWORD: 您的 Teamwork 密码

设置凭据

您可以通过三种方式提供您的 Teamwork 凭据：

1. 环境变量: 在您的环境中设置 TEAMWORK_DOMAIN、TEAMWORK_USERNAME 和 TEAMWORK_PASSWORD。

2. .env 文件: 创建一个包含所需变量的 .env 文件，如上所示。

3. 命令行参数: 运行应用程序时传递凭据：

   node build/index.js --teamwork-domain=your-company --teamwork-username=your-email@example.com --teamwork-password=your-password

或者使用简短形式：

   node build/index.js --domain=your-company --user=your-email@example.com --pass=your-password

工具过滤

您可以使用以下命令行参数控制哪些工具可用于 MCP 服务器：

1. 允许列表: 仅公开特定工具：

      node build/index.js --allow-tools=getProjects,getTasks,getTaskById
   

   或者使用简短形式：

      node build/index.js --allow=getProjects,getTasks,getTaskById
   

2. 拒绝列表: 公开除指定工具之外的所有工具：

      node build/index.js --deny-tools=deleteTask,updateTask
   

   或者使用简短形式：

      node build/index.js --deny=deleteTask,updateTask
   

使用组进行工具过滤

您现在可以指定工具组进行过滤，从而更灵活地控制哪些工具可用于 MCP 服务器。 可用的组包括：

• Projects: 包括所有与项目相关的工具。
• Tasks: 包括所有与任务相关的工具。
• People: 包括所有与人员相关的工具。
• Reporting: 包括所有与报告相关的工具。
• Time: 包括所有与时间相关的工具。

在工具过滤中使用组

您可以在允许或拒绝列表中指定这些组，以包括或排除组中的所有工具。 例如：

1. 带有组的允许列表: 仅公开特定工具组：

   node build/index.js --allow-tools=Tasks,People
   

   或者使用简短形式：

   node build/index.js --allow=Tasks,People
   

2. 带有组的拒绝列表: 公开除指定组中的工具之外的所有工具：

   node build/index.js --deny-tools=Reporting,Time
   

   或者使用简短形式：

   node build/index.js --deny=Reporting,Time
   

默认情况下，如果未提供允许列表或拒绝列表，则会公开所有工具。 如果同时提供两者，则允许列表优先。

工具过滤在两个级别强制执行，以增强安全性：

1. 列出可用工具时（不在允许列表或拒绝列表中的工具将不可见）
2. 执行工具调用时（尝试调用已过滤的工具将被拒绝并显示错误）

设置您的 Teamwork 项目

要将您当前的解决方案与 Teamwork 项目关联，您可以使用以下方法：

使用配置文件

您可以在项目的根目录中创建一个 .teamwork 文件，其结构如下：

PROJECT_ID = YourTeamworkProjectID

这个简单的配置文件将您的解决方案与特定的 Teamwork 项目相关联，我们将来可能会使用它来存储更多详细信息。

配置完成后，MCP 将能够找到您的 Teamwork 项目并将其与您当前的解决方案相关联，从而减少获取与您正在处理的解决方案相关的项目和任务所需的 API 调用次数。

用法

使用 NPX (推荐)

使用 Teamwork MCP 最简单的方法是使用 npx：

npx teamwork-mcp

您还可以传递配置选项：

npx teamwork-mcp --domain=your-company --user=your-email@example.com --pass=your-password

构建应用程序

注意：如果您只想使用 MCP，则不需要这样做，请使用上面的 NPX 说明。

构建应用程序：

npm run build

这将编译 TypeScript 代码，准备好用作 MCP 服务器

作为 MCP 服务器运行

要作为 MCP 服务器运行以与 Cursor 和其他应用程序集成，如果您使用 .env 文件来存储您的用户名、密码和 url，或者如果您已将它们保存在环境变量中：

注意：不要忘记根据您保存存储库的位置更改驱动器和路径详细信息。

node C:/your-full-path/build/index.js

或者您可以使用行参数传递它们：

node C:/your-full-path/build/index.js --teamwork-domain=your-company --teamwork-username=your-email@example.com --teamwork-password=your-password

您也可以使用简短形式：

node C:/your-full-path/build/index.js --domain=your-company --user=your-email@example.com --pass=your-password

使用 MCP 检查器

要运行 MCP 检查器进行调试：

npm run inspector

添加到 Cursor（和其他 MCP 客户端）

要将此 MCP 服务器添加到 Cursor：

0.47 之前的版本

1. 打开 Cursor 设置 > 功能 > MCP
2. 单击“+ 添加新的 MCP 服务器”
3. 输入服务器的名称（例如，“Teamwork API”）
4. 选择“stdio”作为传输类型
5. 输入运行服务器的命令：npx @vizioz/teamwork-mcp 并添加上面提到的凭据和域命令行参数。
   • 您可以包括工具过滤选项：--allow=getProjects,getTasks 或 --deny=deleteTask
6. 单击“添加”

0.47 之后的版本（手动编辑配置）

    "Teamwork": {
      "command": "npx",
      "args": [
        "-y",
        "@vizioz/teamwork-mcp",
        "--domain",
        "yourdomain",
        "--user",
        "youruser@yourdomain.com",
        "--pass",
        "yourPassword"
      ]
    }

如果您想添加上面提到的允许或拒绝参数，您只需像这样添加它们，您可以添加上面给出的任何示例，您还可以添加组和单个工具，如下所示：

    "Teamwork": {
      "command": "npx",
      "args": [
        "-y",
        "@vizioz/teamwork-mcp",
        "--domain",
        "yourdomain",
        "--user",
        "youruser@yourdomain.com",
        "--pass",
        "yourPassword",
        "--allow",
        "Tasks,Projects",
        "--deny",
        "getProjectsPeopleMetricsPerformance,getProjectsPeopleUtilization"
      ]

Teamwork MCP 工具现在将在 Composer 中的 Cursor Agent 中可用。

许可证

该项目根据 MIT 许可证获得许可 - 有关详细信息，请参阅 LICENSE 文件。

免责声明

本项目与 Teamwork.com 无关，未经 Teamwork.com 认可或赞助。 在包名称 (@vizioz/teamwork-mcp) 中使用名称“Teamwork”仅用于描述目的，以表明与 Teamwork.com API 的兼容性。