twist

Twist MCP 服务

还不了解 MCP？获取最新信息最简单的方式是阅读我们在 PulseMCP 上发布的每周通讯。

---

这是一个 MCP（模型上下文协议）服务，可将 MCP 客户端与 Twist 的团队消息和协作平台集成，通过统一的界面管理频道、话题串和消息。

Twist 是一款团队通信应用，强调通过有序的话题串进行异步沟通。与传统聊天应用不同，Twist 旨在通过将对话整理到频道和话题串中来减少信息过载。此服务可直接连接其 REST API。开始使用前，你需要获取 Twist bearer token。

本项目与 Twist 没有官方关联。

目录

• 亮点
• 功能
• 使用技巧
• 示例
• 设置
  • 速查表
  • Claude Desktop
    • 手动设置

亮点

频道管理：列出并获取频道信息，了解团队的沟通结构。

话题串操作：创建新话题串并访问现有话题串，以开展有序且聚焦主题的讨论。

发布消息：以编程方式向话题串添加消息，实现自动更新和通知。

优先支持异步沟通：遵循 Twist 平和、有序的沟通理念，无需立即回复。

功能

此服务在 macOS 上使用 Claude Desktop 构建并测试，也应适用于其他 MCP 客户端。

工具名称	描述
get_channels	获取工作区中的所有频道列表。
get_channel	根据 ID 获取特定频道的详细信息。
get_threads	获取频道中的话题串列表，并可选择筛选条件。
get_thread	获取特定话题串的详细信息，包括消息。
create_thread	在频道中创建话题串，并设置标题和初始内容。
add_message_to_thread	向现有话题串添加新消息。

使用技巧

• 首先使用 get_channels，查看工作区中可用的频道
• 创建话题串时，请使用清晰且能准确描述内容的标题，以保持条理
• 使用话题串归纳相关讨论，避免为同一主题创建多个话题串
• 大多数操作都需要工作区 ID，可通过环境变量进行配置
• 话题串和消息内容支持 Markdown 格式，可使用富文本
• 所有列表操作均支持分页，适用于包含大量项目的工作区

示例

发现频道并创建话题串

User: "Show me all channels in my Twist workspace"
Assistant: I'll get the list of channels in your workspace.

[Uses get_channels tool]

I found 5 channels in your workspace:
1. #general (ID: ch_123) - General discussions
2. #engineering (ID: ch_456) - Engineering team channel
3. #product (ID: ch_789) - Product discussions
...

User: "Create a thread in the engineering channel about the new API design"
Assistant: I'll create a new thread in the #engineering channel.

[Uses create_thread tool with channel_id: ch_456]

I've created a new thread titled "API Design Discussion - v2.0" in the #engineering channel. The thread ID is th_999.

在现有话题串中添加消息

User: "Add a message to thread th_999 with the latest API documentation link"
Assistant: I'll add that message to the thread.

[Uses add_message_to_thread tool]

I've added your message with the API documentation link to the thread.

开发

测试

本项目使用 Vitest 进行单元测试。每次向主分支推送或创建拉取请求时，都会自动运行测试。

在本地运行测试

# Install dependencies
npm run install-all

# Run tests once
npm run test:run

# Run tests in watch mode (recommended for development)
npm test

# Run tests with UI
npm run test:ui

测试结构

测试文件位于 tests/ 目录中：

• tests/functional/ - 各个组件的功能测试
• tests/integration/ - 使用模拟 Twist API 的集成测试
• tests/manual/ - 调用真实 Twist API 的手动测试（不会在 CI 中运行）
• tests/mocks/ - 模拟实现和测试数据

有关测试方式的更多详情，请参阅 tests/README.md。

手动测试

手动测试是端到端系统测试，用于验证与真实 Twist API 的完整集成。这些测试：

• 需要真实的 API 凭据（TWIST_BEARER_TOKEN 和 TWIST_WORKSPACE_ID 环境变量）
• 调用实际的 Twist 生产 API，而非模拟 API
• 按照真实的工作流串联 API 调用
• 不会在 CI 中运行，以避免触发 API 速率限制以及依赖外部服务
• 修改 TwistClient 代码或任何与外部 API 交互的代码时，应运行这些测试

运行手动测试：

# Copy .env.example to .env and add your credentials
cp .env.example .env
# Edit .env to add your real bearer token and workspace ID

# Run manual tests
npm run test:manual

# Run manual tests in watch mode
npm run test:manual:watch

设置

前置条件

• Node.js v24.2.0（如果已安装 nvm，请使用 nvm use）
• 一个 Twist bearer token
• 你的 Twist 工作区 ID

速查表

环境变量	说明	必需	默认值	示例
TWIST_BEARER_TOKEN	你的 Twist bearer token。可在 twist.com 获取	Y	N/A	oauth2:4238438234..
TWIST_WORKSPACE_ID	你的 Twist 工作区 ID	Y	N/A	12345

Claude Desktop

请准备好 Twist bearer token 和你的工作区 ID。

然后，选择下方你偏好的服务配置方式。如果你是第一次使用 MCP 服务，请确保已安装 Claude Desktop 应用程序，并按照 MCP 官方设置说明进行操作。

手动设置

你需要在计算机上安装 Node，以便在终端中运行 npx 命令。如果尚未安装 Node，可以从 nodejs.org 安装。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json

Windows：%APPDATA%\Claude\claude_desktop_config.json

修改 claude_desktop_config.json 文件，添加以下内容：

{
  "mcpServers": {
    "twist": {
      "command": "npx",
      "args": ["-y", "twist-mcp-server"],
      "env": {
        "TWIST_BEARER_TOKEN": "Bearer your-token-here",
        "TWIST_WORKSPACE_ID": "your-workspace-id"
      }
    }
  }
}

重启 Claude Desktop，即可开始使用！

实施计划

阶段 1：初始设置 ✅

• 根据模板创建项目结构
• 编写全面的 README 文档
• 规划 API 集成方案

阶段 2：核心基础设施

• 设置 TypeScript 配置
• 创建具有适当身份验证机制的 Twist API 客户端
• 实现错误处理和重试逻辑
• 设置测试基础设施（功能测试、集成测试、手动测试）

阶段 3：工具实现

• 实现 get_channels——列出工作区中的所有频道
• 实现 get_channel——获取指定频道的详细信息
• 实现 get_threads——列出主题串，并提供筛选选项
• 实现 get_thread——获取主题串及其消息
• 实现 create_thread——创建新的讨论主题串
• 实现 add_message_to_thread——向主题串发布消息

阶段 4：测试与完善

• 编写全面的单元测试
• 创建使用模拟 API 的集成测试
• 实现用于验证真实 API 的手动测试
• 添加恰当的错误消息和用户反馈
• 记录 API 的任何限制或特殊行为

阶段 5：未来增强（MVP 之后）

• 添加主题串搜索支持
• 实现消息编辑和删除
• 添加文件附件支持
• 支持表情回应和提及
• 添加工作区用户管理工具

技术决策

API 集成

• 使用 REST API（https://developer.twist.com/v3/）
• 实现速率限制和重试逻辑
• 处理列表操作的分页
• 妥善处理网络问题

身份验证

• 通过 Authorization 标头进行 Bearer 令牌身份验证
• 大多数操作都需要工作区 ID
• 通过环境变量安全地存储凭据

工具设计

• 工具应专注于单一用途
• 使用一致的命名方式（get**、create*_、add__）
• 返回易于使用的结构化数据
• 针对常见问题提供有用的错误消息