Teletype

English | Русский

Teletype MCP 服务

架构 | MCP 客户端 | 工具参考

适用于 Teletype 的 MCP 服务。其工具涵盖日常支持工作：查找和阅读对话、查询客户资料、发送回复、补充内部背景信息以及查看项目状态。

快速开始

连接时，VS Code 会提示输入项目令牌。对于 Cursor，请在打开连接前于应用环境中设置 TELETYPE_API_TOKEN。请参阅客户端指南。

托管服务（推荐）。 Teletype 在 https://mcp.teletype.app/mcp 上运行 MCP 服务。使用项目的 Public API 令牌连接。无需本地安装。在 Claude Code 中：

claude mcp add --transport http teletype https://mcp.teletype.app/mcp \
  --header "X-Teletype-Api-Token: your-teletype-public-api-token"

或者将此文件合并到 .mcp.json 中（Claude Code 会从环境变量中展开 ${TELETYPE_API_TOKEN}）：

{
  "mcpServers": {
    "teletype": {
      "type": "http",
      "url": "https://mcp.teletype.app/mcp",
      "headers": { "X-Teletype-Api-Token": "${TELETYPE_API_TOKEN}" }
    }
  }
}

对于 Claude Code 和 Codex，插件可一步安装该服务和 teletype-support 技能。请参阅 Claude Code、Codex 和 Cursor 插件。

本地运行。 macOS 或 Windows 上的 Claude Desktop 用户可以从项目的发布页面下载 .mcpb 文件，打开后按提示输入 Teletype Public API 令牌。若要从源代码运行，请使用 npm ci && npm run build，然后将 MCP 客户端指向 node /absolute/path/to/dist/index.js --stdio，并在其环境中设置 TELETYPE_API_TOKEN。

对于其他客户端，请使用 Node.js 20.19+、22.13+ 或 24.x，以及 Teletype Public API 令牌。你也可以手动将此服务添加到 Claude Desktop 的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "teletype": {
      "command": "npx",
      "args": ["-y", "teletype-mcp-server", "--stdio"],
      "env": { "TELETYPE_API_TOKEN": "your-teletype-public-api-token" }
    }
  }
}

重启客户端，并让它列出 Teletype 工具。该服务支持 2025 initialize 握手和 MCP 2026-07-28。你可以在不联系 Teletype 的情况下检查本地设置：

TELETYPE_API_TOKEN=your-token npx -y teletype-mcp-server doctor --stdio

对于 Cursor、Zed 和其他 MCP 客户端，请使用相同的命令、参数和环境变量。

对于 Cursor、支持 Copilot 的 VS Code、Codex、Claude Code、OpenCode、Antigravity CLI 和其他受支持的客户端，请参阅 MCP 客户端。示例涵盖托管 HTTP 和本地 stdio 连接。单独的 OpenAI 兼容端点为可选项，仅供 eval:model 使用。

对于 Claude Code 和 Codex，有一些插件可以一步安装该服务和 teletype-support 技能，并支持斜杠命令。请参阅 Claude Code、Codex 和 Cursor 插件。

工具

这 17 个工具分为以下工具集：conversations、messaging、admin 和 meta。你可以注册所有工具（默认），通过 --toolsets 将服务限制为选定的工具集，或通过 --read-only 以只读模式运行。工具参考 记录了每个参数。

