fix: Add basic auth support to server health checks and reconnection logic

src/client.ts

@@ -76,10 +76,14 @@ export class OpenCodeClient {
   private authHeader?: string;
   private autoServe: boolean;
   private reconnectAttempts = 0;
+  private username?: string;
+  private password?: string;
 
   constructor(options: OpenCodeClientOptions) {
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
     this.autoServe = options.autoServe ?? false;
+    this.username = options.username;
+    this.password = options.password;
     if (options.password) {
       const username = options.username ?? "opencode";
       this.authHeader =
@@ -202,9 +206,14 @@ export class OpenCodeClient {
         `Connection failed (attempt ${this.reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS}), attempting server reconnection...`,
       );
       try {
-        const status = await isServerRunning(this.baseUrl);
+        const status = await isServerRunning(this.baseUrl, this.username, this.password);
         if (!status.healthy) {
-          await ensureServer({ baseUrl: this.baseUrl, autoServe: true });
+          await ensureServer({ 
+            baseUrl: this.baseUrl, 
+            autoServe: true,
+            username: this.username,
+            password: this.password
+          });
         }
         // Retry the original request once after reconnection
         return this.request<T>(method, path, opts);

src/index.ts

@@ -191,7 +191,7 @@ registerPrompts(server);
 async function main() {
   // Step 1: Ensure OpenCode server is available (auto-start if needed).
   try {
-    await ensureServer({ baseUrl, autoServe });
+    await ensureServer({ baseUrl, autoServe, username, password });
   } catch (err) {
     // Log the error but don't prevent MCP from starting — tools will
     // report connection errors individually, and the server may come

src/server-manager.ts

@@ -23,6 +23,10 @@ export interface ServerManagerOptions {
   autoServe?: boolean;
   /** Max time (ms) to wait for the server to become healthy after spawning. */
   startupTimeoutMs?: number;
+  /** Username for HTTP basic auth (optional) */
+  username?: string;
+  /** Password for HTTP basic auth (optional) */
+  password?: string;
 }
 
 export interface ServerStatus {
@@ -44,13 +48,23 @@ let shutdownRegistered = false;
  */
 export async function isServerRunning(
   baseUrl: string,
+  username?: string,
+  password?: string,
 ): Promise<{ healthy: boolean; version?: string }> {
   try {
     const url = `${baseUrl.replace(/\/$/, "")}/global/health`;
     const controller = new AbortController();
     const timeout = setTimeout(() => controller.abort(), 3_000);
+
+    const headers: Record<string, string> = {};
+    if (password) {
+      const user = username ?? "opencode";
+      headers["Authorization"] = "Basic " + Buffer.from(`${user}:${password}`).toString("base64");
+    }
+
     const res = await fetch(url, {
       method: "GET",
+      headers,
       signal: controller.signal,
     });
     clearTimeout(timeout);
@@ -132,10 +146,12 @@ function parseBaseUrl(baseUrl: string): { hostname: string; port: number } {
 async function waitForHealthy(
   baseUrl: string,
   timeoutMs: number,
+  username?: string,
+  password?: string,
 ): Promise<boolean> {
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
-    const { healthy } = await isServerRunning(baseUrl);
+    const { healthy } = await isServerRunning(baseUrl, username, password);
     if (healthy) return true;
     await new Promise((r) => setTimeout(r, HEALTH_POLL_INTERVAL_MS));
   }
@@ -178,6 +194,8 @@ export async function startServer(
   binaryPath: string,
   baseUrl: string,
   timeoutMs: number = DEFAULT_STARTUP_TIMEOUT_MS,
+  username?: string,
+  password?: string,
 ): Promise<{ version?: string }> {
   const { hostname, port } = parseBaseUrl(baseUrl);
 
@@ -226,7 +244,7 @@ export async function startServer(
 
   // Race: either the server becomes healthy or the child crashes.
   const healthy = await Promise.race([
-    waitForHealthy(baseUrl, timeoutMs),
+    waitForHealthy(baseUrl, timeoutMs, username, password),
     earlyExit.catch(() => false as const),
   ]);
 
@@ -241,7 +259,7 @@ export async function startServer(
   }
 
   // Grab the version from the now-running server.
-  const status = await isServerRunning(baseUrl);
+  const status = await isServerRunning(baseUrl, username, password);
   return { version: status.version };
 }
 
@@ -271,7 +289,7 @@ export async function ensureServer(
   const timeoutMs = opts.startupTimeoutMs ?? DEFAULT_STARTUP_TIMEOUT_MS;
 
   // Step 1: Check if server is already running.
-  const existing = await isServerRunning(baseUrl);
+  const existing = await isServerRunning(baseUrl, opts.username, opts.password);
   if (existing.healthy) {
     console.error(
       `OpenCode server already running at ${baseUrl} (v${existing.version ?? "unknown"})`,
@@ -305,7 +323,13 @@ export async function ensureServer(
 
   // Step 3: Start the server.
   console.error(`Starting: opencode serve --port ${parseBaseUrl(baseUrl).port}`);
-  const result = await startServer(binaryPath, baseUrl, timeoutMs);
+  const result = await startServer(
+    binaryPath,
+    baseUrl,
+    timeoutMs,
+    opts.username,
+    opts.password,
+  );
   console.error(
     `OpenCode server started successfully (v${result.version ?? "unknown"})`,
   );

tests/server-manager.test.ts

@@ -109,7 +109,40 @@ describe("isServerRunning", () => {
     expect(result).toEqual({ healthy: true, version: "1.2.0" });
     expect(fetchMock).toHaveBeenCalledWith(
       "http://127.0.0.1:4096/global/health",
-      expect.objectContaining({ method: "GET" }),
+      expect.objectContaining({ 
+        method: "GET",
+        headers: {}
+      }),
+    );
+  });
+
+  it("includes authorization header when password is provided", async () => {
+    mockFetchHealthy("1.2.0");
+    const result = await isServerRunning("http://127.0.0.1:4096", "admin", "secret123");
+    expect(result).toEqual({ healthy: true, version: "1.2.0" });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://127.0.0.1:4096/global/health",
+      expect.objectContaining({ 
+        method: "GET",
+        headers: {
+          "Authorization": "Basic YWRtaW46c2VjcmV0MTIz"
+        }
+      }),
+    );
+  });
+
+  it("uses default username 'opencode' when password provided without username", async () => {
+    mockFetchHealthy("1.2.0");
+    const result = await isServerRunning("http://127.0.0.1:4096", undefined, "secret123");
+    expect(result).toEqual({ healthy: true, version: "1.2.0" });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://127.0.0.1:4096/global/health",
+      expect.objectContaining({ 
+        method: "GET",
+        headers: {
+          "Authorization": "Basic b3BlbmNvZGU6c2VjcmV0MTIz"
+        }
+      }),
     );
   });
 
@@ -136,7 +169,10 @@ describe("isServerRunning", () => {
     await isServerRunning("http://127.0.0.1:4096/");
     expect(fetchMock).toHaveBeenCalledWith(
       "http://127.0.0.1:4096/global/health",
-      expect.anything(),
+      expect.objectContaining({ 
+        method: "GET",
+        headers: {}
+      }),
     );
   });
 
@@ -231,6 +267,84 @@ describe("ensureServer", () => {
     );
   });
 
+  it("includes authorization header when checking server with auth", async () => {
+    mockFetchHealthy("1.2.0");
+    const result = await ensureServer({
+      baseUrl: "http://127.0.0.1:4096",
+      username: "admin",
+      password: "secret123",
+    });
+    expect(result).toEqual({
+      running: true,
+      version: "1.2.0",
+      managedByUs: false,
+    });
+    expect(fetchMock).toHaveBeenCalledWith(
+      "http://127.0.0.1:4096/global/health",
+      expect.objectContaining({ 
+        method: "GET",
+        headers: {
+          "Authorization": "Basic YWRtaW46c2VjcmV0MTIz"
+        }
+      }),
+    );
+  });
+
+  it("uses authorization headers during auto-start health polling", async () => {
+    const expectedAuth = "Basic YWRtaW46c2VjcmV0MTIz";
+    const fakeChild = createFakeChild();
+    spawnMock.mockReturnValueOnce(fakeChild as any);
+
+    let healthCheckCalls = 0;
+    fetchMock.mockImplementation(async (_url: string, init?: RequestInit) => {
+      healthCheckCalls += 1;
+
+      if (healthCheckCalls === 1) {
+        throw new Error("ECONNREFUSED");
+      }
+
+      const headers = (init?.headers ?? {}) as Record<string, string>;
+      if (headers.Authorization !== expectedAuth) {
+        return {
+          ok: true,
+          status: 200,
+          json: async () => ({ healthy: false }),
+        } as unknown as Response;
+      }
+
+      return {
+        ok: true,
+        status: 200,
+        json: async () => ({ healthy: true, version: "1.1.53" }),
+      } as unknown as Response;
+    });
+
+    mockExecFileSuccess("/usr/local/bin/opencode\n");
+    mockExecFileSuccess("1.1.53\n");
+
+    const result = await ensureServer({
+      baseUrl: "http://127.0.0.1:4096",
+      startupTimeoutMs: 1_000,
+      username: "admin",
+      password: "secret123",
+    });
+
+    expect(result).toEqual({
+      running: true,
+      version: "1.1.53",
+      managedByUs: true,
+    });
+    for (const [, init] of fetchMock.mock.calls.slice(1)) {
+      expect(init).toEqual(
+        expect.objectContaining({
+          headers: {
+            Authorization: expectedAuth,
+          },
+        }),
+      );
+    }
+  });
+
   it("throws when auto-serve is disabled and server is not running", async () => {
     mockFetchDown();
     await expect(