@gopersonal/advisor

An MCP server that gives AI agents access to a separate AI advisor via OpenCode SDK. 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

Quick Start

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

Setup

Option A: OpenAI-compatible endpoint

Works with OpenAI, MiniMax, Together, Groq, and any /v1/chat/completions endpoint.

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

Example with MiniMax (tested):

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-compatible endpoint

Works with Anthropic and any /v1/messages endpoint.

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

Example with a proxy (tested):

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 \
  -- npx -y @gopersonal/advisor

No config (uses your local opencode setup)

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:

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 | 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 (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 installed (brew install sst/tap/opencode or npm i -g opencode)
• A configured AI provider (Anthropic, OpenAI, MiniMax, or any of 75+ supported providers)

Development

cd advisor
npm install
npm run build

Test locally with Claude Code:

claude mcp add advisor -- node /path/to/advisor/build/index.js

Publishing to npm

1. Login to npm (one-time):

npm login

2. Update the version:

npm version patch   # 1.0.0 -> 1.0.1 (bug fixes)
npm version minor   # 1.0.0 -> 1.1.0 (new features)
npm version major   # 1.0.0 -> 2.0.0 (breaking changes)

3. Publish:

npm publish --access public

4. Verify:

npm view @gopersonal/advisor