• find_conversations：按状态、渠道、渠道类型（channel_type）、客户、标签、操作员、类别、搜索查询和分页（page）查找对话。
• list_clients：分页列出客户，或按电话号码查找客户，不会更改数据。
• find_messages：列出项目消息，或逐页查看较早的消息文本。当 has_more 为 true 时继续。
• lookup_client_profile：返回包含自定义字段、备注和近期对话的客户资料。
• read_conversation_thread：默认只读消息和链接，不会更改数据。mark_seen: true 会将对话标记为已读，并且需要 confirm: true。include_sessions: true 会添加会话历史记录，session_id 用于选择会话详情，include_group_clients: true 会添加群聊参与者。
• read_client_history：一次调用即可读取客户近期对话，最多读取五个对话及每个对话的一部分消息（dialogs_limit、messages_per_dialog）。回复前可用它收集多个对话中的上下文。
• send_reply_to_client：回复现有对话、通过 /channel/send-message 发起新对话（支持 auto_close: true），或通过 /dialog/create 创建不含消息的对话（create_dialog_only: true）。
• create_dialog_by_phone：按电话号码创建或查找对话，但不发送消息。需要 confirm: true，并支持 dry_run。
• send_whatsapp_template：在 24 小时窗口之外，向现有的 WhatsApp Edna 对话发送经批准的 WABA 模板。模板 ID 来自项目导入的 WABA 模板，而非快捷回复列表。
• manage_sent_message：编辑、删除或重新发送操作员消息。
• annotate_client_record：更新客户身份信息（name、phone、email、additional_payload、force_additional_payload）、标签、备注、删除备注（delete_note_id）、自定义字段或对话类别。
• resolve_conversation：关闭对话、将其重新分配给操作员（或通过 assign_operator: "auto" 自动分配）、保持对话打开（close: false），或将打开的对话标记为已答复（mark_answered: true）或未答复（mark_unanswered: true）。
• list_workspace_metadata：列出渠道（带有 channel_type 和 only_active 筛选条件）、标签、类别、模板、模板文件夹（template_directories）、操作员组和操作员。
• get_project_status：返回 Teletype 项目的计费信息、操作员可用情况和技术状态。
• manage_operator_group：添加或移除群组成员（add_member、remove_member），添加或移除群组渠道（add_channel、remove_channel），设置主管角色（set_supervisor），并配置渠道对话可见性（set_channel_visibility）。
• configure_project_webhook：通过 /project/update-public-api 设置目标 webhook URL 和已启用的活动事件。
• get_capabilities：返回服务当前启用的工具映射（项目名称和域名、只读模式、启用的工具集、已注册的工具）。始终可用。

对于未答复的工作，使用 find_conversations 并设置 status: "unanswered"。要查看渠道清单，使用 list_workspace_metadata 并设置 resource: "channels"。要检查渠道和 Public API 的运行状况，使用 get_project_status 并设置 aspect: "technical"。这些筛选条件可避免获取无关数据，以及受限的 all 列表。关闭对话时，除非用户指定了类别，否则省略 category。如果用户指定了类别，请先从 resource: "categories" 获取其确切名称。类别未知时，调用会在进行任何更改前停止。 更改数据的工具需要设置 confirm: true。此标志可减少意外调用。MCP 客户端仍必须处理授权和用户同意。send_reply_to_client 和 send_whatsapp_template 支持设置 dry_run: true，以预览目标和消息而不发送。create_dialog_by_phone 支持设置 dry_run: true，以预览目标和可能产生的副作用，而不创建或分配对话。试运行不需要 confirm。

每个工具都会发布一个 outputSchema。简短的 content 文本提供主要结果和链接。完整结果位于 structuredContent 中，服务端会根据架构检查该内容。部分写入会返回错误，并列出已执行的操作和失败项。写入操作在超时、取消或架构错误后重试前，请检查远程状态。

Public API 响应解码器接受额外字段。它们会检查读取、写入和状态报告所用的响应字段。必需字段不可用时，工具会报错，但不会停止 MCP 服务。

提示词

该服务提供以下支持提示词：

• triage-inbox：按紧急程度和优先级对尚未回复的入站对话进行分流。
• draft-reply：根据对话历史和语气起草客户回复。
• client-summary：总结客户资料、过往问题和待处理事项。
• escalate-issue：为工程团队或高级支持人员生成结构化升级问题材料。
• shift-handover：生成支持班次交接报告，涵盖积压队列、渠道状态和团队可用情况。

资源与模板

静态资源

• teletype://project/status：当前项目状态、渠道状态和余额。
• teletype://workspace/metadata：工作区渠道、操作员、群组、标签和类别。
• teletype://dialogs/unanswered：当前尚未回复的客户对话队列，附带直接链接。

资源模板

• teletype://dialogs/{dialogId}：按对话 ID 获取特定对话的完整消息历史。
• teletype://clients/{clientId}：按客户 ID 获取客户资料、标签和备注。

Claude Code、Codex 和 Cursor 插件

该仓库包含 Claude Code、Codex 和 Cursor 的市场目录。plugin/ 目录包含 .claude-plugin/plugin.json 和 .cursor-plugin/plugin.json、可移植的 Agent Plugins 清单 plugin.json 和 mcp.json、共享的支持技能，以及命令。配置和数据访问方法请参阅插件 README。

Claude Code

