fleet_session_create

Instructions

Implementation Reference

• src/index.ts:611-630 (registration)

  The tool 'fleet_session_create' is registered via server.tool() with schema definition and handler in a single block.

  server.tool(
    "fleet_session_create",
    "Create a new persistent fleet monitoring session. Returns a session ID for subsequent rounds. Max 16 nodes. Response: { session_id, node_count, node_names, created_at }. Workflow: fleet_session_create → fleet_session_round (repeat) → fleet_session_state (check) → fleet_session_delete (cleanup).",
    {
      node_count: z.number().int().min(1).max(16).describe("Number of nodes in the fleet"),
      node_names: z.array(z.string()).optional().describe("Optional names for each node (must match node_count)"),
    },
    async ({ node_count, node_names }) => {
      const guard = requireApiKey();
      if (guard) return guard;
      const body: Record<string, unknown> = { action: "create", node_count };
      if (node_names) body.node_names = node_names;
      const result = await apiFetch("/api/fleet-session", {
        method: "POST",
        headers: apiKeyHeaders(),
        body,
      });
      return formatResult(result);
    }
  );

• src/index.ts:614-617 (schema)

  Input schema for fleet_session_create: node_count (int 1-16 required) and node_names (optional string array).

  {
    node_count: z.number().int().min(1).max(16).describe("Number of nodes in the fleet"),
    node_names: z.array(z.string()).optional().describe("Optional names for each node (must match node_count)"),
  },

• src/index.ts:618-630 (handler)

  Handler function that authenticates via requireApiKey(), then POSTs to /api/fleet-session with action='create', node_count, and optional node_names.

    async ({ node_count, node_names }) => {
      const guard = requireApiKey();
      if (guard) return guard;
      const body: Record<string, unknown> = { action: "create", node_count };
      if (node_names) body.node_names = node_names;
      const result = await apiFetch("/api/fleet-session", {
        method: "POST",
        headers: apiKeyHeaders(),
        body,
      });
      return formatResult(result);
    }
  );

• src/index.ts:73-82 (helper)

  formatResult helper used by the handler to format the API response as MCP text content.

  function formatResult(result: ApiResult): { content: Array<{ type: "text"; text: string }> } {
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(result.data, null, 2),
        },
      ],
    };
  }

• src/index.ts:47-70 (helper)

  apiFetch helper used by the handler to make HTTP requests to the backend API.

  async function apiFetch(
    path: string,
    opts: { method?: string; headers?: Record<string, string>; body?: unknown } = {}
  ): Promise<ApiResult> {
    const url = `${BASE_URL}${path}`;
    try {
      const res = await fetch(url, {
        method: opts.method || "GET",
        headers: opts.headers || { "Content-Type": "application/json" },
        body: opts.body ? JSON.stringify(opts.body) : undefined,
      });
      const text = await res.text();
      let data: unknown;
      try {
        data = JSON.parse(text);
      } catch {
        data = { raw: text };
      }
      return { ok: res.ok, status: res.status, data };
    } catch (err: unknown) {
      const message = err instanceof Error ? err.message : String(err);
      return { ok: false, status: 0, data: { error: `Network error: ${message}` } };
    }
  }