Imported from doohinkus/opencode_claude_mcp_cli (AGENTS.md). Install upstream with npx skills add doohinkus/opencode_claude_mcp_cli. Copyright stays with the author.

MCP Chat — Agent Guide

Setup

• Python >=3.10 required
• Copy .env.example or create .env with these vars (.env is gitignored):

  CLAUDE_MODEL="claude-sonnet-4-5"
  ANTHROPIC_API_KEY="<your-key>"
  USE_UV=1   # set to 0 if installing without uv

  For OpenCode provider (see Provider Switching below):

  PROVIDER=opencode
  OPENCODE_BASE_URL="<url>"
  OPENCODE_API_KEY="<key>"

• Install: uv venv && uv pip install -e . (uv) or python -m venv .venv && pip install anthropic python-dotenv prompt-toolkit "mcp[cli]==1.8.0"

Run

• With uv: uv run main.py (default; USE_UV=1)
• Without uv: USE_UV=0 python main.py
• Pass extra MCP server scripts as args: uv run main.py path/to/server.py

Architecture

MCP transport is stdio — server runs as a child process.

CLI Conventions

• @doc_id — mentions a document resource (auto-completes on Tab)
• /command doc_id — invokes an MCP prompt (auto-completes on Tab after / and space)
• Type / anywhere to trigger command completion; @ to trigger doc completion

TODO / Incomplete Code

mcp_client.py — 5 stub methods that return empty values:

• list_tools(), call_tool(), list_prompts(), get_prompt(), read_resource()

mcp_server.py — 6 TODOs for tools and resources:

• read_doc tool, edit_doc tool
• Resource listing all doc IDs, resource for single doc content
• Prompts for rewriting (markdown) and summarizing a doc

Testing / Linting / Typechecking

None exist. README: "There are no lint or type checks implemented." Do not assume pytest, mypy, ruff, or any other tool is set up — verify before introducing one.

Windows

main.py:64 sets WindowsProactorEventLoopPolicy for asyncio on win32.

Env Quirk

• USE_UV=0 switches the doc server from uv run mcp_server.py to python mcp_server.py
• Extra server scripts (args) always use uv run

Provider Switching

Set PROVIDER=claude (default) or PROVIDER=opencode in .env.

Claude provider requires CLAUDE_MODEL and ANTHROPIC_API_KEY.

OpenCode provider requires OPENCODE_BASE_URL and OPENCODE_API_KEY. Model defaults to big-pickle (overridable via OPENCODE_MODEL). Uses the OpenAI-compatible /chat/completions endpoint behind the scenes, with automatic message/tool format conversion.