fix: resolve discourse-mcp TS2345 build error and add env-var auth

The discourse-mcp was BLOCKED with a TypeScript TS2345 error caused by
the Dockerfile forcing SDK ^1.23.0 via `pnpm add`, while the upstream
code requires the lockfile's v1.17.3. Removed the override to use
`pnpm install --frozen-lockfile`.

The upstream server does not read environment variables directly — it
requires CLI args (--auth-pairs, --site) or a --profile JSON file. Added
a docker-entrypoint.sh that converts DISCOURSE_URL, DISCOURSE_API_KEY,
and DISCOURSE_API_USERNAME env vars into a profile JSON with auth_pairs
and site tethering.

Validated end-to-end: MCP handshake passes, site auto-tethers on startup,
live tool calls (discourse_search, discourse_filter_topics) return real
data from community.turnsys.com.

Updates STATUS.md and README.md to reflect discourse-mcp as production
ready. Adds JOURNAL.md entries for discourse-cli, discourse-mcp fix, and
protocol improvements.

💘 Generated with Crush

Assisted-by: Crush:glm-5.2
This commit is contained in:
2026-07-30 16:53:12 -05:00
parent e2d4bb333c
commit 11ec4cf4a3
5 changed files with 125 additions and 7 deletions
+64
View File
@@ -1924,3 +1924,67 @@ is the canonical home for all AI middleware going forward.
`tea` commands run on the host; everything else is containerized. Custom images
are published to the Gitea container registry at
`git.knownelement.com/reachableceo/<image>`.
## 2026-07-30
### [ADR] discourse-cli: Standalone CLI for Discourse (following redmine-cli pattern)
**Date/Time**: 2026-07-30 5:50 PM EST
**Type**: Implementation
**Status**: Accepted
**Context**: The existing discourse-mcp was BLOCKED (TS2345 build error), but
the redmine-cli pattern (standalone CLI container, on-demand via docker run)
provides a reliable alternative for Crush (which has Docker/CLI access).
**Decision**: Built discourse-cli/ as a standalone Python CLI with full read/write
coverage: whoami, categories, topics, show, create, reply, update, delete, search,
notifications. Uses requests library with JSON body encoding for POST/PUT/DELETE.
Validated 10/10 against community.turnsys.com.
**Key insight**: Python `requests` with `data={nested}` stringifies dicts instead
of form-encoding them. Must use `json=data` for nested payloads to Discourse API.
The `/session/current.json` endpoint doesn't work with API keys (returns 403);
use `/notifications.json` or `/u/<username>.json` instead for connection tests.
### [ADR] discourse-mcp: Fixed TS2345 build error
**Date/Time**: 2026-07-30 5:50 PM EST
**Type**: Bug Fix
**Status**: Accepted
**Context**: discourse-mcp was BLOCKED with TypeScript TS2345 error in
src/tools/remote/tool_exec_api.ts:58. The Dockerfile was forcing
`@modelcontextprotocol/sdk@^1.23.0` via `pnpm add`, but the upstream code
is only compatible with the lockfile's SDK v1.17.3.
**Decision**: Removed the `pnpm add @modelcontextprotocol/sdk@^1.23.0` line
from the Dockerfile. Using `pnpm install --frozen-lockfile` instead.
**Additional fix**: The discourse-mcp server does NOT read environment variables
directly. It requires CLI args (`--auth-pairs`, `--site`) or a `--profile` JSON
file. Added a docker-entrypoint.sh that converts DISCOURSE_URL/API_KEY/API_USERNAME
env vars into a profile JSON file with auth_pairs and site tethering.
**Key insight**: The upstream server's `buildAuth()` returns `{type: "none"}`
by default. Auth comes from auth_pairs overrides in the profile. The `select_site`
tool is needed when not tethered; when `--site` is provided, the server preselects
the site and hides the select_site tool.
Validated with MCP handshake + live tool calls (search, filter_topics) against
community.turnsys.com.
### Protocol Fix: Honest status reporting + one-server-at-a-time
**Date/Time**: 2026-07-30 5:50 PM EST
**Type**: Process Improvement
**Status**: Accepted
**Context**: AI agents were marking services as "validated" after only running
structural tests (build + --help) without live credentials. Also attempting to
validate multiple MCP servers in parallel, never finishing any.
**Decision**: Added two mandatory rules to AGENTS.md:
1. Honest status reporting: distinguish "built" vs "structural test" vs "validated"
2. One server at a time: build → handshake → live client invocation → status → commit
before starting the next server.