opencode-mcp 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2025-02-08
+
+### Added
+
+- **70 MCP tools** covering the entire OpenCode headless server API
+- **7 high-level workflow tools** — `opencode_ask`, `opencode_reply`, `opencode_conversation`, `opencode_sessions_overview`, `opencode_context`, `opencode_wait`, `opencode_review_changes`
+- **18 session management tools** — create, list, get, delete, update, fork, share, abort, revert, diff, summarize, permissions
+- **6 message tools** — send prompts (sync/async), list/get messages, slash commands, shell execution
+- **6 file & search tools** — text/regex search, file finder, symbol search, directory listing, file reading, VCS status
+- **8 config & provider tools** — configuration management, provider listing, auth (API keys, OAuth)
+- **9 TUI control tools** — remote-control the OpenCode TUI
+- **13 system & monitoring tools** — health, VCS, LSP, formatters, MCP servers, agents, commands, logging, events
+- **10 MCP resources** — browseable data endpoints for project, config, providers, agents, commands, health, VCS, sessions, MCP servers, file status
+- **5 MCP prompts** — guided workflow templates for code review, debugging, project setup, implementation, session summary
+- **Robust HTTP client** — automatic retry with exponential backoff (429/502/503/504), error categorization, timeout support
+- **Smart response formatting** — extracts meaningful text from message parts, truncation for large outputs
+- **SSE event polling** — monitor real-time server events
+- **`npx` support** — run with `npx opencode-mcp` without installing globally

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alaeddine Messadi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,241 @@
+# opencode-mcp
+
+[![npm version](https://img.shields.io/npm/v/opencode-mcp.svg)](https://www.npmjs.com/package/opencode-mcp)
+[![license](https://img.shields.io/npm/l/opencode-mcp.svg)](https://github.com/AlaeddineMessadi/opencode-mcp/blob/main/LICENSE)
+[![node](https://img.shields.io/node/v/opencode-mcp.svg)](https://nodejs.org/)
+
+An [MCP](https://modelcontextprotocol.io/) server that gives any MCP-compatible client full access to a running [OpenCode](https://opencode.ai/) instance. Manage sessions, send prompts, search files, review diffs, configure providers, control the TUI, and more.
+
+**70 tools** | **10 resources** | **5 prompts**
+
+## Quick Start
+
+### 1. Start an OpenCode server
+
+```bash
+opencode serve
+```
+
+### 2. Add to your MCP client
+
+**Claude Desktop** (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "opencode": {
+      "command": "npx",
+      "args": ["-y", "opencode-mcp"]
+    }
+  }
+}
+```
+
+**Claude Code:**
+
+```bash
+claude mcp add opencode -- npx -y opencode-mcp
+```
+
+**Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "opencode": {
+      "command": "npx",
+      "args": ["-y", "opencode-mcp"]
+    }
+  }
+}
+```
+
+**Windsurf** (`~/.windsurf/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "opencode": {
+      "command": "npx",
+      "args": ["-y", "opencode-mcp"]
+    }
+  }
+}
+```
+
+**opencode** (`opencode.json`):
+
+```json
+{
+  "mcp": {
+    "opencode-mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "opencode-mcp"]
+    }
+  }
+}
+```
+
+That's it. Your MCP client now has access to the entire OpenCode API.
+
+### Custom server URL or auth
+
+If the OpenCode server is on a different host/port or has auth enabled, pass environment variables:
+
+```json
+{
+  "mcpServers": {
+    "opencode": {
+      "command": "npx",
+      "args": ["-y", "opencode-mcp"],
+      "env": {
+        "OPENCODE_BASE_URL": "http://192.168.1.10:4096",
+        "OPENCODE_SERVER_USERNAME": "myuser",
+        "OPENCODE_SERVER_PASSWORD": "mypass"
+      }
+    }
+  }
+}
+```
+
+## What Can It Do?
+
+### Workflow Tools (start here)
+
+High-level tools designed to be the easiest way for an LLM to interact with OpenCode:
+
+| Tool | What it does |
+|---|---|
+| `opencode_ask` | Create session + send prompt + get answer in one call |
+| `opencode_reply` | Follow-up message in an existing session |
+| `opencode_conversation` | Formatted conversation history |
+| `opencode_sessions_overview` | Quick overview of all sessions |
+| `opencode_context` | Project + path + VCS + config + agents in one call |
+| `opencode_wait` | Poll an async session until it finishes |
+| `opencode_review_changes` | Formatted diff summary for a session |
+
+### Session Tools (18)
+
+Create, list, get, delete, update, fork, share, abort, revert sessions. Get diffs, todos, summaries, child sessions, and respond to permission requests.
+
+### Message Tools (6)
+
+Send prompts (sync or async), list/get messages, execute slash commands, run shell commands.
+
+### File & Search Tools (6)
+
+Search text/regex across the project, find files by name, find workspace symbols, list directories, read files, check VCS file status.
+
+### Config & Provider Tools (8)
+
+Get/update config, list providers and models, manage auth (API keys, OAuth).
+
+### TUI Control Tools (9)
+
+Remote-control the OpenCode TUI: append/submit/clear prompts, execute commands, show toasts, open dialogs (help, sessions, models, themes).
+
+### System & Monitoring Tools (13)
+
+Health checks, VCS info, LSP/formatter status, MCP server management, agent/command listing, logging, SSE event polling.
+
+### Resources (10)
+
+Browseable data endpoints:
+
+| URI | Description |
+|---|---|
+| `opencode://project/current` | Current active project |
+| `opencode://config` | Current configuration |
+| `opencode://providers` | Providers with models |
+| `opencode://agents` | Available agents |
+| `opencode://commands` | Available commands |
+| `opencode://health` | Server health and version |
+| `opencode://vcs` | Version control info |
+| `opencode://sessions` | All sessions |
+| `opencode://mcp-servers` | MCP server status |
+| `opencode://file-status` | VCS file status |
+
+### Prompts (5)
+
+Guided workflow templates:
+
+| Prompt | Description |
+|---|---|
+| `opencode-code-review` | Structured code review from session diffs |
+| `opencode-debug` | Guided debugging workflow |
+| `opencode-project-setup` | Get oriented in a new project |
+| `opencode-implement` | Have OpenCode implement a feature |
+| `opencode-session-summary` | Summarize a session |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `OPENCODE_BASE_URL` | URL of the OpenCode server | `http://127.0.0.1:4096` |
+| `OPENCODE_SERVER_USERNAME` | HTTP basic auth username | `opencode` |
+| `OPENCODE_SERVER_PASSWORD` | HTTP basic auth password | *(none — auth disabled)* |
+
+## How It Works
+
+```
+MCP Client  <--stdio-->  opencode-mcp  <--HTTP-->  OpenCode Server
+(Claude, Cursor, etc.)   (this package)            (opencode serve)
+```
+
+The MCP server communicates over **stdio** using the Model Context Protocol. When a client invokes a tool, the server translates it into HTTP calls against the OpenCode headless API. The OpenCode server must be running separately (`opencode serve`).
+
+## Architecture
+
+```
+src/
+  index.ts              Entry point — wires everything together
+  client.ts             HTTP client with retry, SSE, error categorization
+  helpers.ts            Smart response formatting for LLM-friendly output
+  resources.ts          MCP Resources (10 browseable data endpoints)
+  prompts.ts            MCP Prompts (5 guided workflow templates)
+  tools/
+    workflow.ts         High-level workflow tools (7)
+    session.ts          Session management tools (18)
+    message.ts          Message/prompt tools (6)
+    file.ts             File and search tools (6)
+    tui.ts              TUI remote control tools (9)
+    config.ts           Config tools (3)
+    provider.ts         Provider/auth tools (5)
+    misc.ts             System, agents, LSP, MCP, logging tools (13)
+    events.ts           SSE event polling (1)
+    global.ts           Health check (1)
+    project.ts          Project tools (2)
+```
+
+## Development
+
+```bash
+git clone https://github.com/AlaeddineMessadi/opencode-mcp.git
+cd opencode-mcp
+npm install
+npm run build    # compiles TypeScript and sets executable permissions
+npm start        # runs the MCP server
+npm run dev      # watch mode
+```
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) — step-by-step setup guide
+- [Configuration](docs/configuration.md) — all env vars and MCP client configs
+- [Tools Reference](docs/tools.md) — detailed reference for all 70 tools
+- [Resources Reference](docs/resources.md) — all 10 MCP resources
+- [Prompts Reference](docs/prompts.md) — all 5 MCP prompts
+- [Usage Examples](docs/examples.md) — real workflow examples
+- [Architecture](docs/architecture.md) — system design and data flow
+
+## References
+
+- [OpenCode Documentation](https://opencode.ai/docs/)
+- [OpenCode Server API](https://opencode.ai/docs/server/)
+- [OpenCode SDK](https://opencode.ai/docs/sdk/)
+- [Model Context Protocol](https://modelcontextprotocol.io/)
+
+## License
+
+[MIT](LICENSE)

package/dist/client.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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)
+ */
+export interface OpenCodeClientOptions {
+    baseUrl: string;
+    username?: string;
+    password?: string;
+}
+export declare class OpenCodeError extends Error {
+    readonly status: number;
+    readonly method: string;
+    readonly path: string;
+    readonly body: string;
+    constructor(message: string, status: number, method: string, path: string, body: string);
+    get isTransient(): boolean;
+    get isNotFound(): boolean;
+    get isAuth(): boolean;
+}
+export declare class OpenCodeClient {
+    private baseUrl;
+    private authHeader?;
+    constructor(options: OpenCodeClientOptions);
+    getBaseUrl(): string;
+    private buildUrl;
+    private headers;
+    private request;
+    get<T = unknown>(path: string, query?: Record<string, string>): Promise<T>;
+    post<T = unknown>(path: string, body?: unknown, opts?: {
+        timeout?: number;
+    }): Promise<T>;
+    patch<T = unknown>(path: string, body?: unknown): Promise<T>;
+    put<T = unknown>(path: string, body?: unknown): Promise<T>;
+    delete<T = unknown>(path: string, query?: Record<string, string>): Promise<T>;
+    /**
+     * Subscribe to SSE events. Returns an async iterable of parsed events.
+     * The caller should break out of the loop when done.
+     */
+    subscribeSSE(path: string): AsyncGenerator<{
+        event: string;
+        data: string;
+    }, void, undefined>;
+}

package/dist/client.js

@@ -0,0 +1,197 @@
+/**
+ * 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)
+ */
+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;
+export class OpenCodeClient {
+    baseUrl;
+    authHeader;
+    constructor(options) {
+        this.baseUrl = options.baseUrl.replace(/\/$/, "");
+        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) {
+        const h = {
+            "Content-Type": "application/json",
+            Accept: accept ?? "application/json",
+        };
+        if (this.authHeader) {
+            h["Authorization"] = this.authHeader;
+        }
+        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(),
+                    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;
+            }
+        }
+        throw lastError ?? new Error(`${method} ${path} failed after retries`);
+    }
+    async get(path, query) {
+        return this.request("GET", path, { query });
+    }
+    async post(path, body, opts) {
+        return this.request("POST", path, { body, timeout: opts?.timeout });
+    }
+    async patch(path, body) {
+        return this.request("PATCH", path, { body });
+    }
+    async put(path, body) {
+        return this.request("PUT", path, { body });
+    }
+    async delete(path, query) {
+        return this.request("DELETE", path, { query });
+    }
+    /**
+     * Subscribe to SSE events. Returns an async iterable of parsed events.
+     * The caller should break out of the loop when done.
+     */
+    async *subscribeSSE(path) {
+        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",
+            },
+        });
+        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 = "";
+        try {
+            while (true) {
+                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 {
+            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,53 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+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;
+/**
+ * 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;
+    }[];
+};