@mekareteriker/opencode-mcp 1.10.2-mekareteriker.0

package/dist/client.js

@@ -0,0 +1,282 @@
+/**
+ * HTTP client wrapper for the OpenCode server API.
+ *
+ * Features:
+ *  - Basic auth support
+ *  - Automatic retry with exponential backoff for transient errors
+ *  - Proper 204 No Content handling on all methods
+ *  - SSE streaming support
+ *  - Error categorization (transient vs permanent)
+ *  - Directory path normalization and validation
+ *  - Lazy server reconnection on connection failure
+ */
+import { normalizeDirectory } from "./helpers.js";
+import { ensureServer, isServerRunning } from "./server-manager.js";
+export class OpenCodeError extends Error {
+    status;
+    method;
+    path;
+    body;
+    constructor(message, status, method, path, body) {
+        super(message);
+        this.status = status;
+        this.method = method;
+        this.path = path;
+        this.body = body;
+        this.name = "OpenCodeError";
+    }
+    get isTransient() {
+        return (this.status === 429 ||
+            this.status === 502 ||
+            this.status === 503 ||
+            this.status === 504);
+    }
+    get isNotFound() {
+        return this.status === 404;
+    }
+    get isAuth() {
+        return this.status === 401 || this.status === 403;
+    }
+}
+const MAX_RETRIES = 2;
+const BASE_DELAY_MS = 500;
+/** Max reconnection attempts per MCP session lifetime. */
+const MAX_RECONNECT_ATTEMPTS = 3;
+/** Check if an error looks like a connection failure (server unreachable). */
+function isConnectionError(err) {
+    const msg = err.message.toLowerCase();
+    return (msg.includes("econnrefused") ||
+        msg.includes("enotfound") ||
+        msg.includes("ehostunreach") ||
+        msg.includes("fetch failed") ||
+        msg.includes("network error") ||
+        msg.includes("socket hang up"));
+}
+export class OpenCodeClient {
+    baseUrl;
+    authHeader;
+    autoServe;
+    reconnectAttempts = 0;
+    username;
+    password;
+    constructor(options) {
+        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 =
+                "Basic " +
+                    Buffer.from(`${username}:${options.password}`).toString("base64");
+        }
+    }
+    getBaseUrl() {
+        return this.baseUrl;
+    }
+    buildUrl(path, query) {
+        const url = new URL(path, this.baseUrl);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value !== undefined && value !== "") {
+                    url.searchParams.set(key, value);
+                }
+            }
+        }
+        return url.toString();
+    }
+    headers(accept, directory) {
+        const h = {
+            "Content-Type": "application/json",
+            Accept: accept ?? "application/json",
+        };
+        if (this.authHeader) {
+            h["Authorization"] = this.authHeader;
+        }
+        // Normalize and validate the directory path before sending as header
+        const normalized = normalizeDirectory(directory);
+        if (normalized) {
+            h["x-opencode-directory"] = normalized;
+        }
+        return h;
+    }
+    async request(method, path, opts) {
+        const url = this.buildUrl(path, opts?.query);
+        let lastError;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            if (attempt > 0) {
+                const delay = BASE_DELAY_MS * Math.pow(2, attempt - 1);
+                await new Promise((r) => setTimeout(r, delay));
+            }
+            try {
+                const controller = new AbortController();
+                const timeoutId = opts?.timeout
+                    ? setTimeout(() => controller.abort(), opts.timeout)
+                    : undefined;
+                const res = await fetch(url, {
+                    method,
+                    headers: this.headers(undefined, opts?.directory),
+                    body: opts?.body !== undefined ? JSON.stringify(opts.body) : undefined,
+                    signal: controller.signal,
+                });
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                if (!res.ok) {
+                    const text = await res.text();
+                    const err = new OpenCodeError(`${method} ${path} failed (${res.status}): ${text}`, res.status, method, path, text);
+                    if (err.isTransient && attempt < MAX_RETRIES) {
+                        lastError = err;
+                        continue;
+                    }
+                    throw err;
+                }
+                // Handle 204 No Content
+                if (res.status === 204) {
+                    return undefined;
+                }
+                const contentType = res.headers.get("content-type") ?? "";
+                if (contentType.includes("application/json")) {
+                    return (await res.json());
+                }
+                // Return text for non-JSON responses
+                return (await res.text());
+            }
+            catch (e) {
+                if (e instanceof OpenCodeError)
+                    throw e;
+                lastError = e;
+                if (attempt >= MAX_RETRIES)
+                    break;
+            }
+        }
+        // Lazy reconnection: if all retries exhausted and error looks like a
+        // connection failure, try restarting the server and retry once.
+        if (this.autoServe &&
+            this.reconnectAttempts < MAX_RECONNECT_ATTEMPTS &&
+            lastError &&
+            isConnectionError(lastError)) {
+            this.reconnectAttempts++;
+            console.error(`Connection failed (attempt ${this.reconnectAttempts}/${MAX_RECONNECT_ATTEMPTS}), attempting server reconnection...`);
+            try {
+                const status = await isServerRunning(this.baseUrl, this.username, this.password);
+                if (!status.healthy) {
+                    await ensureServer({
+                        baseUrl: this.baseUrl,
+                        autoServe: true,
+                        username: this.username,
+                        password: this.password
+                    });
+                }
+                // Retry the original request once after reconnection
+                return this.request(method, path, opts);
+            }
+            catch (reconnectErr) {
+                console.error(`Server reconnection failed: ${reconnectErr instanceof Error ? reconnectErr.message : String(reconnectErr)}`);
+            }
+        }
+        throw lastError ?? new Error(`${method} ${path} failed after retries`);
+    }
+    async get(path, query, directory) {
+        return this.request("GET", path, { query, directory });
+    }
+    async post(path, body, opts) {
+        return this.request("POST", path, {
+            body,
+            timeout: opts?.timeout,
+            directory: opts?.directory,
+        });
+    }
+    async patch(path, body, directory) {
+        return this.request("PATCH", path, { body, directory });
+    }
+    async put(path, body, directory) {
+        return this.request("PUT", path, { body, directory });
+    }
+    async delete(path, query, directory) {
+        return this.request("DELETE", path, { query, directory });
+    }
+    /**
+     * Subscribe to SSE events. Returns an async iterable of parsed events.
+     * The caller should break out of the loop when done.
+     */
+    async *subscribeSSE(path, opts) {
+        const url = this.buildUrl(path);
+        const res = await fetch(url, {
+            method: "GET",
+            headers: {
+                ...this.headers("text/event-stream"),
+                Accept: "text/event-stream",
+                "Cache-Control": "no-cache",
+            },
+            signal: opts?.signal,
+        });
+        if (!res.ok) {
+            const text = await res.text();
+            throw new OpenCodeError(`SSE ${path} failed (${res.status}): ${text}`, res.status, "GET", path, text);
+        }
+        if (!res.body) {
+            throw new Error("No response body for SSE stream");
+        }
+        const reader = res.body.getReader();
+        const decoder = new TextDecoder();
+        let buffer = "";
+        let currentEvent = "";
+        let currentData = "";
+        const abortHandler = () => {
+            try {
+                // Cancels any pending reader.read() and causes the generator to unwind.
+                void reader.cancel().catch(() => {
+                    // ignore
+                });
+            }
+            catch {
+                // ignore
+            }
+        };
+        if (opts?.signal) {
+            if (opts.signal.aborted)
+                abortHandler();
+            else
+                opts.signal.addEventListener("abort", abortHandler, { once: true });
+        }
+        try {
+            while (true) {
+                if (opts?.signal?.aborted)
+                    break;
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                buffer += decoder.decode(value, { stream: true });
+                const lines = buffer.split("\n");
+                buffer = lines.pop() ?? "";
+                for (const line of lines) {
+                    if (line.startsWith("event:")) {
+                        currentEvent = line.slice(6).trim();
+                    }
+                    else if (line.startsWith("data:")) {
+                        currentData = line.slice(5).trim();
+                    }
+                    else if (line === "") {
+                        if (currentData) {
+                            yield { event: currentEvent || "message", data: currentData };
+                            currentEvent = "";
+                            currentData = "";
+                        }
+                    }
+                }
+            }
+        }
+        finally {
+            if (opts?.signal) {
+                try {
+                    opts.signal.removeEventListener("abort", abortHandler);
+                }
+                catch {
+                    // ignore
+                }
+            }
+            reader.releaseLock();
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}

package/dist/helpers.d.ts

@@ -0,0 +1,150 @@
+/**
+ * Smart response formatting helpers.
+ *
+ * Instead of dumping raw JSON to the LLM, these helpers extract the
+ * meaningful content from OpenCode API responses so the LLM can reason
+ * about them efficiently.
+ */
+import { z } from "zod";
+/** Read-only tool: does not modify state. */
+export declare const readOnly: {
+    readonly readOnlyHint: true;
+    readonly destructiveHint: false;
+};
+/** Destructive tool: permanently deletes data or shuts down services. */
+export declare const destructive: {
+    readonly readOnlyHint: false;
+    readonly destructiveHint: true;
+};
+/**
+ * Shared Zod parameter for project directory targeting.
+ * When provided, sent as the x-opencode-directory header so the
+ * OpenCode server scopes the request to that project.
+ */
+export declare const directoryParam: z.ZodOptional<z.ZodString>;
+/**
+ * Set the global default provider and model.
+ * Called once from index.ts during startup.
+ */
+export declare function setModelDefaults(providerID?: string, modelID?: string): void;
+/**
+ * Apply model defaults: use explicit params if both are provided,
+ * otherwise fall back to env-var defaults if both are set,
+ * otherwise return undefined (let the server decide).
+ *
+ * Returns `{ providerID, modelID }` or `undefined`.
+ */
+export declare function applyModelDefaults(providerID?: string, modelID?: string, variant?: string): {
+    providerID: string;
+    modelID: string;
+    variant?: string;
+} | undefined;
+/**
+ * Normalize and validate a directory path:
+ *  - Resolves to absolute (handles "..", ".", trailing slashes, and
+ *    converts relative inputs against `process.cwd()`)
+ *  - Confirms the resolved path is absolute for the current platform
+ *  - Validates that the path exists on disk
+ *
+ * Accepts both POSIX ("/home/user/my-project") and Windows
+ * ("C:\\Users\\me\\my-project", "\\\\server\\share") absolute paths via
+ * the platform-aware `resolve` + `isAbsolute` from `node:path`.
+ *
+ * Returns the normalized path, or undefined if input was undefined.
+ * Throws a descriptive Error on validation failure.
+ */
+export declare function normalizeDirectory(directory?: string): string | undefined;
+/**
+ * Extract a human-readable summary from a message response.
+ * Pulls text content from parts, summarizes tool calls, etc.
+ * Accepts any shape — casts internally for safety.
+ */
+export declare function formatMessageResponse(response: unknown): string;
+/**
+ * Format a list of messages, extracting text content from each.
+ *
+ * When the assistant message has no text content (common with some providers
+ * that only emit tool calls), we show a concise summary of tool actions
+ * instead of blank output.  Cost/token metadata from step-finish parts is
+ * appended when available.
+ */
+export declare function formatMessageList(messages: unknown[]): string;
+/**
+ * Format a diff response into a readable summary.
+ */
+export declare function formatDiffResponse(diffs: unknown[]): string;
+/**
+ * Format session objects for LLM-friendly display.
+ */
+export declare function formatSessionList(sessions: unknown[]): string;
+/**
+ * Generic safe JSON stringify with truncation for very large responses.
+ */
+export declare function safeStringify(value: unknown, maxLength?: number): string;
+/**
+ * Analyze an AI message response for signs of failure:
+ *  - Completely empty (null/undefined)
+ *  - Has parts but no text content (provider returned nothing)
+ *  - Contains error indicators in parts
+ *
+ * Returns a diagnostic object with `isEmpty`, `hasError`, and `warning` text.
+ */
+export declare function analyzeMessageResponse(response: unknown): {
+    isEmpty: boolean;
+    hasError: boolean;
+    warning: string | null;
+};
+/**
+ * Redact values that look like API keys, tokens, or secrets.
+ * Replaces the value with the first 4 characters + "***REDACTED***".
+ * Works recursively on objects and arrays.
+ *
+ * Three layers of detection:
+ * 1. Key-name based: key names matching sensitive patterns (KEY, TOKEN, SECRET, etc.)
+ * 2. Value-based: string values matching known API key prefixes or long hex/base64 tokens
+ * 3. URL-based: query parameters in URL strings that contain secrets
+ */
+export declare function redactSecrets(value: unknown): unknown;
+/**
+ * Determine whether a provider object from the OpenCode API is truly configured
+ * (i.e. has usable credentials), as opposed to being a built-in default.
+ *
+ * Detection layers:
+ *  - source "env" / "config" / "api" → always configured
+ *  - source "custom" with a non-empty apiKey → configured
+ *  - source "custom" for "anthropic" with extra option keys (OAuth sets headers) → configured
+ *  - Everything else → not configured
+ */
+export declare function isProviderConfigured(p: Record<string, unknown>): boolean;
+/**
+ * Resolve a session status value from the OpenCode API.
+ *
+ * The API may return status as a plain string ("idle", "running") or as an
+ * object like `{ state: "running", ... }`.  This helper normalises both forms
+ * into a human-readable string.
+ */
+export declare function resolveSessionStatus(raw: unknown): string;
+/**
+ * Standard tool response builder.
+ */
+export declare function toolResult(text: string, isError?: boolean): {
+    isError?: boolean | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function toolError(e: unknown): {
+    isError?: boolean | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function toolJson(value: unknown): {
+    isError?: boolean | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};