@vymalo/opencode-devtools-mcp 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 vymalo contributors
+
+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,45 @@
+# @vymalo/opencode-devtools-mcp
+
+> The [`@vymalo/opencode-devtools`](../opencode-devtools) utilities for **any MCP client** — Claude
+> Code, Cursor, Cline, Zed, …
+
+[![npm](https://img.shields.io/npm/v/@vymalo/opencode-devtools-mcp)](https://www.npmjs.com/package/@vymalo/opencode-devtools-mcp)
+![node: >=22](https://img.shields.io/badge/node-%3E%3D22-339933)
+![license: MIT](https://img.shields.io/badge/license-MIT-blue)
+
+An MCP **stdio server** exposing the same local developer utilities (math, codec, crypto, datetime,
+convert, http) over the Model Context Protocol. No bridge, no auth — each tool is pure in-process
+compute. The MCP server and the OpenCode plugin share **one tool catalog**, so the two surfaces
+never drift.
+
+## Setup
+
+```jsonc
+{
+  "mcpServers": {
+    "devtools": {
+      "command": "npx",
+      "args": ["-y", "@vymalo/opencode-devtools-mcp"],
+      "env": {
+        "OCD_GROUPS": "math,codec,crypto,datetime,convert",
+        "OCD_HTTP_ALLOW_PRIVATE": "0",
+        "OCD_HTTP_TIMEOUT": "30000"
+      }
+    }
+  }
+}
+```
+
+| Env | Default | Meaning |
+| --- | --- | --- |
+| `OCD_GROUPS` | the 5 offline groups | Comma list of groups to expose (add `http` to enable egress). |
+| `OCD_HTTP_ALLOW_PRIVATE` | `0` | `1` to let the `http` group reach loopback/private hosts (SSRF guard off). |
+| `OCD_HTTP_TIMEOUT` | `30000` | Per-request timeout (ms). |
+
+Logs go to **stderr** (stdout carries the MCP JSON-RPC stream).
+
+Full tool reference and security model: [`docs/devtools.md`](../../docs/devtools.md).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { type McpContent, type McpToolResult, toMcpContent, toMcpError } from "./render.js";
+export { createMcpServer, groupsFromEnv, type McpServerDeps, selectTools } from "./server.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { toMcpContent, toMcpError } from "./render.js";
+export { createMcpServer, groupsFromEnv, selectTools } from "./server.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAuC,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC5F,OAAO,EAAE,eAAe,EAAE,aAAa,EAAsB,WAAW,EAAE,MAAM,aAAa,CAAC"}

package/dist/mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/mcp.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { DEFAULT_GROUPS, resolveOptions, TOOL_GROUPS } from "@vymalo/opencode-devtools/lib";
+import { createMcpServer, groupsFromEnv } from "./server.js";
+async function main() {
+    const groups = groupsFromEnv(process.env.OCD_GROUPS, TOOL_GROUPS, DEFAULT_GROUPS);
+    const options = resolveOptions({
+        groups,
+        http: {
+            allowPrivateNetwork: /^(1|true|yes|on)$/i.test(process.env.OCD_HTTP_ALLOW_PRIVATE ?? ""),
+            timeoutMs: Number(process.env.OCD_HTTP_TIMEOUT ?? 30_000)
+        }
+    });
+    process.stderr.write(`opencode-devtools-mcp: groups ${options.groups.join(", ")}\n`);
+    if (options.groups.includes("http")) {
+        process.stderr.write(`opencode-devtools-mcp: http egress enabled (allowPrivateNetwork=${options.http.allowPrivateNetwork})\n`);
+    }
+    const server = createMcpServer(options);
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    process.stderr.write(`opencode-devtools-mcp fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp.js","sourceRoot":"","sources":["../src/mcp.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,cAAc,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAE5F,OAAO,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE7D,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,cAAc,CAAC,CAAC;IAClF,MAAM,OAAO,GAAG,cAAc,CAAC;QAC7B,MAAM;QACN,IAAI,EAAE;YACJ,mBAAmB,EAAE,oBAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,EAAE,CAAC;YACxF,SAAS,EAAE,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,gBAAgB,IAAI,MAAM,CAAC;SAC1D;KACF,CAAC,CAAC;IAEH,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,iCAAiC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrF,IAAI,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;QACpC,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,mEAAmE,OAAO,CAAC,IAAI,CAAC,mBAAmB,KAAK,CACzG,CAAC;IACJ,CAAC;IAED,MAAM,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,CAAC;IACxC,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;AACnD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACnB,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,gCAAgC,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CACrF,CAAC;IACF,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/render.d.ts

@@ -0,0 +1,18 @@
+import type { NeutralResult } from "@vymalo/opencode-devtools/lib";
+/** An MCP tool-result content block. Devtools results are text-only. */
+export type McpContent = {
+    type: "text";
+    text: string;
+};
+export interface McpToolResult {
+    content: McpContent[];
+    isError?: boolean;
+}
+/**
+ * Render an adapter-neutral result into MCP tool-result content. Devtools tools
+ * never return images, so both `text` and `json` results map to a TextContent
+ * (the neutral result's `text` is always self-sufficient).
+ */
+export declare function toMcpContent(result: NeutralResult): McpToolResult;
+/** Render a thrown error as an MCP tool error result (so the model sees it). */
+export declare function toMcpError(err: unknown): McpToolResult;

package/dist/render.js

@@ -0,0 +1,14 @@
+/**
+ * Render an adapter-neutral result into MCP tool-result content. Devtools tools
+ * never return images, so both `text` and `json` results map to a TextContent
+ * (the neutral result's `text` is always self-sufficient).
+ */
+export function toMcpContent(result) {
+    return { content: [{ type: "text", text: result.text }] };
+}
+/** Render a thrown error as an MCP tool error result (so the model sees it). */
+export function toMcpError(err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+//# sourceMappingURL=render.js.map

package/dist/render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.js","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"AAUA;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,MAAqB;IAChD,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;AAC5D,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,UAAU,CAAC,GAAY;IACrC,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IACjE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;AACvE,CAAC"}

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { selectTools, type ToolContext, type ToolGroup, type ResolvedDevtoolsOptions } from "@vymalo/opencode-devtools/lib";
+export { selectTools };
+export interface McpServerDeps {
+    /** Inject the execution context (clock / randomness / fetch) for tests. */
+    context?: Partial<Omit<ToolContext, "options">>;
+}
+/**
+ * Build an MCP server that exposes the group-filtered devtools catalog and runs
+ * each tool's handler locally (no bridge — these are pure compute tools).
+ */
+export declare function createMcpServer(options: ResolvedDevtoolsOptions, deps?: McpServerDeps): Server;
+/** Selected group ids from a comma-separated env string, falling back to defaults. */
+export declare function groupsFromEnv(raw: string | undefined, all: readonly ToolGroup[], fallback: readonly ToolGroup[]): ToolGroup[];

package/dist/server.js

@@ -0,0 +1,50 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
+import { buildContext, selectTools, toJsonSchema } from "@vymalo/opencode-devtools/lib";
+import { toMcpContent, toMcpError } from "./render.js";
+export { selectTools };
+/**
+ * Build an MCP server that exposes the group-filtered devtools catalog and runs
+ * each tool's handler locally (no bridge — these are pure compute tools).
+ */
+export function createMcpServer(options, deps = {}) {
+    const specs = selectTools(options.groups);
+    const byName = new Map(specs.map((spec) => [spec.name, spec]));
+    const ctx = buildContext(options, deps.context);
+    const server = new Server({ name: "opencode-devtools", version: "0.9.0" }, { capabilities: { tools: {} } });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: specs.map((spec) => ({
+            name: spec.name,
+            description: spec.description,
+            inputSchema: toJsonSchema(spec.input)
+        }))
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const render = (r) => r;
+        const spec = byName.get(request.params.name);
+        if (!spec) {
+            return render(toMcpError(new Error(`unknown tool: ${request.params.name}`)));
+        }
+        const args = (request.params.arguments ?? {});
+        try {
+            const result = await spec.handler(args, ctx);
+            return render(toMcpContent(result));
+        }
+        catch (err) {
+            return render(toMcpError(err));
+        }
+    });
+    return server;
+}
+/** Selected group ids from a comma-separated env string, falling back to defaults. */
+export function groupsFromEnv(raw, all, fallback) {
+    if (!raw) {
+        return [...fallback];
+    }
+    const parts = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((g) => all.includes(g));
+    return parts.length > 0 ? parts : [...fallback];
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

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

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@vymalo/opencode-devtools-mcp",
+  "version": "0.9.0",
+  "description": "MCP server for @vymalo/opencode-devtools — exposes the same local developer utilities (math, codec, crypto, datetime, convert, http) over the Model Context Protocol so any MCP client (Claude Code, Cursor, Cline, …) can call them. No bridge, no auth — pure deterministic compute.",
+  "license": "MIT",
+  "author": "vymalo contributors",
+  "homepage": "https://github.com/vymalo/opencode-oauth2#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vymalo/opencode-oauth2.git",
+    "directory": "packages/opencode-devtools-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/vymalo/opencode-oauth2/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "utilities",
+    "math",
+    "crypto",
+    "jwt",
+    "datetime",
+    "cron"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "opencode-devtools-mcp": "dist/mcp.js"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@vymalo/opencode-devtools": "0.9.0"
+  },
+  "devDependencies": {
+    "vite": "^8.0.14",
+    "vitest": "^4.1.7"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "lint": "biome lint .",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "coverage": "vitest run --coverage",
+    "format": "biome format --write .",
+    "format:check": "biome format ."
+  }
+}