fleet_session_list

Instructions

Implementation Reference

• src/index.ts:669-683 (registration)

  Tool registration for fleet_session_list. It is defined with server.tool(), no input schema (empty {}), and sends a POST to /api/fleet-session with { action: 'list' }.

  server.tool(
    "fleet_session_list",
    "List all active fleet sessions. Response: { sessions: [{ session_id, node_count, round_count, created_at }] }.",
    {},
    async () => {
      const guard = requireApiKey();
      if (guard) return guard;
      const result = await apiFetch("/api/fleet-session", {
        method: "POST",
        headers: apiKeyHeaders(),
        body: { action: "list" },
      });
      return formatResult(result);
    }
  );

• src/index.ts:669-683 (handler)

  The handler logic for fleet_session_list. It checks API key auth via requireApiKey(), then calls apiFetch('/api/fleet-session') with action: 'list', and formats the result.

  server.tool(
    "fleet_session_list",
    "List all active fleet sessions. Response: { sessions: [{ session_id, node_count, round_count, created_at }] }.",
    {},
    async () => {
      const guard = requireApiKey();
      if (guard) return guard;
      const result = await apiFetch("/api/fleet-session", {
        method: "POST",
        headers: apiKeyHeaders(),
        body: { action: "list" },
      });
      return formatResult(result);
    }
  );

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

  The apiFetch helper used by fleet_session_list to make HTTP POST requests to the backend API.

  /** Generic fetch wrapper — returns structured result, never throws */
  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}` } };
    }
  }

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

  The formatResult helper used by fleet_session_list to format the API response into MCP text content.

  /** Format an ApiResult into 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:257-294 (helper)

  The requireApiKey helper used by fleet_session_list to check if API key is configured.

  function requireApiKey(): McpToolResult | null {
    if (API_KEY) return null;
    return {
      content: [
        {
          type: "text" as const,
          text: JSON.stringify(
            {
              error: "missing_api_key",
              message:
                "No API key configured. You need a CI-1T API key to use this tool.",
              setup_steps: [
                `1. Create a free account at ${SIGNUP_URL} — you get 1,000 free credits on signup`,
                "2. Go to Dashboard → API Keys and create a new key (starts with ci_...)",
                "3. Set the CI1T_API_KEY environment variable in your MCP client config",
                "4. Restart the MCP server — all tools will be unlocked",
              ],
              config_example: {
                claude_desktop: {
                  mcpServers: {
                    ci1t: {
                      env: {
                        CI1T_API_KEY: "ci_your_key_here",
                      },
                    },
                  },
                },
              },
              free_tools:
                "You can use interpret_scores, convert_scores, generate_config, and onboarding without an API key or credits.",
            },
            null,
            2
          ),
        },
      ],
    };
  }