Tappy

Tappy

The open-source living document for humans, agents, live data, code, and provenance.

Connect sources once, then turn AI work into durable artifacts: editable prose, tables, charts, code, React blocks, source context, comments, work items, and git-like history inside one collaborative workspace.

Quick Start | Demo | Features | Agents & MCP | Providers | Self-hosting | Releases

---

Why Tappy?

Most AI tools still end in chat: a response, a pasted snippet, a one-off script, a screenshot. Tappy is built for the next step: a living document where agents and people work against the same sources, code, data, and history.

Tappy launches first as Tappy Docs, but the underlying model is broader than a document editor. It is a set of primitives for agent-native work:

Artifacts, not chat scrollbackProse, tables, SQL, charts, KPIs, Python, images, and React blocks live inside the document and remain editable. Live data and provenanceConnect sources once, then keep source chips, generated queries, code, outputs, and actor history attached to the artifact. Humans and agents as peersFirst-class identity, presence, comments, work items, assignments, and actor attribution for every meaningful change. Bring your own agentsConnect Claude Code, Codex, Cursor, Hermes, OpenClaw, OpenCode, ChatGPT-compatible MCP clients, or your own tool harness. Bring your own modelsUse OpenAI, Anthropic, Google, Ollama, OpenAI-compatible gateways, or the provider keys your self-host already trusts. Reviewable by constructionCheckpoints, actor sessions, diffs, chronicle events, and revert-forward keep agent work inspectable instead of magical. OSS-firstMIT licensed, Docker self-hostable, MCP-native, no telemetry by default (analytics and error monitoring activate only if you set your own PostHog/Sentry keys, are consent-gated, and are fully documented), and designed so contributors can extend the primitive layer.

Product Screenshots

Agent-native workspace The public surface shows the core model: people and agents working inside the same editable document.

Docs for humans and agents Setup, MCP, editor, provider, and deployment guides are available as browser pages and Markdown for agents.

Demo

▶ Watch the launch demo (50s) — agents enter the workspace, create structured work, update blocks, and leave a visible trail.

Editor clips

Command paletteAdd work, sources, and blocks without leaving the doc. Inline blocksInsert structured artifacts directly in the writing flow. Inline AI editsRewrite a selected block in place with source-aware instructions.

Add block flowUse the editor chrome to add blocks where the work belongs. Project setupCreate a workspace and start from a real document surface. Self-hosted by defaultRun the same OSS app locally or with Docker, then connect your own models, sources, and agents.

Quick Start

Local development

Requirements: Node.js 22, pnpm 10 via Corepack, and Git.

git clone https://github.com/MustafaK99/tappy.git
cd tappy

nvm install 22
nvm use 22
corepack enable
corepack prepare pnpm@10.34.5 --activate
pnpm install

pnpm setup:env
pnpm dev

> The first pnpm install is heavy: it downloads the Python sandbox runtimes and compiles native modules (sharp, better-sqlite3). Expect a few minutes on a cold cache.

Open http://localhost:3000.

The local profile is intentionally simple: SQLite, single-user auth, in-memory queues, local disk storage, and Pyodide for Python. Do not expose the local profile to the public internet.

Self-host with Docker

One command — bootstraps .env with fresh secrets, then brings up the full stack:

./run.sh up

Or run the steps explicitly:

pnpm setup:env
docker compose up -d
docker inspect -f '{{.State.Health.Status}}' "$(docker compose ps -q app)"

The Compose stack runs the app, Postgres, Redis, migrations, and the index worker. For HTTPS, OAuth, storage, sandbox, and production provider setup, read [docs/self-hosting.md](docs/self-hosting.md) and [docs/deployment.md](docs/deployment.md).

Connect an agent

Give a human or agent this URL from your running Tappy host:

https:///api/mcp/install

Local self-host:

http://localhost:3000/api/mcp/install

The install manifest is safe to share. It contains the MCP endpoint, OAuth discovery URLs, supported client hints, and agent-readable setup prompts. It does not contain secrets or bearer tokens.

Features

| Surface | What is in Tappy today | | --- | --- | | Documents | Live prose, comments, work items, presence, source-backed sections, and structured blocks. | | Blocks | Tables, charts, KPIs, SQL, Python, images, and interactive React artifacts. | | Sources | Uploaded files, web pages and extraction prompts, REST APIs, Google Sheets, Google Drive, OneDrive, PostgreSQL, Snowflake, Stripe Sigma, HubSpot, Composio, and outbound MCP. | | Agents | Built-in executor harness plus external MCP/self-pickup agents with scoped identities. | | Collaboration | Human and agent cursors, co-typing, comments, assignments, shared panels, and visible activity. | | History | Actor-attributed checkpoints, session snapshots, chronicle events, view-time diffs, and revert-forward. | | Runtime | Next.js app, custom Node server, Automerge CRDT state, Drizzle persistence, workers, queues, and sandboxed execution. | | Setup | Local profile for evaluation, Docker Compose for self-hosting, and documented provider/OAuth paths. |

