@gopersonal/advisor 1.0.0

package/README.md

@@ -0,0 +1,57 @@
+# @gopersonal/advisor
+
+An MCP server that gives AI agents access to a separate AI advisor via [OpenCode SDK](https://opencode.ai). Agents call the advisor only when they're genuinely stuck or need a second opinion — not for routine tasks.
+
+## Tools
+
+- **ask_advisor** — Get help when stuck after multiple failed attempts
+- **get_second_opinion** — Sanity-check a decision between approaches
+
+## Add to Claude Code
+
+```bash
+claude mcp add advisor -- npx -y @gopersonal/advisor
+```
+
+### With a custom provider
+
+```bash
+claude mcp add advisor \
+  -e ADVISOR_MODEL=anthropic/claude-sonnet-4-5 \
+  -e ADVISOR_API_KEY=sk-your-key \
+  -- npx -y @gopersonal/advisor
+```
+
+### With a proxy endpoint
+
+```bash
+claude mcp add advisor \
+  -e ADVISOR_MODEL=anthropic/gpt-5.2-codex \
+  -e ADVISOR_API_KEY=none \
+  -e ADVISOR_BASE_URL=https://your-proxy.example.com \
+  -- npx -y @gopersonal/advisor
+```
+
+## Environment Variables
+
+| Variable | Description | Example |
+|---|---|---|
+| `ADVISOR_MODEL` | Model in `provider/model` format | `anthropic/claude-sonnet-4-5` |
+| `ADVISOR_API_KEY` | API key for the provider | `sk-...` |
+| `ADVISOR_BASE_URL` | Custom base URL (proxies, etc.) | `https://proxy.example.com` |
+| `ADVISOR_NPM` | AI SDK npm package (rare, for non-native providers) | `@ai-sdk/openai-compatible` |
+
+If no env vars are set, the advisor connects to a running opencode instance or starts one using your default opencode config.
+
+## How it works
+
+1. Agent calls `ask_advisor` or `get_second_opinion` via MCP
+2. The server creates a temporary OpenCode session
+3. Sends the prompt asynchronously, polls for the response
+4. Auto-answers any interactive questions from the OpenCode agent
+5. Returns the advisor's response and cleans up the session
+
+## Requirements
+
+- [OpenCode](https://opencode.ai) installed (`brew install sst/tap/opencode` or `npm i -g opencode`)
+- A configured AI provider (Anthropic, OpenAI, MiniMax, or any of 75+ supported providers)

package/build/index.js

@@ -0,0 +1,370 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createOpencode, createOpencodeClient } from "@opencode-ai/sdk/v2";
+// --- Environment-based configuration ---
+//
+// Pass these via the "env" field in the MCP config JSON.
+//
+// OpenCode natively supports 75+ providers (Anthropic, OpenAI, MiniMax, etc.)
+// so most of the time you just need ADVISOR_MODEL and ADVISOR_API_KEY.
+//
+//   ADVISOR_MODEL     - model in "provider/model" format, e.g. "anthropic/claude-sonnet-4-5"
+//                       or "openai/gpt-5.2-codex" or "minimax/minimax-m2.5"
+//   ADVISOR_API_KEY   - API key for the provider (optional if already set in opencode)
+//   ADVISOR_BASE_URL  - custom base URL override (optional, for proxies or custom endpoints)
+//   ADVISOR_NPM       - AI SDK npm package (optional, only for non-native providers)
+//
+function buildOpencodeConfig() {
+    const model = process.env.ADVISOR_MODEL;
+    const apiKey = process.env.ADVISOR_API_KEY;
+    const baseURL = process.env.ADVISOR_BASE_URL;
+    const npm = process.env.ADVISOR_NPM;
+    const config = {
+        // Disable title generation (it uses small_model which may not work with custom providers)
+        small_model: model || undefined,
+    };
+    if (model) {
+        config.model = model;
+        console.error(`[advisor] Model: ${model}`);
+    }
+    // Extract provider id and model name (e.g. "anthropic" + "gpt-5.2-codex")
+    const providerId = model?.split("/")[0];
+    const modelId = model?.split("/").slice(1).join("/");
+    if (providerId && (apiKey || baseURL || npm)) {
+        const options = {};
+        if (apiKey)
+            options.apiKey = apiKey;
+        if (baseURL)
+            options.baseURL = baseURL;
+        const providerConfig = { options };
+        if (npm)
+            providerConfig.npm = npm;
+        // Register the model so opencode knows its capabilities
+        if (modelId) {
+            providerConfig.models = {
+                [modelId]: {
+                    name: modelId,
+                    tool_call: true,
+                    attachment: false,
+                    reasoning: false,
+                    temperature: false, // many proxies don't support temperature
+                    limit: { context: 200000, output: 16384 },
+                },
+            };
+        }
+        config.provider = { [providerId]: providerConfig };
+        if (baseURL)
+            console.error(`[advisor] Custom base URL: ${baseURL}`);
+    }
+    return config;
+}
+// --- OpenCode connection management ---
+let opcClient = null;
+let opcServer = null;
+async function checkServerHealth(baseUrl) {
+    try {
+        const resp = await fetch(`${baseUrl}/project`, {
+            signal: AbortSignal.timeout(3000),
+            headers: { Accept: "application/json" },
+        });
+        if (!resp.ok)
+            return false;
+        const ct = resp.headers.get("content-type") ?? "";
+        return ct.includes("json");
+    }
+    catch {
+        return false;
+    }
+}
+async function getOpencodeClient() {
+    if (opcClient)
+        return opcClient;
+    // Try connecting to existing opencode servers
+    for (const port of [4096, 4097, 4098]) {
+        const baseUrl = `http://127.0.0.1:${port}`;
+        if (await checkServerHealth(baseUrl)) {
+            opcClient = createOpencodeClient({ baseUrl });
+            console.error(`[advisor] Connected to existing opencode server at ${baseUrl}`);
+            return opcClient;
+        }
+    }
+    // Start a new server with provider config from env vars
+    console.error("[advisor] No existing server found, starting new one...");
+    const config = buildOpencodeConfig();
+    try {
+        const { client, server } = await createOpencode({
+            timeout: 30000,
+            ...(Object.keys(config).length > 0 ? { config } : {}),
+        });
+        opcClient = client;
+        opcServer = server;
+        console.error(`[advisor] Started opencode server at ${server.url}`);
+        return opcClient;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Failed to start opencode server: ${msg}. ` +
+            `Make sure opencode is installed (https://opencode.ai) and configured with a provider.`);
+    }
+}
+// Model override for session prompts (from ADVISOR_MODEL env var)
+function getModelOverride() {
+    const model = process.env.ADVISOR_MODEL;
+    if (!model || !model.includes("/"))
+        return undefined;
+    const [providerID, ...rest] = model.split("/");
+    return { providerID, modelID: rest.join("/") };
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function askOpencode(prompt, systemPrompt) {
+    const client = await getOpencodeClient();
+    const sessionResult = await client.session.create({
+        title: "Advisor Query",
+    });
+    if (!sessionResult.data) {
+        throw new Error("Failed to create opencode session");
+    }
+    const sessionId = sessionResult.data.id;
+    const modelOverride = getModelOverride();
+    try {
+        // Send the prompt asynchronously - returns 204 immediately while session processes
+        try {
+            await client.session.promptAsync({
+                sessionID: sessionId,
+                system: systemPrompt,
+                ...(modelOverride ? { model: modelOverride } : {}),
+                parts: [{ type: "text", text: prompt }],
+            });
+            console.error(`[advisor] Prompt submitted async`);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Failed to submit prompt: ${msg}`);
+        }
+        // Poll for the assistant's response and auto-answer any questions
+        const maxWaitMs = 90_000;
+        const pollIntervalMs = 2000;
+        const startTime = Date.now();
+        let lastTextLength = 0;
+        let stableCount = 0;
+        const answeredQuestions = new Set();
+        await sleep(3000);
+        while (Date.now() - startTime < maxWaitMs) {
+            // Auto-answer any pending questions (opencode agent may ask permission)
+            try {
+                const questions = await client.question.list({});
+                if (questions.data && Array.isArray(questions.data)) {
+                    for (const q of questions.data) {
+                        if (q.sessionID === sessionId && !answeredQuestions.has(q.id)) {
+                            console.error(`[advisor] Auto-answering question: ${q.id}`);
+                            const answers = q.questions.map((qi) => {
+                                // Pick the first option for each question
+                                const opts = qi.options;
+                                return opts && opts.length > 0 ? [opts[0].label] : ["yes"];
+                            });
+                            await client.question.reply({
+                                requestID: q.id,
+                                answers,
+                            });
+                            answeredQuestions.add(q.id);
+                        }
+                    }
+                }
+            }
+            catch {
+                // question API may not be available, ignore
+            }
+            // Check messages for the assistant's response
+            const messagesResult = await client.session.messages({
+                sessionID: sessionId,
+            });
+            const messages = messagesResult.data;
+            if (!messages || !Array.isArray(messages)) {
+                await sleep(pollIntervalMs);
+                continue;
+            }
+            // Find the latest assistant message
+            const assistantMsg = [...messages].reverse().find((m) => m.info && typeof m.info === "object" && "role" in m.info && m.info.role === "assistant");
+            if (!assistantMsg) {
+                await sleep(pollIntervalMs);
+                continue;
+            }
+            // Extract text parts
+            const textParts = [];
+            if (Array.isArray(assistantMsg.parts)) {
+                for (const part of assistantMsg.parts) {
+                    if (part && typeof part === "object" && part.type === "text" && "text" in part) {
+                        textParts.push(String(part.text));
+                    }
+                }
+            }
+            const currentText = textParts.join("\n");
+            // Check if the message is marked as completed
+            const info = assistantMsg.info;
+            if (info.time && typeof info.time === "object") {
+                const time = info.time;
+                if (time.completed && currentText.length > 0) {
+                    console.error(`[advisor] Response completed (${currentText.length} chars)`);
+                    return currentText;
+                }
+            }
+            // Fallback: text stopped growing for 3 cycles
+            if (currentText.length > 0) {
+                if (currentText.length === lastTextLength) {
+                    stableCount++;
+                    if (stableCount >= 3) {
+                        console.error(`[advisor] Response stable (${currentText.length} chars)`);
+                        return currentText;
+                    }
+                }
+                else {
+                    stableCount = 0;
+                    lastTextLength = currentText.length;
+                }
+            }
+            await sleep(pollIntervalMs);
+        }
+        throw new Error("Timed out waiting for advisor response");
+    }
+    finally {
+        try {
+            await client.session.delete({ sessionID: sessionId });
+        }
+        catch {
+            // ignore cleanup errors
+        }
+    }
+}
+// --- MCP Server setup ---
+const server = new McpServer({
+    name: "advisor",
+    version: "2.0.0",
+});
+// Tool 1: ask_advisor
+server.registerTool("ask_advisor", {
+    description: "Get an external opinion from a separate AI when you are STUCK. " +
+        "Call this ONLY when: (1) you have already tried at least 2 different approaches and they failed, " +
+        "OR (2) you hit an error you genuinely don't understand after investigating it. " +
+        "Do NOT call this for routine tasks or things you can figure out yourself. " +
+        "You must describe what you already tried and why it didn't work.",
+    inputSchema: {
+        problem: z
+            .string()
+            .describe("What you are trying to do and what is going wrong"),
+        failed_attempts: z
+            .string()
+            .describe("The specific approaches you already tried and WHY each one failed. " +
+            "Be honest and detailed - the advisor needs this to avoid suggesting the same things."),
+        error_context: z
+            .string()
+            .optional()
+            .describe("Error messages, stack traces, or unexpected output you're seeing"),
+        code_context: z
+            .string()
+            .optional()
+            .describe("Relevant code that's involved in the problem"),
+    },
+}, async ({ problem, failed_attempts, error_context, code_context }) => {
+    const systemPrompt = `You are a senior engineer acting as an advisor to an AI coding agent that is stuck. ` +
+        `The agent has already tried multiple approaches and failed. Your job is to:\n` +
+        `1. Identify what the agent is missing or getting wrong\n` +
+        `2. Suggest a DIFFERENT approach the agent hasn't tried\n` +
+        `3. If the agent's approach was close, pinpoint the exact mistake\n` +
+        `Be direct and specific. No preamble. Start with the most likely fix.`;
+    let userPrompt = `## What I'm trying to do\n${problem}\n\n## What I already tried (and why it failed)\n${failed_attempts}`;
+    if (error_context) {
+        userPrompt += `\n\n## Errors I'm seeing\n\`\`\`\n${error_context}\n\`\`\``;
+    }
+    if (code_context) {
+        userPrompt += `\n\n## Relevant code\n\`\`\`\n${code_context}\n\`\`\``;
+    }
+    try {
+        const advice = await askOpencode(userPrompt, systemPrompt);
+        return { content: [{ type: "text", text: advice }] };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Advisor unavailable: ${msg}\nMake sure opencode is installed and configured with a provider.`,
+                }],
+            isError: true,
+        };
+    }
+});
+// Tool 2: get_second_opinion
+server.registerTool("get_second_opinion", {
+    description: "Get a second opinion from a separate AI before committing to an approach you're unsure about. " +
+        "Call this ONLY when: (1) you see multiple valid approaches and aren't confident which is best, " +
+        "OR (2) you're about to make a significant architectural choice and want a sanity check. " +
+        "Do NOT call this for straightforward decisions or trivial choices.",
+    inputSchema: {
+        situation: z
+            .string()
+            .describe("What you're working on and what decision you need to make"),
+        option_a: z
+            .string()
+            .describe("The approach you're leaning toward and why"),
+        option_b: z
+            .string()
+            .optional()
+            .describe("An alternative approach you're also considering"),
+        worry: z
+            .string()
+            .optional()
+            .describe("What specifically makes you unsure — the risk or trade-off you're worried about"),
+    },
+}, async ({ situation, option_a, option_b, worry }) => {
+    const systemPrompt = `You are a senior engineer giving a quick second opinion to an AI coding agent. ` +
+        `The agent is at a decision point and wants a sanity check. Be brief:\n` +
+        `- State which option you'd pick and why (1-2 sentences)\n` +
+        `- Flag any gotcha the agent might be missing\n` +
+        `- If both options are fine, just say so and pick one\n` +
+        `No long analysis. The agent just needs a nudge in the right direction.`;
+    let userPrompt = `## Situation\n${situation}\n\n## Option A (leaning toward)\n${option_a}`;
+    if (option_b) {
+        userPrompt += `\n\n## Option B\n${option_b}`;
+    }
+    if (worry) {
+        userPrompt += `\n\n## What I'm worried about\n${worry}`;
+    }
+    try {
+        const opinion = await askOpencode(userPrompt, systemPrompt);
+        return { content: [{ type: "text", text: opinion }] };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Advisor unavailable: ${msg}\nMake sure opencode is installed and configured.`,
+                }],
+            isError: true,
+        };
+    }
+});
+// --- Start the server ---
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[advisor] MCP Advisor server running on stdio");
+}
+main().catch((error) => {
+    console.error("[advisor] Fatal error:", error);
+    process.exit(1);
+});
+process.on("SIGINT", () => {
+    if (opcServer)
+        opcServer.close();
+    process.exit(0);
+});
+process.on("SIGTERM", () => {
+    if (opcServer)
+        opcServer.close();
+    process.exit(0);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@gopersonal/advisor",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./build/index.js",
+  "bin": {
+    "advisor-mcp": "./build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node build/index.js"
+  },
+  "keywords": ["mcp", "advisor", "opencode", "ai", "model-context-protocol"],
+  "author": "gopersonal",
+  "license": "ISC",
+  "description": "MCP server that gives AI agents a second opinion via OpenCode SDK",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/gopersonal/calvincode-mcps"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@opencode-ai/sdk": "^1.2.5",
+    "zod": "^3.25.76"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "typescript": "^5.9.3"
+  }
+}