feat(ai): add administration toolsets

Add opt-in domains for managing AI agents, scripted custom tools, and AI feature settings with admin and write safeguards. Include compact discovery views, import/export support, custom-tool authoring guidance, and conditional resource registration.

Prevent sensitive HTTP response bodies from reaching logs and handle empty 204 responses from delete operations.

Author: SamSaffron

README.md

@@ -88,13 +88,13 @@ The server registers tools under the MCP server name `@discourse/mcp`. Choose a
   - `--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
+    - `debug`: Shows HTTP request URLs, statuses, and detailed network/retry information (response bodies are never logged because admin APIs may echo sensitive content)
     - `info`: Shows retry attempts and general operational messages
     - `error`: Shows only errors
     - `silent`: No logging output
   - `--show_emails` (default: false). includes emails in user tools. Requires admin access
   - `--tools_mode <auto|discourse_api_only|tool_exec_api>` (default: auto)
-  - `--toolsets <name[,name...]>`: Expose selected built-in domains. Omit for the default catalog (all non-opt-in domains); use `--toolsets all` to include opt-in domains such as `workflows`. See [Built-in toolsets](#built-in-toolsets).
+  - `--toolsets <name[,name...]>`: Expose selected built-in domains. Omit for the default catalog (all non-opt-in domains); use `--toolsets all` to include opt-in workflows and AI administration domains. See [Built-in toolsets](#built-in-toolsets).
   - `--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`.
@@ -151,7 +151,7 @@ Flags still override values from the profile.
 
 ### Built-in toolsets
 
-Toolsets let an operator expose only the built-in domains needed by an MCP client. They are optional: when `--toolsets` and the profile field are both omitted, the server registers the default catalog (all non-opt-in domains). The experimental admin-only `workflows` domain is opt-in. Use `--toolsets all` to explicitly load every domain.
+Toolsets let an operator expose only the built-in domains needed by an MCP client. They are optional: when `--toolsets` and the profile field are both omitted, the server registers the default catalog (all non-opt-in domains). The admin-only `workflows`, `ai_agents`, `ai_custom_tools`, and `ai_features` domains are opt-in. Use `--toolsets all` to explicitly load every domain.
 
 Pass one name or a comma-separated union:
 
@@ -201,6 +201,9 @@ Available toolsets are:
 | `uploads` | File upload |
 | `data_explorer` | Query retrieval, execution, creation, update, and deletion |
 | `workflows` *(opt-in)* | Admin-only workflow discovery, graph authoring, expression evaluation, pin-data, draft runs, step runs, executions, and version management |
+| `ai_agents` *(opt-in)* | Admin-only AI agent discovery, typed lifecycle, bot-user creation, and portable import/export |
+| `ai_custom_tools` *(opt-in)* | Admin-only database-backed scripted custom-tool guide, lifecycle, actual execution testing, and import/export |
+| `ai_features` *(opt-in)* | Admin-only AI feature discovery and exact-area, non-secret feature-setting updates; also includes agent discovery |
 | `all` *(sentinel)* | Expands to every built-in toolset, including opt-in domains; absorbs other selections |
 
 Toolset membership is intentionally separate from safety and authorization:
@@ -227,6 +230,32 @@ The `workflows` toolset targets the experimental `discourse-workflows` plugin (`
 
 Flat connections such as `[{"from":"Start","to":"Check","type":"main"}]` are accepted and converted to Discourse's nested wire format. Use the source node's catalog output key: condition/filter ports are `true` and `false`, not always `main`. MCP rejects one-sided graph updates before HTTP. Runs are not dry-runs and can create posts, send chat messages, or call external HTTP.
 