Architecture

Tappy is a Next.js application with a custom Node server for WebSocket collaboration, Automerge document state, Drizzle-backed Postgres/SQLite persistence, Redis/Postgres/in-memory queues, sandboxed execution, and an MCP server built into the app.

Core primitives:

• Blocks: typed workspace objects for prose, data, code, visuals, and live UI.
• Sources: files, web, APIs, databases, connected apps, and outbound tools bound to work.
• Actors: people, built-in agents, and external agents with identity, scopes, and attribution.
• Commands: block operations, co-typed prose/config, source queries, work-board flows, and history reads.
• History: snapshots as document commits, chronicle events as the activity feed, and revert-forward for recovery.

Read more in [ARCHITECTURE.md](ARCHITECTURE.md), [docs/code-tour.md](docs/code-tour.md), and [docs/editor-primitives.md](docs/editor-primitives.md).

Agents and MCP

Tappy exposes the workspace as a Streamable HTTP MCP server:

https:///api/mcp

Typical first moves for an MCP client:

1. initialize and read the server instructions.
2. Read tappy://guide/overview and tappy://mcp/capabilities.
3. Query documents, sources, and blocks.
4. Edit with block operations or co-typed prose/config tools.
5. Use work-board tools to claim, run, and submit assigned work.

Supported setup paths include generic MCP clients plus client-shaped hints for Claude Code, Codex, Cursor, Hermes, OpenClaw, OpenCode, and custom harnesses. See [docs/mcp-clients.md](docs/mcp-clients.md) and the full [docs/mcp-api-catalog.md](docs/mcp-api-catalog.md).

Providers and Sources

Tappy is designed for teams that already have model, data, and infrastructure preferences.

| Category | Options | | --- | --- | | Model providers | OpenAI, Anthropic, Google, Ollama, OpenAI-compatible gateways, and self-hosted compatible endpoints. | | Auth | better-auth (OSS, default) or Clerk (opt-in hosted, AUTH=clerk) behind a shared [adapter](src/lib/adapters/index.ts); local single-user profile for evaluation; scoped external-agent tokens. | | Data sources | Web pages, webpage scraping/extraction prompts, uploads, REST APIs, Google Sheets, Google Drive, OneDrive, PostgreSQL, Snowflake, Stripe Sigma, HubSpot. | | Tool sources | Composio and outbound MCP servers. | | Python execution | Pyodide locally, with E2B/Microsandbox/local CPython options documented for operators. | | Storage/queues | Local disk/SQLite for dev, Postgres/Redis/object storage paths for self-hosting. |

Provider setup lives in [docs/self-hosting.md](docs/self-hosting.md), [docs/deployment.md](docs/deployment.md), and [docs/integration-model.md](docs/integration-model.md).

Development

source ~/.nvm/nvm.sh
nvm use 22
NODE_OPTIONS=--max-old-space-size=6144 pnpm verify

Useful commands:

pnpm dev                    # local app server
pnpm test                   # vitest
pnpm build                  # production build
docker compose build app    # production container
docker compose up -d app    # run the self-host stack

pnpm verify runs typecheck, lint, and changed tests. Use pnpm verify:full for broad launch or release verification.

Documentation

