Authentication: Call easytopic_whoami first to authenticate and retrieve configuration.
Kanban / Task Management:
List and get topics (tasks), including descriptions, plans, comments, and status.
Transition topic statuses through a predefined workflow (e.g., todo → planning → planned → in_progress → done), enforcing checks; never self-approve or close.
Write implementation plans and add comments for communication.
Documentation:
List documentation projects and their page trees.
Get full page content (rich-text HTML).
Update existing pages (title, content, meta description); changes are versioned.
Create new pages (requires admin role).
Conventions: The bot respects human-only steps (approval, closure) and maps errors to familiar check IDs.
Provides tools to manage EasyTopic Kanban boards stored in Firebase, including creating, updating, and transitioning topics, and adding comments via Firebase Cloud Functions.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@EasyTopic MCP Server pull the next topic from the ToDo column and begin planning"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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).
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: DutyHub MCP Server
All of this is done through the existing app UI (Workflow / Topic / Board Designer are already shipped):
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.
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).
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.
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).
BoardType (Board Designer) — references the Workflow,
hiddenStatusKeys: ["created"].
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.
Creating work — a human creates "Claude Task" Topics with
description = the prompt, and drags them from backlog into todo when
ready.
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:
Status | Set by | When / meaning |
| Human | The story is being written: |
| Human | Queues the Topic. From here on the agent may pick it up and plan it. |
| Agent | Set the moment the agent starts planning. |
| Agent | The plan is written to the |
| Human | The approval itself. The agent may only set this if the human has explicitly approved — via a Topic comment or directly in conversation — never on its own initiative. |
| Agent | Set when implementation starts. |
| Agent | Set once the work is finished from the agent's own perspective. |
| Human only | The final sign-off, after the human has actually verified the work. The agent never sets this, under any circumstance. |
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.
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. closedThese 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.
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.
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.
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.
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.
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.
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).
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/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.
Tool | Purpose |
| Auth check, echoes resolved config + the bot's role in the configured Project |
| Topics filtered by status |
| Title substring search; without |
| Topic + comments + legal transitions + parent/children + links + |
| Post a comment |
| Write the plan custom field (versioned) |
| Change status via the matching Workflow transition |
| Create a Topic (admin only; optional parent, assignee, custom fields, due date) |
| Change title/description/custom fields/due date — versioned, in Topic History |
| Re-hang a Topic in the Project's tree ( |
| Link two Topics; the inverse direction is written automatically |
| The Topic's links, with the |
| Remove a link (best-effort on the far side) |
| Assign or clear — this is what the autonomous worker routes on |
| Switch Topic Type; reports |
| Permanent delete; direct children are re-hung onto the deleted Topic's parent |
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):
Code | Meaning |
| Creating a Topic needs the |
| The Topic does not exist or the bot may not read it. The two are indistinguishable to any client: the |
| The race-condition detector has locked the Topic; every client write is refused until a human resolves the conflict in the app. |
| The proposed parent is the Topic itself or one of its own descendants. |
| Topic Type gate, same vocabulary as |
| A Topic Type change would reset the status into one the Workflow's status rights do not let this role enter. |
|
|
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.
Posts a comment on a Topic — the only channel to communicate with the human (questions, progress notes, completion summaries). The human is notified automatically.
| Name | Required | Description | Default |
|---|---|---|---|
| body | Yes | ||
| topicId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description discloses the core behavior (adds a comment, notifies human). It does not address potential side effects or reversibility, but for a simple write tool this is reasonable. The description adds meaningful context beyond the bare schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that immediately states the primary action, followed by essential context. No unnecessary words; every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with two required parameters and no output schema, the description covers the action and its primary effect (notification) but omits parameter guidance and any constraints. It is minimally viable but incomplete for an agent to use correctly without additional inference.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description does not explicitly explain the two parameters ('topicId' and 'body'). While the purpose sentence implies their roles ('posts a comment on a Topic'), it lacks explicit details like format, length constraints, or examples. The description should compensate more given no schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the action ('posts a comment'), the resource ('Topic'), and explicitly frames it as the exclusive communication channel with the human, differentiating it from sibling tools like 'easytopic_transition_status' or 'easytopic_write_plan'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Describes the tool as 'the only channel to communicate with the human' and lists specific use cases (questions, progress notes, completion summaries), providing strong context for when to use it. The automatic notification detail reinforces its role. No explicit exclusions are needed given its exclusive framing.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Creates a new Documentation page (Topic) under the given parent (null = top-level page) in a Documentation Project. Firestore rules only allow Topic creation by a Project ADMIN (no plain-participant fallback) — this tool checks that up front and returns { error: "notProjectAdmin" } instead of a raw permission error if the bot is only a member. Ask the human to promote the bot to admin on that Project's participants if you hit this.
| Name | Required | Description | Default |
|---|---|---|---|
| title | Yes | ||
| projectId | Yes | ||
| topicTypeId | No | ||
| parentTopicId | No | ||
| descriptionHtml | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses key behaviors: admin check before creation, specific error response ('notProjectAdmin'), and that parentTopicId null means top-level. No annotations provided, so the description carries full burden and does it well.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with purpose. No wasted words, but the first sentence is somewhat long. Overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters and no output schema, the description explains permission flow and parent parameter well, but fails to describe other parameters (topicTypeId, descriptionHtml) and the return value. Adequate but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaning only for 'parentTopicId' (null = top-level), but does not explain 'title', 'projectId', 'topicTypeId', or 'descriptionHtml'. Leaves significant gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (creates), the resource (Documentation page/Topic), and the context (under given parent, in a Documentation Project). It distinguishes from sibling tools like list_topics or get_topic by specifying creation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains when to use (to create a page), the admin prerequisite, and the error handling ('Ask the human to promote the bot'). It implies when not to use if not admin, but lacks explicit comparison to alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches one Documentation page (Topic) in full: title, description (the page's rich-text HTML body), parentTopicId, isPublic, metaDescription, and its direct child pages (id/title only). Get projectId from easytopic_list_doc_projects and topicId from easytopic_list_doc_tree.
| Name | Required | Description | Default |
|---|---|---|---|
| topicId | Yes | ||
| projectId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full burden. It details the output (title, HTML description, parentTopicId, isPublic, metaDescription, child pages). It does not mention side effects, but for a fetch operation this is acceptable. It could explicitly state it's read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, concise and front-loaded. The first sentence explains the action and output; the second advises on obtaining parameters. No unnecessary words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, the description lists return fields. Parameter guidance covers obtaining inputs. It lacks information on error handling, pagination, or permissions, but for a simple get tool this is adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no descriptions on parameters). The description compensates by indicating where to get parameter values (from other tools), but it does not explain what the parameters represent (e.g., topicId is the page ID). This adds some value but still leaves ambiguity.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches one Documentation page (Topic) in full, listing the specific fields returned. The title reinforces the action. It distinguishes from siblings like easytopic_list_doc_tree (which lists tree structure) and easytopic_get_topic (likely a different concept).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides explicit guidance on how to obtain the required parameters (projectId from easytopic_list_doc_projects and topicId from easytopic_list_doc_tree). However, it does not explicitly state when not to use this tool or compare it to alternatives like easytopic_get_topic.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetches one Topic in full: title, description (the prompt), custom field values (incl. the plan field), current status, the subset of workflow transitions currently legal from this status, all comments oldest-first, and awaitingHumanReply (true if the bot's own question is still the most recent comment — do not re-ask, wait for a reply).
| Name | Required | Description | Default |
|---|---|---|---|
| topicId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Despite no annotations, the description fully discloses what the tool returns (title, description, custom fields, status, transitions, comments, awaitingHumanReply) and provides important behavioral guidance: 'do not re-ask, wait for a reply' when awaitingHumanReply is true.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, well-structured sentence that front-loads the main action and enumerates the returned fields concisely. No redundant information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simple input schema (1 parameter) and no output schema, the description provides a thorough enumeration of return fields and behavioral context, making it complete for an agent to understand and use the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, and the description does not explicitly elaborate on the 'topicId' parameter. However, the parameter name and tool purpose make it obvious that this is the topic identifier, so the lack of additional detail is acceptable but not exceptional.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool fetches one Topic in full, listing the specific fields (title, description, etc.). This distinguishes it from siblings like easytopic_list_topics which presumably lists multiple topics.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is for retrieving detailed information on a single topic ('Fetches one Topic in full'), but does not explicitly indicate when to use it over siblings or provide exclusions. Still, the purpose is clear enough for an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every Documentation Project (Project.isDocumentationProject === true) in the configured company that the bot currently participates in. A Documentation Project holds its content as a tree of publishable Topics (see easytopic_list_doc_tree/easytopic_get_doc_page). The bot only sees a Project here once a human has added it as a Project participant in that Project's settings — company employment alone is not enough (Firestore rules require real participancy for list queries). To also create new pages (easytopic_create_doc_page) or read the Project's FULL existing tree, the bot needs to be added as an ADMIN participant specifically, not just a member — see CLAUDE.md's participancy/admin-visibility notes.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Discloses Firestore rules requiring participancy and admin requirements for further operations. Lacks output format details but is otherwise transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single paragraph, front-loaded with core purpose, each sentence adds essential information without redundancy. Matches the input schema's simplicity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects: filter condition, participancy, admin requirements. No output schema, so return structure is implied but not explicit. Adequate for a simple list tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema has no parameters (100% coverage). Description adds value by explaining the implicit filter (isDocumentationProject true) and participancy condition beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly defines the tool's purpose: listing Documentation Projects where Project.isDocumentationProject === true that the bot participates in. It distinguishes from sibling tools like easytopic_list_doc_tree and easytopic_get_doc_page.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to use (list projects) and when not (bot must be added as participant, not just employee). Also provides guidance for related actions requiring admin role, referencing CLAUDE.md.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists every page (Topic) the bot can see in the given Documentation Project, flattened, ordered by sortOrder within each parent — use parentTopicId to reconstruct the tree (null = top-level page). Returns id/title/parentTopicId/isPublic only; call easytopic_get_doc_page for a page's actual content. Get projectId from easytopic_list_doc_projects.
| Name | Required | Description | Default |
|---|---|---|---|
| projectId | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided; description discloses flattening, ordering, returned fields, and that only visible pages are included. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no redundancy. First covers purpose and output, second provides prerequisite guidance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, description adequately explains output fields and ordering. Sufficient for agent to use correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Single parameter projectId: schema has 0% coverage, but description explains how to obtain it from another tool, adding context beyond parameter name.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states it lists every page in a documentation project, flattened and ordered. It distinguishes from sibling tools like easytopic_get_doc_page (content retrieval) and easytopic_list_doc_projects (project list).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use this vs easytopic_get_doc_page for content, and how to get projectId from easytopic_list_doc_projects. Also explains tree reconstruction using parentTopicId.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Lists Topics in the configured company/project whose currentStatusKey is one of the given statusKeys, oldest-updated first. Use the configured todoStatusKey/planningStatusKey/plannedStatusKey/approvedStatusKey/inProgressStatusKey/doneStatusKey values from easytopic_whoami.
| Name | Required | Description | Default |
|---|---|---|---|
| statusKeys | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must disclose behavior. It states it's a read operation ('Lists') and specifies ordering and filtering, but omits details on pagination, empty results, or potential side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, no wasted words, purpose front-loaded, efficient structure.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema exists, but the description does not explain the return structure (e.g., fields of each topic). For a simple list tool, this is a moderate gap that could leave the agent uncertain about the output format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description adds essential meaning: 'statusKeys' are the filter criteria and should be obtained from 'easytopic_whoami'. This clarifies the parameter's purpose and provides actionable guidance.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb 'lists' and resource 'Topics', specifies the filter by status keys and ordering by oldest-updated first, and distinguishes from siblings like 'easytopic_get_topic' (single topic) and 'easytopic_transition_status' (state change).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent to use status key values from 'easytopic_whoami', which provides context for parameter values, but does not explicitly state when to use this tool versus alternatives or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Moves a Topic to a new status via the matching Workflow transition (runs the same beforeChecks the human UI runs, e.g. requiredFieldsFilled). Errors use the same vocabulary as the app: a WorkflowCheckId (assigneeRequired/dueDateRequired/descriptionRequired/requiredFieldsFilled), notProjectAdmin, hasActiveConflict, or noMatchingTransition. Status lifecycle convention (created -> todo -> planning -> planned -> approved -> in_progress -> done -> closed): you may set planning/planned yourself once you start/finish planning, and in_progress/done yourself once you start/finish the work. Never set the approved status yourself unless the human has given explicit approval via a Topic comment or directly in conversation — otherwise wait for them to set it. Never set the closed status yourself under any circumstance — that is the human's exclusive final sign-off after verifying the work.
| Name | Required | Description | Default |
|---|---|---|---|
| comment | No | ||
| topicId | Yes | ||
| toStatusKey | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It discloses that the tool runs the same beforeChecks as the human UI (e.g., requiredFieldsFilled), lists possible error types (WorkflowCheckId, notProjectAdmin, etc.), and explains the status lifecycle convention.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured, starting with the action, then error vocabulary, then lifecycle rules. It is detailed but not overly verbose; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Comprehensive for a transition tool: explains constraints, error vocabulary, and status conventions. However, it does not describe the return value (e.g., success message or updated topic), which is a minor gap given no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, and the description adds meaning for topicId and toStatusKey (the topic and target status) but does not describe the optional 'comment' parameter. This leaves some semantic gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool moves a Topic to a new status via a Workflow transition, explicitly distinguishing it from sibling tools like easytopic_list_topics or easytopic_add_comment. It specifies the action, resource, and business logic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit when-to-use and when-not-to-use guidance, including when the agent may set planning/planned/in_progress/done statuses, and strict prohibitions on setting approved (without human approval) and closed (never). This helps avoid misuse.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Authenticates against EasyTopic and returns the bot's identity plus the configured company/project/board/status-key/plan-field settings. Call this first in every run — if it errors, stop immediately (auth/config problem), do not attempt any workaround.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes authentication and return of settings; implies idempotent health check. No mention of side effects or rate limits, but sufficient for 0-param tool without annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose, then critical usage directive. No waste.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a 0-param auth tool: explains what it does, when to use, and error handling. No output schema needed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters; schema coverage 100%. Description adds no parameter info but none needed; baseline applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states authenticates and returns identity plus configuration settings. Distinct from siblings which are data operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs 'Call this first in every run' and specifies error handling: stop immediately if it errors, no workarounds.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Updates an existing Documentation page's title and/or rich-text HTML content (descriptionHtml) and/or metaDescription. Only fields you pass are touched; title/descriptionHtml changes are versioned into Topic History like every other Topic edit, metaDescription is not. Requires the bot to already be a participant of the page's Project (see easytopic_list_doc_projects) — does not require admin.
| Name | Required | Description | Default |
|---|---|---|---|
| title | No | ||
| topicId | Yes | ||
| projectId | Yes | ||
| descriptionHtml | No | ||
| metaDescription | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses partial update behavior ('Only fields you pass'), versioning for title/descriptionHtml, and that metaDescription is not versioned. Mentions auth requirement but no rate limits or idempotency. With no annotations, this is solid.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with action and scope. No redundant phrases. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main behavior, versioning, and precondition. Missing return value information (no output schema, and description does not mention what is returned). Otherwise complete given complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema description coverage, the description explains the three optional params (title, descriptionHtml, metaDescription) with versioning context. Required params (projectId, topicId) are not detailed but are self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states verb 'Updates' and resource 'Documentation page', specifying which fields (title, descriptionHtml, metaDescription). Distinguishes from sibling 'easytopic_create_doc_page' as an update operation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides precondition (bot must be project participant) and references sibling for checking participation. Implies use case via 'Updates', but lacks explicit when-not or alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Writes the implementation plan into the Topic's configured plan custom field (versioned, recorded in Topic History). Call this before transitioning a Topic out of the todo status — write the plan first, then transition.
| Name | Required | Description | Default |
|---|---|---|---|
| topicId | Yes | ||
| planHtml | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description reveals versioning and history recording, which are important behavioral traits. It does not mention idempotency or side effects, but for a simple write operation it is fairly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no waste. Critical information is front-loaded, covering action, target, versioning, usage sequence, and distinction from sibling.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and no annotations, the description covers purpose, usage, and behavioral traits adequately. However, it lacks parameter descriptions, making it slightly incomplete for a 2-param tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not explain the two parameters (topicId, planHtml). It implies planHtml is the plan content but does not clarify format or that topicId identifies the topic. This is a significant gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action (writes implementation plan), the target (Topic's plan custom field), and key traits (versioned, recorded in Topic History). It distinguishes from sibling tools like easytopic_transition_status by naming the specific resource and action.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly tells when to use ('before transitioning a Topic out of the todo status') and provides a sequence instruction ('write the plan first, then transition'). This clearly differentiates from easytopic_transition_status and gives direct usage context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
v0.1.0easytopic_add_commenteasytopic_create_doc_pageeasytopic_get_doc_pageeasytopic_get_topiceasytopic_list_doc_projectseasytopic_list_doc_treeeasytopic_list_topicseasytopic_transition_statuseasytopic_whoamieasytopic_write_doc_pageeasytopic_write_planTools are clearly separated into topic management and documentation project management groups, with each tool having a distinct purpose (list vs get vs add vs write vs transition vs create). No overlapping functionalities.
All tools follow the 'easytopic_verb_noun' pattern with consistent verbs (list, get, add, write, transition, create). The only outlier is 'whoami', which is a standard authentication term and fits the pattern.
With 11 tools covering two main domains (topic management and documentation projects), the number is well-scoped. Each tool serves a necessary role without redundancy.
Significant gaps exist: no create_topic or delete_topic for topic management, and no delete_doc_page for documentation. Updates to custom fields beyond the plan field are missing. However, core workflows (list, get, update status, add comments, and documentation CRUD for creation/reading/updating) are covered.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Read and manage your EasyKanban kanban boards: to-do summaries, create, update, and move cards.
AI-native Kanban board — connect Claude to claim, work and move your tasks over MCP.
Remote MCP for Kanban AI boards—manage projects, tasks, and comments from AI tools.
Task & board management for AI agents + humans. Kanban, comments, digests via MCP.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/EB-CON-GmbH/easytopic-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
