EasyTopic MCP server

Also mirrored publicly at github.com/EB-CON-GmbH/easytopic-mcp-server for reuse outside this monorepo (one-way export via git subtree split, re-run manually after a significant change here — see Topic c6seMyvsgYKaQjEOdzt8).

Lets a Claude Code agent in any project pull its work from an EasyTopic Kanban board instead of a human typing prompts into the console: it picks up Topics in "ToDo", plans, asks questions via comments, waits for a human approval column, implements, and closes the ticket.

EasyTopic's data model: companies/{companyId}/projects/{projectId}/topics/{topicId} is the actual task/ticket, gated by participancy (a participantUids: string[] array on the Topic, not company employment) — see "Why sign in as a real Firebase Auth user" below for why that matters for this server specifically.

Standalone package (own package.json/tsconfig.json, no dependency on any other part of the EasyTopic app).

Why sign in as a real Firebase Auth user, not Admin SDK

firestore.rules requires changedBy == request.auth.uid on history writes, plus an exact participantUids array match against the live Topic. Only a genuine client-SDK sign-in satisfies that — so this server authenticates (signInWithEmailAndPassword) as a dedicated bot Firebase Auth account, onboarded exactly like a human teammate (Company employee + Project participant). That also means rules enforcement and Topic History bookkeeping work automatically, with zero extra code.

Comments are the one write this authenticated client does NOT make directly: firestore.rules' comments create rule is if false for every caller (rate-limiting reasons) — addComment() (src/topics.ts) instead calls the app's createTopicComment Cloud Function via client.functions, the same callable the app's own web UI uses. The onTopicCommentCreated notification fan-out still fires either way, since it triggers off the resulting Firestore write regardless of whether that write came from a direct client SDK call or a Cloud Function.

Related MCP server: vibeops

One-time EasyTopic setup (per target Company/Project — no app code changes)

All of this is done through the existing app UI (Workflow / Topic / Board Designer are already shipped):

