delphi-mcp
Provides read-only access to Discourse forums, defaulting to Chief Delphi but configurable to any Discourse instance via DELPHI_BASE_URL. Includes tools for listing categories, browsing topic listings, keyword-based topic discovery, reading threads as post windows or raw Discourse markdown, and viewing user profiles.
Click on "Deploy 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., "@delphi-mcp find Chief Delphi threads about 2025 FRC robot reveals"
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.
delphi-mcp
A read-only Model Context Protocol server that lets an AI agent read Chief Delphi — the discussion forum of the FIRST Robotics Competition, running on Discourse.
No account, no API key, no write access. The server speaks the anonymous read endpoints a browser already
uses, and it enforces the site's robots.txt in code rather than in a comment.
cd_categories → cd_find / cd_topics → cd_raw / cd_topic → cd_user
scope it find the thread read the thread vet the claim
cd_watch → what changed in a listing since you last lookedThe npm package name is chief-delphi-mcp. delphi-mcp was already taken on npm by an unrelated
project (a multi-model consensus tool), so the repository keeps the short name while the package does not.
Why this exists
Chief Delphi is where FRC teams post game rumors, strategy, code and CAD releases, and event discussion.
An agent asked to research one of those needs a way into the forum, and the obvious answer — the Discourse
/search.json endpoint — is explicitly disallowed for crawlers by Chief Delphi's robots.txt. This server
is the attempt at getting useful recall without that endpoint. See
Compliance.
Related MCP server: discourse-mcp
Requirements
Node.js 18 or newer to run the server (global
fetch; developed and tested on Node 24)Node.js 21 or newer for
npm test, which passes a glob tonode --testNo build step — plain ESM JavaScript
Install
From npm:
npm install -g chief-delphi-mcpFrom the repository:
git clone https://github.com/CaryWang1234/delphi-mcp.git
cd delphi-mcp
npm installConnect it to your MCP client
All clients take the same stdio entry; only the config file differs.
If you installed globally, the package provides a chief-delphi-mcp command:
{
"mcpServers": {
"chief-delphi": { "command": "chief-delphi-mcp" }
}
}Otherwise point args at the absolute path of src/index.js:
{
"mcpServers": {
"chief-delphi": {
"command": "node",
"args": ["/absolute/path/to/delphi-mcp/src/index.js"]
}
}
}Client | File |
Claude Desktop |
|
Cursor |
|
Qoder |
|
Any other stdio client | its own |
Some hosts cache the tool list after the first handshake. If you change a tool description in
src/index.js and the client still shows the old one, reload MCP servers (/mcp reload in Qoder) or
restart the host. On Windows, prefer an absolute command path such as
C:\\Program Files\\nodejs\\node.exe — hosts do not always inherit your shell's PATH.
Tools
Every tool accepts max_chars (default 20000, ceiling 120000). When a reply would exceed it, the
output is cut and the last line says so and tells you how to continue — one call cannot flood the model's
context.
Tool | What it does | Arguments (defaults) |
| Every category and subcategory with numeric id, slug, topic count and restricted flag. Call first to scope anything else. | — |
| One page of a topic listing: |
|
| Keyword lookup without |
|
| A thread window with per-post metadata: author, user title, timestamp, likes, which post is replied to, post id, deleted/hidden flags. |
|
| A thread as plain Discourse markdown — the cheapest full read. |
|
| An account profile: trust level, titles, join/last-seen/last-posted, profile views, time read, badges, location, website, bio, and profile fields such as team number. |
|
| What changed in one listing since the previous |
|
Listing rows and search hits carry the topic id, which is what cd_topic and cd_raw take. URLs are
${DELPHI_BASE_URL}/t/<slug>/<id>.
Compliance is structural, not advisory
src/discourse.js fetches robots.txt, parses it per the RFC 9309 grouping rules, and checks every
outgoing request against the longest matching rule for this client. A disallowed path throws
RobotsBlockedError and never leaves the process. On Chief Delphi that currently blocks /search*,
/admin*, /session*, /my*, /email*, /badges, /g, /tag/*/l, /c/*.rss and /t/*/*.rss,
plus anything else the site adds later.
Consequences worth knowing before you file a "search is broken" issue:
cd_findis not a full-text index. It ranks topics inside a listing window. A miss means "not in this window", not "the forum has no such thread", and the tool output says exactly that in its header. Widen withpages=(each page is ~30 topics, 40 max), narrow withcategory=, or switchmode=.mode=auto— the default — merges atoppool (most engaged) with alatestpool (most recent), because pooling onlytopsystematically misses last week's thread and pooling onlylatestsystematically misses the decade-old classic.cd_usercannot list a user's posts. That needs/search?q=user:..., which is disallowed. It also cannot report post counts or likes: the anonymous/u/<name>.jsonpayload does not carry them.RSS is not a shortcut around this. The feeds that would actually help are disallowed:
/t/<slug>/<id>.rssand/c/<slug>/<id>.rssboth throwRobotsBlockedError. The global/latest.rssand/top.rssare not forbidden byrobots.txt, but they are strictly worse than the/latest.jsonand/top.jsonpages the server already uses — one anonymous feed page is ~113 KB of XML for the same 30 topics, so nothing here reaches for them.
Being polite to the host is the other half of the same section: all requests are serialized through one
queue with a 350 ms floor (DELPHI_MIN_INTERVAL_MS) because Chief Delphi sits behind Cloudflare and
parallel or rapid-fire requests get challenged, and every response is cached on disk so a repeat call costs
nothing. The one exception is cd_watch, which reads the listing uncached on purpose — a stale snapshot
would defeat the tool — so each watch call is exactly one request, and repeated watching is what the
throttle is there to keep cheap.
Cache | Default TTL |
topic listings ( | 10 min |
thread bodies ( | 3 h |
| 24 h |
category and field metadata ( | 6 h |
Changing this stance — adding /search.json, dropping the throttle, deleting the guard — is a code change
to src/discourse.js, not a config flag. If that is what you want, that is your call to make, but it is
made against the site's stated policy, so this project would rather not ship it.
Using it against another Discourse forum
The server is not Chief Delphi-specific: set DELPHI_BASE_URL to any Discourse forum and the same seven
tools read it. Check that forum's robots.txt first — the guard will adapt automatically and may simply
refuse the endpoints you wanted.
Configuration
Variable | Default | Notes |
|
| Any Discourse forum |
|
| Raise it if you see 403 / 429 / 503 |
|
| Per request |
|
| The token |
|
| Delete the directory to force a refetch; there is no cache-off switch |
| DELPHI_CACHE_DIR | <repo>/.cache | Delete the directory to force a refetch; there is no cache-off switch |
| DELPHI_STATE_DIR | <repo>/.state | cd_watch baselines. Kept out of the cache on purpose: clearing a cache should not silently erase what you are watching |
Tests
npm test # 52 offline assertions, no network
npm run test:live # 27 assertions against the live forum
npm run test:all # bothnpm test is the offline one and belongs in CI. test/unit/*.test.js covers the logic that can be
proven without touching chiefdelphi.com — robots.txt group parsing and longest-match decisions, listing URL
construction, the post-window anchor arithmetic, /raw post splitting, HTML-to-text, ranking weights, the
max_chars budget, and the watch diff. Fixtures are hand-written synthetic payloads: this repo does not
commit scraped forum text or user data, and it never should, since posts belong to the people who wrote them.
npm run test:live is deliberately not wired into CI. It spawns the server over stdio and hits the real
site, and a scheduled job doing that turns this project into a periodic crawler against a third-party forum —
plus it goes red on any network blip. Run it by hand after touching the request layer. It checks every tool,
error paths, the max_chars budget, and the guard: /search.json, /admin/logs.json and
/c/technical/9.rss blocked, with a control proving /latest.json still passes. Blocking alone is not
evidence; the guard has to be shown not to block everything.
Two habits worth copying if you extend the suite:
Assert mechanism, not forum state. An earlier version asserted that a specific game-prediction thread would appear in
cd_find's default pool. It passed in October and went red once that thread left the yearly-top window — the test was measuring the forum, not the code. It now asserts that the auto pool really mergedtopandlatest, that hits come back in descending score order, and that the output carries its own coverage disclaimer.Create the condition instead of waiting for it. The watch delta is proven by rewriting the stored baseline to claim fewer posts, then checking the reported
from→topair against it. That works whether or not anybody posted in the meantime.
Cold live run ~40 s; warm ~4 s.
Upstream facts worth knowing before you patch this
Verified against the live site, and the reason several first drafts of these tools were wrong:
In a Discourse topic URL,
/t/<id>/<n>.json,<n>is a post number, not a page. The returned window starts five posts before the anchor, socd_topicasks forat_post + 5to land where you meant.?page=on/t/<id>/posts.jsondoes nothing for anonymous requests.A window is padded to
chunk_sizelive posts, so in a thread containing deleted posts consecutivepage=requests can repeat one boundary post.at_postis the gap-safe way to continue, and that is what the "next window" hint in the output emits./u/<name>.jsonwraps the profile in auserkey, and numbereduser_fieldsonly become human-readable ("FRC Team Number") viauser_fieldsin/site.json./c/<slug>.json301s; the canonical path is/c/<slug>/<id>.json, and category-scoped feeds live under/c/<slug>/<id>/l/<feed>.json.
Troubleshooting
Symptom | Cause and fix |
| You asked for a path the site disallows. Not a bug to fix by editing the guard — pick an allowed endpoint. |
| Too fast. Raise |
| The window is too small. |
Tools missing in the client | Host has not loaded the connector: |
Stale tool description after an edit | Same — hosts cache |
Client reports a stdio initialization timeout | This server does no network I/O at startup, so check the |
Publishing
Only maintainers need this. files in package.json limits the tarball to src, README.md and LICENSE,
so neither fixtures nor cached forum data can ship by accident.
npm pack --dry-run # confirm what lands in the tarball
npm publish # 2FA is enforced for publish
npm view chief-delphi-mcp version dist-tags.latestTwo things worth knowing before your first release, both learned the hard way:
A brand-new package goes through staged publishing. npm now queues the first release of a name that does not exist yet: the publish call lands a public placeholder version
0.0.0-stage("stub": true, "Temporary package placeholder for staged publishing") and holds the real version for maintainer approval. Approve it on npmjs.com under Staged Packages, or from the CLI withnpm stage list/npm stage view/npm stage approve— which needs npm ≥ 11.15.0 and Node ≥ 22.14; approval always asks for 2FA even if staging did not. Until you approve,latestpoints at the stub andnpm installhands people an inert two-file placeholder, so verifydist-tags.latestafter approving rather than assuming success. Rejecting the staged version leaves that stub published, so clear it instead of leaving it dangling.Plain
npm publishfails with 403 on a 2FA account (Two-factor authentication or granular access token with bypass 2fa enabled is required). Either pass a one-time code —npm publish --otp=123456— or use a granular access token scoped to this package with 2FA bypass, injected asnpm_config_tokenfor the single command. Never commit a token, and prefer the one-time code when publishing by hand.
The release is only real once the published artifact runs. Install it somewhere clean and speak MCP to it, because this proves the tarball is self-contained in a way a working local checkout cannot:
mkdir /tmp/verify && npm install chief-delphi-mcp --prefix /tmp/verify --no-save
node /tmp/verify/node_modules/chief-delphi-mcp/src/index.js # should wait on stdio, not crash on importpublishConfig.access is already public, so the publish command does not need the flag. If your npm
account has two-factor auth, publish needs an automation or a one-time password from your authenticator.
Disclaimer
Not affiliated with FIRST or Chief Delphi. Forum posts are user-generated content owned by their authors; this server retrieves it for you and does not redistribute it. Whatever you build on top of it — summaries, published research, scraped corpora — is yours to keep within Chief Delphi's terms and that content's rights.
License
MIT — see LICENSE.
Available Tools
7 toolscd_categoriescd_categoriesARead-only
List every Chief Delphi (chiefdelphi.com) category and subcategory with its numeric id and slug. Call this first when you need to scope a search or browse to a forum area such as Technical, Competition or Announcements. Read-only, no login. Returns ids usable in cd_topics/cd_find category=.
Inputs: no named parameters.
cd_findcd_findARead-only
Find Chief Delphi topics matching keywords. Chief Delphi robots.txt disallows /search, so this does NOT call the forum search API: it pulls topic listings (mode/period/category/page window), matches tokens against titles, tags and excerpts, ranks the hits, then fetches /raw for the top with_body candidates to confirm the phrase inside the thread and report which posts matched. Coverage is the listing window you ask for, so the default mode=auto pools both most-engaged (top) and most-recent (latest) topics. An empty result means "not in this window", not "the forum has no such thread" — widen pages= or change mode. Good targets: game rumor/prediction threads, rule clarifications, strategy and build threads, event discussion.
Inputs: query (required), mode, limit, match, +6 more.
cd_rawcd_rawARead-only
Fetch a Chief Delphi thread as plain Discourse markdown (the /raw endpoint) — the cheapest way to read a whole discussion, with author and timestamp headers per post and image references left as upload:// tokens. Read only part of a long thread with start_post/end_post to keep the reply small.
Inputs: topic (required), end_post, max_chars, start_post.
cd_topiccd_topicARead-only
Read a Chief Delphi thread with per-post metadata: author, user title, timestamp, like count, which post is replied to, post id, deleted/hidden flags. Threads render in ~20-post windows; jump with at_post= (exact, gap-safe) or page= (page 2 starts at post 21). Discourse pads a window to ~20 live posts, so a thread containing deleted posts can repeat one boundary post between consecutive pages — prefer at_post for exact continuation. Use format="json" to reason over structured fields, format="text" (default) to read the discussion. For a cheap bulk read of a long thread use cd_raw instead.
Inputs: topic (required), page, chunk, format, +3 more.
cd_topicscd_topicsARead-only
Browse a page of Chief Delphi topic listings: newest (mode=latest), newly created (mode=new), or most-engaged (mode=top with a period). Optionally scope to one category. Use this to survey what is being discussed rather than to look for a specific phrase (use cd_find for that). Each row carries the topic id, slug, category id, post count, view count and last activity; feed ids to cd_raw or cd_topic.
Inputs: mode, page, limit, order, +3 more.
cd_usercd_userARead-only
Look up a Chief Delphi account profile: trust level, titles, join date, last seen, last posted, profile views, time read, badge count, location, website, bio and profile fields (FRC/FTC team number, rookie year, roles). Useful for judging how much weight to give a forum claim. Anonymous Discourse does not expose post counts or likes received, and it does not list that user posts — see the note in the output for why.
Inputs: username (required), max_chars.
cd_watchcd_watchARead-only
Report what changed in a Chief Delphi listing since the previous cd_watch call on the same scope: brand-new topics, plus topics whose post or view counts moved, with deltas. The first call records a baseline and lists nothing new; call it again later to get the diff. Made for following an ongoing discussion — game rumor and prediction threads during a season, a build thread you are tracking, or one category during kickoff week — without re-reading the same listings. State persists in .state/ (separate from the disposable cache), is keyed per scope, and reset starts over.
Inputs: mode, limit, order, reset, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 7 tools
Each tool has a distinct role: cd_categories for id discovery, cd_topics for surveying listings, cd_find for keyword search, cd_topic/cd_raw for reading threads (structured vs cheap bulk), cd_user for profiles, and cd_watch for diffs over time. The descriptions explicitly resolve the closest overlaps, e.g. cd_find tells the agent to use cd_topics for general surveying and warns its search is listing-window based, and cd_topic points to cd_raw for bulk reads. No two tools appear interchangeable.
All tools share a predictable cd_ prefix plus a short snake_case identifier, and the plural/singular split (cd_topics listing vs cd_topic thread) is meaningful rather than accidental. Minor deviation: it mixes noun-style names (cd_categories, cd_user) with verb-style names (cd_find, cd_watch), so the naming is consistent in form but not strictly verb_noun.
Seven tools is well-scoped for a read-only forum client: discovery, listing, search, two read modes, profiles, and polling. Every tool covers a distinct workflow step and none feels redundant or bolted on.
The surface covers the full read lifecycle of a forum—find a category, survey listings, search, read a thread cheaply or richly, inspect a user, and track changes over time. Gaps are minor and partly inherent to anonymous Discourse: there is no way to list a given user's posts, no direct post-id fetch, and no write operations (reasonably out of scope for a login-less server), but agents can work around these via thread reads.
Related MCP Connectors
Read-only MCP server exposing a user ORANO library to their own AI agent.
Remote MCP server for SeenThis AI Hub. Supports browsing, searching, and posting to AI boards.
Read-only MCP for AI usage profiles, leaderboards, stats, and docs; no writes or private data.
One MCP server for all web data. Scrape, search, crawl, and AI research in one install.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceRead-only MCP server that enables Cursor or Grok Bot to query Reddit data via OAuth bearer auth, providing user profile, history, subscriptions, subreddit feeds, and search.34 npmMIT
- FlicenseAqualityCmaintenanceEnables an AI agent to read and act on a single Discourse forum as one user, including posting, private messages, likes, reactions, bookmarks, watch/track/mute, and reading its own notifications via a stdio MCP server.8-
- AlicenseAqualityBmaintenanceA local-first MCP server that lets AI agents read any webpage as clean Markdown, crawl whole sites within configured limits, search without API keys, and solve supported captchas locally — all without cloud services or third-party keys.1221AGPL 3.0
- AlicenseAqualityBmaintenanceA read-only MCP server so AI agents can query the corpus or the live site.1234 PyPI18MIT