该插件捆绑了托管 MCP 服务（https://mcp.teletype.app/mcp，通过插件敏感配置字段提供 X-Teletype-Api-Token 标头进行身份验证）、包含支持工作流和安全规则的 teletype-support 技能，以及与服务端 MCP 提示词对应的五个斜杠命令：/triage-inbox、/draft-reply、/client-summary、/escalate-issue、/shift-handover。

/plugin marketplace add Teletype-App/teletype-mcp-server
/plugin install teletype@teletype-mcp-server

启用插件时，请在 Teletype Public API token 字段中输入令牌。此必需的敏感 userConfig 字段会将值存储在 Claude 的安全凭据存储中，并提供 HTTP 标头。请使用支持 userConfig 的最新 Claude Code 版本。技能包含工具描述无法容纳的多步骤规范：分流顺序、对含糊不清的发送操作先进行试运行，以及关闭对话前查询类别。没有使用斜杠命令时，它会在支持任务中触发。这五种工作流也以 MCP 提示词的形式提供给支持显示提示词的客户端。命令则适用于不显示提示词的会话。

Cursor

原生 Cursor 清单会连接到托管服务，并包含共享技能和命令。通过市场安装时，请在 Plugins → Configure 下设置 TELETYPE_API_TOKEN。若要不使用插件直接连接，请参阅 Cursor 设置指南。

Codex

在启动 Codex 前，在 shell 中导出 TELETYPE_API_TOKEN。捆绑的 stdio 服务会从 Codex 进程继承此变量。

codex plugin marketplace add Teletype-App/teletype-mcp-server

然后在 Codex 中运行 /plugins，安装 teletype，并启动新会话。该插件会添加技能和本地 stdio 服务（Agent Plugins 规范不允许在 HTTP 标头中展开变量，因此无法在插件中附带每位用户的令牌）。若要改为将 Codex 连接到托管端点，请将其添加到 ~/.codex/config.toml：

[mcp_servers.teletype]
url = "https://mcp.teletype.app/mcp"
env_http_headers = { "X-Teletype-Api-Token" = "TELETYPE_API_TOKEN" }

Codex 也会读取未通过插件安装的技能：仓库中的 .agents/skills，或用户目录下的 ~/.agents/skills。

其他 Agent

使用 Skills CLI 安装支持技能：

npx skills add Teletype-App/teletype-mcp-server --skill teletype-support

根据提示选择 Agent 和安装范围。此命令会安装工作流说明。请通过客户端指南单独连接 MCP 服务。

该技能使用开放的 Agent Skills 格式，OpenCode、Cursor、Gemini CLI、GitHub Copilot、Goose 等均支持此格式。npm 包包含该技能，因此常规安装后：

mkdir -p ~/.agents/skills
cp -r node_modules/teletype-mcp-server/plugin/skills/teletype-support ~/.agents/skills/

CLI 用法

服务接受 CLI 标志和环境变量：

teletype-mcp-server --help
# Options:
#   -s, --stdio       Use stdio transport
#   --http            Use Streamable HTTP transport (default)
#   -p, --port <num>  Port for HTTP transport (default: 4311)
#   --host <ip>       Host for HTTP transport (default: 127.0.0.1)
#   -v, --version     Show version
#   -h, --help        Show help

--read-only 和 --toolsets <names>（以逗号分隔的 conversations,messaging,admin,meta）会筛选服务注册的工具，筛选发生在任何客户端连接之前。get_capabilities 始终保持注册状态，并报告当前启用的映射。

要求和本地安装

• 打包的 CLI 需要 Node.js 20.19+、22.13+ 或 24.x。
• 需要从项目设置中获取 Teletype Public API 令牌。

相同的 Node.js 版本也支持本地 npm start、npm run dev 和 npm run eval:model 脚本。

npm ci
npm run build
cp .env.example .env

stdio 传输

本地个人 MCP 客户端请使用 stdio。进程会从其环境中读取令牌。默认情况下，attachment_path 不启用文件上传。若要启用，请设置 ENABLE_LOCAL_UPLOADS=true，并在 TELETYPE_ALLOWED_FILE_ROOTS 中列出允许的目录。请使用其他本地用户无法写入的目录。

本地构建配置：

{
  "mcpServers": {
    "teletype": {
      "command": "node",
      "args": ["/absolute/path/to/teletype-mcp-server/dist/index.js", "--stdio"],
      "env": { "TELETYPE_API_TOKEN": "..." }
    }
  }
}

在本地运行：

