mcpField
H
handset

handset

本地服务
docs.handset.dev通信协作19 周前更新
代码仓库访问官网

关于 handset

handset 提供开源 React 组件和 hooks，可通过 Handset API 将短信功能嵌入产品。组件以可编辑源码复制到项目中，后端代理则避免 API 密钥暴露给客户端。

主要功能

  1. 01响应式收件箱和消息线程组件
  2. 02支持短信分段与 Unicode 检测的编辑器
  3. 03会话、线程和撰写用 React hooks
  4. 04用于 API 请求的 Next.js 代理路由
  5. 05使用项目 Tailwind tokens 的源码组件

适用场景

  1. 01在产品中添加短信收件箱和消息线程
  2. 02用 React hooks 构建自定义消息界面
  3. 03将 Handset API 密钥保留在后端
  4. 04撰写短信时查看分段数量

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置
{
  "mcpServers": {
    "handset-hq-handset": {
      "command": "npx",
      "args": [
        "-y",
        "@handset/mcp"
      ],
      "env": {
        "HANDSET_API_KEY": "<HANDSET_API_KEY>",
        "HANDSET_ALLOW_LIVE": "<HANDSET_ALLOW_LIVE>"
      }
    }
  }
}
启动命令npx -y @handset/mcp
需要配置的环境变量
HANDSET_API_KEY密钥Handset API key. Use a test-mode key (hs_test_…) — simulated carrier, free. Live keys are refused unless HANDSET_ALLOW_LIVE=1.
HANDSET_ALLOW_LIVESet to 1 to permit a live-mode key (the agent can then text and call real people at real cost).

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包
npm@handset/mcp0.1.1

工具

15

收录的工具列表 · 更新于 2 周前

参数类型必填说明
limitinteger否

详细介绍

手持设备 UI

一个下午，即可在你的产品中实现短信功能。

用于嵌入式消息功能的开源 React 组件，基于 Handset API 构建。以 shadcn 的方式分发：CLI 会将源代码复制到你的仓库中，使用你的 Tailwind 设计令牌进行样式设置，你可以自行修改。

# 1. Point the shadcn CLI at the Handset registry
npx shadcn@latest registry add @handset=https://ui.handset.dev/r/{name}.json

# 2. Install a complete texting surface + the server proxy route
npx shadcn@latest add @handset/messaging @handset/next-routes

在环境中设置 HANDSET_API_KEY，将生成的路由中的 resolveTenantId() 连接到你的会话，然后渲染它：

import { HandsetProvider } from "@handset/react";
import { Messaging } from "@/components/handset/messaging";

export default function MessagesPage() {
  return (
    <HandsetProvider>
      <div className="h-[600px]">
        <Messaging />
      </div>
    </HandsetProvider>
  );
}

注册表中包含的内容

项目内容
@handset/messaging双栏短信界面——收件箱 + 对话线程，适配移动设备
@handset/inbox对话列表：预览、相对时间、STOP 徽章、无限滚动
@handset/thread消息历史：送达状态、退订处理、已连接的消息编辑框
@handset/composer草稿框，支持实时 SMS 分段计数和 Unicode 检测
@handset/next-routesNext.js 代理路由——你的 API 密钥永远不会发送到浏览器

架构

两层结构，类似 shadcn-on-Radix：

  • @handset/react（npm，版本化）——无头钩子： useConversations、useThread、useComposer，以及分段计算和一个精简的 客户端。我们负责维护逻辑；如果你更喜欢，也可以自行构建 UI。
  • 注册表（apps/www/registry）——视觉 组件，会以源代码的形式复制到你的项目中。

组件不会持有 API 密钥。它们会调用你的后端中的代理路由（由 @handset/next-routes 添加）；你的服务器持有 Handset 密钥，并由你现有的会话身份验证决定每位已登录用户可以看到哪个租户。其余工作交由 Handset API 处理——号码、送达、对话线程、10DLC 合规性、STOP/HELP。

开发

pnpm install
pnpm --filter @handset/react build   # hooks package
pnpm dev                             # docs site + live demo at localhost:3000
pnpm registry:build                  # compile registry.json → public/r/*.json

文档站点提供了一个模拟 Handset API（apps/www/app/api/handset），因此演示无需任何设置即可运行。

要求

  • React 18+（组件面向 React 19 / Tailwind v4 / shadcn CLI ≥ 3）
  • 如需实际流量，需要一个 Handset 账户——没有账户也可以通过模拟数据运行演示

路线图

参见 ROADMAP.md——已发布的组件、后续计划（通话摘要、MMS 附件、更多框架代理），以及非目标。有实际用例的问题会推动相关事项在列表中提前。

许可证

MIT © Handset HQ, Inc.

评论

支持 Markdown

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。