@kagan-sh/opensearch 0.2.0 → 0.3.0

package/README.md

@@ -22,10 +22,46 @@
 
 ---
 
-`@kagan-sh/opensearch` is an OpenCode plugin for broad investigation. It searches session history, the live web, and public code in parallel, then returns a structured evidence-backed response your agent can act on.
+`@kagan-sh/opensearch` is an evidence-backed search tool for AI coding agents. It searches the live web and public code in parallel, then returns structured JSON your agent can act on.
+
+Works as an **OpenCode plugin** and as a **Claude Code MCP server**.
 
 ## Install
 
+### Claude Code (MCP)
+
+```bash
+claude mcp add opensearch -- npx -y @kagan-sh/opensearch
+```
+
+To enable web search via SearXNG:
+
+```bash
+claude mcp add opensearch \
+  -e OPENSEARCH_WEB_URL=http://localhost:8080 \
+  -- npx -y @kagan-sh/opensearch
+```
+
+Or add it to `.mcp.json` in your project root:
+
+```json
+{
+  "mcpServers": {
+    "opensearch": {
+      "command": "npx",
+      "args": ["-y", "@kagan-sh/opensearch"],
+      "env": {
+        "OPENSEARCH_WEB_URL": "http://localhost:8080"
+      }
+    }
+  }
+}
+```
+
+See the [Claude Code install guide](https://kagan-sh.github.io/opensearch/guides/claude-code/) for full details.
+
+### OpenCode (plugin)
+
 Add the plugin to `opencode.json`:
 
 ```json

package/SKILL.md

@@ -2,7 +2,7 @@
 name: opensearch
 description: Use OpenSearch for broad, evidence-backed investigation across session history, the web, and public code when a user asks to search, research, compare sources, or gather official docs and examples.
 license: MIT
-compatibility: Requires OpenCode with @kagan-sh/opensearch installed. The current web provider is SearXNG, so web results need OPENSEARCH_WEB_URL.
+compatibility: Works as an OpenCode plugin or a Claude Code MCP server. The web source requires a SearXNG instance and OPENSEARCH_WEB_URL. In Claude Code, only web and code sources are available.
 metadata:
   version: 0.0.1
 ---
@@ -42,7 +42,7 @@ Use this skill when the task is primarily about finding, comparing, and synthesi
 
 ## Source Selection Guide
 
-- `session` for prior decisions, earlier runs, and local conversation history
+- `session` for prior decisions, earlier runs, and local conversation history (OpenCode only)
 - `web` for official docs, changelogs, and current vendor guidance
 - `code` for public implementation examples and real usage patterns
 

package/dist/config.d.ts

@@ -1,5 +1,6 @@
 import type { Config, SourceId } from "./schema";
 export declare function defaultConfig(): Config;
+export declare function mcpDefaultConfig(): Config;
 export declare function parsePluginConfig(input: unknown): Config | undefined;
 export declare function isSourceAvailable(config: Config, source: SourceId): boolean;
 export declare function resolveSources(config: Config, requested?: SourceId[]): {

package/dist/config.js

@@ -34,6 +34,20 @@ export function defaultConfig() {
         synth: parseBoolean("OPENSEARCH_SYNTH", process.env.OPENSEARCH_SYNTH, true),
     };
 }
+export function mcpDefaultConfig() {
+    return {
+        sources: {
+            session: false,
+            web: {
+                enabled: parseBoolean("OPENSEARCH_SOURCE_WEB", process.env.OPENSEARCH_SOURCE_WEB, true),
+                url: process.env.OPENSEARCH_WEB_URL,
+            },
+            code: parseBoolean("OPENSEARCH_SOURCE_CODE", process.env.OPENSEARCH_SOURCE_CODE, true),
+        },
+        depth: parseDepth(process.env.OPENSEARCH_DEPTH),
+        synth: false,
+    };
+}
 export function parsePluginConfig(input) {
     if (!input || typeof input !== "object" || !("opensearch" in input)) {
         return undefined;

package/dist/mcp.d.ts

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

package/dist/mcp.js

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { mcpDefaultConfig, resolveSources } from "./config";
+import { noResultsResult, noSourcesResult, rawResultsResult, runSourceSearches, } from "./orchestrator";
+import { SOURCE_IDS } from "./schema";
+function serialize(value) {
+    return JSON.stringify(value, null, 2);
+}
+function parseSourceIds(raw) {
+    if (!Array.isArray(raw))
+        return undefined;
+    return raw.filter((s) => typeof s === "string" && SOURCE_IDS.includes(s));
+}
+const config = mcpDefaultConfig();
+const server = new Server({ name: "opensearch", version: "0.0.1" }, { capabilities: { tools: {} } });
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "opensearch",
+            description: "Evidence-backed search across SearXNG web and public code. Returns structured JSON with sources, relevance scores, and follow-up suggestions.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "What to search for",
+                    },
+                    sources: {
+                        type: "array",
+                        items: { type: "string", enum: ["web", "code"] },
+                        description: "Sources to query. Defaults to all enabled.",
+                    },
+                    depth: {
+                        type: "string",
+                        enum: ["quick", "thorough"],
+                        description: "Search depth. Default: quick",
+                    },
+                },
+                required: ["query"],
+            },
+        },
+    ],
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name !== "opensearch") {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Unknown tool: ${request.params.name}` }],
+        };
+    }
+    const args = request.params.arguments ?? {};
+    const query = typeof args.query === "string" ? args.query : "";
+    const depth = args.depth === "thorough" ? "thorough" : config.depth;
+    const start = Date.now();
+    const requested = parseSourceIds(args.sources);
+    const resolved = resolveSources(config, requested);
+    if (resolved.sources.length === 0) {
+        const result = noSourcesResult({
+            query,
+            start,
+            requested: resolved.requested,
+            unavailable: resolved.unavailable,
+        });
+        return { content: [{ type: "text", text: serialize(result) }] };
+    }
+    const search = await runSourceSearches({
+        directory: process.cwd(),
+        config,
+        query,
+        depth,
+        sources: resolved.sources,
+    });
+    if (search.raw.length === 0) {
+        const result = noResultsResult({
+            query,
+            start,
+            requested: resolved.requested,
+            queried: resolved.sources,
+            unavailable: resolved.unavailable,
+            sourceErrors: search.sourceErrors,
+        });
+        return { content: [{ type: "text", text: serialize(result) }] };
+    }
+    const result = rawResultsResult({
+        query,
+        start,
+        requested: resolved.requested,
+        queried: resolved.sources,
+        unavailable: resolved.unavailable,
+        sourceErrors: search.sourceErrors,
+        raw: search.raw,
+        status: "raw",
+    });
+    return { content: [{ type: "text", text: serialize(result) }] };
+});
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/orchestrator.d.ts