TRANSPORT=stdio TELETYPE_API_TOKEN=... npm start

Streamable HTTP 传输

托管服务 https://mcp.teletype.app 使用此端点。以下配置用于可自托管部署。

/mcp 端点和 stdio 传输均支持 2025 initialize 握手和 MCP 2026-07-28 server/discover。两者使用相同的工具定义。

端点：POST /mcp。每次请求都必须在此标头中发送 Teletype API 令牌：

X-Teletype-Api-Token: <token>

请勿在 Authorization 中发送 Teletype 项目令牌。远程访问请使用 HTTPS。任何拥有项目令牌的人都可以通过 MCP 服务访问其数据，但需遵守部署限制。

公共托管端点 https://mcp.teletype.app/mcp 已禁用 OAuth。请使用 X-Teletype-Api-Token 中的项目令牌进行连接。自托管代码包含可选的 OAuth，默认禁用，可通过单独配置启用。

TRANSPORT=http HOST=127.0.0.1 PORT=4311 npm start

HTTP 端点：

方法	路径	用途
GET	/	俄语和英语落地页
GET	/assets/*	落地页脚本、样式、徽标和字体
POST	/mcp	无状态 Streamable HTTP MCP
GET	/healthz	健康检查

每个 HTTP 请求都会获得独立的 MCP Server 和传输对，因此并发租户不会共享响应或上下文。服务会全局限制并发请求数，并按令牌限制请求数。达到限制时，服务会返回 429，并附带 Retry-After。HTTP 传输无法读取本地文件。

Docker

该镜像以非特权用户身份运行，默认监听 4311 端口：

docker build -t teletype-mcp-server .
docker run --rm -p 127.0.0.1:4311:4311 \
  -e PUBLIC_BASE_URL=http://127.0.0.1:4311 \
  teletype-mcp-server

对于公共域名，请在 PUBLIC_BASE_URL 中设置其源，并在反向代理处终止 HTTPS。

对于通过 stdio 启动容器的 MCP 客户端，请构建 stdio 目标，并从私有环境中传递令牌。使用 -i 保持标准输入打开，并省略 -t，以免干扰 MCP 消息：

docker build --target stdio -t teletype-mcp-stdio .
docker run --rm -i -e TELETYPE_API_TOKEN teletype-mcp-stdio

stdio 目标以相同的非特权用户身份运行，不会公开 HTTP 端口，也不会使用 HTTP 健康检查。设置 TELETYPE_MCP_READ_ONLY=true 可禁用写入工具。

配置

变量	默认值
TRANSPORT	http
HOST / PORT	127.0.0.1 / 4311
PUBLIC_BASE_URL	http://127.0.0.1:4311
ALLOWED_ORIGINS	额外的逗号分隔源
OAUTH_ENABLED	false
OAUTH_DB_PATH	启用 OAuth 时使用的持久化 SQLite 路径
OAUTH_ENCRYPTION_KEY	启用 OAuth 时使用的私有 64 字符十六进制密钥
TELETYPE_API_TOKEN	stdio 模式必需
TELETYPE_API_BASE	https://api.teletype.app/public/api/v1
TELETYPE_PROJECT_URL	teletype.app
TELETYPE_MCP_LOCALE	en（俄语文本使用 ru）
TELETYPE_MCP_READ_ONLY	true 时注销写入工具
TELETYPE_MCP_TOOLSETS	要注册的逗号分隔工具集
REQUEST_TIMEOUT_MS	15000
MAX_RESPONSE_BYTES	5000000
MAX_UPLOAD_BYTES	20000000
MAX_CONCURRENT_REQUESTS	32
MAX_CONCURRENT_PER_TOKEN	4
ENABLE_LOCAL_UPLOADS	false
TELETYPE_ALLOWED_FILE_ROOTS	允许访问的逗号分隔目录

PUBLIC_BASE_URL 和 ALLOWED_ORIGINS 中的每一项都必须是没有路径、查询或片段的源。每当客户端发送 Origin 标头时，服务都会验证该值。

TELETYPE_MCP_LOCALE 设置 MCP 指令、工具描述、提示词、提示信息和服务端生成的错误所使用的语言。它适用于整个服务进程，包括所有 HTTP 客户端。如需俄语文本，请在 MCP 服务环境中将其设为 ru。工具名称、参数名称和 structuredContent 字段保持不变。Teletype 返回的客户数据和错误详情保留其原始语言。服务不会根据主机操作系统或 API 令牌推断区域设置。

故障排除

• 客户端无法连接：使用你的令牌运行 doctor --stdio，然后检查客户端传输设置。
• stdio transport requires TELETYPE_API_TOKEN：将令牌添加到客户端的服务环境中。doctor 只检查本地配置，不会验证令牌是否有效。
• 客户端的工具列表中缺少工具：运行 doctor --stdio 并检查其中的 Mode 和 Toolsets 行，或调用 get_capabilities。--read-only 和 --toolsets 会在注册时隐藏工具。
• Teletype 返回 HTTP 401 或 403：检查 Teletype 项目设置中的令牌。
• 写入操作超时或被取消：再次发送前，请检查会话或项目状态。

开发

npm run dev
npm run dev:stdio
npm run check:fast
npm run check
npm run test:mutation
npm run mcp:smoke
npm run package:smoke
npm run bundle:mcpb
npm run mcp:conformance

mcp:smoke 使用 SDK 客户端通过 HTTP 和 stdio 检查 2025 和 2026-07-28 握手。测试还会检查 HTTP 令牌隔离，并拒绝会破坏其 outputSchema 的工具结果。

package:smoke 会将 npm 压缩包安装到临时目录，并检查其 CLI、导出内容、两个协议版本和 eval 测试夹具。mcp:conformance 会使用本地服务和虚假的 Teletype API，运行独立 MCP 一致性测试套件中的五个简短场景。这两个命令都不会连接 Teletype 项目。

bundle:mcpb 会创建 artifacts/teletype-mcp-server-v<version>.mcpb，验证其清单，并通过 MCP stdio 检查打包后的服务。它不会连接 Teletype。

模型兼容性评测

要通过终端 Agent 运行评测，请将其连接到离线评测测试夹具。Agent 会使用 MCP 工具处理虚假的 Teletype 数据，并可通过 eval_grade_case 请求单独的结果、首次尝试、答案和安全指标。无需模型 API 端点。

评测结果涵盖每个终端客户端的 21 个完整任务和九个工具选择案例，并列出令牌数、耗时和预估的 API 等效令牌成本。

可选的 eval:model 命令会通过兼容 OpenAI 的聊天补全端点运行相同的检查。它会启动本地虚假的 Teletype API 和 MCP 服务，无需真实的项目令牌或客户数据。

设置一个提供兼容 OpenAI 的 POST /chat/completions 的端点：

cp .env.eval.example .env.eval
# Set EVAL_MODEL_BASE_URL, EVAL_MODEL_NAME, and EVAL_MODEL_API_KEY if needed.
npm run eval:model > eval-report.json

要简要检查工具描述，请运行 npm run eval:selection > selection-report.json。它会向所配置的模型发送九个合成请求，并且只检查选择的第一个工具。不会运行任何 Teletype 工具。若选择错误或缺少选择，命令会以代码 2 退出。此检查不会衡量 Agent 是否完成任务。

评测会检查：

• 工具选择。
• 必需参数和运行时验证。
• 只读场景中没有写入调用。
• 发送或关闭之前进行确认。
• 最终答案中的关键结果事实。

默认运行 21 个场景。EVAL_CASES 用于选择子集，EVAL_THRESHOLD 用于设置通过分数。通过时退出代码为 0，分数低于阈值时为 2，配置或运行时错误时为 1。JSON 报告输出到 stdout，诊断信息输出到 stderr。评测会将场景文本和虚假的 API 响应发送到所配置的模型端点。

报告还包括结果、首次尝试、答案和安全率。每个场景都从一个全新的虚假项目开始。单次 Agent 运行中进行的更正计入最终结果，但不会改变首次尝试指标。

npm run check:fast 会运行格式检查、lint、类型检查和测试。npm run check 还会运行 Knip、覆盖率阈值、针对请求隔离和限制的 100% 变异分数门槛、构建，以及使用 Publint 和 Are the Types Wrong 进行的包检查。

npm run test:mutation 会运行完整的变异测试套件，分数下限为 33%，并将报告写入 reports/mutation/。该命令耗时较长，不属于 npm run check 的一部分。

漏洞报告请参阅 SECURITY.md，贡献指南请参阅 CONTRIBUTING.md。本项目采用 MIT 许可证。

支持与隐私

• Teletype 帮助中心
• 报告服务问题
• Teletype 隐私政策