From d8326f13c3308653c3c640afecc822bdc0567972 Mon Sep 17 00:00:00 2001
From: Peter Steinberger <steipete@gmail.com>
Date: Thu, 4 Jun 2026 20:27:46 -0400
Subject: [PATCH] docs: document proxy and mcp helpers

---
 src/mcp/channel-bridge.test.ts                              | 1 +
 src/mcp/channel-bridge.ts                                   | 1 +
 src/mcp/channel-server.shutdown-unhandled-rejection.test.ts | 1 +
 src/mcp/channel-server.test.ts                              | 1 +
 src/mcp/channel-server.ts                                   | 1 +
 src/mcp/channel-shared.ts                                   | 1 +
 src/mcp/channel-tools.ts                                    | 1 +
 src/mcp/openclaw-tools-serve.test.ts                        | 1 +
 src/mcp/plugin-tools-handlers.cancel.test.ts                | 1 +
 src/mcp/plugin-tools-handlers.ts                            | 1 +
 src/mcp/plugin-tools-serve.test.ts                          | 1 +
 src/mcp/tools-stdio-server.ts                               | 1 +
 src/proxy-capture/blob-store.ts                             | 1 +
 src/proxy-capture/ca.ts                                     | 1 +
 src/proxy-capture/coverage.test.ts                          | 1 +
 src/proxy-capture/coverage.ts                               | 1 +
 src/proxy-capture/env.test.ts                               | 1 +
 src/proxy-capture/env.ts                                    | 1 +
 src/proxy-capture/paths.ts                                  | 1 +
 src/proxy-capture/proxy-server.managed-proxy.test.ts        | 1 +
 src/proxy-capture/proxy-server.test.ts                      | 1 +
 src/proxy-capture/proxy-server.ts                           | 1 +
 src/proxy-capture/runtime.test.ts                           | 1 +
 src/proxy-capture/runtime.ts                                | 1 +
 src/proxy-capture/store.sqlite.test.ts                      | 1 +
 src/proxy-capture/store.sqlite.ts                           | 1 +
 26 files changed, 26 insertions(+)

diff --git a/src/mcp/channel-bridge.test.ts b/src/mcp/channel-bridge.test.ts
index 4a17e4a75deb..f25b6d48b022 100644
--- a/src/mcp/channel-bridge.test.ts
+++ b/src/mcp/channel-bridge.test.ts
@@ -1,3 +1,4 @@
+// Channel MCP bridge tests cover request bridging between MCP and channel APIs.
 import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
 import { OpenClawChannelBridge } from "./channel-bridge.js";
 