@@ -2,7 +2,7 @@ import type { createOpencodeClient } from "@opencode-ai/sdk";
 import type { Config, RawResult, Result, Source, SourceError, SourceId, Synthesis } from "./schema";
 export declare function normalize(raw: RawResult): Source;
 export declare function runSourceSearches(input: {
-    client: ReturnType<typeof createOpencodeClient>;
+    client?: ReturnType<typeof createOpencodeClient>;
     directory: string;
     config: Config;
     query: string;

package/dist/orchestrator.js

@@ -1,5 +1,6 @@
 import { searchCode } from "./sources/code";
 import { searchSessions } from "./sources/session";
+import { failure } from "./sources/shared";
 import { searchWeb } from "./sources/web";
 function clampUnit(value) {
     return Math.max(0, Math.min(1, value));
@@ -40,6 +41,9 @@ function createResult(input) {
 export async function runSourceSearches(input) {
     const outcomes = await Promise.all(input.sources.map((source) => {
         if (source === "session") {
+            if (!input.client) {
+                return failure("session", "unavailable", "Session search requires the OpenCode runtime.");
+            }
             return searchSessions(input.client, input.directory, input.query, input.depth);
         }
         if (source === "web") {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kagan-sh/opensearch",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "OpenCode plugin that combines session, web, and code search",
   "license": "MIT",
   "homepage": "https://kagan-sh.github.io/opensearch/",
@@ -14,11 +14,19 @@
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "opensearch-mcp": "./dist/mcp.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js",
+      "default": "./dist/mcp.js"
     }
   },
   "files": [
@@ -29,6 +37,7 @@
     "LICENSE"
   ],
   "scripts": {
+    "mcp": "bun run src/mcp.ts",
     "build": "bun tsc",
     "typecheck": "bun tsc --noEmit",
     "test": "vitest run",
@@ -40,6 +49,7 @@
     "release:dry-run": "semantic-release --dry-run"
   },
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
     "@opencode-ai/plugin": "1.2.27",
     "@opencode-ai/sdk": "1.2.27",
     "zod": "^3.24.0",