opencode-samcp 0.0.1__py3-none-any.whl

opencode_samcp/__init__.py

@@ -0,0 +1 @@
+"""opencode-samcp: sub-agent MCP server for opencode."""

opencode_samcp/__main__.py

@@ -0,0 +1,3 @@
+from opencode_samcp.server import main
+
+main()

opencode_samcp/server.py

@@ -0,0 +1,316 @@
+"""MCP server that lets any MCP client (Devin, Codex, Claude Code, ...) delegate coding tasks to opencode and manage its sessions."""
+
+import argparse
+import asyncio
+import json
+import os
+import shutil
+import signal
+import sys
+import time
+import uuid
+
+from mcp.server.fastmcp import FastMCP
+
+OPENCODE = os.environ.get("OPENCODE_BIN", "opencode")
+DEFAULT_MODEL = os.environ.get("OPENCODE_MODEL")  # unset -> opencode's configured default
+
+mcp = FastMCP("opencode-samcp")
+JOBS: dict[str, dict] = {}
+MAX_JOBS = int(os.environ.get("OPENCODE_MAX_JOBS", "200"))  # finished jobs beyond this are evicted
+
+
+def _clip(s, n):
+    s = s if isinstance(s, str) else json.dumps(s)
+    return s if len(s) <= n else s[:n] + f"... [+{len(s) - n} chars]"
+
+
+def _resolve_dir(directory):
+    d = os.path.abspath(os.path.expanduser(directory))
+    if not os.path.isdir(d):
+        raise ValueError(f"directory does not exist: {d}")
+    return d
+
+
+async def _cli(args, cwd):
+    proc = await asyncio.create_subprocess_exec(
+        OPENCODE, *args, cwd=cwd,
+        stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
+    )
+    out, err = await proc.communicate()
+    if proc.returncode != 0:
+        raise RuntimeError(f"opencode {' '.join(args)} failed ({proc.returncode}): {err.decode()[-2000:]}")
+    return out.decode()
+
+
+def _handle_event(job, ev):
+    job["session_id"] = job["session_id"] or ev.get("sessionID")
+    part = ev.get("part") or {}
+    kind = ev.get("type")
+    if kind == "text" and part.get("text", "").strip():
+        job["texts"].append(part["text"].strip())
+    elif kind == "tool_use":
+        st = part.get("state") or {}
+        job["tools"].append({
+            "tool": part.get("tool"),
+            "status": st.get("status"),
+            "input": _clip(st.get("input"), 300),
+            "output": _clip(st.get("output") or "", 300),
+        })
+    elif kind == "step_finish":
+        tok = part.get("tokens") or {}
+        job["tokens"]["input"] += tok.get("input", 0)
+        job["tokens"]["output"] += tok.get("output", 0)
+        job["cost"] += part.get("cost") or 0
+    elif kind == "error":
+        err = ev.get("error") or {}
+        job["errors"].append(err.get("message") or json.dumps(err))
+
+
+async def _run_job(job, args):
+    try:
+        proc = await asyncio.create_subprocess_exec(
+            OPENCODE, *args, cwd=job["directory"],
+            stdin=asyncio.subprocess.DEVNULL, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE,
+            limit=16 * 1024 * 1024, start_new_session=True,
+        )
+        job["proc"] = proc
+        stderr_task = asyncio.create_task(proc.stderr.read())
+        async for raw in proc.stdout:
+            line = raw.decode(errors="replace").strip()
+            if not line:
+                continue
+            try:
+                _handle_event(job, json.loads(line))
+            except json.JSONDecodeError:
+                job["errors"].append(_clip(line, 500))
+        job["exit_code"] = await proc.wait()
+        stderr = (await stderr_task).decode(errors="replace").strip()
+        if job["exit_code"] != 0 and stderr:
+            job["errors"].append(_clip(stderr, 2000))
+        if job["status"] == "running":
+            job["status"] = "failed" if job["exit_code"] != 0 or (job["errors"] and not job["texts"]) else "completed"
+    except Exception as e:  # noqa: BLE001 - surface any failure on the job instead of hanging
+        job["errors"].append(f"{type(e).__name__}: {e}")
+        if job["status"] == "running":
+            job["status"] = "failed"
+        proc = job.get("proc")
+        if proc and proc.returncode is None:
+            _kill_group(proc, signal.SIGKILL)
+    finally:
+        job["finished"] = time.time()
+
+
+def _kill_group(proc, sig):
+    try:
+        os.killpg(proc.pid, sig)
+    except (ProcessLookupError, PermissionError):
+        pass
+
+
+def _evict_old_jobs():
+    done = [j for j in JOBS.values() if j["status"] != "running"]
+    for j in sorted(done, key=lambda j: j["finished"] or 0)[: max(0, len(JOBS) - MAX_JOBS)]:
+        JOBS.pop(j["id"], None)
+
+
+def _report(job, full=True):
+    r = {
+        "job_id": job["id"],
+        "status": job["status"],
+        "session_id": job["session_id"],
+        "directory": job["directory"],
+        "title": job["title"],
+        "elapsed_s": round((job["finished"] or time.time()) - job["started"], 1),
+    }
+    if full:
+        r.update({
+            "final_text": job["texts"][-1] if job["texts"] else "",
+            "tool_calls": job["tools"][-40:],
+            "tool_call_count": len(job["tools"]),
+            "errors": job["errors"],
+            "tokens": job["tokens"],
+            "cost": round(job["cost"], 4),
+        })
+        if len(job["texts"]) > 1:
+            r["earlier_text"] = [_clip(t, 600) for t in job["texts"][-6:-1]]
+    return r
+
+
+async def _wait(job, wait_seconds):
+    try:
+        await asyncio.wait_for(asyncio.shield(job["task"]), timeout=max(wait_seconds, 0))
+    except asyncio.TimeoutError:
+        pass
+
+
+@mcp.tool()
+async def opencode_run(
+    prompt: str,
+    directory: str,
+    session_id: str | None = None,
+    fork: bool = False,
+    model: str | None = None,
+    agent: str | None = None,
+    title: str | None = None,
+    files: list[str] | None = None,
+    auto_approve: bool = True,
+    wait_seconds: int = 600,
+) -> dict:
+    """Send a coding task to opencode in `directory`.
+
+    Starts a new opencode session, or continues `session_id` (with `fork=True`, branches it first).
+    Waits up to `wait_seconds` for completion; if still running, returns status "running" with a
+    job_id — poll it with opencode_job. Use wait_seconds=0 to start in the background and run
+    several sessions in parallel (use separate git worktrees so they don't clash).
+    `auto_approve` lets opencode edit files/run commands without asking (required for headless use).
+    `model` is "provider/model"; defaults to opencode's configured model.
+    Returns the session_id, opencode's final message, a summary of tool calls, errors, and usage.
+    """
+    if fork and not session_id:
+        raise ValueError("fork=True requires session_id")
+    d = _resolve_dir(directory)
+    args = ["run", "--format", "json"]
+    if auto_approve:
+        args.append("--auto")
+    if session_id:
+        args += ["--session", session_id]
+        if fork:
+            args.append("--fork")
+    model = model or DEFAULT_MODEL
+    if model:
+        args += ["--model", model]
+    if agent:
+        args += ["--agent", agent]
+    if title:
+        args += ["--title", title]
+    for f in files or []:
+        args += ["--file", f]
+    # opencode duplicates args after "--", so pass the prompt positionally; a leading space
+    # stops a prompt starting with "-" from being parsed as a flag.
+    args.append(" " + prompt if prompt.startswith("-") else prompt)
+
+    job = {
+        "id": uuid.uuid4().hex[:8], "status": "running", "directory": d, "title": title,
+        "session_id": None if fork else session_id, "texts": [], "tools": [], "errors": [],
+        "tokens": {"input": 0, "output": 0}, "cost": 0.0, "exit_code": None,
+        "started": time.time(), "finished": None, "proc": None,
+    }
+    job["task"] = asyncio.create_task(_run_job(job, args))
+    JOBS[job["id"]] = job
+    _evict_old_jobs()
+    await _wait(job, wait_seconds)
+    return _report(job)
+
+
+@mcp.tool()
+async def opencode_job(job_id: str, wait_seconds: int = 0) -> dict:
+    """Get the status/result of an opencode_run job, optionally waiting up to `wait_seconds` for it to finish."""
+    job = JOBS.get(job_id)
+    if not job:
+        raise ValueError(f"unknown job_id {job_id}")
+    if job["status"] == "running" and wait_seconds > 0:
+        await _wait(job, wait_seconds)
+    return _report(job)
+
+
+@mcp.tool()
+async def opencode_jobs() -> list[dict]:
+    """List opencode_run jobs started by this server (running and finished)."""
+    return [_report(j, full=False) for j in JOBS.values()]
+
+
+@mcp.tool()
+async def opencode_cancel(job_id: str) -> dict:
+    """Stop a running opencode job. The session is kept and can be continued later."""
+    job = JOBS.get(job_id)
+    if not job:
+        raise ValueError(f"unknown job_id {job_id}")
+    if job["status"] == "running" and job["proc"] and job["proc"].returncode is None:
+        job["status"] = "cancelled"
+        _kill_group(job["proc"], signal.SIGTERM)
+        try:
+            await asyncio.wait_for(asyncio.shield(job["task"]), timeout=10)
+        except asyncio.TimeoutError:
+            _kill_group(job["proc"], signal.SIGKILL)
+            await job["task"]
+    return _report(job, full=False)
+
+
+@mcp.tool()
+async def opencode_sessions(directory: str, limit: int = 20) -> list[dict]:
+    """List opencode sessions for the project containing `directory`, newest first."""
+    d = _resolve_dir(directory)
+    out = await _cli(["session", "list", "--format", "json", "-n", str(limit)], d)
+    return json.loads(out or "[]")
+
+
+@mcp.tool()
+async def opencode_transcript(session_id: str, directory: str, max_chars: int = 30000) -> dict:
+    """Get a condensed transcript of an opencode session: user prompts, assistant text, and tool calls with results."""
+    d = _resolve_dir(directory)
+    data = json.loads(await _cli(["session", "export", session_id], d))
+    info = data.get("info", {})
+    lines = []
+    for msg in data.get("messages", []):
+        if msg.get("type") == "user":
+            lines.append(f"USER: {msg.get('text', '')}")
+            continue
+        for c in msg.get("content", []):
+            if c.get("type") == "text" and c.get("text", "").strip():
+                lines.append(f"ASSISTANT: {c['text'].strip()}")
+            elif c.get("type") == "tool":
+                st = c.get("state") or {}
+                result = " ".join(x.get("text", "") for x in st.get("content") or [] if isinstance(x, dict))
+                lines.append(f"TOOL {c.get('name')} [{st.get('status')}] {_clip(st.get('input'), 400)}"
+                             f"\n  -> {_clip(result, 400)}")
+    text = "\n".join(lines)
+    if len(text) > max_chars:
+        text = f"[... {len(text) - max_chars} earlier chars omitted ...]\n" + text[-max_chars:]
+    return {
+        "session_id": info.get("id", session_id),
+        "outcome": info.get("outcome"),
+        "model": info.get("model"),
+        "tokens": info.get("tokens"),
+        "cost": info.get("cost"),
+        "transcript": text,
+    }
+
+
+@mcp.tool()
+async def opencode_delete_session(session_id: str, directory: str) -> str:
+    """Delete an opencode session and its child sessions."""
+    d = _resolve_dir(directory)
+    await _cli(["session", "delete", session_id], d)
+    return f"deleted {session_id}"
+
+
+def check_opencode() -> str:
+    """Return the resolved opencode binary path, or exit with a clear error if it is missing."""
+    path = shutil.which(OPENCODE)
+    if not path:
+        sys.exit(
+            f"opencode-samcp failed: opencode not installed on machine "
+            f"('{OPENCODE}' not found on PATH). Install it from https://opencode.ai "
+            f"or set OPENCODE_BIN to its path."
+        )
+    return path
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="opencode-samcp", description=__doc__)
+    parser.add_argument("--transport", choices=["stdio", "sse", "streamable-http"], default="stdio")
+    parser.add_argument("--host", default="127.0.0.1", help="bind address for HTTP transports")
+    parser.add_argument("--port", type=int, default=8765, help="port for HTTP transports")
+    args = parser.parse_args()
+    check_opencode()
+    if args.transport != "stdio" and args.host not in ("127.0.0.1", "localhost", "::1"):
+        print(f"WARNING: serving unauthenticated MCP on {args.host}:{args.port}; anyone who can reach it "
+              "can run commands on this machine. Use localhost or an authenticated proxy.", file=sys.stderr)
+    mcp.settings.host = args.host
+    mcp.settings.port = args.port
+    mcp.run(transport=args.transport)
+
+
+if __name__ == "__main__":
+    main()

