discourse-mcp: Instructions file for Codex

Discourse MCP — Agent Guide

What this is

• Purpose: An MCP (Model Context Protocol) stdio server that exposes Discourse forum capabilities as tools for AI agents.
• Entry point: src/index.ts → compiled to dist/index.js (binary name: discourse-mcp).
• SDK: @modelcontextprotocol/sdk. Node ≥ 18.

How it works

• On start, the server validates CLI flags via Zod, constructs a dynamic site state, and registers tools on an MCP server named @discourse/mcp.
• Choose a target Discourse site by either:
  • Calling the discourse_select_site tool (validates via /about.json), or
  • Starting with --site <url> to tether to a single site (validates via /about.json and hides discourse_select_site).
• Outputs are text-oriented; some tools embed compact JSON in fenced code blocks for structured extraction.

Authentication & permissions

• Supported auth:
  • None (read-only public data)
  • Per-site overrides via --auth_pairs, e.g. [{"site":"https://example.com","api_key":"...","api_username":"system"}].
• Writes are disabled by default. Write tools (discourse_create_post, discourse_create_topic, discourse_create_category, discourse_create_user) are only registered when all are true:
  • --allow_writes AND not --read_only AND a matching auth_pairs entry exists for the selected site.
• Secrets are never logged; config is redacted before logging.

Tools exposed (built-in)

• discourse_search
  • Input: { query: string; with_private?: boolean; max_results?: number (1–50, default 10) }
  • Output: Top topics with titles and URLs; appends a JSON footer of { results: [{ id, url, title }] } inside a fenced block.
• discourse_read_topic
  • Input: { topic_id: number; post_limit?: number (1–20, default 5); start_post_number?: number }
  • Output: Title, category, tags, and the first N posts (raw preferred when available) up to the configured max read length per post; includes canonical topic link.
• discourse_read_post
  • Input: { post_id: number }
  • Output: Author, timestamp, content (raw preferred) truncated to the configured max read length, and a direct link.
• discourse_list_categories
  • Input: {}
  • Output: Category names with topic counts.
• discourse_list_tags
  • Input: {}
  • Output: Tags with usage counts (or notice if tags are disabled).
• discourse_get_user
  • Input: { username: string }
  • Output: Display name, trust level, joined date, short bio, and profile link.
• discourse_filter_topics
  • Input: { filter: string; page?: number; per_page?: number (1–50) }
  • Output: Paginated topic list with titles and URLs; appends a JSON footer { page, per_page, results: [{ id, url, title }], next_url? }.
  • Query language: key:value tokens separated by spaces; category/categories (comma = OR, =category = without subcats, - exclude); tag/tags (comma = OR, + = AND) and tag_group; status:(open|closed|archived|listed|unlisted|public); personal in: (bookmarked|watching|tracking|muted|pinned); dates created/activity/latest-post-(before|after) as YYYY-MM-DD or N days; numeric likes[-op]-(min|max), posts-(min|max), posters-(min|max), views-(min|max); order: with optional -asc; free text terms allowed.
• discourse_create_post (conditionally available; see permissions)
  • Input: { topic_id: number; raw: string (≤ 30k chars) }
  • Output: Link to created post/topic. Includes a simple 1 req/sec rate limit.
• discourse_create_topic (conditionally available; see permissions)
  • Input: { title: string; raw: string (≤ 30k chars); category_id?: number; tags?: string[] }
  • Output: Link to created topic. Includes a simple 1 req/sec rate limit.
• discourse_create_category (conditionally available; see permissions)
  • Input: { name: string; color?: hex; text_color?: hex; parent_category_id?: number; description?: string }
  • Output: Link to created category. Includes a simple 1 req/sec rate limit.
• discourse_select_site (hidden when --site is provided)
  • Input: { site: string }
  • Output: Confirms selection; validates via /about.json. Triggers remote tool discovery when enabled.