opencode-samcp 0.0.1__tar.gz

opencode_samcp-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,12 @@
+name: ci
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv run --python ${{ matrix.python }} --group dev pytest

opencode_samcp-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - name: Tag, package.json and pyproject.toml versions must match
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          NPM_V=$(node -p "require('./package.json').version")
+          PY_V=$(python3 -c "import tomllib;print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          echo "tag=$TAG npm=$NPM_V pypi=$PY_V"
+          [ "$TAG" = "$NPM_V" ] && [ "$TAG" = "$PY_V" ] || { echo "version mismatch"; exit 1; }
+      - run: uv run --group dev pytest
+
+  pypi:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # PyPI trusted publishing
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - run: uv publish --trusted-publishing always
+
+  npm:
+    needs: verify
+    runs-on: ubuntu-latest
+    environment: npm
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          registry-url: https://registry.npmjs.org
+      - run: npm publish --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

opencode_samcp-0.0.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+node_modules/
+*.tgz

opencode_samcp-0.0.1/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.

opencode_samcp-0.0.1/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,106 @@
+# 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/bin/opencode-samcp.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+// npm launcher for opencode-samcp. The server itself is Python; this shim runs the
+// copy bundled in this package through uv (uvx), so no manual Python setup is needed.
+const { spawn, spawnSync } = require("node:child_process");
+const path = require("node:path");
+
+const pkgRoot = path.resolve(__dirname, "..");
+const args = process.argv.slice(2);
+
+function has(cmd) {
+  return spawnSync(cmd, ["--version"], { stdio: "ignore" }).status === 0;
+}
+
+let cmd, cmdArgs;
+if (has("uvx")) {
+  [cmd, cmdArgs] = ["uvx", ["--from", pkgRoot, "opencode-samcp", ...args]];
+} else if (has("uv")) {
+  [cmd, cmdArgs] = ["uv", ["tool", "run", "--from", pkgRoot, "opencode-samcp", ...args]];
+} else {
+  console.error(
+    "opencode-samcp failed: uv is not installed on machine (needed to run the Python server). " +
+      "Install it from https://docs.astral.sh/uv/getting-started/installation/"
+  );
+  process.exit(1);
+}
+
+const child = spawn(cmd, cmdArgs, { stdio: "inherit" });
+for (const sig of ["SIGINT", "SIGTERM"]) process.on(sig, () => child.kill(sig));
+child.on("error", (e) => { console.error(`opencode-samcp failed to start: ${e.message}`); process.exit(1); });
+child.on("exit", (code, signal) => process.exit(signal ? 1 : code ?? 1));

opencode_samcp-0.0.1/package.json

@@ -0,0 +1,14 @@
+{
+  "name": "opencode-samcp",
+  "version": "0.0.1",
+  "description": "Sub-agent MCP: let Devin, Codex, Claude Code and other agents spawn opencode sessions to do work",
+  "license": "MIT",
+  "author": "Amir Daraby",
+  "repository": { "type": "git", "url": "git+https://github.com/amirdaraby/opencode-samcp.git" },
+  "homepage": "https://github.com/amirdaraby/opencode-samcp#readme",
+  "bugs": { "url": "https://github.com/amirdaraby/opencode-samcp/issues" },
+  "bin": { "opencode-samcp": "bin/opencode-samcp.js" },
+  "files": ["bin", "src", "!**/__pycache__", "pyproject.toml", "README.md", "LICENSE"],
+  "keywords": ["mcp", "opencode", "subagent", "devin", "codex", "ai-agents"],
+  "engines": { "node": ">=18" }
+}

opencode_samcp-0.0.1/pyproject.toml

@@ -0,0 +1,37 @@
+[project]
+name = "opencode-samcp"
+version = "0.0.1"
+description = "Sub-agent MCP: let Devin, Codex, Claude Code and other agents spawn opencode sessions to do work"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+dependencies = ["mcp>=1.2,<2"]
+authors = [{ name = "Amir Daraby" }]
+classifiers = [
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Software Development",
+]
+keywords = ["mcp", "opencode", "subagent", "devin", "codex", "ai-agents"]
+
+[project.urls]
+Homepage = "https://github.com/amirdaraby/opencode-samcp"
+Repository = "https://github.com/amirdaraby/opencode-samcp"
+Issues = "https://github.com/amirdaraby/opencode-samcp/issues"
+
+[project.scripts]
+opencode-samcp = "opencode_samcp.server:main"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/opencode_samcp"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

opencode_samcp-0.0.1/src/opencode_samcp/__init__.py

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

opencode_samcp-0.0.1/src/opencode_samcp/__main__.py

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