{"id":49215797,"url":"https://github.com/brainblend-ai/tesseron","last_synced_at":"2026-05-23T09:02:05.287Z","repository":{"id":352933165,"uuid":"1217201645","full_name":"BrainBlend-AI/tesseron","owner":"BrainBlend-AI","description":"Expose typed web-app actions to MCP-compatible AI agents over WebSocket. TypeScript SDK + matching MCP gateway.","archived":false,"fork":false,"pushed_at":"2026-04-27T08:28:00.000Z","size":1959,"stargazers_count":12,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-27T09:25:11.540Z","etag":null,"topics":["ai-agents","claude-code","mcp","model-context-protocol","sdk","typescript","websocket"],"latest_commit_sha":null,"homepage":"https://brainblend-ai.github.io/tesseron/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/BrainBlend-AI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-21T16:41:13.000Z","updated_at":"2026-04-27T08:26:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/BrainBlend-AI/tesseron","commit_stats":null,"previous_names":["kennyvaneetvelde/tesseron"],"tags_count":105,"template":false,"template_full_name":null,"purl":"pkg:github/BrainBlend-AI/tesseron","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrainBlend-AI%2Ftesseron","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrainBlend-AI%2Ftesseron/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrainBlend-AI%2Ftesseron/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrainBlend-AI%2Ftesseron/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BrainBlend-AI","download_url":"https://codeload.github.com/BrainBlend-AI/tesseron/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BrainBlend-AI%2Ftesseron/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32375625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T09:24:15.638Z","status":"ssl_error","status_checked_at":"2026-04-28T09:24:15.071Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agents","claude-code","mcp","model-context-protocol","sdk","typescript","websocket"],"created_at":"2026-04-24T00:01:06.383Z","updated_at":"2026-05-23T09:02:05.281Z","avatar_url":"https://github.com/BrainBlend-AI.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./assets/logo/tesseron-smallcaps-dark.png\"\u003e\n  \u003cimg src=\"./assets/logo/tesseron-smallcaps-light.png\" alt=\"Tesseron\" width=\"520\"\u003e\n\u003c/picture\u003e\n\n### Typed live-app actions for MCP-compatible AI agents, over WebSocket.\n\n\u003cp\u003e\n  \u003ca href=\"https://github.com/BrainBlend-AI/tesseron/stargazers\"\u003e\u003cimg alt=\"GitHub stars\" src=\"https://img.shields.io/github/stars/BrainBlend-AI/tesseron?style=flat-square\u0026color=f59e0b\u0026logo=github\u0026labelColor=0b1220\"\u003e\u003c/a\u003e\n  \u003ca href=\"./LICENSE\"\u003e\u003cimg alt=\"License: BUSL-1.1\" src=\"https://img.shields.io/badge/License-BUSL--1.1-f59e0b?style=flat-square\u0026labelColor=0b1220\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://discord.gg/J3W9b5AZJR\"\u003e\u003cimg alt=\"Discord\" src=\"https://img.shields.io/badge/chat-on%20discord-7289DA?logo=discord\u0026style=flat-square\u0026labelColor=0b1220\"\u003e\u003c/a\u003e\n  \u003cimg alt=\"Protocol 1.0.0\" src=\"https://img.shields.io/badge/Protocol-1.0.0-f59e0b?style=flat-square\u0026labelColor=0b1220\"\u003e\n  \u003cimg alt=\"TypeScript\" src=\"https://img.shields.io/badge/TypeScript-5.7-3178c6?style=flat-square\u0026logo=typescript\u0026logoColor=white\u0026labelColor=0b1220\"\u003e\n  \u003cimg alt=\"Node 20+\" src=\"https://img.shields.io/badge/Node-%E2%89%A5%2020-339933?style=flat-square\u0026logo=node.js\u0026logoColor=white\u0026labelColor=0b1220\"\u003e\n  \u003cimg alt=\"Tests\" src=\"https://img.shields.io/badge/Tests-98%20passing-22c55e?style=flat-square\u0026labelColor=0b1220\"\u003e\n\u003c/p\u003e\n\n\u003cp\u003e\n  \u003ca href=\"https://brainblend-ai.github.io/tesseron/\"\u003e\u003cb\u003eDocs\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"./examples\"\u003e\u003cb\u003eExamples\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#install\"\u003e\u003cb\u003eInstall\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"#packages\"\u003e\u003cb\u003ePackages\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://discord.gg/J3W9b5AZJR\"\u003e\u003cb\u003eDiscord\u003c/b\u003e\u003c/a\u003e \u0026nbsp;·\u0026nbsp;\n  \u003ca href=\"https://github.com/BrainBlend-AI/tesseron/discussions\"\u003e\u003cb\u003eDiscussions\u003c/b\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003ca href=\"https://brainblendai.com/\"\u003e\u003cimg src=\"./assets/brainblend-ai/logo.svg\" width=\"22\" height=\"18\" align=\"center\" alt=\"BrainBlend AI\"\u003e\u003c/a\u003e \u003csub\u003eBuilt by \u003ca href=\"https://brainblendai.com/\"\u003e\u003cb\u003eBrainBlend AI\u003c/b\u003e\u003c/a\u003e\u003c/sub\u003e\n\n\u003c/div\u003e\n\n---\n\n**NEW: Join our community on Discord at [discord.gg/J3W9b5AZJR](https://discord.gg/J3W9b5AZJR) — protocol questions, feedback, and SDK-contribution chat all welcome.**\n\nLive applications (browser tabs, Electron/Tauri desktop apps, Node daemons, CLIs) declare actions with a Zod-style builder; agents (Claude Code, Claude Desktop, Cursor, Copilot, Codex, Cline, ...) call them as MCP tools. Your real handler runs against your real state. **No browser automation, no scraping, no Playwright.**\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./assets/diagrams/pieces-fit-together.png\" alt=\"USER prompts the agent; YOUR APP (browser or Node, using @tesseron/web or /server) opens a loopback WebSocket and announces itself; the MCP GATEWAY (@tesseron/mcp) discovers it via ~/.tesseron/instances/ and dials in; the gateway bridges to the MCP CLIENT (Claude Code, Codex, OpenCode, Pi, Cursor, Claude Desktop, ...) over stdio.\" width=\"900\"\u003e\n\u003c/p\u003e\n\n## Why Tesseron\n\n- **Typed actions, not scraped DOMs.** Declare with Zod or any [Standard Schema](https://standardschema.dev) validator; the handler is a plain function against your real state.\n- **Framework-agnostic.** Same API for vanilla TS, React, Svelte, Vue, and Node. Pick your stack.\n- **MCP-native.** Every action, resource, and capability maps to a standard MCP primitive. Users pick their agent.\n- **Click-to-connect.** Six-character claim code handshake. No API keys, no OAuth dance, no per-client configuration.\n- **First-class capabilities.** `ctx.confirm` for yes/no, `ctx.elicit` for schema-validated prompts, `ctx.sample` for agent LLM calls, `ctx.progress` for streaming updates, subscribable resources for live reads.\n- **Cross-client delivery.** First-class install paths for Claude Code, Codex, OpenCode, and Pi — each one a single command or short config snippet that wires the [MCP gateway](./packages/mcp) in. No bundled binary; the gateway is `npx -y @tesseron/mcp@\u003cversion\u003e` on demand.\n\n## Install\n\nTesseron has first-class install paths for four agent clients. Pick the one you use:\n\n### Claude Code\n\n```text\n/plugin marketplace add BrainBlend-AI/tesseron\n/plugin install tesseron@tesseron\n```\n\nInstalls the [`tesseron`](./plugin) Claude Code plugin. The MCP gateway and docs server are launched on demand via `npx`.\n\n### Codex CLI\n\n```bash\ncodex plugin marketplace add BrainBlend-AI/tesseron\n```\n\nCodex consumes the same plugin manifest as Claude Code, so the gateway, docs server, and skills come along automatically.\n\n### Pi\n\nPi has no built-in MCP support, but the community-maintained [`pi-mcp-adapter`](https://www.npmjs.com/package/pi-mcp-adapter) is the canonical bridge. Install it once:\n\n```bash\npi install npm:pi-mcp-adapter\n```\n\nThen add Tesseron to `.mcp.json` in your project root (or `~/.config/mcp/mcp.json` for a global install):\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"tesseron\": { \"command\": \"npx\", \"args\": [\"-y\", \"@tesseron/mcp@2.9.1\"] },\n    \"tesseron-docs\": { \"command\": \"npx\", \"args\": [\"-y\", \"@tesseron/docs-mcp@2.9.1\"] }\n  }\n}\n```\n\n`pi-mcp-adapter` discovers and exposes the Tesseron tools to Pi automatically. Use `\"directTools\": true` per server entry to surface each Tesseron action as a top-level Pi tool instead of going through the `mcp` proxy.\n\nTo pick up the skill bundle as well, point Pi's settings `skills` array at a clone of [`plugin/skills/`](./plugin/skills) — the same folder Claude Code / Codex use.\n\n### OpenCode\n\nOpenCode reads MCP servers from `opencode.json` rather than a plugin manifest. Save this as `.opencode/opencode.json` in your project root (or `~/.config/opencode/opencode.json` for global use):\n\n```jsonc\n{\n  \"$schema\": \"https://opencode.ai/config.json\",\n  \"mcp\": {\n    \"tesseron\": { \"type\": \"local\", \"command\": [\"npx\", \"-y\", \"@tesseron/mcp@2.9.1\"], \"enabled\": true },\n    \"tesseron-docs\": { \"type\": \"local\", \"command\": [\"npx\", \"-y\", \"@tesseron/docs-mcp@2.9.1\"], \"enabled\": true }\n  }\n}\n```\n\nTo also pick up the skill bundle, point OpenCode's `skills.paths` at a clone of [`plugin/skills/`](./plugin/skills) — see [`plugin/README.md`](./plugin/README.md#opencode) for the snippet.\n\n### Other MCP clients\n\nClaude Desktop, Cursor, VS Code Copilot, Cline, and any other MCP-compatible client work too — the gateway is plain stdio MCP. See the one-time setup in [`examples/README.md`](./examples/README.md#2-wire-the-mcp-gateway-into-your-mcp-client).\n\n### Then in your app\n\nDrop [`@tesseron/web`](./packages/web), [`@tesseron/server`](./packages/server), [`@tesseron/react`](./packages/react), [`@tesseron/svelte`](./packages/svelte), or [`@tesseron/vue`](./packages/vue) into your project, declare actions, and let the agent drive your real UI:\n\n```ts\nimport { tesseron } from '@tesseron/web';\nimport { z } from 'zod';\n\ntesseron.app({ id: 'todo_app', name: 'Todo App' });\n\ntesseron\n  .action('addTodo')\n  .input(z.object({ text: z.string().min(1) }))\n  .handler(({ text }) =\u003e {\n    state.todos.push({ id: newId(), text, done: false });\n    render();\n    return { ok: true };\n  });\n\nawait tesseron.connect();\n```\n\nSee [`examples/`](./examples) for working apps in vanilla TS, React, Svelte, Vue, Express, and plain Node.\n\n## Packages\n\n| Package | Purpose |\n|---|---|\n| [`@tesseron/core`](./packages/core) | Protocol types, action builder. Zero runtime deps beyond Standard Schema. |\n| [`@tesseron/web`](./packages/web) | Browser SDK. |\n| [`@tesseron/server`](./packages/server) | Node SDK. |\n| [`@tesseron/react`](./packages/react) | React hooks adapter. |\n| [`@tesseron/svelte`](./packages/svelte) | Svelte 5 adapter. |\n| [`@tesseron/vue`](./packages/vue) | Vue 3 adapter. |\n| [`@tesseron/vite`](./packages/vite) | Vite plugin: dev-server bridge for browser tabs to dial the gateway over the same origin as your app. |\n| [`@tesseron/mcp`](./packages/mcp) | MCP gateway server (`tesseron-mcp` CLI; launched by each client's install path via `npx`). |\n| [`@tesseron/docs-mcp`](./packages/docs-mcp) | MCP server that serves the Tesseron docs (`search_docs`, `read_doc`, `list_docs`) for chapter-and-verse spec lookups inside agent sessions. |\n| [`@tesseron/devtools`](./packages/devtools) | In-browser debug UI served by the MCP gateway *(private stub, not yet published)*. |\n| [`create-tesseron`](./packages/create-tesseron) | `npm create tesseron@latest` scaffolder *(private stub, not yet published)*. |\n\nThe Claude Code / Codex plugin lives at [`plugin/`](./plugin), exposed via the marketplace manifests at [`.claude-plugin/marketplace.json`](./.claude-plugin/marketplace.json) (Claude) and [`.agents/plugins/marketplace.json`](./.agents/plugins/marketplace.json) (Codex).\n\n## Client capability support\n\nTesseron's action context gives handlers four capabilities beyond plain tool invocation, each backed by an MCP primitive. Whether a given call actually fires depends on what the user's MCP client advertises:\n\n| SDK surface | MCP primitive |\n|---|---|\n| `tool(...)` (action invocation) | `tools` |\n| `resource(...)` (live reads, subscriptions) | `resources` (+ `resources.subscribe`) |\n| `ctx.sample(...)` | `sampling` |\n| `ctx.confirm(...)` / `ctx.elicit(...)` | `elicitation` |\n| `ctx.progress(...)` | `notifications/progress` (client must pass `_meta.progressToken` on `tools/call`) |\n\nFor the authoritative, continuously-updated list of which client supports which primitive, see the **[official MCP client compatibility matrix](https://modelcontextprotocol.io/clients)** — filter by `Sampling` or `Elicitation` to see how narrow the field still is. A few points worth knowing before you pick a capability:\n\n- **Tools** are universal — every MCP client can invoke your actions.\n- **Sampling** is the rarest. Claude Code, Claude Desktop, and Claude.ai do **not** expose it; today's support is concentrated in VS Code + GitHub Copilot, [goose](https://block.github.io/goose/), and [fast-agent](https://github.com/evalstate/fast-agent).\n- **Elicitation** (MCP 2025-06) landed in Claude Code (2.1.76, March 2026), Cursor, Codex, VS Code Copilot, goose, and fast-agent, but **not** Claude Desktop, Claude.ai, ChatGPT, Windsurf, or Zed.\n- When a capability is missing, Tesseron raises a typed error (`SamplingNotAvailableError`, `ElicitationNotAvailableError`) or collapses to the safe default (`ctx.confirm` returns `false`), so handlers can branch explicitly rather than silently misbehaving.\n\n## Status\n\n**v1.0** shipped April 2026; the SDK is at **v2.6** as of writing. The protocol is stable at [**1.0.0**](./docs/src/content/docs/protocol) and intentionally kept small: bidirectional JSON-RPC 2.0 over WebSocket, dynamic MCP tool registration, click-to-connect handshake, streaming progress, cancellation, sampling, confirmation, schema-validated elicitation, subscribable resources, session resume.\n\nPublished to npm: `@tesseron/{core,web,server,react,mcp,docs-mcp}` ship in lockstep at the same version (currently **2.7.0**). `@tesseron/{svelte,vue,vite}` version independently. The JS/TS SDKs are the reference implementation; the protocol spec is [CC BY 4.0](./docs/src/content/docs/protocol/LICENSE) so anyone can write a compatible client or server in any language.\n\nOn the roadmap: the devtools UI, a Streamable HTTP transport, a Python SDK, and bindings for desktop-native runtimes (Rust for Tauri, etc.).\n\n## Development\n\n```bash\npnpm install\npnpm typecheck\npnpm test                            # vitest across core + mcp\npnpm lint                            # biome\npnpm sync-plugin-version --check     # CI guard: plugin manifests + Pi pin + skill mirror in lockstep\n```\n\n## Contributing\n\nBug reports, protocol refinements, new framework adapters, and improvements to the reference implementation are welcome.\n\n- Read [`CONTRIBUTING.md`](./CONTRIBUTING.md) for the workflow.\n- Every commit must be **`Signed-off-by:`** under the [Developer Certificate of Origin](https://developercertificate.org/) — use `git commit -s`.\n- Open an issue first for anything larger than a small fix.\n\n## Star history\n\n\u003ca href=\"https://star-history.com/#BrainBlend-AI/tesseron\u0026Date\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/svg?repos=BrainBlend-AI/tesseron\u0026type=Date\u0026theme=dark\"\u003e\n    \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/svg?repos=BrainBlend-AI/tesseron\u0026type=Date\" width=\"720\"\u003e\n  \u003c/picture\u003e\n\u003c/a\u003e\n\n## License\n\n**Reference implementation** — [Business Source License 1.1](./LICENSE) (source-available). You may embed Tesseron in your own applications, use it internally, fork it, and redistribute it freely. You may **not** offer Tesseron or a substantial portion of it as a hosted or managed service to third parties. Each release auto-converts to Apache-2.0 four years after publication.\n\n**Protocol specification** — [CC BY 4.0](./docs/src/content/docs/protocol/LICENSE). A compatible implementation in any language, for any purpose including commercial, is explicitly encouraged.\n\nContributions are welcome under the [Developer Certificate of Origin](./CONTRIBUTING.md) — every commit must be `Signed-off-by`.\n\n---\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://brainblendai.com/\"\u003e\u003cimg src=\"./assets/brainblend-ai/logo.svg\" width=\"32\" height=\"27\" alt=\"BrainBlend AI\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n  Built and maintained by \u003ca href=\"https://brainblendai.com/\"\u003e\u003cb\u003eBrainBlend AI\u003c/b\u003e\u003c/a\u003e.\u003cbr\u003e\n  © 2026 Kenny Vaneetvelde.\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrainblend-ai%2Ftesseron","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbrainblend-ai%2Ftesseron","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbrainblend-ai%2Ftesseron/lists"}