nodebb-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| NODEBB_UID | No | Acting uid. Required when the token is a master token; ignored for user tokens. | |
| NODEBB_URL | Yes | Forum root, e.g. https://forum.example.com (a subdirectory mount is fine). | |
| NODEBB_API_TOKEN | No | Bearer token from ACP → Settings → API Access. Without it the server sees only publicly readable content. | |
| NODEBB_TIMEOUT_MS | No | Per-request timeout. | 15000 |
| NODEBB_SHOTEF_NAMESPACE | No | Plugin id namespace under /api/v3/plugins/<id>. | shotef |
| NODEBB_CAPABILITY_TTL_MS | No | How long plugin detection is cached. | 300000 |
| NODEBB_MAX_POSTS_PER_TOPIC | No | Cap on posts pulled per topic. | 50 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
This server publishes no instructions, or was last inspected before Glama recorded them.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| prompts | {
"listChanged": true
} |
| resources | {
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| forum_capabilitiesA | Report which forum features this server can actually use: reachability, authentication, full-text search, the Q&A plugin (accepted answers), and the Shotef triage plugin. Call this first when a result looks thin or a tool reports a feature as unavailable — it explains what is missing and what would enable it. |
| search_forumA | Full-text search across topic titles and post bodies. Returns ranked matches with a snippet showing why each matched. Requires a search plugin on the forum (NodeBB core has none); when one is absent this falls back to scanning recent topics by title and says so. For answering a question, prefer find_answers, which also extracts the answers. |
| get_topicA | Read a topic in full: the original post, replies in order, and — when the relevant plugins are installed — which reply is the accepted answer and where the topic sits on the triage board. This is the tool for understanding a reported issue in the reporter's own words. |
| get_postA | Read one post by its id, with the topic it belongs to. Use when a search result or a link points at a specific reply and you only need that reply. |
| list_categoriesA | List the forum's category tree with ids, descriptions and topic counts. Use it to find the category id to pass to search_forum, list_recent_topics, or investigate_issue. |
| list_recent_topicsA | Browse topic listings — recent, popular, top, or unread — optionally inside one category. Useful for getting a feel for what is being reported lately, and as the way to explore a forum that has no search plugin. |
| find_answersA | Find topics that already answer a question, and extract the answer from each. Prefers author-accepted answers when the Q&A plugin is installed, and falls back to the strongest reply otherwise — always labelling which it used, so an unconfirmed reply is never presented as a confirmed answer. This is the first tool to reach for when someone asks a question the forum may have seen before. |
| get_topic_answerA | Get the answer to one specific topic. With the Q&A plugin this is the accepted answer, and an open question is reported as genuinely unanswered rather than guessed at. Without it, returns the most-upvoted reply, labelled as unconfirmed. |
| list_unanswered_questionsA | List questions nobody has answered yet — the queue for someone who wants to help. With the Q&A plugin this is the forum's real unsolved list; without it, recent topics that have no replies, which approximates it but cannot tell a question from a discussion. Shows triage status per item when the Shotef plugin is installed. |
| investigate_issueA | The full sweep for a reported problem: find every related topic, extract the answers that already exist, separate them from the reports still open, fold in triage status, and end with concrete next steps. Use this when someone reports a problem and you need to know whether the forum has seen it before, whether it was solved, and whether anyone is already on it. Slower than find_answers because it opens several topics — prefer find_answers for a plain question. |
| get_triage_statusA | Where a topic stands in the support workflow: received, in progress, awaiting the reporter, or closed — plus which team handles it and whether it is parked. Answers "is anyone working on this, and was it ever resolved?". Requires the Shotef triage plugin; without it, reports that cleanly and suggests reading the topic instead. |
| get_triage_boardA | The team's triage board: every open ticket by workflow column, with priority, owner and age. Use it to see the current support workload, or to find which issues are stalled. Requires the Shotef plugin and a token belonging to a team member — a non-member gets an explanation rather than an error. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| answer_forum_question | Search the forum for an existing answer, then draft a reply grounded in what it finds. |
| investigate_report | Work out whether a reported problem is known, solved, or already being worked on. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| nodebb-plugin-overview | Start here. The build-vs-restart mental model, minimum viable plugin anatomy, plugin.json wiring, the five rules that prevent most pain, and a triage checklist for when a change isn't taking effect. |
| nodebb-plugin-architecture | The nbb core-module loader, the core modules worth knowing, a plugin file layout that scales, package.json essentials, the startup lifecycle, cluster awareness via nconf runJobs, soft integration with other plugins, notifications, and privilege helpers. |
| nodebb-plugin-hooks | The static:/filter:/action: hook families and their contracts, sequential firing and noErrorHooks semantics, payload-shape drift across NodeBB majors, filtering out a topic's main post, avoiding re-entrancy on your own writes, and how to discover a hook's exact payload from the NodeBB source. |
| nodebb-plugin-endpoints | Choosing between page routes, /api/v3/plugins routes, and socket methods; setupPageRoute and setupAdminPageRoute; formatApiResponse and the wrap() error helper; CSRF from the browser; socket auth from socket.uid; live updates with rooms and ping broadcasts; optimistic concurrency. |
| nodebb-plugin-data-layer | NodeBB's db abstraction (hashes, sets, sorted sets, lists), designing a namespaced key schema with indexes per view, backend-safe encode/decode of arrays and booleans, which reads are cached and which are not, batching reads to avoid N+1, funnelling writes through one state-machine function, and audit trails. |
| nodebb-plugin-client-acp-templates | AMD client scripts and the action:ajaxify.end SPA lifecycle, available globals and app.require, attribute-safe escaping, ACP modules via the plugin.json modules map (and the empty-define requirement), Benjamin .tpl syntax, language keys with positional args, and dark-mode-safe CSS for Bootswatch skins. |
| nodebb-plugin-gotchas | Sixteen traps as symptom → cause → fix: the HTML double-escape on titles, build js skipping templates and CSS, stale client bundles, server code cached in memory, npm install pruning the dev symlink, out-of-process writes hidden behind caches, top-level nbb() breaking unit tests, standalone script config crashes, async notification delivery, isActive cached at init, ACP define() resolving undefined, dark-skin token defaults, Redis dev data loss, EMFILE builds, and deploy-branch confusion. |
| nodebb-plugin-testing | Three test layers. Unit tests with node:test by stubbing the nodebb global before requiring your modules (capturing responses and writes); seeding mock data from a standalone NodeBB-context script with the nconf/meta bootstrap that doesn't crash; driving the running forum over HTTP with a session cookie and CSRF token; and Playwright for visual confirmation. |
| nodebb-plugin-recipes | Copy-paste starting points: a minimal plugin skeleton (package.json, plugin.json, nbb.js, library.js), setting up a local NodeBB + Redis dev forum from scratch with a symlinked plugin, the build/restart iteration loop, health checks, an auditable state-change function, a best-effort notification helper, and cluster-safe cron with idempotent per-period buckets. |
| nodebb-plugin-worked-example | An annotated tour of nodebb-plugin-shotef, a ~5,200-line production plugin: its module map and line counts, how page routes, API routes and 21 socket methods divide the work, and the patterns worth copying (one state machine, config-driven behaviour, dual projections, wrapped action hooks, re-entrancy guards, graceful optional integration, ping broadcasts). |
TDQS
Scored across 12 tools
There is meaningful overlap in the search/answer cluster (search_forum, find_answers, investigate_issue, get_topic_answer), but the descriptions explicitly cross-reference and route the agent (e.g. 'prefer find_answers', 'prefer find_answers for a plain question'). get_topic vs get_post and triage status vs board are cleanly separated, so an agent can reliably pick.
Almost everything follows a verb_noun pattern: get_post, list_categories, search_forum, get_topic, find_answers, investigate_issue, get_triage_status, get_triage_board. The lone deviation is forum_capabilities (noun-only, no verb), but it stays snake_case and readable.
12 tools is well within the ideal band and each earns its place by covering a distinct read/triage action. No redundant or filler tools are apparent.
The set covers reading posts, topics, categories, listings, search, answer extraction, unanswered queues, and triage status/board — a coherent read-and-triage surface. It is read-only, so any posting/replying/updating workflow the domain might need is absent, but that appears intentional and is not a dead end for the stated purpose.