{"_id":"@addai/entity-chat-mcp","_rev":"4-e48e28753706a8783bfdf0b46a9d473d","name":"@addai/entity-chat-mcp","dist-tags":{"latest":"0.5.1"},"versions":{"0.3.0":{"name":"@addai/entity-chat-mcp","version":"0.3.0","license":"MIT","_id":"@addai/entity-chat-mcp@0.3.0","maintainers":[{"name":"addai","email":"npm@add.ai"}],"bin":{"entity-chat-mcp":"dist/index.js"},"dist":{"shasum":"4a73a5006616d1252aadbedc1838e03230b8c487","tarball":"https://registry.npmjs.org/@addai/entity-chat-mcp/-/entity-chat-mcp-0.3.0.tgz","fileCount":7,"integrity":"sha512-50n0n+cEnEnEMVSsaHI9TjCCCMc7DVNVMggmwFufxs4hIxXeKvSgS+6Yy198h9mCeBk+2YcDh2yKWudA86LvSw==","signatures":[{"sig":"MEUCIQDRi00//a2/k8wBeMBjnqhpba/Nxu6inwcd/Q0Rp4cFKQIgFjnhgWdAI/DwVox3a2GT0cMDA8B4gTI06aWqJP7dG+0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":19116},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist"},"_npmUser":{"name":"addai","email":"npm@add.ai"},"_npmVersion":"10.9.2","description":"MCP server that lets a +Ai entity send DMs, messages, widget cards and question cards in +Ai Chat.","directories":{},"_nodeVersion":"22.17.1","dependencies":{"zod":"^3.24.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/entity-chat-mcp_0.3.0_1785234023644_0.06065047714396821","host":"s3://npm-registry-packages-npm-production"}},"0.4.0":{"name":"@addai/entity-chat-mcp","version":"0.4.0","license":"MIT","_id":"@addai/entity-chat-mcp@0.4.0","maintainers":[{"name":"addai","email":"npm@add.ai"}],"bin":{"entity-chat-mcp":"dist/index.js"},"dist":{"shasum":"0504e0771f8e550c40e42b4fca913fc254dc6146","tarball":"https://registry.npmjs.org/@addai/entity-chat-mcp/-/entity-chat-mcp-0.4.0.tgz","fileCount":10,"integrity":"sha512-lj8eNJq/tb6wqKuJdD0G5DGmV/K17Y4mckMaTtQcIZ5MgWONLd7GTFt/HXVGGGYoSilJ3dKLqYRK3o0e2a7RDA==","signatures":[{"sig":"MEUCIQCQjm4rpvZSmr9KRI1q09RNUSWMASewqZxKA6S85hpziQIgEf9Pvo7iWPE0yiCl9WsfoBaaKc6hpk79Txq32CmkQ1c=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":32978},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"gitHead":"250f23284a7c7b050cc81d51c25c30bf6d8a1dc7","scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"addai","email":"npm@add.ai"},"_npmVersion":"10.9.2","description":"MCP server that lets a +Ai entity send DMs, messages, widget cards, question cards and chat styling in +Ai Chat.","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/entity-chat-mcp_0.4.0_1785510887466_0.5452912325386956","host":"s3://npm-registry-packages-npm-production"}},"0.5.0":{"name":"@addai/entity-chat-mcp","version":"0.5.0","license":"MIT","_id":"@addai/entity-chat-mcp@0.5.0","maintainers":[{"name":"addai","email":"npm@add.ai"}],"bin":{"entity-chat-mcp":"dist/index.js"},"dist":{"shasum":"17d90cb6e8cad387ac90ac3a2a759f6ccf609119","tarball":"https://registry.npmjs.org/@addai/entity-chat-mcp/-/entity-chat-mcp-0.5.0.tgz","fileCount":10,"integrity":"sha512-ONz1dFGq0PxroeQkBNca2uKWYqTXn1jn7eBWVOqf3hF/Z1bdbaQsonAWa/ZiEVKCEOBQUCwPt3wUE0tCj0rM5A==","signatures":[{"sig":"MEYCIQCqpCfg3q3LIYus8lpMurbinppISRKSBO9JjljHE3fpCwIhAI5EfrVOQzvG2eE/GpSX/4vKW+gI708JsgGtioknQpjJ","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":35613},"main":"dist/index.js","type":"module","types":"./dist/index.d.ts","engines":{"node":">=18"},"scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"_npmUser":{"name":"addai","email":"npm@add.ai"},"_npmVersion":"10.9.2","description":"MCP server that lets a +Ai entity send DMs, messages, widget cards, question cards and chat styling in +Ai Chat.","directories":{},"_nodeVersion":"22.14.0","dependencies":{"zod":"^3.24.0","@modelcontextprotocol/sdk":"^1.0.0"},"publishConfig":{"access":"public"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.6.0","@types/node":"^20.0.0"},"_npmOperationalInternal":{"tmp":"tmp/entity-chat-mcp_0.5.0_1785836747125_0.04987167301129336","host":"s3://npm-registry-packages-npm-production"}},"0.5.1":{"name":"@addai/entity-chat-mcp","version":"0.5.1","description":"MCP server that lets a +Ai entity send DMs, messages, widget cards, question cards and chat styling in +Ai Chat.","license":"MIT","type":"module","main":"dist/index.js","bin":{"entity-chat-mcp":"dist/index.js"},"publishConfig":{"access":"public"},"scripts":{"build":"tsc -p tsconfig.json","clean":"rm -rf dist","prepublishOnly":"npm run clean && npm run build"},"engines":{"node":">=18"},"dependencies":{"@modelcontextprotocol/sdk":"^1.0.0","zod":"^3.24.0"},"devDependencies":{"@types/node":"^20.0.0","typescript":"^5.6.0"},"_id":"@addai/entity-chat-mcp@0.5.1","types":"./dist/index.d.ts","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-GvIMdPwwtqukCdwW1lYrd48rfiag7LMMoqSzUl61NLhV8pugusOEfn0KHAm0IQDjLCRvAXufNzTXXgJ2ET2Gpw==","shasum":"5e56380b8d72e703132a45798760ade426e93a96","tarball":"https://registry.npmjs.org/@addai/entity-chat-mcp/-/entity-chat-mcp-0.5.1.tgz","fileCount":10,"unpackedSize":36067,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCoI7gKUSYhLZceXjn+6FZ4Hj3lyTn8Ez3VorjcB/F0LAIgcoFHgxYe1IPAe9a0b/saVK2a1FELWkHqeglv2dft86s="}]},"_npmUser":{"name":"addai","email":"npm@add.ai"},"directories":{},"maintainers":[{"name":"addai","email":"npm@add.ai"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/entity-chat-mcp_0.5.1_1785838683935_0.4672588970145315"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-28T10:20:23.528Z","modified":"2026-08-04T10:18:04.249Z","0.3.0":"2026-07-28T10:20:23.788Z","0.4.0":"2026-07-31T15:14:47.629Z","0.5.0":"2026-08-04T09:45:47.259Z","0.5.1":"2026-08-04T10:18:04.085Z"},"license":"MIT","description":"MCP server that lets a +Ai entity send DMs, messages, widget cards, question cards and chat styling in +Ai Chat.","maintainers":[{"name":"addai","email":"npm@add.ai"}],"readme":"# entity-chat-mcp — widget-cards patch\n\nAdds four tools to the published **`@tomaddai/entity-chat-mcp`** package so entities can\npost and update **data-filled inline widget cards** in +Ai Chat (e.g. \"Bob\" the trainer\nposting a stats card). Everything server-side is already deployed; this patch is only the\nthin MCP tool layer, which lives in the (external) npm package.\n\n## Server side (two migrations, split by intent)\n\n- **`20260710000000_entity_chat_widgets.sql`** — the RPCs the tools call\n  (`entity_widgets_list`, `entity_chat_send_widget`, `entity_chat_send_widget_dm`,\n  `entity_widget_update`). Purely additive/inert: brand-new functions, invisible to\n  running entities. **Safe to apply any time.**\n- **`20260710000100_entity_chat_widgets_enable.sql`** — appends the widget tools to the\n  `entity-chat-mcp` marketplace `tools` metadata + `system_prompt_injection`, and adds the\n  `chat-widget-cards` skill. This is what *tells* every chat-enabled entity about the tools.\n  **Apply this at the same time you publish the package below** — not before, or entities\n  are told about tools they can't call yet.\n\nBoth migrations are append-only and idempotent. Once the package is published **and** the\nenable migration is applied, **any entity that already has the Chat capability gains the\nwidget tools on its next run** — no new provision step, no Studio UI change.\n\n## What this patch is\n\nTwo files to drop into the `@tomaddai/entity-chat-mcp` source:\n\n- `src/tools/widgets.ts` — `registerWidgetTools(server, client)`; the 4 tools, written in the\n  same `server.tool(name, desc, zodShape, handler)` style as the package's existing tools.\n- `src/entity-rpc-client.ts` — a reference `EntityRpcClient` (only needed if the package\n  doesn't already expose an RPC helper that injects `p_entity_key`).\n\n## Wiring (2 steps)\n\n**1. Register the tools** where the server is built (next to `send_dm` / `send_message`):\n\n```ts\nimport { registerWidgetTools } from './tools/widgets.js';\n\n// Option A — the package already has an RPC helper that injects p_entity_key:\nregisterWidgetTools(server, existingRpcClient); // must satisfy { rpc(fn, args) }\n\n// Option B — standalone:\nimport { EntityRpcClient } from './entity-rpc-client.js';\nregisterWidgetTools(server, new EntityRpcClient(process.env.ENTITY_API_KEY!));\n```\n\n`registerWidgetTools`'s `client` just needs `rpc<T>(fn, args): Promise<T>` that POSTs to\n`/rest/v1/rpc/<fn>` and injects `p_entity_key`. The package's existing `send_dm`/`send_message`\ntools already do exactly this against `entity_chat_send_dm`/`entity_chat_send` — reuse that path\nand Option A is a one-liner.\n\n**2. Publish.** Bump the version and `npm publish`. The entity runtime installs\n`@tomaddai/entity-chat-mcp@latest` via `npx`, so entities pick it up on the next session.\n\n## Env\n\nSame as the package already uses: `ENTITY_API_KEY` (per-entity, injected by the runtime),\nplus `SUPABASE_URL` / `SUPABASE_ANON_KEY` for the RPC endpoint (the RPCs are granted to `anon`,\nauthenticated by `p_entity_key`).\n\n## Tool → RPC → return\n\n| Tool | RPC | Returns |\n|------|-----|---------|\n| `list_widgets({ search?, include_public? })` | `entity_widgets_list` | `[{ widget_id, name, slug, description, icon, visibility }]` |\n| `send_widget({ conversation_id, widget_id, widget_state, content?, reply_to_id?, host_id? })` | `entity_chat_send_widget` | `{ sent, message_id, conversation_id, widget_id, widget_name, host_id, widget_instance_id }` |\n| `send_widget_dm({ search, widget_id, widget_state, content? })` | `entity_chat_send_widget_dm` | `{ ...send_widget, target_profile_id, target_name }` |\n| `get_widget_state({ widget_id, host_id })` | `entity_widget_state` | `{ found, widget_id, host_id, widget_instance_id, updated_at, public_state }` |\n| `update_widget({ host_id, widget_id, widget_state, merge? })` | `entity_widget_update` | `{ updated, merged, widget_id, host_id, widget_instance_id }` |\n\n## How a card ends up showing data\n\n`send_widget` seeds the widget's per-instance `public_state` in `widget_instances_v2` at\n`(widget_id, host_type='chat', host_id='menubar-'||<attachment host_id>)`, **then** sends a\n`widget_v2` attachment. When the chat renders the message it opens\n`tools.add.ai/embed/<widget_id>?host=chat&hid=menubar-<host_id>`; `widgets_v2_open_instance`\nfinds the seeded instance and the widget paints with the data on first open. `update_widget`\nre-seeds and fires a `realtime.send` on `widget_instance:<id>` so already-open cards refresh live.\n\n## Refreshing a card without destroying what people did (0.5.0)\n\nThe widget's `public_state` is shared ground: the `widget-action` edge function writes user\ninteractions (ticking an item off, claiming a row) into the same column an entity refresh\nwrites. Before 0.5.0 `update_widget` was an unconditional replace with no way to read the\nstate back, so every refresh silently wiped those interactions — and entities that noticed\nresorted to shelling `curl` at the REST API to try to preserve them.\n\n- `get_widget_state` returns the live `public_state`.\n- `update_widget({ ..., merge: true })` shallow-merges over it: keys you supply win, keys you\n  omit survive. Use it for any card people can touch. The merge is deliberately **not**\n  recursive — a deep merge would make it impossible to shrink a nested array, which refreshes\n  routinely need to do.\n\n`host_id` is also canonical now. Both post and update used to prepend `menubar-`\nunconditionally, so feeding back a host_id read from the API addressed a *second* instance\n(prod accumulated hosts as deep as `menubar-menubar-menubar-chat-msg-…`). The prefix is\napplied idempotently, so either form resolves to the same card.\n\n## Notes / current limits\n\n- The widget must be **published** and **workspace or public** visibility (personal widgets\n  won't render for other members). `list_widgets` already filters to usable ones.\n- `widget_state` must match the shape the widget's view reads — unknown keys are ignored,\n  missing keys render blank. The `chat-widget-cards` skill explains this to entities.\n- Widgets shared *into* the workspace via workspace-grants aren't listed yet (only owned +\n  public). Easy follow-up if needed.\n\n## Question cards (second patch — 2026-07-16)\n\n`src/tools/questions.ts` adds `registerQuestionTools(server, client)` with two tools —\n`ask_question` / `ask_question_dm` — letting entities ask structured, tappable questions\n(single/multi/dropdown/slider/scale/fork/text). Server side:\n\n- `20260716120000_entity_chat_questions.sql` — the RPCs (`entity_chat_send_question`,\n  `entity_chat_send_question_dm`, `chatflows_answer_question`). Inert; safe to apply any time.\n- `20260716120100_entity_chat_questions_enable.sql` — tool metadata + prompt injection.\n  **Apply only when publishing the package with these tools.**\n\nWire-up is identical to the widget tools: `registerQuestionTools(server, existingRpcClient)`\nnext to `registerWidgetTools`, bump, `npm publish`.\n","readmeFilename":"README.md"}