@gopersonal/advisor 1.0.2 → 1.0.4

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,25 +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` |
+| 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_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`)
@@ -103,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.
@@ -19,8 +20,9 @@ import { createOpencode, createOpencodeClient } from "@opencode-ai/sdk/v2";
 //   ADVISOR_API_KEY   = "sk-ant-..."
 //   ADVISOR_BASE_URL  = "https://api.anthropic.com"
 //
-// ADVISOR_BASE_URL is required when using a custom/proxy endpoint.
-// If omitted, the default API URL for the provider is used.
+// Optional:
+//   ADVISOR_DIRECTORY    = project directory for opencode context (e.g. "/Users/me/myproject")
+//   ADVISOR_INSTRUCTIONS = path to instructions file (e.g. "/Users/me/myproject/AGENTS.md")
 //
 function resolveProviderAndModel() {
     const explicitProvider = process.env.ADVISOR_PROVIDER?.toLowerCase();
@@ -67,10 +69,18 @@ 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 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,
+        // Additional instruction files (e.g. AGENTS.md)
+        ...(instructions ? { instructions: [instructions] } : {}),
     };
+    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}`);
@@ -162,8 +172,10 @@ function sleep(ms) {
 }
 async function askOpencode(prompt, systemPrompt) {
     const client = await getOpencodeClient();
+    const directory = process.env.ADVISOR_DIRECTORY;
     const sessionResult = await client.session.create({
         title: "Advisor Query",
+        ...(directory ? { directory } : {}),
     });
     if (!sessionResult.data) {
         throw new Error("Failed to create opencode session");
@@ -177,6 +189,7 @@ async function askOpencode(prompt, systemPrompt) {
                 sessionID: sessionId,
                 system: systemPrompt,
                 ...(modelOverride ? { model: modelOverride } : {}),
+                ...(directory ? { directory } : {}),
                 parts: [{ type: "text", text: prompt }],
             });
             console.error(`[advisor] Prompt submitted async`);
@@ -392,7 +405,8 @@ server.registerTool("get_second_opinion", {
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error("[advisor] MCP Advisor server running on stdio");
+    const dir = process.env.ADVISOR_DIRECTORY;
+    console.error(`[advisor] MCP Advisor server running on stdio${dir ? ` (directory: ${dir})` : ""}`);
 }
 main().catch((error) => {
     console.error("[advisor] Fatal error:", error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gopersonal/advisor",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "type": "module",
   "main": "./build/index.js",
   "bin": {