server_status

Instructions

Implementation Reference

• src/tools/health.ts:7-36 (handler)

  The registerHealthTools function registers the 'server_status' tool with an MCP server. The handler calls deps.client.healthCheck() to get server health, counts active tabs via listTrackedTabs(), and returns health data including ok, running, reachable, browserConnected, browserSessionActive, version, consecutiveFailures, activeOps, activeTabCount, and guidance.

  export function registerHealthTools(server: McpServer, deps: ToolDeps): void {
    server.tool("server_status", "Check CamoFox server health and browser connection. Call first to verify server is running. Returns version, browser status, and active tab count.", {}, async () => {
      try {
        const health = await deps.client.healthCheck();
        const activeTabCount = listTrackedTabs().length;
        const running = health.running ?? health.browserConnected ?? false;
        const reachable = health.ok === true;
        const browserSessionActive = health.browserConnected;
        const guidance =
          reachable && !browserSessionActive
            ? "CamoFox Browser is reachable, but no browser session is active yet. Continue with create_tab to start a session."
            : undefined;
  
        return okResult({
          ok: health.ok,
          running,
          reachable,
          browserConnected: health.browserConnected,
          browserSessionActive,
          version: health.version ?? "unknown",
          consecutiveFailures: health.consecutiveFailures,
          activeOps: health.activeOps,
          activeTabCount,
          guidance
        });
      } catch (error) {
        return toErrorResult(error);
      }
    });
  }

• src/tools/health.ts:7-36 (registration)

  The tool 'server_status' is registered on the McpServer via server.tool("server_status", ...) inside registerHealthTools, which is called from src/server.ts at line 39.

  export function registerHealthTools(server: McpServer, deps: ToolDeps): void {
    server.tool("server_status", "Check CamoFox server health and browser connection. Call first to verify server is running. Returns version, browser status, and active tab count.", {}, async () => {
      try {
        const health = await deps.client.healthCheck();
        const activeTabCount = listTrackedTabs().length;
        const running = health.running ?? health.browserConnected ?? false;
        const reachable = health.ok === true;
        const browserSessionActive = health.browserConnected;
        const guidance =
          reachable && !browserSessionActive
            ? "CamoFox Browser is reachable, but no browser session is active yet. Continue with create_tab to start a session."
            : undefined;
  
        return okResult({
          ok: health.ok,
          running,
          reachable,
          browserConnected: health.browserConnected,
          browserSessionActive,
          version: health.version ?? "unknown",
          consecutiveFailures: health.consecutiveFailures,
          activeOps: health.activeOps,
          activeTabCount,
          guidance
        });
      } catch (error) {
        return toErrorResult(error);
      }
    });
  }

• src/server.ts:39-39 (registration)

  Registration call site: registerHealthTools(server, deps) in the createServer function, which wires up the tool with the server instance.

  registerHealthTools(server, deps);

• src/errors.ts:45-49 (helper)

  okResult helper used by the server_status handler to wrap the returned data into a text-based ToolResult.

  export function okResult(data: unknown): ToolResult {
    return {
      content: [{ type: "text", text: JSON.stringify(data) }]
    };
  }

• src/errors.ts:79-90 (helper)

  toErrorResult helper used by the server_status handler to normalize and return errors in a standard format.

  export function toErrorResult(error: unknown): ToolResult {
    const appError = normalizeError(error);
    const payload = {
      isError: true,
      code: appError.code,
      message: appError.message
    };
  
    return {
      isError: true,
      content: [{ type: "text", text: JSON.stringify(payload) }]
    };