# discourse-mcp
## 基本信息
- Slug: `discourse-discourse-mcp`
- Source: modelscope
- Publisher: @discourse/discourse-mcp
- Categories: content-management-systems / app-automation
- Hosted: No
- License: MIT License
- Source URL: https://www.modelscope.cn/mcp/servers/@discourse/discourse-mcp
## 简介
暂无描述。
## 安装提示

```bash
npx -y @discourse/mcp@latest
```

## MCP Server 详情

## Discourse MCP

A Model Context Protocol (MCP) 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

### Quick start (release)

- **Run (readonly, recommended to start)**
```bash
npx -y @discourse/mcp@latest
```
Then, in your MCP client, either:
- Call the `discourse_select_site` tool with `{ "site": "https://try.discourse.org" }` to choose a site, or
- Start the server tethered to a site using `--site https://try.discourse.org` (in which case `discourse_select_site` is hidden).

- **Enable writes (optin, safeguarded)**
```bash
npx -y @discourse/mcp@latest --allow_writes --read_only=false --auth_pairs '[{"site":"https://try.discourse.org","api_key":"'$DISCOURSE_API_KEY'","api_username":"system"}]'
```

- **Use in an MCP client (example: Claude Desktop)  via npx**
```json
{
  "mcpServers": {
    "discourse": {
      "command": "npx",
      "args": ["-y", "@discourse/mcp@latest"],
      "env": {}
    }
  }
}
```

> Alternative: if you prefer a global binary after install, the package exposes `discourse-mcp`.
> ```json
> {
>   "mcpServers": {
>     "discourse": { "command": "discourse-mcp", "args": [] }
>   }
> }
> ```

## Configuration

The server registers tools under the MCP server name `@discourse/mcp`. Choose a target Discourse site either by:
- Using the `discourse_select_site` tool at runtime (validates via `/about.json`), or
- Supplying `--site <url>` to tether the server to a single site at startup (validates via `/about.json` and hides `discourse_select_site`).

- **Auth**
  - **None** by default.
  - **Admin API Keys** (require admin permissions): **`--auth_pairs '[{"site":"https://example.com","api_key":"...","api_username":"system"}]'`**
  - **User API Keys** (any user can generate): **`--auth_pairs '[{"site":"https://example.com","user_api_key":"...","user_api_client_id":"..."}]'`**
  - You can include multiple entries in `auth_pairs`; the matching entry is used for the selected site. If both `user_api_key` and `api_key` are provided for the same site, `user_api_key` takes precedence.

- **Write safety**
  - Writes are disabled by default.
  - The tools `discourse_create_post`, `discourse_create_topic`, `discourse_create_category`, and `discourse_create_user` are only registered when all are true:
    - `--allow_writes` AND not `--read_only` AND some auth is configured (either default flags or a matching `auth_pairs` entry).
  - A ~1 req/sec rate limit is enforced for write actions.

- **Flags & defaults**
  - `--read_only` (default: true)
  - `--allow_writes` (default: false)
  - `--timeout_ms <number>` (default: 15000)
  - `--concurrency <number>` (default: 4)
  - `--log_level <silent|error|info|debug>` (default: info)
    - `debug`: Shows all HTTP requests, responses, and detailed error information
    - `info`: Shows retry attempts and general operational messages
    - `error`: Shows only errors
    - `silent`: No logging output
  - `--tools_mode <auto|discourse_api_only|tool_exec_api>` (default: auto)
  - `--site <url>`: Tether MCP to a single site and hide `discourse_select_site`.
  - `--default-search <prefix>`: Unconditionally prefix every search query (e.g., `tag:ai order:latest`).
  - `--max-read-length <number>`: Maximum characters returned for post content (default 50000). Applies to `discourse_read_post` and per-post content in `discourse_read_topic`. The tools prefer `raw` content by requesting `include_raw=true`.
  - `--transport <stdio|http>` (default: stdio): Transport type. Use `stdio` for standard input/output (default), or `http` for Streamable HTTP transport (stateless mode with JSON responses).
  - `--port <number>` (default: 3000): Port to listen on when using HTTP transport.
  - `--cache_dir <path>` (reserved)
  - `--profile <path.json>` (see below)

- **Profile file** (keep secrets off the command line)
```json
{
  "auth_pairs": [
    { "site": "https://try.discourse.org", "api_key": "<redacted>", "api_username": "system" },
    { "site": "https://example.com", "user_api_key": "<user_api_key>", "user_api_client_id": "<client_id>" }
  ],
  "read_only": false,
  "allow_writes": true,
  "log_level": "info",
  "tools_mode": "auto",
  "site": "https://try.discourse.org",
  "default_search": "tag:ai order:latest",
  "max_read_length": 50000,
  "transport": "stdio",
  "port": 3000
}
```
Run with:
```bash
node dist/index.js --profile /absolute/path/to/profile.json
```
Flags still override values from the profile.

- **Remote Tool Execution API (optional)**
  - With `tools_mode=auto` (default) or `tool_exec_api`, the server discovers remote tools via GET `/ai/tools` after you select a site (or immediately at startup if `--site` is provided) and registers them dynamically. Set `--tools_mode=discourse_api_only` to disable remote tool discovery.

- **Networking & resilience**
  - Retries on 429/5xx with backoff (3 attempts).
  - Lightweight inmemory GET cache for selected endpoints.

- **Privacy**
  - Secrets are redacted in logs. Errors are returned as humanreadable messages to MCP clients.

## Tools

Builtin tools (always present unless noted):

- `discourse_search`
  - Input: `{ query: string; with_private?: boolean; max_results?: number (150, default 10) }`
  - Output: text summary plus a compact footer like:
    ```json
    { "results": [{ "id": 123, "url": "https://", "title": "" }] }
    ```
- `discourse_read_topic`
  - Input: `{ topic_id: number; post_limit?: number (120, default 5) }`
- `discourse_read_post`
  - Input: `{ post_id: number }`
- `discourse_list_categories`
  - Input: `{}`
- `discourse_list_tags`
  - Input: `{}`
- `discourse_get_user`
  - Input: `{ username: string }`
- `discourse_filter_topics`
  - Input: `{ filter: string; page?: number (default 1); per_page?: number (150) }`
  - Query language (succinct): key:value tokens separated by spaces; category/categorie…