Teamwork MCP

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

功能

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

前提条件

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

可用的Teamwork MCP工具

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

项目工具

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

任务工具

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

人员工具

• getPeople - 从Teamwork获取所有人
• getPersonById - 根据ID从Teamwork获取特定人
• 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: 日志级别（信息、错误、调试）
• 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服务器可用的工具。可用的组包括：

• 项目：包含所有与项目相关的工具。
• 任务：包含所有与任务相关的工具。
• 人员：包含所有与人员相关的工具。
• 报告：包含所有与报告相关的工具。
• 时间：包含所有与时间相关的工具。

在工具过滤中使用组

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

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服务器运行

为了与Cursor及其他应用集成而作为MCP服务器运行，如果您使用.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代理可用。

许可证

该项目采用MIT许可证发布 - 查看LICENSE文件了解详细信息。

免责声明

本项目与Teamwork.com无关联，也未得到Teamwork.com的认可或赞助。包名(@vizioz/teamwork-mcp)中使用“Teamwork”这一名称仅是为了描述目的，表明与Teamwork.com API兼容。