diff --git a/src/mcp/channel-bridge.ts b/src/mcp/channel-bridge.ts
index f300a3afa39b..da88b6b47f2f 100644
--- a/src/mcp/channel-bridge.ts
+++ b/src/mcp/channel-bridge.ts
@@ -1,3 +1,4 @@
+// Channel MCP bridge translates MCP tool calls into channel runtime operations.
 import { randomUUID } from "node:crypto";
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import {
diff --git a/src/mcp/channel-server.shutdown-unhandled-rejection.test.ts b/src/mcp/channel-server.shutdown-unhandled-rejection.test.ts
index 4321124b69bb..d048fe05fb81 100644
--- a/src/mcp/channel-server.shutdown-unhandled-rejection.test.ts
+++ b/src/mcp/channel-server.shutdown-unhandled-rejection.test.ts
@@ -1,3 +1,4 @@
+// Channel MCP shutdown tests cover unhandled rejection behavior during shutdown.
 import { afterEach, describe, expect, it, vi } from "vitest";
 
 const transportState = vi.hoisted(() => ({
diff --git a/src/mcp/channel-server.test.ts b/src/mcp/channel-server.test.ts
index f8c3ab5d066f..92dc5c2ab103 100644
--- a/src/mcp/channel-server.test.ts
+++ b/src/mcp/channel-server.test.ts
@@ -1,3 +1,4 @@
+// Channel MCP server tests cover channel tool registration and requests.
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { describe, expect, test, vi } from "vitest";
diff --git a/src/mcp/channel-server.ts b/src/mcp/channel-server.ts
index ae3774b3ad8a..c4a2c81b2d5f 100644
--- a/src/mcp/channel-server.ts
+++ b/src/mcp/channel-server.ts
@@ -1,3 +1,4 @@
+// Channel MCP server wires channel bridge tools into an MCP server instance.
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import type { OpenClawConfig } from "../config/types.openclaw.js";
diff --git a/src/mcp/channel-shared.ts b/src/mcp/channel-shared.ts
index 96db586ffe6b..27c90cae12b7 100644
--- a/src/mcp/channel-shared.ts
+++ b/src/mcp/channel-shared.ts
@@ -1,3 +1,4 @@
+// Shared MCP channel helpers normalize channel tool payloads and responses.
 import {
   normalizeOptionalLowercaseString,
   normalizeOptionalString as toText,
diff --git a/src/mcp/channel-tools.ts b/src/mcp/channel-tools.ts
index d36f72a8952c..f9e8c808f5be 100644
--- a/src/mcp/channel-tools.ts
+++ b/src/mcp/channel-tools.ts
@@ -1,3 +1,4 @@
+// Channel MCP tools expose channel operations through an MCP server.
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 import type { OpenClawChannelBridge } from "./channel-bridge.js";
diff --git a/src/mcp/openclaw-tools-serve.test.ts b/src/mcp/openclaw-tools-serve.test.ts
index 115e1a6e9657..121b3ad91181 100644
--- a/src/mcp/openclaw-tools-serve.test.ts
+++ b/src/mcp/openclaw-tools-serve.test.ts
@@ -1,3 +1,4 @@
+// OpenClaw MCP tools tests cover core tool server startup and registration.
 import { describe, expect, it } from "vitest";
 import { resolveOpenClawToolsForMcp } from "./openclaw-tools-serve.js";
 import { createPluginToolsMcpHandlers } from "./plugin-tools-handlers.js";
diff --git a/src/mcp/plugin-tools-handlers.cancel.test.ts b/src/mcp/plugin-tools-handlers.cancel.test.ts
index adc8f0740a35..aeb5b91fca17 100644
--- a/src/mcp/plugin-tools-handlers.cancel.test.ts
+++ b/src/mcp/plugin-tools-handlers.cancel.test.ts
@@ -1,3 +1,4 @@
+// Plugin MCP cancellation tests cover cancellation of in-flight plugin tool calls.
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
 import { describe, expect, it } from "vitest";
diff --git a/src/mcp/plugin-tools-handlers.ts b/src/mcp/plugin-tools-handlers.ts
index e31275ff2e49..879bf7d32d4a 100644
--- a/src/mcp/plugin-tools-handlers.ts
+++ b/src/mcp/plugin-tools-handlers.ts
@@ -1,3 +1,4 @@
+// Plugin MCP tool handlers route plugin tool calls through the active runtime.
 import {
   isToolWrappedWithBeforeToolCallHook,
   rewrapToolWithBeforeToolCallHook,
diff --git a/src/mcp/plugin-tools-serve.test.ts b/src/mcp/plugin-tools-serve.test.ts
index 6211019b106b..7c5a17eb6108 100644
--- a/src/mcp/plugin-tools-serve.test.ts
+++ b/src/mcp/plugin-tools-serve.test.ts
@@ -1,3 +1,4 @@
+// Plugin MCP serve tests cover serving plugin tools over MCP.
 import { afterEach, describe, expect, it, vi } from "vitest";
 import {
   type HookContext,
diff --git a/src/mcp/tools-stdio-server.ts b/src/mcp/tools-stdio-server.ts
index 7713e40b6076..af2b20b3ace0 100644
--- a/src/mcp/tools-stdio-server.ts
+++ b/src/mcp/tools-stdio-server.ts
@@ -1,3 +1,4 @@
+// MCP stdio server exposes OpenClaw tools over the MCP stdio transport.
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
diff --git a/src/proxy-capture/blob-store.ts b/src/proxy-capture/blob-store.ts
index dd8b8160fa62..e985f1d73371 100644
--- a/src/proxy-capture/blob-store.ts
+++ b/src/proxy-capture/blob-store.ts
@@ -1,3 +1,4 @@
+// Proxy capture blob store persists captured request and response bodies by hash.
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
diff --git a/src/proxy-capture/ca.ts b/src/proxy-capture/ca.ts
index 8ae1a17f6761..7f2b6f4d619d 100644
--- a/src/proxy-capture/ca.ts
+++ b/src/proxy-capture/ca.ts
@@ -1,3 +1,4 @@
+// Proxy capture CA helpers create and inspect local capture CA certificates.
 import { execFile } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
diff --git a/src/proxy-capture/coverage.test.ts b/src/proxy-capture/coverage.test.ts
index 00cedf7b7f15..eafd23714a6b 100644
--- a/src/proxy-capture/coverage.test.ts
+++ b/src/proxy-capture/coverage.test.ts
@@ -1,3 +1,4 @@
+// Proxy capture coverage tests cover capture coverage accounting and summaries.
 import { describe, expect, it } from "vitest";
 import { buildDebugProxyCoverageReport } from "./coverage.js";
 
diff --git a/src/proxy-capture/coverage.ts b/src/proxy-capture/coverage.ts
index dffafcd7c534..b058f2ccd0ea 100644
--- a/src/proxy-capture/coverage.ts
+++ b/src/proxy-capture/coverage.ts
@@ -1,3 +1,4 @@
+// Proxy capture coverage helpers summarize which network calls were captured.
 import process from "node:process";
 import { resolveDebugProxySettings, type DebugProxySettings } from "./env.js";
 import type { CaptureProtocol } from "./types.js";
diff --git a/src/proxy-capture/env.test.ts b/src/proxy-capture/env.test.ts
index d34fc28d8976..d93634220c3c 100644
--- a/src/proxy-capture/env.test.ts
+++ b/src/proxy-capture/env.test.ts
@@ -1,3 +1,4 @@
+// Proxy capture env tests cover environment variable generation for capture sessions.
 import { describe, expect, it } from "vitest";
 import {
   OPENCLAW_DEBUG_PROXY_ENABLED,
diff --git a/src/proxy-capture/env.ts b/src/proxy-capture/env.ts
index fa1d65a3e868..5567dc8c6b03 100644
--- a/src/proxy-capture/env.ts
+++ b/src/proxy-capture/env.ts
@@ -1,3 +1,4 @@
+// Proxy capture env helpers build proxy-related env vars for child processes.
 import { randomUUID } from "node:crypto";
 import type { Agent } from "node:http";
 import process from "node:process";
diff --git a/src/proxy-capture/paths.ts b/src/proxy-capture/paths.ts
index d3c09f0c415e..ce3dce3a9290 100644
--- a/src/proxy-capture/paths.ts
+++ b/src/proxy-capture/paths.ts
@@ -1,3 +1,4 @@
+// Proxy capture path helpers resolve capture directories and database paths.
 import path from "node:path";
 import { resolveStateDir } from "../config/paths.js";
 
diff --git a/src/proxy-capture/proxy-server.managed-proxy.test.ts b/src/proxy-capture/proxy-server.managed-proxy.test.ts
index e56677f39b4b..084915e2a0c2 100644
--- a/src/proxy-capture/proxy-server.managed-proxy.test.ts
+++ b/src/proxy-capture/proxy-server.managed-proxy.test.ts
@@ -1,3 +1,4 @@
+// Managed proxy tests cover proxy server lifecycle with managed capture files.
 import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import { createServer as createHttpServer } from "node:http";
 import { Socket, type AddressInfo } from "node:net";
diff --git a/src/proxy-capture/proxy-server.test.ts b/src/proxy-capture/proxy-server.test.ts
index fc120f527f38..2829964728df 100644
--- a/src/proxy-capture/proxy-server.test.ts
+++ b/src/proxy-capture/proxy-server.test.ts
@@ -1,3 +1,4 @@
+// Proxy capture server tests cover request recording and response handling.
 import { describe, expect, it } from "vitest";
 import { parseConnectTarget } from "./proxy-server.js";
 
diff --git a/src/proxy-capture/proxy-server.ts b/src/proxy-capture/proxy-server.ts
index c1ebd4550296..b933a77b2c43 100644
--- a/src/proxy-capture/proxy-server.ts
+++ b/src/proxy-capture/proxy-server.ts
@@ -1,3 +1,4 @@
+// Proxy capture server records proxied HTTP traffic for deterministic test fixtures.
 import { randomUUID } from "node:crypto";
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
 import { request as httpRequest } from "node:http";
diff --git a/src/proxy-capture/runtime.test.ts b/src/proxy-capture/runtime.test.ts
index 166ffa1cc2e2..eb71fbc4a048 100644
--- a/src/proxy-capture/runtime.test.ts
+++ b/src/proxy-capture/runtime.test.ts
@@ -1,3 +1,4 @@
+// Proxy capture runtime tests cover session creation and capture lifecycle.
 import { beforeEach, describe, expect, it } from "vitest";
 import type { DebugProxySettings } from "./env.js";
 import {
diff --git a/src/proxy-capture/runtime.ts b/src/proxy-capture/runtime.ts
index 55bf1ebca355..45e111d04078 100644
--- a/src/proxy-capture/runtime.ts
+++ b/src/proxy-capture/runtime.ts
@@ -1,3 +1,4 @@
+// Proxy capture runtime coordinates capture sessions, proxy startup, and storage.
 import { randomUUID } from "node:crypto";
 import { URL } from "node:url";
 import { normalizeRequestInitHeadersForFetch } from "../infra/fetch-headers.js";
diff --git a/src/proxy-capture/store.sqlite.test.ts b/src/proxy-capture/store.sqlite.test.ts
index dafd07464f11..49549a65bc31 100644
--- a/src/proxy-capture/store.sqlite.test.ts
+++ b/src/proxy-capture/store.sqlite.test.ts
@@ -1,3 +1,4 @@
+// Proxy capture SQLite store tests cover persisted capture reads and writes.
 import { mkdtempSync, rmSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
diff --git a/src/proxy-capture/store.sqlite.ts b/src/proxy-capture/store.sqlite.ts
index a085dfab7165..60451a401517 100644
--- a/src/proxy-capture/store.sqlite.ts
+++ b/src/proxy-capture/store.sqlite.ts
@@ -1,3 +1,4 @@
+// Proxy capture SQLite store persists capture metadata and replayable exchanges.
 import fs from "node:fs";
 import path from "node:path";
 import type { DatabaseSync } from "node:sqlite";