discourse-mcp/AGENTS.md

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.

Remote Tool Execution API (optional)

• If the target Discourse site exposes an MCP-compatible Tool Execution API:
  • GET /ai/tools is discovered after selecting a site when tools_mode is auto (default) or tool_exec_api (or immediately at startup if --site is provided).
  • Each remote tool is registered dynamically using its JSON Schema input.
  • Calls POST /ai/tools/{name}/call with { arguments, context: {} }.
  • Results may include details.artifacts[]; links are surfaced at the end of the tool output.
• Set --tools_mode=discourse_api_only to disable remote tool discovery.

CLI configuration

• Optional flags:
  • --auth_pairs (JSON)
  • --read_only (default true), --allow_writes (default false)
  • --timeout_ms <number> (default 15000)
  • --concurrency <number> (default 4)
  • --cache_dir <path> (currently unused; in-memory caching is built-in)
  • --log_level <silent|error|info|debug> (default info)
  • --tools_mode <auto|discourse_api_only|tool_exec_api> (default auto)
  • --profile <path.json>: load partial config from JSON (flags override)
  • --site <url>: tether to a single site (hides discourse_select_site)
  • --default-search <prefix>: unconditionally prefix every search query (e.g., category:support tag:ai)
  • --max-read-length <number> (default 50000): maximum number of characters returned for post content in discourse_read_post and per-post content in discourse_read_topic. Tools prefer raw content via Discourse API (include_raw=true) when available.

Networking & resilience

• User-Agent: Discourse-MCP/0.x (+https://github.com/discourse-mcp).
• Retries on 429/5xx with backoff (3 attempts).
• Lightweight in-memory GET cache for selected endpoints (e.g., topics, site metadata).

Errors & rate limits

• Tool failures return isError: true with human-readable messages.
• discourse.create_post and discourse.create_category enforce ~1 request/second to avoid flooding.

Source map

• MCP server and CLI: src/index.ts
• HTTP client: src/http/client.ts
• Tool registry: src/tools/registry.ts
• Built-in tools: src/tools/builtin/*
• Remote tools: src/tools/remote/tool_exec_api.ts
• Logging/redaction: src/util/logger.ts, src/util/redact.ts

Quick start (for human operators)

• Build: pnpm build
• Run: node dist/index.js
• Select site with discourse_select_site in your client