+#### Discourse AI administration
+
+The three AI administration domains require a Discourse admin API key (or an admin user API key accepted by the selected endpoint). They are independently opt-in and default-off. Mutations—and custom-tool test execution—also require both `--allow_writes` and `--read_only=false`.
+
+```bash
+# Configure agents without exposing scripted source management
+npx -y @discourse/mcp@latest --site https://forum.example.com \
+  --toolsets ai_agents --tools_mode discourse_api_only \
+  --auth_pairs '[{"site":"https://forum.example.com","api_key":"...","api_username":"system"}]' \
+  --allow_writes --read_only=false
+
+# Assign agents and update safe feature settings, but do not expose custom-tool code editing
+npx -y @discourse/mcp@latest --site https://forum.example.com \
+  --toolsets ai_agents,ai_features --tools_mode discourse_api_only \
+  --auth_pairs '[{"site":"https://forum.example.com","api_key":"...","api_username":"system"}]' \
+  --allow_writes --read_only=false
+```
+
+The agent index is intentionally concise by default: `discourse_ai_list_agents` omits system prompts and per-agent configuration, returning summary counts plus slim tool/model catalogs. Use `discourse_ai_get_agent` with an ID to inspect one full configuration. `view: "full"` is available only for clients that explicitly need the complete upstream index.
+
+`discourse_ai_list_custom_tools` follows the same pattern: it returns compact records and preset signatures without scripts, bindings, or verbose parameter documentation. Use `discourse_ai_get_custom_tool` for one stored tool, or call the guide with `topic: "presets"` and a `preset_id` for one complete preset example.
+
+`ai_custom_tools` manages Discourse's database-backed `AiTool` records. It is separate from remote tools dynamically discovered at `/ai/tools`, which remain controlled by `--tools_mode`. Script authoring is synchronous MiniRacer JavaScript: define `invoke(parameters)`; do not use `async`, browser APIs, or Node modules. Call `discourse_ai_get_custom_tool_guide` with only the focused `topic` you need. `preset_id` is optional and meaningful only for `topic: "presets"`; it is ignored for other topics. Use `topic: "preamble"` for the exact selected-server contract before creating or substantially changing a script. The same exact live preamble and minimal template is exposed as the conditional `discourse://ai/custom-tools/authoring-guide` resource when this toolset is selected. Resources are application-driven; the guide tool is model-controlled, so autonomous clients should use the tool rather than assume a host attached the resource. A future optional authoring prompt would be user-controlled and would guide an explicitly initiated workflow rather than replace model-callable discovery.
+
+**Safety:** `discourse_ai_test_custom_tool` actually executes code and can issue external requests or cause site side effects. Feature updates alter production behavior immediately and are limited to non-secret settings returned from one exact `ai-features/<module>` area. Custom-tool source, prompts, bindings, exports, and test parameters should be treated as sensitive. Use the narrowest toolset combination and test on a non-production site first.
+
 - **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.
@@ -278,6 +307,12 @@ Resources provide static/semi-static read-only data via URI addressing. Use thes
   - Output: `{ drafts: [{draft_key, sequence, title, category_id, created_at, reply_preview}], meta: {total} }`
   - Requires authentication
 
+- **discourse://ai/custom-tools/authoring-guide** *(conditional)*
+  - Registered only when `ai_custom_tools` is selected (including through `all`)
+  - Returns the exact selected-site `empty_tool` JavaScript preset: Discourse's current preamble plus minimal `invoke`/`details` template
+  - MIME type: `text/javascript`; requires selected-site admin credentials
+  - Applications may attach this resource; models can retrieve the same content with `discourse_ai_get_custom_tool_guide` and `topic: "preamble"`
+
 ## Tools
 
 Built‑in tools (always present unless noted). All tools return **strict JSON** (no Markdown).