opencode_samcp-0.0.1.dist-info/METADATA

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: opencode-samcp
+Version: 0.0.1
+Summary: Sub-agent MCP: let Devin, Codex, Claude Code and other agents spawn opencode sessions to do work
+Project-URL: Homepage, https://github.com/amirdaraby/opencode-samcp
+Project-URL: Repository, https://github.com/amirdaraby/opencode-samcp
+Project-URL: Issues, https://github.com/amirdaraby/opencode-samcp/issues
+Author: Amir Daraby
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,codex,devin,mcp,opencode,subagent
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development
+Requires-Python: >=3.10
+Requires-Dist: mcp<2,>=1.2
+Description-Content-Type: text/markdown
+
+# opencode-samcp
+
+**S**ub-**A**gent **MCP** — an MCP server that lets an AI agent (Devin, Codex, Claude Code, Cursor, …) spawn [opencode](https://opencode.ai) sessions as sub-agents and hand them coding work.
+
+The parent agent calls `opencode_run` with a prompt and a directory; opencode does the work headlessly (`opencode run --format json --auto`) and the result comes back as structured data: final message, tool-call summary, errors, token usage and cost. Sessions can be continued, forked, run in parallel in the background, inspected and deleted.
+
+## Requirements
+
+- [opencode](https://opencode.ai) installed and authenticated (`opencode` on `PATH`, or set `OPENCODE_BIN`)
+- [uv](https://docs.astral.sh/uv/) (or `pip install`)
+
+## Install / run
+
+The server is Python; every option below needs [uv](https://docs.astral.sh/uv/) and opencode on the machine.
+
+| Method | Command |
+|---|---|
+| **npx** (no install) | `npx -y opencode-samcp` |
+| **npm** (global) | `npm i -g opencode-samcp` then `opencode-samcp` |
+| **uvx** from PyPI | `uvx opencode-samcp` |
+| **uvx** from GitHub | `uvx --from git+https://github.com/amirdaraby/opencode-samcp opencode-samcp` |
+| **pip** | `pip install opencode-samcp` then `opencode-samcp` |
+
+The npm package is a thin launcher: it bundles the Python server and runs it through `uvx`.
+If `uv` or `opencode` is missing, it exits with a clear "not installed on machine" error.
+
+## Configure your client
+
+### Devin
+Settings → MCP Marketplace → *Add Your Own* (STDIO):
+
+| Field | Value |
+|---|---|
+| Command | `npx` |
+| Args | `-y opencode-samcp` |
+
+Devin runs in its own VM, so opencode must be installed and logged in **there** (add it to the machine setup / snapshot).
+
+### Codex (`~/.codex/config.toml`)
+```toml
+[mcp_servers.opencode]
+command = "npx"
+args = ["-y", "opencode-samcp"]
+```
+
+### Claude Code
+```bash
+claude mcp add opencode -- npx -y opencode-samcp
+```
+
+### Generic JSON
+```json
+{ "mcpServers": { "opencode": { "command": "npx", "args": ["-y", "opencode-samcp"] } } }
+```
+
+### HTTP transport
+For clients that only speak remote MCP:
+```bash
+opencode-samcp --transport streamable-http --host 127.0.0.1 --port 8765   # endpoint: /mcp
+opencode-samcp --transport sse ...                                         # endpoint: /sse
+```
+There is **no authentication** and the sub-agent can edit files and run commands — keep it on localhost or behind an authenticated tunnel/proxy.
+
+## Tools
+
+| Tool | Purpose |
+|---|---|
+| `opencode_run` | Start a session (or continue `session_id`, optionally `fork`) in `directory`. Waits up to `wait_seconds` (default 600); `0` runs in the background. Supports `model`, `agent`, `title`, `files`, `auto_approve`. |
+| `opencode_job` | Poll/wait on a background job by `job_id`. |
+| `opencode_jobs` | List jobs started by this server. |
+| `opencode_cancel` | Stop a running job (session is kept). |
+| `opencode_sessions` | List opencode sessions for a project directory. |
+| `opencode_transcript` | Condensed transcript of a session. |
+| `opencode_delete_session` | Delete a session and its children. |
+
+**Parallel work:** start several jobs with `wait_seconds=0`, each in its own git worktree so they don't clash, then poll with `opencode_job`.
+
+## Environment variables
+
+| Var | Meaning |
+|---|---|
+| `OPENCODE_BIN` | Path to the opencode binary (default `opencode`) |
+| `OPENCODE_MODEL` | Default `provider/model` when the caller doesn't pass one |
+
+## Security
+
+`auto_approve` defaults to `true` (required for headless runs): the sub-agent can modify files and run shell commands in the given directory. Only expose this server to agents you trust, and point it at disposable checkouts/worktrees where possible.
+
+## Notes
+
+- Job state is in-memory; it is lost when the server process restarts (opencode sessions themselves persist and can be resumed by `session_id`).
+
+## Publishing (maintainers)
+
+```bash
+npm publish            # npm / npx
+uv build && uv publish # PyPI / uvx / pip
+```
+
+## Development
+
+```bash
+uv run --group dev pytest
+```
+
+MIT licensed.

opencode_samcp-0.0.1.dist-info/RECORD

@@ -0,0 +1,8 @@
+opencode_samcp/__init__.py,sha256=QzEmjJlndNoQ3tEP0ULk7zzeca4UqZ1aC1lntWsGoTQ,57
+opencode_samcp/__main__.py,sha256=qqHoLbN4n2aHyq2wCvGHw6ULuJ5t-x3VWquT2i9Qg4Q,47
+opencode_samcp/server.py,sha256=3HsHHPEe0mhOhVgWt-cid3nmtJSXAJk7u3hDJLyzkmc,12036
+opencode_samcp-0.0.1.dist-info/METADATA,sha256=-UHpqhS1K0IvjDih7qIlCtTznw7aTnIGTKaJctq1zac,4762
+opencode_samcp-0.0.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+opencode_samcp-0.0.1.dist-info/entry_points.txt,sha256=OEYWXEAv0JuloHMlh1Nz99JFEXDwzun0knMxOGGpsOA,62
+opencode_samcp-0.0.1.dist-info/licenses/LICENSE,sha256=8-L4qkT60D9VHJVWrvTsgBSK7i1Dm2x_iwuSdhNXY0o,1068
+opencode_samcp-0.0.1.dist-info/RECORD,,

opencode_samcp-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

opencode_samcp-0.0.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+opencode-samcp = opencode_samcp.server:main

opencode_samcp-0.0.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amir Daraby
+
+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.