• [README.md](README.md#quick-start) - shortest path from clone to running app
• [docs/self-hosting.md](docs/self-hosting.md) - Docker, production env, OAuth, storage, and operations
• [docs/deployment.md](docs/deployment.md) - deploy targets and production checklist
• [docs/editor-primitives.md](docs/editor-primitives.md) - how Tappy's editor model fits together
• [docs/mcp-clients.md](docs/mcp-clients.md) - agent/client setup
• [docs/mcp-api-catalog.md](docs/mcp-api-catalog.md) - MCP tools, resources, prompts, and scopes
• [docs/integration-model.md](docs/integration-model.md) - native sources and provider extension model
• [docs/releasing.md](docs/releasing.md) - versioning, release, GHCR, and GitHub release flow
• [docs/analytics-and-error-monitoring.md](docs/analytics-and-error-monitoring.md) - exactly what Tappy sends to PostHog/Sentry (off by default) and how to control it
• [SECURITY.md](SECURITY.md) - vulnerability reporting
• [CONTRIBUTING.md](CONTRIBUTING.md) - contribution workflow

Roadmap

Tappy is an OSS release candidate. Use [docs/releasing.md](docs/releasing.md) for release mechanics and CHANGELOG.md for historical launch notes.

Near-term direction:

• Public v0.1 OSS release and tagged GitHub/GHCR artifacts.
• More provider and source plugins.
• Hidden/live forks for agent work on parallel document states.
• More artifact surfaces built on the same actor/source/block/history primitives.
• A reusable history layer for attributed, reversible, agent-edited artifacts.

Acknowledgements

> "He who does not thank the people is not thankful to Allah." > — Prophet Muhammad ﷺ, Sunan Abi Dawud 4811

Tappy stands on the work of countless open-source maintainers, researchers, builders, and projects that made this possible. I am deeply grateful to everyone whose work, ideas, libraries, tools, and examples helped shape this project.

This project is my attempt to build on that foundation and contribute something useful back.

Tappy especially benefits from the maintainers and communities behind Node.js, pnpm, TypeScript, React, Next.js, Tailwind CSS, PostgreSQL, SQLite, Redis, Valkey, Docker, the Model Context Protocol, Automerge, ProseMirror, CodeMirror, DuckDB, Pyodide, Radix UI, Lucide, Vite, Vitest, ESLint, Drizzle, and the wider web platform.

Direct open-source packages Tappy uses

Runtime dependencies:

@ai-sdk/anthropic, @ai-sdk/openai, @ai-sdk/provider, @ai-sdk/react, @anthropic-ai/sdk, @automerge/automerge, @automerge/automerge-codemirror, @automerge/automerge-repo, @automerge/automerge-repo-network-messagechannel, @automerge/automerge-repo-network-websocket, @automerge/automerge-repo-react-hooks, @automerge/automerge-repo-storage-indexeddb, @automerge/prosemirror, @aws-sdk/client-s3, @aws-sdk/client-ses, @aws-sdk/s3-request-presigner, @clerk/backend, @clerk/nextjs, @codemirror/autocomplete, @codemirror/commands, @codemirror/lang-javascript, @codemirror/lang-python, @codemirror/lang-sql, @codemirror/state, @codemirror/view, @composio/core, @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, @duckdb/node-api, @e2b/code-interpreter, @iconify/icons-logos, @iconify/react, @iconify/types, @modelcontextprotocol/sdk, @mozilla/readability, @openrouter/ai-sdk-provider, @radix-ui/react-dialog, @radix-ui/react-dropdown-menu, @radix-ui/react-label, @radix-ui/react-popover, @radix-ui/react-scroll-area, @radix-ui/react-select, @radix-ui/react-separator, @radix-ui/react-slot, @radix-ui/react-switch, @radix-ui/react-tabs, @radix-ui/react-tooltip, @tabler/icons-react, @tanstack/query-sync-storage-persister, @tanstack/react-query, @tanstack/react-query-persist-client, @tanstack/react-virtual, @upstash/redis, ai, axios, better-auth, better-sqlite3, chart.js, class-variance-authority, clsx, codemirror, date-fns, dotenv, drizzle-orm, e2b, echarts, exa-js, framer-motion, googleapis, html-react-parser, ioredis, isomorphic-ws, jsdom, lucide-react, mammoth, next, nodemailer, openai, pdf-parse, pg, postcss-nested, postgres, pptxgenjs, prismjs, prosemirror-commands, prosemirror-history, prosemirror-inputrules, prosemirror-keymap, prosemirror-model, prosemirror-schema-list, prosemirror-state, prosemirror-transform, prosemirror-view, pyodide, react, react-chartjs-2, react-dom, react-dropzone, react-icons, react-markdown, react-uploader, rehype-raw, rehype-sanitize, remark-gfm, sanitize-html, sharp, snowflake-sdk, sonner, stripe, svix, tailwind-merge, tailwindcss-animate, typescript, unzipper, uuid, ws, xlsx, zod, zustand.

Development and build dependencies:

@eslint/eslintrc, @tailwindcss/typography, @testing-library/jest-dom, @testing-library/react, @types/better-sqlite3, @types/jsdom, @types/node, @types/nodemailer, @types/pdf-parse, @types/pg, @types/react, @types/react-dom, @types/sanitize-html, @types/unzipper, @types/ws, @typescript-eslint/eslint-plugin, @typescript-eslint/parser, autoprefixer, babel-plugin-react-compiler, drizzle-kit, esbuild, eslint, eslint-config-next, js-yaml, postcss, tailwindcss, ts-node, tsx, vite, vitest.

Tappy also depends on many transitive packages maintained by the broader OSS ecosystem; the full dependency graph is recorded in [pnpm-lock.yaml](pnpm-lock.yaml).

> xlsx is intentionally pinned to the SheetJS CDN tarball (https://cdn.sheetjs.com/...) rather than an npm range, because SheetJS no longer publishes to the npm registry. This is expected, not a supply-chain anomaly.

License

Tappy is MIT licensed. See [LICENSE](LICENSE).

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: MustafaK99
• Source: MustafaK99/tappy
• License: MIT
• Homepage: https://tappy.sh

Install and usage instructions live in the source repository linked above.