Skip to main content
Glama

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 looked

The 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 to node --test

  • No build step — plain ESM JavaScript

Install

From npm:

npm install -g chief-delphi-mcp

From the repository:

git clone https://github.com/CaryWang1234/delphi-mcp.git
cd delphi-mcp
npm install

Connect 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

claude_desktop_config.json

Cursor

.cursor/mcp.json

Qoder

settings.json in the app data dir (%USERPROFILE%\.qoder-cn\ on Windows, ~/.qoder-cn/ elsewhere)

Any other stdio client

its own mcpServers / servers map

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)

cd_categories

Every category and subcategory with numeric id, slug, topic count and restricted flag. Call first to scope anything else.

—

cd_topics

One page of a topic listing: latest, new, or top over a period; optionally within one category.

mode=latest category period=monthly order page=0 limit=30

cd_find

Keyword lookup without /search.json: pool listings, match titles/tags/excerpts, rank, then read /raw of the best candidates to confirm the match inside the thread and report which posts matched.

query mode=auto period=yearly category pages=4 match=all with_body=8 limit=12

cd_topic

A thread window with per-post metadata: author, user title, timestamp, likes, which post is replied to, post id, deleted/hidden flags.

topic at_post page=1 chunk=20 max_posts=20 format=text

cd_raw

A thread as plain Discourse markdown — the cheapest full read.

topic start_post end_post

cd_user

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.

username

cd_watch

What changed in one listing since the previous cd_watch on the same scope: new topics, plus per-topic +N posts (from→to) and view deltas. First call only records a baseline.

mode=latest category period=daily limit=25 reset

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_find is 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 with pages= (each page is ~30 topics, 40 max), narrow with category=, or switch mode=. mode=auto — the default — merges a top pool (most engaged) with a latest pool (most recent), because pooling only top systematically misses last week's thread and pooling only latest systematically misses the decade-old classic.

  • cd_user cannot 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>.json payload does not carry them.

  • RSS is not a shortcut around this. The feeds that would actually help are disallowed: /t/<slug>/<id>.rss and /c/<slug>/<id>.rss both throw RobotsBlockedError. The global /latest.rss and /top.rss are not forbidden by robots.txt, but they are strictly worse than the /latest.json and /top.json pages 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 (latest / new / top)

10 min

thread bodies (/t/, /raw/) and profiles

3 h

robots.txt

24 h

category and field metadata (/site.json)

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

DELPHI_BASE_URL

https://www.chiefdelphi.com

Any Discourse forum

DELPHI_MIN_INTERVAL_MS

350

Raise it if you see 403 / 429 / 503

DELPHI_REQUEST_TIMEOUT_MS

20000

Per request

DELPHI_USER_AGENT

delphi-mcp/0.1 (+read-only Discourse client)

The token robots.txt rules are matched against

DELPHI_CACHE_DIR

<repo>/.cache

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  # both

npm 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 merged top and latest, 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→to pair 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, so cd_topic asks for at_post + 5 to land where you meant.

  • ?page= on /t/<id>/posts.json does nothing for anonymous requests.

  • A window is padded to chunk_size live posts, so in a thread containing deleted posts consecutive page= requests can repeat one boundary post. at_post is the gap-safe way to continue, and that is what the "next window" hint in the output emits.

  • /u/<name>.json wraps the profile in a user key, and numbered user_fields only become human-readable ("FRC Team Number") via user_fields in /site.json.

  • /c/<slug>.json 301s; 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

ERROR RobotsBlockedError

You asked for a path the site disallows. Not a bug to fix by editing the guard — pick an allowed endpoint.

HTTP 403 / 503 from Cloudflare

Too fast. Raise DELPHI_MIN_INTERVAL_MS, or wait; results are cached so a retry is cheap.

cd_find finds nothing

The window is too small. pages=, category=, mode=latest.

Tools missing in the client

Host has not loaded the connector: /mcp reload or restart.

Stale tool description after an edit

Same — hosts cache tools/list.

Client reports a stdio initialization timeout

This server does no network I/O at startup, so check the command path resolves; on Windows use an absolute one.

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.latest

Two 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 with npm 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, latest points at the stub and npm install hands people an inert two-file placeholder, so verify dist-tags.latest after approving rather than assuming success. Rejecting the staged version leaves that stub published, so clear it instead of leaving it dangling.

  • Plain npm publish fails 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 as npm_config_token for 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 import

publishConfig.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 tools
cd_categoriescd_categoriesA
Read-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_findA
Read-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_rawA
Read-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_topicA
Read-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_topicsA
Read-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_userA
Read-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_watchA
Read-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

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Read-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 npm
      MIT
    • F
      license
      A
      quality
      C
      maintenance
      Enables 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
      -
    • A
      license
      A
      quality
      B
      maintenance
      A 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.
      12
      21
      AGPL 3.0