1. Bot account — sign up through the normal app Sign-Up flow using an invite code for the target Company (e.g. email claude-bot@yourcompany.com). Store the password only in .secrets/ (new file, following this repo's existing convention) or your routine host's secret store — never in a committed .mcp.json.

2. Project participant, role admin (NOT member — real bug found 2026-07-17: Topic.participantUids is seeded at creation from the project's current admins only, and firestore.rules' Topic get/list rule is purely participantUids-array-based with no isProjectAdmin bypass, unlike update. A member bot never gets auto-included in new Topics and can't see old ones either — it would structurally never find any work). An existing Project admin adds the bot's uid as a participant with role: "admin", then fans out participantUids to every already-existing Topic/Board in the project (replicate useUpdateProjectParticipantRole's fan-out, src/hooks/useProjects.ts:272-334 — promoting alone only affects future Topics).

3. Workflow "Claude Automation" (Workflow Designer) — statuses, in this exact array order (board columns render in statuses array order, not by any separate sort field — closed MUST be last, not right after created where seedStatusesAndTransitions() puts it by default, or "Fertig"/"Closed" renders as the first visible column): created (fixed) → todo → planning → planned → approved → in_progress → done → closed (fixed). closed is deliberately the real reserved status key (not a custom "done"), so isCompleted/admin-only-reopen come for free — done is a separate, ordinary status just before it (the agent's own "I'm finished" signal; closed stays the human's exclusive final sign-off, see easytopic_transition_status's tool description). Forward transitions — place each beforeChecks on the transition that gates entry into the NEXT phase, not on the transition leaving that phase (a Topic must not be able to enter a phase it doesn't yet qualify for — getting this backwards was an actual bug in the first real setup). The live "Claude Automation" Workflow (verified against the real Firestore config, not just this original design doc) only actually needs two:

   • created → todo — beforeChecks: [descriptionRequired]. A Topic can't enter the queue at all without a prompt already written — otherwise a human could queue an empty Topic and the agent would waste a cycle "planning" against nothing.

   • planned → approved — beforeChecks: [requiredFieldsFilled] (gates on the plan field being non-empty) — a human must not be able to approve a Topic that has no plan on it, or the agent starts "In Progress" with nothing to execute. Otherwise human-driven only. The agent must never perform this transition itself — it's the human's sole approval step.

   • Every other forward transition (todo → planning, planning → planned, approved → in_progress, in_progress → done, done → closed) has no beforeChecks at all. Also add backward transitions with empty beforeChecks/afterActions — moving a card back must always be possible (e.g. a plan turns out wrong, or an approval was premature). The live setup isn't limited to one step back — it also has a few direct shortcuts to an earlier stage for convenience: todo → created, planning → todo, planned → planning, planned → todo, approved → planned, in_progress → approved, done → in_progress, done → todo, closed → todo, plus closed → created as the dedicated "Reopen" action.

4. TopicType "Claude Task" (Topic Designer) — workflowId set to the above Workflow, plus one multiline field key: "plan", label: "Plan", required: true (safe — required only gates the transitions above, not Topic creation/save).

5. BoardType (Board Designer) — references the Workflow, hiddenStatusKeys: ["created"].

6. Enable both in Project settings — add the new TopicType id to Project.settings.allowedTopicTypeIds and the new BoardType id to Project.settings.allowedBoardTypeIds (arrayUnion, don't overwrite — a Project may already have other allowed types). Both are empty by default; skipping this step means neither shows up in the app's own pickers even though the underlying Workflow/TopicType/BoardType exist. Any current Project participant may write Project.settings (it's an "ordinary field" per firestore.rules) — the bot's own session is enough for this one step, no admin needed.

7. Creating work — a human creates "Claude Task" Topics with description = the prompt, and drags them from backlog into todo when ready.

Status lifecycle (Workflow "Claude Automation")

A Topic moves through the "Claude Automation" Workflow in one canonical order:

created → todo → planning → planned → approved → in_progress → done → closed

That array order is also the board column order (see setup step 3 for why that matters and why closed has to be last).

Every status has one designated actor who is supposed to set it — the human and the agent alternate:

Gated transitions

Only two forward transitions carry beforeChecks at all:

• created → todo — descriptionRequired, so an empty Topic can never enter the queue and leave the agent planning against nothing.

• planned → approved — requiredFieldsFilled, which gates on the plan field being non-empty (it's required: true on the "Claude Task" TopicType), so nobody can approve a Topic that has no plan on it.

Every other forward transition (todo → planning, planning → planned, approved → in_progress, in_progress → done, done → closed) has no checks. Checks sit by convention on the transition that gates entry into the next phase, not on the one leaving a phase — see setup step 3.

Going backwards

Backward transitions exist throughout, all with empty beforeChecks/afterActions: moving a card back must always be possible (a plan turns out wrong, an approval was premature). The live setup isn't limited to one step back — it also has direct shortcuts to an earlier stage: todo → created, planning → todo, planned → planning, planned → todo, approved → planned, in_progress → approved, done → in_progress, done → todo, closed → todo, plus closed → created as the dedicated "Reopen" action.

done vs. closed

These two are routinely confused, and they are not interchangeable:

• done is an ordinary custom status just before the end. It carries no special semantics of its own — it is purely the agent's "I'm finished" signal.

• closed is the real reserved status key, which is why isCompleted and the admin-only reopen behaviour apply to it automatically, and it stays the human's exclusive closing signature after real verification.

So a Topic in done has been handed in, not accepted.

Convention, not enforcement

The actor assignment in the table above is convention only. It is enforced exclusively by the prompt text in easytopic_transition_status's tool description — not by firestore.rules, not by any beforeChecks, and not by the role/permission model, which has no notion of "this transition is human-only". Nothing structurally prevents an agent from jumping straight to approved or closed; it relies entirely on the tool description telling it not to, and on the agent honouring that.

The one gate that is enforced in code is the project-admin requirement for leaving closed — and that applies identically to a human and to the bot.

agent-worker/src/orchestrate.ts adds its own deterministic checks on top: the plan step refuses to run unless the Topic is in todo, and the implement step requires both approved and a non-empty plan field. That hardens that one worker, though — it is not a server-side guarantee, and any other client can still move a Topic however it likes.

Where the keys live

The status keys (not the display names) are mirrored in several places: EASYTOPIC_*_STATUS_KEY in the .mcp.json env block or in mcp-server/.env, and as defaults in src/config.ts; easytopic_whoami echoes the resolved values. Renaming a key in the Workflow Designer means updating these in the same change — a mismatch fails silently: easytopic_list_topics simply returns nothing, with no error.

See loop-prompt-template.md for the prompt that drives this lifecycle.

Configuration

Copy .env.example to .env (local testing) or supply the same variables through your /schedule routine's env/secret mechanism. See .env.example for the full list — the Firebase web config values are public (same as what ships in the EasyTopic app bundle); EASYTOPIC_BOT_PASSWORD is the one real secret.

config.ts also loads mcp-server/.env itself as a fallback (fills only env vars not already set — never overrides a real .mcp.json env block), so a self-hosted setup (the MCP server living in the same repo it serves, like this one does for EasyTopic itself) can point .mcp.json at the bundle with no env block at all, keeping the committed .mcp.json secret-free.

App Check

If your Firebase project enforces App Check on Firestore/Storage, this bot needs EASYTOPIC_FIREBASE_APPCHECK_DEBUG_TOKEN set (see .env.example) or every tool call fails with a permission error — a Node process can't do the real reCAPTCHA/DeviceCheck/Play Integrity attestation a browser or native app does.

Register a debug token per bot instance, not one shared across bots: Firebase Console → your project → Build → App Check → Apps → (your web app) → Manage debug tokens → Add debug token, give it a name that identifies which bot it's for. Each debug token is independently revocable — if one bot is ever suspected of misbehaving, delete just its token and it's immediately locked out of Firestore/Storage, with zero effect on any other bot instance or on that bot's own Firebase Auth password.

Deliberately not using an Admin SDK-minted App Check token here, even though that's also an officially supported pattern for trusted server environments: minting a token that way needs a service account with roles/firebaseappcheck.admin, and that role's actual permission set includes firebaseappcheck.services.update (very likely the App Check enforcement on/off switch itself) and .debugTokens.update (manage debug tokens for any app) — no narrower "just mint tokens" permission exists. A leaked key with that role could disable App Check enforcement project-wide, not just impersonate one bot. A leaked per-bot debug token, by contrast, can only ever impersonate that one bot to App Check — a much smaller blast radius, and it costs nothing to register (no new service account, no IAM grant).

App Check only answers "is this a request from a client we recognize?" — never confuse it with a behavioral leash on what a bot can then do. That's still entirely down to Firestore/Storage security rules (participantUids/ role checks) and the bot's own Firebase Auth credentials, both completely unaffected by any of this.

Why a committed, dependency-free bundle (dist/bundle.cjs), not lib/

Real incident (2026-07-17): a /schedule cloud routine's very first run failed because the MCP server declared in .mcp.json is spawned by the Claude Code host at session bootstrap, before the routine's own prompt-driven Bash steps ever run. In a fresh git clone, neither mcp-server/lib/ (tsc output) nor mcp-server/node_modules/ exist yet — both are gitignored — so node mcp-server/lib/index.js crashed immediately with a module-not-found error. By the time the agent's prompt got around to running npm install && npm run build, the already-spawned (dead) process was never retried — there's no in-session way to restart an MCP connection.

Fix: npm run bundle (esbuild, src/index.ts → dist/bundle.cjs, --bundle --platform=node --format=cjs) produces a single file with every dependency (firebase, @modelcontextprotocol/sdk, zod) inlined — zero node_modules needed at runtime. This file is committed to git (unlike lib/, which stays gitignored dev output) specifically so it exists immediately in any fresh clone, before any build step could possibly run. Verified by copying just dist/bundle.cjs (+ a .env) into an empty directory with no node_modules anywhere nearby and confirming it starts and serves tool calls correctly. npm run build runs tsc && npm run bundle together — always re-run and re-commit dist/bundle.cjs after any src/ change, or a /schedule routine keeps running stale code indefinitely (a git-ignored build artifact would silently drift; this one doesn't because it's tracked and reviewable in diffs).

.mcp.json in the target project

{
  "mcpServers": {
    "easytopic": {
      "command": "node",
      "args": ["/absolute/path/to/easytopic/mcp-server/dist/bundle.cjs"],
      "env": {
        "EASYTOPIC_FIREBASE_API_KEY": "...",
        "EASYTOPIC_FIREBASE_AUTH_DOMAIN": "...",
        "EASYTOPIC_FIREBASE_PROJECT_ID": "...",
        "EASYTOPIC_FIREBASE_STORAGE_BUCKET": "...",
        "EASYTOPIC_FIREBASE_MESSAGING_SENDER_ID": "...",
        "EASYTOPIC_FIREBASE_APP_ID": "...",
        "EASYTOPIC_BOT_EMAIL": "...",
        "EASYTOPIC_BOT_PASSWORD": "...",
        "EASYTOPIC_COMPANY_ID": "...",
        "EASYTOPIC_PROJECT_ID": "...",
        "EASYTOPIC_BOARD_ID": "...",
        "EASYTOPIC_TODO_STATUS_KEY": "todo",
        "EASYTOPIC_PLANNING_STATUS_KEY": "planning",
        "EASYTOPIC_PLANNED_STATUS_KEY": "planned",
        "EASYTOPIC_APPROVED_STATUS_KEY": "approved",
        "EASYTOPIC_IN_PROGRESS_STATUS_KEY": "in_progress",
        "EASYTOPIC_DONE_STATUS_KEY": "done",
        "EASYTOPIC_PLAN_FIELD_KEY": "plan"
      }
    }
  }
}

Open point (verify before real use): a /schedule cloud routine runs in a cloud sandbox, not on this machine — a local absolute args path is only reachable if that sandbox has this easytopic repo checked out too, which isn't guaranteed. If it doesn't, publish this package to an npm registry the sandbox can reach and use "command": "npx", "args": ["-y", "@easytopic/mcp-server"] instead (npx fetches on demand, same "no local build step required" property as the committed bundle). Also don't commit EASYTOPIC_BOT_PASSWORD in a real .mcp.json — reference it as an env var name and inject the actual value through whatever secret storage the routine host provides.

Loop prompt

See loop-prompt-template.md for the full prompt to give the scheduled Claude Code agent — implements the pick-up/plan/wait-for-approval/ implement/close lifecycle, including the "never self-approve" and question/reply detection rules. Since the bundle needs no build step, the only thing a routine's prompt must still do before its first tool call is write mcp-server/.env (config is loaded lazily per tool call — see config.ts — so the server process itself is already up and running by the time that file appears).

Development

npm install
npm run build   # tsc (lib/, dev-only) + esbuild bundle (dist/bundle.cjs, committed)
npm start       # runs the stdio MCP server against .env, from lib/

Tool reference

Every Topic tool takes an optional projectId; omitted, it uses the configured EASYTOPIC_PROJECT_ID. Passing another Project only works as far as the Firestore rules let the bot in — that hangs on its role there, not on the parameter.

Plus the Documentation-Project tools: easytopic_list_doc_projects, easytopic_list_doc_tree, easytopic_get_doc_page, easytopic_write_doc_page, easytopic_create_doc_page.

Errors from easytopic_transition_status use the same vocabulary as the app's own useTransitionTopicStatus hook: a WorkflowCheckId (assigneeRequired/dueDateRequired/descriptionRequired/ requiredFieldsFilled), notProjectAdmin, hasActiveConflict, or noMatchingTransition. The Topic tools answer in the same shape ({ "error": "<code>" }, never a raw permission error):

Two behaviours worth knowing before using the write tools:

• easytopic_link_topics writes BOTH directions in one call. A link is two mirror documents sharing one id, one under each Topic, and the far side gets the inverse type (blocks ↔ isBlockedBy, relatesTo is its own inverse). Never call it twice to "build the other side". There is no way to change a link's type — remove it and make a new one.

• easytopic_set_topic_parent writes no Topic History entry and does not renumber siblings, exactly like the app: placement in the tree is metadata of the same tier as boardId, not a tracked field change.