ask-another: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What This Is

An MCP (Model Context Protocol) server that lets Claude Desktop query other LLMs through a unified interface. It uses LiteLLM as the multi-provider backend and FastMCP for the server framework. Providers are configured via environment variables, and models are discovered dynamically via provider APIs.

Commands

uv sync                                                                    # Install dependencies
PROVIDER_OPENAI="sk-test" uv run ask-another                               # Run the server locally

Release workflow — always pull after push

CI auto-bumps the patch version on every fix(...) commit pushed to main, then tags and builds the .mcpb. The bump appears as a chore: bump patch to X.Y.Z [skip ci] commit on origin/main that your local won't have. After any push that may have triggered the bump, git pull before doing more work — otherwise the repo's manifest.json/plugin.json will be one version behind reality and you'll build/install a stale bundle.

Tests can be run with:

uv run --with pytest python -m pytest tests/ -v

Architecture

The entire server lives in a single file: src/ask_another/server.py. It exposes these MCP tools:

• search_families — discovers model families across configured providers, with optional substring search
• search_models — finds specific model identifiers with optional substring search; enriches results with metadata (Elo, knowledge cutoff, context length, pricing, notes) from the annotations file
• completion — proxies a completion request to a specified LLM via LiteLLM, supports full model identifiers or favourite shorthand; tracks usage in the annotations file
• annotate_models — adds or updates a personal note on a model; notes appear in search results and server instructions
• refresh_models — force re-scan of all providers and re-fetch benchmark data from LMArena arena-catalog (GitHub JSON) and LMArena metadata (HuggingFace CSV)
• feedback — collects usability issues from the LLM client into a JSONL log file (~/.ask-another-feedback.jsonl by default, configurable via FEEDBACK_LOG env var)
• start_research — starts a deep research task that runs in the background via a lifespan task group. Supports two paths: OpenRouter (Perplexity/OpenAI via litellm.completion) and Gemini deep research (via litellm.interactions.create with polling). Blocks until results arrive or timeout, then returns results or a job handle. If interrupted (user hits escape), the research continues in the background.
• check_research — lists all research jobs as a markdown table, or retrieves full results for a specific job_id
• cancel_research — cancels a running research task by its job_id
• generate_image — generates an image from a text prompt. Automatically routes between two LiteLLM paths: litellm.image_generation() for dedicated image models (gpt-image-1, dall-e-3, imagen-4) and litellm.completion() with modalities=["image","text"] for native image-output models (Gemini Nano Banana family). Returns images inline via MCP ImageContent and saves to disk.