English Français العربية

io.github.handset-hq/handset

السجل الرسمي الوسائط والتصميم

A business phone system for AI agents: send texts, place calls, read transcripts, buy numbers.

الشيفرة المصدرية الموقع التوثيق

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

NPM package @handset/mcp
Claude Code 
claude mcp add handset -e 'HANDSET_API_KEY=<your handset_api_key>' -e 'HANDSET_ALLOW_LIVE=<HANDSET_ALLOW_LIVE>' -- npx -y @handset/mcp@0.1.1
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "handset": {
            "command": "npx",
            "args": [
                "-y",
                "@handset/mcp@0.1.1"
            ],
            "env": {
                "HANDSET_API_KEY": "<your handset_api_key>",
                "HANDSET_ALLOW_LIVE": "<HANDSET_ALLOW_LIVE>"
            }
        }
    }
}

متغيرات البيئة

  • 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_LIVE Set to 1 to permit a live-mode key (the agent can then text and call real people at real cost).

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. Handset UI
  2. What's in the registry
  3. Architecture
  4. Development
  5. Requirements
  6. Roadmap
  7. License

Handset UI

Texting inside your product, in an afternoon.

Open-source React components for embedded messaging, built on the Handset API. Distributed the shadcn way: the CLI copies the source into your repo, styled with your Tailwind tokens, yours to change.

# 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

Set HANDSET_API_KEY in your env, wire resolveTenantId() in the generated route to your session, and render it:

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

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

What's in the registry

ItemWhat it is
@handset/messagingTwo-pane texting surface — inbox + thread, responsive to mobile
@handset/inboxConversation list: previews, relative times, STOP badges, infinite scroll
@handset/threadMessage history: delivery states, opt-out handling, wired composer
@handset/composerDraft box with live SMS segment counting and unicode detection
@handset/next-routesNext.js proxy route — your API key never reaches the browser

Architecture

Two layers, like shadcn-on-Radix:

  • @handset/react (npm, versioned) — headless hooks: useConversations, useThread, useComposer, plus segment math and a tiny client. Logic we maintain; bring your own UI if you prefer.
  • The registry (apps/www/registry) — the visual components, copied into your project as source.

Components never hold API keys. They call proxy routes in your backend (added by @handset/next-routes); your server holds the Handset key and your existing session auth decides which tenant each signed-in user sees. The Handset API handles the rest — numbers, delivery, threading, 10DLC compliance, STOP/HELP.

Development

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

The docs site serves a mock Handset API (apps/www/app/api/handset) so the demo works with zero setup.

Requirements

  • React 18+ (components target React 19 / Tailwind v4 / shadcn CLI ≥ 3)
  • A Handset account for real traffic — the demo runs on mock data without one

Roadmap

See ROADMAP.md — shipped components, what's next (call summaries, MMS attachments, more framework proxies), and non-goals. Issues with real use cases move items up the list.

License

MIT © Handset HQ, Inc.

الأسئلة الشائعة

ما هو io.github.handset-hq/handset؟

A business phone system for AI agents: send texts, place calls, read transcripts, buy numbers.

كيف أثبّت io.github.handset-hq/handset؟

يعمل على جهازك. في Claude Code: claude mcp add handset -e 'HANDSET_API_KEY=<your handset_api_key>' -e 'HANDSET_ALLOW_LIVE=<HANDSET_ALLOW_LIVE>' -- npx -y @handset/mcp@0.1.1. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.handset-hq/handset إلى مفتاح API؟

نعم. يتطلب HANDSET_API_KEY، وتضبطها في إعداداته.

هل io.github.handset-hq/handset مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.handset-hq/handset؟

ينشره handset-hq. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.