Open-source SEO, GEO, and marketing skills for AI agents.
refactor(mcp): extract shared rpc helper from mcp-state
Yuting Zhongad1ae0eeb30a
diff --git a/src/server/mcp-state.ts b/src/server/mcp-state.tsindex 30b41694..b1ceed4f 100644--- a/src/server/mcp-state.ts+++ b/src/server/mcp-state.ts@@ -1,4 +1,5 @@import { openclaw, OpenClawError } from "@/server/openclaw/cli";+import { bearerFromHeaders, mcpRpc, readMcpConfigRow } from "@/server/mcp/rpc";/*** Read the merged state of a configured MCP server from OpenClaw + a fast@@ -11,6 +12,9 @@ import { openclaw, OpenClawError } from "@/server/openclaw/cli";* - "connected": row + token + probe succeeded* - "stale_token": row + token but probe came back 401/403* - "unreachable": row + token but probe failed (network/timeout/5xx)+ *+ * HTTP plumbing (config-read, bearer parse, JSON-RPC POST, SSE handling)+ * lives in `@/server/mcp/rpc`. This file owns only the UI status mapping.*/export type McpRuntimeStatus =@@ -35,35 +39,8 @@ export type McpRuntimeStatus =last_checked_at: string;};-type McpConfigRow = {- url?: string;- transport?: string;- headers?: Record<string, string>;-};--async function readMcpConfig(key: string): Promise<McpConfigRow | null> {- try {- const out = await openclaw(["mcp", "show", key], { json: true });- if (!out || typeof out !== "object") return null;- return out as McpConfigRow;- } catch (err) {- // OpenClaw exits non-zero when the key is unknown — treat as "not configured".- if (err instanceof OpenClawError) return null;- throw err;- }-}--function bearerFromHeaders(headers: Record<string, string> | undefined): string | null {- if (!headers) return null;- // Headers can arrive case-mixed; check both common spellings.- const raw = headers.Authorization ?? headers.authorization;- if (!raw) return null;- const m = raw.match(/^Bearer\s+(.+)$/i);- return m ? m[1].trim() : null;-}-export async function getMcpStatus(key: string): Promise<McpRuntimeStatus> {- const config = await readMcpConfig(key);+ const config = await readMcpConfigRow(key);if (!config || !config.url) return { state: "not_configured" };const url = config.url;const token = bearerFromHeaders(config.headers);@@ -72,71 +49,64 @@ export async function getMcpStatus(key: string): Promise<McpRuntimeStatus> {}/**- * Lightweight liveness probe. We POST a JSON-RPC `tools/list` — that's the- * cheapest MCP call that exercises auth + transport in one round-trip.- * 2s timeout: this is rendered server-side on the MCP tab and we'd rather- * show "unreachable" than block the page.+ * Lightweight liveness probe. POSTs JSON-RPC `tools/list` — the cheapest MCP+ * call that exercises auth + transport in one round-trip. 2s timeout: this+ * renders server-side on the MCP tab and we'd rather show "unreachable" than+ * block the page.*/async function probe(url: string, token: string): Promise<McpRuntimeStatus> {const last_checked_at = new Date().toISOString();- try {- const controller = new AbortController();- const t = setTimeout(() => controller.abort(), 2000);- let res: Response;- try {- res = await fetch(url, {- method: "POST",- headers: {- "Content-Type": "application/json",- Accept: "application/json, text/event-stream",- Authorization: `Bearer ${token}`,- },- body: JSON.stringify({- jsonrpc: "2.0",- id: 1,- method: "tools/list",- params: {},- }),- signal: controller.signal,- });- } finally {- clearTimeout(t);- }- if (res.status === 401 || res.status === 403) {- return { state: "stale_token", url, http_status: res.status, last_checked_at };- }- if (!res.ok) {- return {- state: "unreachable",- url,- error: `HTTP ${res.status}`,- last_checked_at,- };- }- // MCP can stream SSE for tools/list. Either format carries the JSON in a- // single frame, so a substring count of `"name"` is a decent- // tool-count proxy without paying for full SSE parsing here.- const text = await res.text();- const tools_count = countTools(text);- return { state: "connected", url, tools_count, last_checked_at };- } catch (err) {- const msg = err instanceof Error ? err.message : String(err);- return { state: "unreachable", url, error: msg, last_checked_at };+ const r = await mcpRpc<{ tools?: unknown }>(+ url,+ token,+ "tools/list",+ {},+ { timeoutMs: 2000 },+ );+ if (r.ok) {+ return {+ state: "connected",+ url,+ tools_count: countToolsFromResult(r.result),+ last_checked_at,+ };+ }+ if (r.kind === "http_error" && (r.status === 401 || r.status === 403)) {+ return { state: "stale_token", url, http_status: r.status, last_checked_at };+ }+ if (r.kind === "http_error") {+ return { state: "unreachable", url, error: `HTTP ${r.status}`, last_checked_at };+ }+ if (r.kind === "timeout") {+ return { state: "unreachable", url, error: "timed out", last_checked_at };+ }+ if (r.kind === "aborted") {+ return { state: "unreachable", url, error: "aborted", last_checked_at };+ }+ if (r.kind === "rpc_error") {+ return {+ state: "unreachable",+ url,+ error: `rpc error ${r.code}: ${r.message}`,+ last_checked_at,+ };+ }+ if (r.kind === "malformed_response") {+ return {+ state: "unreachable",+ url,+ error: `malformed response: ${r.message}`,+ last_checked_at,+ };}+ // network_error+ return { state: "unreachable", url, error: r.message, last_checked_at };}-function countTools(payload: string): number | null {- // Tools come as `{"name":"...","description":"...","inputSchema":{...}}`.- // We don't fully parse SSE here — count occurrences of `"name":` inside a- // `"tools":[...]` array to avoid double-counting server/client name fields.- const idx = payload.indexOf('"tools"');- if (idx < 0) return null;- const slice = payload.slice(idx);- const matches = slice.match(/"name"\s*:/g);- if (!matches) return null;- // Subtract 1 for any spurious match outside the array — heuristic, good- // enough for UI display.- return Math.max(0, matches.length);+function countToolsFromResult(result: { tools?: unknown } | undefined): number | null {+ if (!result || typeof result !== "object") return null;+ if (!Array.isArray(result.tools)) return null;+ return result.tools.length;}export async function disconnectMcp(key: string): Promise<void> {diff --git a/src/server/mcp/rpc.test.ts b/src/server/mcp/rpc.test.tsnew file mode 100644index 00000000..84668902--- /dev/null+++ b/src/server/mcp/rpc.test.ts@@ -0,0 +1,281 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";++import { OpenClawError } from "@/server/openclaw/cli";++const openclawMock = vi.fn();+vi.mock("@/server/openclaw/cli", async (importOriginal) => {+ const actual = await importOriginal<typeof import("@/server/openclaw/cli")>();+ return {+ ...actual,+ openclaw: (...args: unknown[]) => openclawMock(...args),+ };+});++import {+ bearerFromHeaders,+ getMcpConfig,+ mcpRpc,+ readMcpConfigRow,+} from "./rpc";++describe("bearerFromHeaders", () => {+ it("extracts bearer from Authorization header", () => {+ expect(bearerFromHeaders({ Authorization: "Bearer abc123" })).toBe("abc123");+ });++ it("accepts lowercase 'authorization' key", () => {+ expect(bearerFromHeaders({ authorization: "Bearer xyz" })).toBe("xyz");+ });++ it("accepts case-mixed 'bearer' scheme", () => {+ expect(bearerFromHeaders({ Authorization: "bearer abc" })).toBe("abc");+ expect(bearerFromHeaders({ Authorization: "BEARER abc" })).toBe("abc");+ });++ it("returns null on undefined headers", () => {+ expect(bearerFromHeaders(undefined)).toBeNull();+ });++ it("returns null on empty headers", () => {+ expect(bearerFromHeaders({})).toBeNull();+ });++ it("returns null when scheme is not Bearer", () => {+ expect(bearerFromHeaders({ Authorization: "Basic abc" })).toBeNull();+ });++ it("trims trailing whitespace from token", () => {+ expect(bearerFromHeaders({ Authorization: "Bearer abc " })).toBe("abc");+ });+});++describe("readMcpConfigRow", () => {+ beforeEach(() => {+ openclawMock.mockReset();+ });++ it("returns the row when openclaw succeeds", async () => {+ const row = {+ url: "https://example.com/mcp",+ transport: "streamable-http",+ headers: { Authorization: "Bearer t" },+ };+ openclawMock.mockResolvedValueOnce(row);+ await expect(readMcpConfigRow("test-key")).resolves.toEqual(row);+ expect(openclawMock).toHaveBeenCalledWith(["mcp", "show", "test-key"], {+ json: true,+ });+ });++ it("returns null when openclaw returns non-object", async () => {+ openclawMock.mockResolvedValueOnce(null);+ await expect(readMcpConfigRow("test-key")).resolves.toBeNull();+ });++ it("returns null when openclaw throws OpenClawError", async () => {+ openclawMock.mockRejectedValueOnce(new OpenClawError("unknown key", "", 1));+ await expect(readMcpConfigRow("missing-key")).resolves.toBeNull();+ });++ it("re-throws non-OpenClawError errors", async () => {+ openclawMock.mockRejectedValueOnce(new TypeError("totally different"));+ await expect(readMcpConfigRow("test-key")).rejects.toThrow(TypeError);+ });+});++describe("getMcpConfig", () => {+ beforeEach(() => {+ openclawMock.mockReset();+ });++ it("returns {url, token} when row has both", async () => {+ openclawMock.mockResolvedValueOnce({+ url: "https://example.com",+ headers: { Authorization: "Bearer t" },+ });+ await expect(getMcpConfig("k")).resolves.toEqual({+ url: "https://example.com",+ token: "t",+ });+ });++ it("returns null when row missing", async () => {+ openclawMock.mockResolvedValueOnce(null);+ await expect(getMcpConfig("k")).resolves.toBeNull();+ });++ it("returns null when row has url but no bearer", async () => {+ openclawMock.mockResolvedValueOnce({ url: "https://example.com" });+ await expect(getMcpConfig("k")).resolves.toBeNull();+ });++ it("returns null when row has bearer but no url", async () => {+ openclawMock.mockResolvedValueOnce({+ headers: { Authorization: "Bearer t" },+ });+ await expect(getMcpConfig("k")).resolves.toBeNull();+ });+});++describe("mcpRpc", () => {+ const fetchMock = vi.fn();+ const originalFetch = globalThis.fetch;++ beforeEach(() => {+ fetchMock.mockReset();+ globalThis.fetch = fetchMock as unknown as typeof fetch;+ });++ afterEach(() => {+ globalThis.fetch = originalFetch;+ });++ function jsonResponse(status: number, body: unknown): Response {+ return new Response(JSON.stringify(body), {+ status,+ headers: { "Content-Type": "application/json" },+ });+ }++ function sseResponse(status: number, frames: string[]): Response {+ const body = frames.map((f) => `data: ${f}`).join("\n\n") + "\n\n";+ return new Response(body, {+ status,+ headers: { "Content-Type": "text/event-stream" },+ });+ }++ it("returns {ok, result} on a successful JSON envelope", async () => {+ fetchMock.mockResolvedValueOnce(+ jsonResponse(200, { jsonrpc: "2.0", id: 1, result: { tools: [] } }),+ );+ const r = await mcpRpc("http://x", "tok", "tools/list");+ expect(r).toEqual({ ok: true, result: { tools: [] } });+ });++ it("sends bearer auth header and JSON-RPC envelope in body", async () => {+ fetchMock.mockResolvedValueOnce(+ jsonResponse(200, { jsonrpc: "2.0", id: 1, result: { ok: true } }),+ );+ await mcpRpc("http://x", "tok", "tools/call", { name: "X" });+ const [, init] = fetchMock.mock.calls[0]!;+ expect(init.method).toBe("POST");+ expect((init.headers as Record<string, string>).Authorization).toBe(+ "Bearer tok",+ );+ expect(JSON.parse(init.body as string)).toMatchObject({+ jsonrpc: "2.0",+ method: "tools/call",+ params: { name: "X" },+ });+ });++ it("returns {ok, result} on SSE-framed response with final data: frame", async () => {+ fetchMock.mockResolvedValueOnce(+ sseResponse(200, [+ JSON.stringify({ jsonrpc: "2.0", id: 1, result: { partial: true } }),+ JSON.stringify({ jsonrpc: "2.0", id: 1, result: { final: true } }),+ ]),+ );+ const r = await mcpRpc("http://x", "tok", "tools/list");+ expect(r).toEqual({ ok: true, result: { final: true } });+ });++ it("returns rpc_error on JSON-RPC error envelope", async () => {+ fetchMock.mockResolvedValueOnce(+ jsonResponse(200, {+ jsonrpc: "2.0",+ id: 1,+ error: { code: -32601, message: "Method not found" },+ }),+ );+ const r = await mcpRpc("http://x", "tok", "nope");+ expect(r).toEqual({+ ok: false,+ kind: "rpc_error",+ code: -32601,+ message: "Method not found",+ });+ });++ it("returns http_error with 401 status", async () => {+ fetchMock.mockResolvedValueOnce(new Response("", { status: 401 }));+ const r = await mcpRpc("http://x", "tok", "tools/list");+ expect(r).toEqual({ ok: false, kind: "http_error", status: 401 });+ });++ it("returns http_error with 500 status", async () => {+ fetchMock.mockResolvedValueOnce(new Response("server fire", { status: 500 }));+ const r = await mcpRpc("http://x", "tok", "tools/list");+ expect(r).toEqual({ ok: false, kind: "http_error", status: 500 });+ });++ it("returns network_error when fetch throws (not abort)", async () => {+ fetchMock.mockRejectedValueOnce(new TypeError("fetch failed"));+ const r = await mcpRpc("http://x", "tok", "tools/list");+ expect(r).toMatchObject({ ok: false, kind: "network_error" });+ if (!r.ok && r.kind === "network_error") {+ expect(r.message).toBe("fetch failed");+ }+ });++ it("returns timeout when our internal timer fires", async () => {+ fetchMock.mockImplementationOnce(+ (_url, init) =>+ new Promise((_resolve, reject) => {+ const sig = (init as RequestInit).signal as AbortSignal;+ sig.addEventListener("abort", () => {+ const e = new Error("aborted");+ e.name = "AbortError";+ reject(e);+ });+ }),+ );+ const r = await mcpRpc("http://x", "tok", "tools/list", {}, { timeoutMs: 10 });+ expect(r).toEqual({ ok: false, kind: "timeout" });+ });++ it("returns aborted when caller's signal fires before timeout", async () => {+ const caller = new AbortController();+ fetchMock.mockImplementationOnce(+ (_url, init) =>+ new Promise((_resolve, reject) => {+ const sig = (init as RequestInit).signal as AbortSignal;+ sig.addEventListener("abort", () => {+ const e = new Error("aborted");+ e.name = "AbortError";+ reject(e);+ });+ }),+ );+ const p = mcpRpc(+ "http://x",+ "tok",+ "tools/list",+ {},+ { timeoutMs: 60_000, signal: caller.signal },+ );+ caller.abort();+ await expect(p).resolves.toEqual({ ok: false, kind: "aborted" });+ });++ it("returns malformed_response on empty body", async () => {+ fetchMock.mockResolvedValueOnce(new Response("", { status: 200 }));+ const r = await mcpRpc("http://x", "tok", "tools/list");+ expect(r).toMatchObject({ ok: false, kind: "malformed_response" });+ });++ it("returns malformed_response on invalid JSON body", async () => {+ fetchMock.mockResolvedValueOnce(new Response("not json", { status: 200 }));+ const r = await mcpRpc("http://x", "tok", "tools/list");+ expect(r).toMatchObject({ ok: false, kind: "malformed_response" });+ });++ it("returns malformed_response when envelope has neither result nor error", async () => {+ fetchMock.mockResolvedValueOnce(+ jsonResponse(200, { jsonrpc: "2.0", id: 1 }),+ );+ const r = await mcpRpc("http://x", "tok", "tools/list");+ expect(r).toMatchObject({ ok: false, kind: "malformed_response" });+ });+});diff --git a/src/server/mcp/rpc.ts b/src/server/mcp/rpc.tsnew file mode 100644index 00000000..25d97702--- /dev/null+++ b/src/server/mcp/rpc.ts@@ -0,0 +1,225 @@+import { openclaw, OpenClawError } from "@/server/openclaw/cli";++/**+ * Shared MCP HTTP plumbing. Two callers use this today:+ * - `mcp-state.ts:probe()` (liveness check via tools/list)+ * - `onboarding/audit.ts` (real audit via tools/call runScript)+ *+ * Single source of truth for: subprocess-config read, bearer extraction,+ * JSON-RPC envelope construction, SSE-vs-JSON response parsing, error shapes.+ *+ * Security: never log the McpConfig.token. The bearer is held in memory only+ * for the duration of one RPC call. `openclaw mcp show` subprocess output+ * must never be logged either (full stdout contains the token in headers).+ */++export type McpConfigRow = {+ url?: string;+ transport?: string;+ headers?: Record<string, string>;+};++export type McpConfig = { url: string; token: string };++export type RpcResult<T> =+ | { ok: true; result: T }+ | { ok: false; kind: "http_error"; status: number }+ | { ok: false; kind: "timeout" }+ | { ok: false; kind: "aborted" }+ | { ok: false; kind: "network_error"; message: string }+ | { ok: false; kind: "rpc_error"; code: number; message: string }+ | { ok: false; kind: "malformed_response"; message: string };++/**+ * Read the raw MCP config row from OpenClaw. Returns null when the key is+ * unknown (OpenClaw exits non-zero). Callers that need to distinguish+ * "no row" from "row but no bearer" (e.g., the UI status surface) should+ * use this + bearerFromHeaders directly. Callers that just need usable+ * credentials should use getMcpConfig.+ */+export async function readMcpConfigRow(key: string): Promise<McpConfigRow | null> {+ try {+ const out = await openclaw(["mcp", "show", key], { json: true });+ if (!out || typeof out !== "object") return null;+ return out as McpConfigRow;+ } catch (err) {+ if (err instanceof OpenClawError) return null;+ throw err;+ }+}++/** Parse the bearer out of an `Authorization: Bearer <token>` header. */+export function bearerFromHeaders(+ headers: Record<string, string> | undefined,+): string | null {+ if (!headers) return null;+ const raw = headers.Authorization ?? headers.authorization;+ if (!raw) return null;+ const m = raw.match(/^Bearer\s+(.+)$/i);+ return m ? m[1].trim() : null;+}++/**+ * Convenience wrapper for callers that just need URL + bearer. Returns null+ * when the key isn't configured OR has no bearer — the two failure modes+ * collapse to the same "can't talk to this MCP" answer.+ */+export async function getMcpConfig(key: string): Promise<McpConfig | null> {+ const row = await readMcpConfigRow(key);+ if (!row || !row.url) return null;+ const token = bearerFromHeaders(row.headers);+ if (!token) return null;+ return { url: row.url, token };+}++export type McpRpcOpts = {+ /** Hard timeout in ms. Defaults to 10s. */+ timeoutMs?: number;+ /** Caller's abort signal — composed with our internal timeout. */+ signal?: AbortSignal;+};++/**+ * Send one JSON-RPC call to an MCP server over streamable-http transport.+ *+ * Every failure has a named kind so callers can branch:+ * - http_error — non-2xx HTTP (401/403 = stale token; 5xx = server)+ * - timeout — our internal timer fired+ * - aborted — caller's signal fired+ * - network_error — fetch threw before getting a response+ * - rpc_error — server returned a JSON-RPC error envelope+ * - malformed_response — body wasn't parseable JSON-RPC+ *+ * Body is buffered (text() then parsed). MCP can reply with either plain+ * JSON or SSE-framed (`data: ...\n\n`); for a single RPC we want the final+ * envelope, so we extract the last `data:` frame when SSE is detected.+ */+export async function mcpRpc<T = unknown>(+ url: string,+ token: string,+ method: string,+ params: Record<string, unknown> = {},+ opts: McpRpcOpts = {},+): Promise<RpcResult<T>> {+ const timeoutMs = opts.timeoutMs ?? 10_000;+ const controller = new AbortController();+ let timerFired = false;+ const timer = setTimeout(() => {+ timerFired = true;+ controller.abort();+ }, timeoutMs);++ const onCallerAbort = () => controller.abort();+ if (opts.signal) {+ if (opts.signal.aborted) controller.abort();+ else opts.signal.addEventListener("abort", onCallerAbort, { once: true });+ }++ const cleanup = () => {+ clearTimeout(timer);+ opts.signal?.removeEventListener("abort", onCallerAbort);+ };++ let res: Response;+ try {+ res = await fetch(url, {+ method: "POST",+ headers: {+ "Content-Type": "application/json",+ Accept: "application/json, text/event-stream",+ Authorization: `Bearer ${token}`,+ },+ body: JSON.stringify({ jsonrpc: "2.0", id: 1, method, params }),+ signal: controller.signal,+ });+ } catch (err) {+ cleanup();+ if (timerFired) return { ok: false, kind: "timeout" };+ if (opts.signal?.aborted) return { ok: false, kind: "aborted" };+ return {+ ok: false,+ kind: "network_error",+ message: err instanceof Error ? err.message : String(err),+ };+ }++ if (!res.ok) {+ cleanup();+ return { ok: false, kind: "http_error", status: res.status };+ }++ let body: string;+ try {+ body = await res.text();+ } catch (err) {+ cleanup();+ if (timerFired) return { ok: false, kind: "timeout" };+ if (opts.signal?.aborted) return { ok: false, kind: "aborted" };+ return {+ ok: false,+ kind: "network_error",+ message: err instanceof Error ? err.message : String(err),+ };+ }+ cleanup();++ return parseRpcBody<T>(body);+}++function parseRpcBody<T>(body: string): RpcResult<T> {+ const envelope = pickRpcEnvelope(body);+ if (envelope === null) {+ return { ok: false, kind: "malformed_response", message: "empty body" };+ }+ let parsed: { result?: T; error?: { code: number; message: string } };+ try {+ parsed = JSON.parse(envelope) as typeof parsed;+ } catch (err) {+ return {+ ok: false,+ kind: "malformed_response",+ message: err instanceof Error ? err.message : "JSON parse failed",+ };+ }+ if (parsed.error) {+ return {+ ok: false,+ kind: "rpc_error",+ code: parsed.error.code,+ message: parsed.error.message,+ };+ }+ if (parsed.result === undefined) {+ return {+ ok: false,+ kind: "malformed_response",+ message: "envelope has neither result nor error",+ };+ }+ return { ok: true, result: parsed.result };+}++/**+ * MCP streamable-http can return plain JSON OR SSE (`data: ...\n\n`).+ * For a single RPC we want the last full `data:` frame; for plain JSON we+ * return the body as-is. Returns null when the body has no usable envelope.+ */+function pickRpcEnvelope(body: string): string | null {+ const trimmed = body.trim();+ if (!trimmed) return null;+ if (!trimmed.startsWith("data:") && !trimmed.startsWith("event:")) {+ return trimmed;+ }+ const frames = trimmed+ .split(/\n\n+/)+ .map((frame) =>+ frame+ .split("\n")+ .filter((line) => line.startsWith("data:"))+ .map((line) => line.slice("data:".length).trim())+ .join(""),+ )+ .filter((s) => s.length > 0);+ if (frames.length === 0) return null;+ return frames[frames.length - 1] ?? null;+}diff --git a/vitest.config.ts b/vitest.config.tsindex f8e267e5..f7c1c689 100644--- a/vitest.config.ts+++ b/vitest.config.ts@@ -13,11 +13,10 @@ export default defineConfig({},},test: {+ // Default environment is `node`. Component / page tests that need a DOM+ // must add `// @vitest-environment jsdom` at the top of the file (vitest 4+ // removed `environmentMatchGlobs` in favor of per-file comments).environment: "node",- environmentMatchGlobs: [- ["src/components/**", "jsdom"],- ["src/app/**/*.test.tsx", "jsdom"],- ],globals: false,include: ["src/**/*.test.ts", "src/**/*.test.tsx"],setupFiles: ["./vitest.setup.ts"],