Skip to content
Back to search

app-assistant

Let users run your app by chatting: an AI assistant that does what your UI does through your MCP server, each change after they confirm, with results as MCP Apps cards. FastAPI + LangGraph, in production in 3 apps.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/mikedutuandu--app-assistant/badge.svg)](/listings/mikedutuandu--app-assistant)

HTML

<a href="/listings/mikedutuandu--app-assistant"><img src="/api/listings/mikedutuandu--app-assistant/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 180 lines
  1. # App Assistant
  2. [![CI](https://github.com/mikedutuandu/app-assistant/actions/workflows/ci.yml/badge.svg)](https://github.com/mikedutuandu/app-assistant/actions/workflows/ci.yml)
  3. [![npm](https://img.shields.io/npm/v/@app-assistant/host)](https://www.npmjs.com/package/@app-assistant/host)
  4. [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
  5. Let your users run your app by chatting. What they would do by clicking through your UI, they can ask for instead:
  6. the assistant reads their real data and does it for them through your own **MCP server**, **each change only after
  7. they tap Confirm** (human-in-the-loop), and shows what it read as your own UI: an **MCP Apps** card, the same one
  8. Claude and ChatGPT draw. Your UI stays; the chat is a second way to use all of it.
  9. It can also write for your users (posts, changelogs, emails) from what they actually did, in their voice, **never
  10. inventing a number**, and they can attach screenshots, PDFs and voice notes. Your app decides where a draft goes; the
  11. bot never publishes anything by itself.
  12. It is a **LangGraph** agent in production: a FastAPI service with Postgres checkpoints, any S3-compatible bucket, and
  13. models through OpenRouter, running three real apps (below). Your app talks to it through a small, versioned contract:
  14. one token, four HTTPS endpoints, and a JSON "pack" that describes what the assistant is for. New to LangGraph? The
  15. [architecture guide](docs/ARCHITECTURE.md) walks through the graph, its state and checkpoints step by step.
  16. ## Used by
  17. Three apps run on it today, each a different way to use it:
  18. | App | What the assistant does there | Uses |
  19. |---|---|---|
  20. | [HookPlaybook](https://hookplaybook.com) (X growth) | **Ask HookPlaybook**, on its own page: writes X posts and threads from what the user did, in their voice; reads their posts, results and schedule, and changes or schedules a post after Confirm | `writes`, actions, cards, its own chat page (`botFetch`, `AppView`); paid from the user's credits |
  21. | [StreakPlan](https://streakplan.com) (daily Shorts) | **Ask StreakPlan**: plans videos, writes scripts, starts AI edits after Confirm | actions only (`writes: []`), a video card, the chat window; paid from the user's credit balance |
  22. | [SiteSeed](https://siteseed.ai) (SEO articles) | **Ask SiteSeed**: reads sites, the plan, articles and Google's numbers; plans, edits and publishes after Confirm | actions only, ten cards, the chat window; paid from the user's tokens |
  23. In each, every model call the bot makes is charged to the user through the app's `/charge`, at the app's own price.
  24. ## How it works
  25. The code, step by step and for someone new to LangGraph: **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)**.
  26. ```
  27. your page ── chat window (script tag or React) ──► app-assistant ──► OpenRouter (chat + writer models)
  28. │ │
  29. └─ your server signs a short-lived token └─ calls your app: /context /drafts /material /charge
  30. ```
  31. 1. Your server signs a short-lived token (HS256, up to 1 hour) for the signed-in user's workspace.
  32. 2. The chat window talks to the bot with that token; the bot sends the same token to your app's four endpoints: read
  33. context (the user's voice, recent posts), save a draft, keep facts the user told it, report what a message cost.
  34. 3. A chat model holds the conversation and keeps what the user says as facts; a writer model drafts from those facts
  35. only. Every number and claim in a draft is checked against what the user gave or a file showed: a draft that fails
  36. is rewritten once, then dropped.
  37. 4. A draft reaches your app only when the user taps to save it. There is no tool that publishes.
  38. 5. Optional actions: your pack points at your own MCP server. Tools marked read-only run at once; any other tool is
  39. shown as a card and runs only when the user taps Confirm ([docs/integration.md](docs/integration.md#actions-optional-your-mcp-server)).
  40. 6. Optional cards: a read tool can name a page of your own (MCP Apps), and the chat draws its result with it instead
  41. of text. The same card shows in Claude and ChatGPT ([docs/integration.md](docs/integration.md#cards-show-a-read-as-your-own-ui-mcp-apps)).
  42. ## Try it in two minutes (Docker)
  43. No cloud account needed: the bot, Postgres 16 and files on local disk.
  44. ```bash
  45. git clone https://github.com/mikedutuandu/app-assistant && cd app-assistant
  46. export OPENROUTER_API_KEY=sk-or-... # needed for real replies
  47. docker compose up --build
  48. ```
  49. Open <http://localhost:8000/demo> for **Shipnote**, a demo app built on the same contract (`apps/demo.yaml`,
  50. `src/assistant/demo/`). `http://localhost:8000/health` answers `{"ok": true}`. Your data stays in Docker volumes until
  51. `docker compose down -v`.
  52. ## Add it to your app
  53. There are two parts, and you need both: **the bot**, a service you run (it holds the conversation and calls the
  54. models), and **your app**, which tells the bot who the user is and keeps the drafts. The npm package is the second
  55. part; it does not replace the bot. The whole contract is one page: **[docs/integration.md](docs/integration.md)**
  56. (version 1).
  57. ### Part 1: run the bot
  58. Deploy it (the button below, or Docker on your own server) and tell it about your app with three variables:
  59. ```bash
  60. APP_ID=shipnote # your app's id, used in the tokens and the chat window
  61. APP_SITE=https://shipnote.app # where your app serves its pack
  62. APP_SECRET=... # openssl rand -hex 32; your app keeps the same value
  63. ```
  64. The bot only talks to apps its owner names this way, so a stranger's app can't spend your model credit. One bot can
  65. serve several apps: list them in `apps/registry.yaml` or `APPS` instead ([docs/integration.md](docs/integration.md#the-registry-entry-the-bot-owner-adds-it)).
  66. ### Part 2: connect your app
  67. 1. **Serve the pack and the four endpoints.** The pack is JSON at `{site}/.well-known/app-assistant.json`; the
  68. endpoints are `POST {api_base}/context`, `/drafts`, `/material` and `/charge`. In a JavaScript app,
  69. [`@app-assistant/host`](sdk/js/README.md) does both from four functions you write:
  70. ```bash
  71. npm install @app-assistant/host
  72. ```
  73. In any other language, follow the contract; its scenarios (`tests/contract/scenarios.json`) check your app.
  74. 2. **Put the chat window on a page**, with a session route that signs the token for the signed-in user (with
  75. `APP_SECRET`):
  76. ```tsx
  77. <AssistantChat app="shipnote" botUrl="https://bot.example.com" sessionUrl="/api/assistant/session" />
  78. ```
  79. or one script tag:
  80. ```html
  81. <script src="https://bot.example.com/widget.js" data-app="shipnote" data-session-url="/api/assistant/session"></script>
  82. ```
  83. A pack file kept on the bot, and apps reached over MCP instead of HTTPS: [docs/packs.md](docs/packs.md).
  84. ## Deploy
  85. [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fmikedutuandu%2Fapp-assistant&project-name=app-assistant&repository-name=app-assistant&env=OPENROUTER_API_KEY,PUBLIC_BASE_URL,APP_ID,APP_SITE,APP_SECRET,DEMO_SESSION_SECRET,CRON_SECRET,S3_ENDPOINT,S3_REGION,S3_BUCKET,S3_ACCESS_KEY,S3_SECRET_KEY&envDescription=OpenRouter%20key,%20the%20bot%27s%20public%20URL,%20your%20app%27s%20id%20and%20site,%20three%20secrets%20%28openssl%20rand%20-hex%2032%29,%20and%20a%20bucket%20for%20files&envLink=https%3A%2F%2Fgithub.com%2Fmikedutuandu%2Fapp-assistant%2Fblob%2Fmain%2Fdocs%2FDEPLOY.md)
  86. - **Vercel:** the button clones the repo into your account. Add Neon from the Vercel Marketplace for Postgres, and an
  87. S3-compatible bucket for files (Neon Object Storage, Cloudflare R2, S3).
  88. - **Your own server:** the Docker setup above, with your own secrets and domain.
  89. Step by step, with the checks to run after: **[docs/DEPLOY.md](docs/DEPLOY.md)**. Every variable is explained in
  90. [`.env.example`](.env.example). As the bot's owner you set ceilings over every app: a message's spend cap
  91. (`MAX_MESSAGE_USD`), the models an app may use (`ALLOWED_MODELS`) and one app's daily spend (`MAX_APP_DAILY_USD`).
  92. ## Run locally without Docker
  93. You need Python 3.12 with [uv](https://docs.astral.sh/uv/) and a Postgres.
  94. ```bash
  95. docker compose -f docker-compose.test.yml up -d # a Postgres on localhost:54329 (user, password and db: test)
  96. uv sync
  97. cp .env.example .env # then fill it in
  98. uv run uvicorn assistant.main:create_app --factory --reload
  99. ```
  100. Set `DATABASE_URL=postgresql://test:test@localhost:54329/test`, then open <http://localhost:8000/demo> (the
  101. `.env.example` demo secret works on localhost only; set your own with `openssl rand -hex 32` before going online). Files go on local disk (`DATA_DIR`) unless you set `S3_*`. An app whose secret
  102. variable is unset is off (the log says which); with none set, the server does not start.
  103. ## Develop
  104. ```bash
  105. TEST_DATABASE_URL=postgresql://test:test@localhost:54329/test uv run pytest
  106. uv run ruff check . && uv run ruff format --check .
  107. (cd widget && npm ci && npm test) # the chat window behind the script tag
  108. (cd sdk/js && npm ci && npm test) # @app-assistant/host
  109. ```
  110. The built `src/assistant/static/widget.js` is committed, so the server needs no Node. After changing `widget/` or the
  111. package's card code (`sdk/js/src/view`, which the widget bundles), run `npm run build` in `widget/`: CI fails when the
  112. committed build is stale. [CONTRIBUTING.md](CONTRIBUTING.md) has the rest.
  113. **Conversation tests.** `tests/conversations/cases.yaml` holds about 20 real chats ("hi", "just write it", a screenshot
  114. with a number, Vietnamese, "say we have 10k users"...), each with notes a judge model decides and hard rules checked in
  115. code (at most one question per reply, the language, every number in a draft given by the user). Recordings in
  116. `tests/conversations/recorded/` replay in CI with no key; re-record after changing a prompt, a model or a case:
  117. ```bash
  118. OPENROUTER_API_KEY=... uv run python scripts/converse_eval.py --live # real models, then the judge
  119. OPENROUTER_API_KEY=... uv run python scripts/converse_eval.py --live --record # and save the cases that pass
  120. uv run python scripts/converse_eval.py # replay the recordings, no key
  121. ```
  122. ## Layout
  123. | Path | What it is |
  124. |---|---|
  125. | `src/assistant/` | the service: chat API, LangGraph agent, tools, file intake, storage, the demo app |
  126. | `apps/` | `registry.yaml`: the apps that serve their own pack (HookPlaybook, StreakPlan, SiteSeed); a pack kept on the bot (`demo.yaml`, the demo app's) |
  127. | `widget/` | the chat window behind the script tag |
  128. | `sdk/js/` | `@app-assistant/host`: the contract for JavaScript apps, and the React chat window |
  129. | `docs/` | the contract, its JSON schema, deployment, packs |
  130. | `tests/contract/` | language-neutral scenarios any app can be checked against |
  131. ## License
  132. [MIT](LICENSE). Security issues: please report them privately, as [SECURITY.md](SECURITY.md) says.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.