@@ -540,7 +575,7 @@ You can also manually create User API Keys via the Discourse UI (if enabled by t
 - **Should I use Admin API Keys or User API Keys?** Use User API Keys for personal use (no admin required). Use Admin API Keys only when you need admin-level operations or are setting up a system-wide integration.
 - **Getting "fetch failed" errors?** Run with `--log_level debug` to see detailed error information including:
   - The exact URL being requested
-  - HTTP status codes and response bodies
+  - HTTP status codes (response bodies are deliberately not logged because they may contain sensitive content)
   - Network-level errors (DNS, SSL/TLS, connectivity issues)
   - Retry attempts and timing
   - Timeout diagnostics

src/http/client.ts

@@ -136,9 +136,13 @@ export class HttpClient {
         if (!res.ok) {
           const text = await safeText(res);
           const errorBody = safeJson(text);
-          this.opts.logger.error(`HTTP ${res.status} ${res.statusText} for ${method} ${url}: ${text}`);
+          // Keep response bodies available on HttpError for structured client
+          // errors, but never write them to logs: admin endpoints can echo
+          // prompts, scripts, bindings, import bundles, or test parameters.
+          this.opts.logger.error(`HTTP ${res.status} ${res.statusText} for ${method} ${url}`);
           throw new HttpError(res.status, `HTTP ${res.status} ${res.statusText}`, errorBody);
         }
+        if (res.status === 204) return {};
         const ct = res.headers.get("content-type") || "";
         if (ct.includes("application/json")) {
           return res.json();

src/index.ts

@@ -102,7 +102,7 @@ const ProfileSchema = z
     log_level: z.enum(["silent", "error", "info", "debug"]).optional().default("info"),
     show_emails: z.boolean().optional().default(false),
     tools_mode: z.enum(["auto", "discourse_api_only", "tool_exec_api"]).optional().default("auto"),
-    toolsets: BuiltinToolsetsSchema.optional().describe("Built-in tool domains to expose (array or comma-separated string). Omit for the default catalog; use all to include opt-in domains such as workflows."),
+    toolsets: BuiltinToolsetsSchema.optional().describe("Built-in tool domains to expose (array or comma-separated string). Omit for the default catalog; use all to include opt-in workflows and AI administration domains."),
     site: z.string().url().optional().describe("Tether MCP to a single Discourse site; hides select_site and preselects this site"),
     default_search: z.string().optional().describe("Optional search prefix added to every search query (set via --default-search)"),
     max_read_length: z
@@ -307,7 +307,7 @@ async function main() {
   });
 
   // Register MCP resources (URI-addressable read-only data)
-  registerAllResources(server, { siteState, logger });
+  registerAllResources(server, { siteState, logger }, { toolsets: config.toolsets });
 
   // Register MCP prompts (guided workflows)
   registerAllPrompts(server, { siteState, logger });

src/resources/ai_custom_tools.ts

@@ -0,0 +1,22 @@
+import { requireAdminAccess } from "../util/access.js";
+import type { ResourceContext, ResourceRegistrar } from "./registry.js";
+import { GUIDE_RESOURCE_URI } from "../tools/builtin/ai_custom_tools/guide_data.js";
+import { loadLiveAuthoringGuide } from "../tools/builtin/ai_custom_tools/guide.js";
+
+export function registerAiCustomToolsAuthoringGuideResource(server: ResourceRegistrar, ctx: ResourceContext): void {
+  server.resource(
+    "ai_custom_tools_authoring_guide",
+    GUIDE_RESOURCE_URI,
+    { title: "Discourse AI Custom Tool Authoring Guide", description: "Authoritative selected-site JavaScript preamble and minimal MiniRacer tool template. Admin-only; intended for assistant authoring context.", mimeType: "text/javascript" },
+    async (uri) => {
+      const access = requireAdminAccess(ctx.siteState);
+      if (access) throw new Error("Selected-site admin API credentials are required to read this resource.");
+      try {
+        const guide = await loadLiveAuthoringGuide(ctx.siteState);
+        return { contents: [{ uri: uri.href, mimeType: "text/javascript", text: guide.text }] };
+      } catch (error) {
+        throw new Error(`Failed to load the live empty_tool preamble: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    },
+  );
+}

src/resources/registry.ts

@@ -27,6 +27,8 @@ import {
   registerExplorerSchemaResource,
   registerExplorerQueriesResource,
 } from "./data_explorer.js";
+import { registerAiCustomToolsAuthoringGuideResource } from "./ai_custom_tools.js";
+import type { BuiltinToolsetMembership } from "../tools/toolsets.js";
 
 /** Narrowed interface for resource registration - only requires resource method */
 export type ResourceRegistrar = Pick<McpServer, "resource">;
@@ -40,9 +42,14 @@ export interface ResourceContext {
  * Registers all MCP resources.
  * Resources are read-only, URI-addressable data endpoints.
  */
+export interface ResourceRegistrationOptions {
+  toolsets?: BuiltinToolsetMembership;
+}
+
 export function registerAllResources(
   server: ResourceRegistrar,
-  ctx: ResourceContext
+  ctx: ResourceContext,
+  opts: ResourceRegistrationOptions = {},
 ): void {
   registerCategoriesResource(server, ctx);
   registerTagsResource(server, ctx);
@@ -54,6 +61,10 @@ export function registerAllResources(
   // Data Explorer resources are always registered; access is checked at call time
   registerExplorerSchemaResource(server, ctx);
   registerExplorerQueriesResource(server, ctx);
+
+  if (opts.toolsets?.includes("ai_custom_tools")) {
+    registerAiCustomToolsAuthoringGuideResource(server, ctx);
+  }
 }
 
 /**