@gopersonal/advisor 1.0.3 → 2.0.0

package/README.md

@@ -7,47 +7,64 @@ An MCP server that gives AI agents access to a separate AI advisor via [OpenCode
 - **ask_advisor** — Get help when stuck after multiple failed attempts
 - **get_second_opinion** — Sanity-check a decision between approaches
 
-## Add to Claude Code
-
-### Option A: OpenAI endpoint
+## Quick Start
 
 ```bash
 claude mcp add advisor \
   -e ADVISOR_PROVIDER=openai \
   -e ADVISOR_MODEL=gpt-4o \
   -e ADVISOR_API_KEY=sk-your-key \
+  -e ADVISOR_BASE_URL=https://api.openai.com/v1 \
   -- npx -y @gopersonal/advisor
 ```
 
-With a custom OpenAI-compatible endpoint:
+## Setup
+
+### Option A: OpenAI-compatible endpoint
+
+Works with OpenAI, MiniMax, Together, Groq, and any `/v1/chat/completions` endpoint.
 
 ```bash
 claude mcp add advisor \
   -e ADVISOR_PROVIDER=openai \
   -e ADVISOR_MODEL=gpt-4o \
   -e ADVISOR_API_KEY=sk-your-key \
-  -e ADVISOR_BASE_URL=https://your-openai-proxy.example.com/v1 \
+  -e ADVISOR_BASE_URL=https://api.openai.com/v1 \
+  -- npx -y @gopersonal/advisor
+```
+
+Example with MiniMax (tested):
+
+```bash
+claude mcp add advisor \
+  -e ADVISOR_PROVIDER=openai \
+  -e ADVISOR_MODEL=MiniMax-M2.5 \
+  -e ADVISOR_API_KEY=sk-your-minimax-key \
+  -e ADVISOR_BASE_URL=https://api.minimax.io/v1 \
   -- npx -y @gopersonal/advisor
 ```
 
-### Option B: Anthropic endpoint
+### Option B: Anthropic-compatible endpoint
+
+Works with Anthropic and any `/v1/messages` endpoint.
 
 ```bash
 claude mcp add advisor \
   -e ADVISOR_PROVIDER=anthropic \
   -e ADVISOR_MODEL=claude-sonnet-4-5 \
   -e ADVISOR_API_KEY=sk-ant-your-key \
+  -e ADVISOR_BASE_URL=https://api.anthropic.com \
   -- npx -y @gopersonal/advisor
 ```
 
-With a custom Anthropic-compatible endpoint:
+Example with a proxy (tested):
 
 ```bash
 claude mcp add advisor \
   -e ADVISOR_PROVIDER=anthropic \
-  -e ADVISOR_MODEL=claude-sonnet-4-5 \
+  -e ADVISOR_MODEL=gpt-5.2-codex \
   -e ADVISOR_API_KEY=none \
-  -e ADVISOR_BASE_URL=https://your-anthropic-proxy.example.com \
+  -e ADVISOR_BASE_URL=https://azure-openai-anthropic-proxy.go-shops.workers.dev \
   -- npx -y @gopersonal/advisor
 ```
 
@@ -57,30 +74,54 @@ claude mcp add advisor \
 claude mcp add advisor -- npx -y @gopersonal/advisor
 ```
 
+### With project context and instructions
+
+Give the advisor context about your project so it can provide more relevant advice:
+
+```bash
+claude mcp add advisor \
+  -e ADVISOR_PROVIDER=anthropic \
+  -e ADVISOR_MODEL=gpt-5.2-codex \
+  -e ADVISOR_API_KEY=none \
+  -e ADVISOR_BASE_URL=https://azure-openai-anthropic-proxy.go-shops.workers.dev \
+  -e ADVISOR_DIRECTORY=/Users/me/myproject \
+  -e ADVISOR_INSTRUCTIONS=/Users/me/myproject/AGENTS.md \
+  -- npx -y @gopersonal/advisor
+```
+
 ## Environment Variables
 
-| Variable | Description | Example |
-|---|---|---|
-| `ADVISOR_PROVIDER` | `openai` or `anthropic` | `openai` |
-| `ADVISOR_MODEL` | Model name | `gpt-4o`, `claude-sonnet-4-5` |
-| `ADVISOR_API_KEY` | API key for the provider | `sk-...` |
-| `ADVISOR_BASE_URL` | Custom base URL (optional) | `https://proxy.example.com` |
-| `ADVISOR_DIRECTORY` | Project directory for opencode context (optional) | `/Users/me/myproject` |
-| `ADVISOR_INSTRUCTIONS` | Path to instructions/AGENTS.md file (optional) | `/Users/me/myproject/AGENTS.md` |
+| Variable | Required | Description | Example |
+|---|---|---|---|
+| `ADVISOR_PROVIDER` | Yes | `openai` or `anthropic` | `openai` |
+| `ADVISOR_MODEL` | Yes | Model name | `gpt-4o`, `claude-sonnet-4-5` |
+| `ADVISOR_API_KEY` | Yes | API key for the provider | `sk-...` |
+| `ADVISOR_BASE_URL` | Yes | API base URL | `https://api.openai.com/v1` |
+| `ADVISOR_DIRECTORY` | No | Project directory for opencode context | `/Users/me/myproject` |
+| `ADVISOR_INSTRUCTIONS` | No | Path to instructions file (AGENTS.md, etc.) | `/Users/me/myproject/AGENTS.md` |
 
-`ADVISOR_DIRECTORY` gives the advisor context about your project (file structure, code, etc.).
-`ADVISOR_INSTRUCTIONS` loads a custom instructions file (like AGENTS.md) so the advisor knows your project conventions.
+- `ADVISOR_PROVIDER` determines the API format: `openai` uses `/v1/chat/completions`, `anthropic` uses `/v1/messages`
+- `ADVISOR_DIRECTORY` gives the advisor access to your project files and structure
+- `ADVISOR_INSTRUCTIONS` loads a custom instructions file so the advisor knows your project conventions
 
 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
+2. The server creates a temporary OpenCode session (scoped to `ADVISOR_DIRECTORY` if set)
 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
 
+## Tested configurations
+
+| Provider | Model | Base URL | Status |
+|---|---|---|---|
+| `anthropic` | `gpt-5.2-codex` | `azure-openai-anthropic-proxy.go-shops.workers.dev` | Working |
+| `openai` | `MiniMax-M2.5` | `api.minimax.io/v1` | Working |
+| `anthropic` | `gpt-5.2-codex` | proxy + `ADVISOR_DIRECTORY` + `ADVISOR_INSTRUCTIONS` | Working |
+
 ## Requirements
 
 - [OpenCode](https://opencode.ai) installed (`brew install sst/tap/opencode` or `npm i -g opencode`)
@@ -108,7 +149,7 @@ claude mcp add advisor -- node /path/to/advisor/build/index.js
 npm login
 ```
 
-2. Update the version in `package.json`:
+2. Update the version:
 
 ```bash
 npm version patch   # 1.0.0 -> 1.0.1 (bug fixes)

package/build/index.js

@@ -3,6 +3,7 @@ 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";
+import { existsSync } from "fs";
 // --- Environment-based configuration ---
 //
 // Pass these via the "env" field in the MCP config JSON.
@@ -68,7 +69,8 @@ function buildOpencodeConfig() {
     const apiKey = process.env.ADVISOR_API_KEY;
     const baseURL = process.env.ADVISOR_BASE_URL;
     const npm = process.env.ADVISOR_NPM || resolved?.npm;
-    const instructions = process.env.ADVISOR_INSTRUCTIONS;
+    const instructionsPath = process.env.ADVISOR_INSTRUCTIONS;
+    const instructions = instructionsPath && existsSync(instructionsPath) ? instructionsPath : undefined;
     const config = {
         // Disable title generation (it uses small_model which may not work with custom providers)
         small_model: resolved?.fullModel || undefined,
@@ -77,6 +79,8 @@ function buildOpencodeConfig() {
     };
     if (instructions)
         console.error(`[advisor] Instructions: ${instructions}`);
+    if (instructionsPath && !instructions)
+        console.error(`[advisor] Instructions file not found: ${instructionsPath}, skipping`);
     if (resolved) {
         config.model = resolved.fullModel;
         console.error(`[advisor] Provider: ${resolved.provider}, Model: ${resolved.model}`);
@@ -166,11 +170,44 @@ function getModelOverride() {
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
-async function askOpencode(prompt, systemPrompt) {
+function extractTextFromMessages(messages) {
+    const allText = [];
+    for (const m of messages) {
+        const msg = m;
+        if (msg.info && typeof msg.info === "object" && "role" in msg.info && msg.info.role === "assistant") {
+            if (Array.isArray(msg.parts)) {
+                for (const part of msg.parts) {
+                    if (part && typeof part === "object" && part.type === "text" && "text" in part) {
+                        allText.push(String(part.text));
+                    }
+                }
+            }
+        }
+    }
+    return allText.join("\n");
+}
+function extractToolSummary(messages) {
+    const tools = [];
+    for (const m of messages) {
+        const msg = m;
+        if (Array.isArray(msg.parts)) {
+            for (const part of msg.parts) {
+                const p = part;
+                if (p && p.type === "tool-invocation" && p.toolName) {
+                    const args = p.args ? JSON.stringify(p.args).slice(0, 200) : "";
+                    tools.push(`- ${p.toolName}${args ? `: ${args}` : ""}`);
+                }
+            }
+        }
+    }
+    return tools.length > 0 ? `\n\n## Tools used\n${tools.join("\n")}` : "";
+}
+async function runOpencodeSession(prompt, systemPrompt, options = {}) {
+    const { timeoutMs = 90_000, stableThreshold = 3, sessionTitle = "Advisor Query", } = options;
     const client = await getOpencodeClient();
     const directory = process.env.ADVISOR_DIRECTORY;
     const sessionResult = await client.session.create({
-        title: "Advisor Query",
+        title: sessionTitle,
         ...(directory ? { directory } : {}),
     });
     if (!sessionResult.data) {
@@ -179,7 +216,6 @@ async function askOpencode(prompt, systemPrompt) {
     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,
@@ -188,21 +224,19 @@ async function askOpencode(prompt, systemPrompt) {
                 ...(directory ? { directory } : {}),
                 parts: [{ type: "text", text: prompt }],
             });
-            console.error(`[advisor] Prompt submitted async`);
+            console.error(`[advisor] Prompt submitted (timeout: ${timeoutMs / 1000}s, stable: ${stableThreshold} cycles)`);
         }
         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 lastContentLength = 0;
         let stableCount = 0;
         const answeredQuestions = new Set();
         await sleep(3000);
-        while (Date.now() - startTime < maxWaitMs) {
+        while (Date.now() - startTime < timeoutMs) {
             // Auto-answer any pending questions (opencode agent may ask permission)
             try {
                 const questions = await client.question.list({});
@@ -211,7 +245,6 @@ async function askOpencode(prompt, systemPrompt) {
                         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"];
                             });
@@ -227,7 +260,6 @@ async function askOpencode(prompt, systemPrompt) {
             catch {
                 // question API may not be available, ignore
             }
-            // Check messages for the assistant's response
             const messagesResult = await client.session.messages({
                 sessionID: sessionId,
             });
@@ -242,12 +274,13 @@ async function askOpencode(prompt, systemPrompt) {
                 await sleep(pollIntervalMs);
                 continue;
             }
-            // Extract text parts
+            // Extract text from latest assistant message
             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 p = part;
+                    if (p && p.type === "text" && "text" in p) {
+                        textParts.push(String(p.text));
                     }
                 }
             }
@@ -257,27 +290,52 @@ async function askOpencode(prompt, systemPrompt) {
             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;
+                    console.error(`[advisor] Completed (${currentText.length} chars)`);
+                    const toolSummary = extractToolSummary(messages);
+                    return currentText + toolSummary;
                 }
             }
-            // Fallback: text stopped growing for 3 cycles
-            if (currentText.length > 0) {
-                if (currentText.length === lastTextLength) {
+            // Stability check: use total content across ALL messages to detect when agent stops working
+            const totalContentLength = messages.reduce((acc, m) => {
+                const msg = m;
+                if (Array.isArray(msg.parts)) {
+                    for (const p of msg.parts) {
+                        const part = p;
+                        if (part && "text" in part)
+                            acc += String(part.text).length;
+                        if (part && part.type === "tool-invocation")
+                            acc += 100; // count tool calls as content
+                    }
+                }
+                return acc;
+            }, 0);
+            if (totalContentLength > 0) {
+                if (totalContentLength === lastContentLength) {
                     stableCount++;
-                    if (stableCount >= 3) {
-                        console.error(`[advisor] Response stable (${currentText.length} chars)`);
-                        return currentText;
+                    if (stableCount >= stableThreshold) {
+                        console.error(`[advisor] Stable after ${stableThreshold} cycles (${totalContentLength} total content)`);
+                        const toolSummary = extractToolSummary(messages);
+                        return currentText + toolSummary;
                     }
                 }
                 else {
                     stableCount = 0;
-                    lastTextLength = currentText.length;
+                    lastContentLength = totalContentLength;
                 }
             }
             await sleep(pollIntervalMs);
         }
-        throw new Error("Timed out waiting for advisor response");
+        // Timeout — return partial results if available
+        const finalMessages = await client.session.messages({ sessionID: sessionId });
+        if (finalMessages.data && Array.isArray(finalMessages.data)) {
+            const text = extractTextFromMessages(finalMessages.data);
+            const toolSummary = extractToolSummary(finalMessages.data);
+            if (text) {
+                console.error(`[advisor] Timed out but returning partial result (${text.length} chars)`);
+                return text + toolSummary + "\n\n[Note: Task timed out but partial work was completed]";
+            }
+        }
+        throw new Error("Timed out waiting for response");
     }
     finally {
         try {
@@ -288,6 +346,14 @@ async function askOpencode(prompt, systemPrompt) {
         }
     }
 }
+// Legacy wrapper for advisory tools
+async function askOpencode(prompt, systemPrompt) {
+    return runOpencodeSession(prompt, systemPrompt, {
+        timeoutMs: 90_000,
+        stableThreshold: 3,
+        sessionTitle: "Advisor Query",
+    });
+}
 // --- MCP Server setup ---
 const server = new McpServer({
     name: "advisor",
@@ -397,6 +463,66 @@ server.registerTool("get_second_opinion", {
         };
     }
 });
+// Tool 3: execute_task
+server.registerTool("execute_task", {
+    description: "Delegate a coding task to a separate AI agent that will actually DO the work — edit files, run commands, " +
+        "create code, fix bugs, etc. Use this when you want another agent to independently complete a task. " +
+        "The agent has full access to the project: it can read/write files, run bash commands, and make changes. " +
+        "Use this for: implementing features, fixing bugs, refactoring code, writing tests, running builds, " +
+        "setting up configurations, or any hands-on coding work you want to delegate. " +
+        "Be specific about what you want done — the agent works independently and returns results when finished.",
+    inputSchema: {
+        task: z
+            .string()
+            .describe("Clear description of what needs to be done. Be specific: include file paths, function names, " +
+            "expected behavior, and acceptance criteria. The more detail you provide, the better the result."),
+        context: z
+            .string()
+            .optional()
+            .describe("Additional context: relevant code snippets, error messages, architectural decisions, " +
+            "or constraints the agent should know about."),
+        files_to_focus: z
+            .string()
+            .optional()
+            .describe("Comma-separated list of file paths the agent should focus on (e.g. 'src/auth.ts, src/routes/login.ts'). " +
+            "Helps the agent find relevant code faster."),
+    },
+}, async ({ task, context, files_to_focus }) => {
+    const systemPrompt = `You are a senior software engineer executing a coding task. Your job is to COMPLETE the task, not discuss it.\n\n` +
+        `RULES:\n` +
+        `1. DO the work. Read files, write code, run commands. Don't just explain what to do.\n` +
+        `2. Start by understanding the codebase — read relevant files before making changes.\n` +
+        `3. Make all necessary changes to fully complete the task.\n` +
+        `4. After making changes, verify they work (run the code, check for errors, test if possible).\n` +
+        `5. If you encounter an error, fix it. Don't stop at the first problem.\n` +
+        `6. When done, provide a brief summary of what you changed and why.\n\n` +
+        `You have full access to the project filesystem and shell. Use your tools actively.`;
+    let userPrompt = `## Task\n${task}`;
+    if (context) {
+        userPrompt += `\n\n## Context\n${context}`;
+    }
+    if (files_to_focus) {
+        userPrompt += `\n\n## Key files to focus on\n${files_to_focus}`;
+    }
+    try {
+        const result = await runOpencodeSession(userPrompt, systemPrompt, {
+            timeoutMs: 300_000, // 5 minutes — tasks need more time than advisory questions
+            stableThreshold: 8, // 16 seconds of no activity — tasks involve tool calls between text
+            sessionTitle: "Task Execution",
+        });
+        return { content: [{ type: "text", text: result }] };
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Task execution failed: ${msg}\nMake sure opencode is installed and configured with a provider.`,
+                }],
+            isError: true,
+        };
+    }
+});
 // --- Start the server ---
 async function main() {
     const transport = new StdioServerTransport();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gopersonal/advisor",
-  "version": "1.0.3",
+  "version": "2.0.0",
   "type": "module",
   "main": "./build/index.js",
   "bin": {
@@ -24,7 +24,7 @@
   ],
   "author": "gopersonal",
   "license": "ISC",
-  "description": "MCP server that gives AI agents a second opinion via OpenCode SDK",
+  "description": "MCP server that gives AI agents advice and can execute coding tasks via OpenCode SDK",
   "repository": {
     "type": "git",
     "url": "https://github.com/gopersonal/calvincode-mcps"