# Coeus AI MCP

Coeus is a provider-neutral MCP server for local AI-assisted engineering workflows.
It gives MCP-capable clients one stable `coeus_*` tool surface for project intake,
model routing, code review, debugging, testing, docs drift checks, release readiness,
design review, and multi-provider verification.

The current registry contains 55 tools. Provider selection is separate from workflow
naming, so clients can keep the same MCP calls while choosing an OAuth-backed CLI or a
direct API provider.

## What Coeus Provides

- A standard MCP stdio server named `coeus`.
- 55 provider-neutral `coeus_*` tools for common developer workflows.
- Runtime provider health, capability, readiness, and catalog reporting.
- Automatic provider routing with bounded fallback when auto-selected providers are unavailable.
- Multi-provider verification with explicit consensus limits.

## Install

Requirements:

- Python 3.11 or newer.
- At least one authenticated provider: an OAuth CLI session for `agy`, `codex`, or
  `claude`, or a direct API key for `deepseek`, `alibaba`, or `openrouter`.

```bash
git clone https://github.com/soryko/coeus-mcp.git
cd coeus-mcp
python3 -m venv .venv
. .venv/bin/activate
python -m pip install -e ".[dev]"
```

For centralized local setup, place the three direct provider keys and other Coeus
settings in the repository-root `.env` file. Coeus loads that file when configuration
is initialized; variables already supplied by the process take precedence. The file
is gitignored and must not be committed.

Start from the included template:

```bash
cp .env.example .env
```

```dotenv
COEUS_DEEPSEEK_API_KEY=
COEUS_ALIBABA_API_KEY=
COEUS_OPENROUTER_API_KEY=
COEUS_DEFAULT_PROVIDER=auto
```

The `agy`, `codex`, and `claude` adapters use subscriptions already authenticated in
their local CLIs. No API key is required or accepted for these adapters. Run the
interactive login once as the same user that runs Coeus:

```bash
agy login
codex login
claude login
```

OAuth tokens remain in the CLI credential stores and must not be copied into `.env`.
Only `COEUS_DEEPSEEK_API_KEY`, `COEUS_ALIBABA_API_KEY`, and
`COEUS_OPENROUTER_API_KEY` are direct API credentials read from `.env`.

Verify the server locally:

```bash
python - <<'PY'
from mcp_server import CoeusMCPServer

server = CoeusMCPServer()
print(server.call_tool("coeus_healthcheck", {}))
print(server.call_tool("coeus_capabilities", {})["providers"])
PY
```

The console script used by MCP clients is:

```bash
./.venv/bin/coeus-ai
```

## MCP Client Configuration

Use an absolute path to `coeus-ai`. Desktop clients often launch without your shell
profile, so relying on `PATH` is brittle.

```json
{
  "mcpServers": {
    "coeus": {
      "command": "/absolute/path/to/coeus-ai-mcp/.venv/bin/coeus-ai",
      "env": {
        "COEUS_DEFAULT_PROVIDER": "auto"
      }
    }
  }
}
```

After connecting, ask your agent:

```text
Use coeus_healthcheck and summarize which providers are ready.
```

More client-specific examples live in [docs/integrations.md](docs/integrations.md).

## Providers, catalogs, and routing

Coeus providers implement the same contract:

- `healthcheck(probe_network=False)`
- `list_models()`
- `ask(prompt, model, temperature, max_tokens)`

| Provider ID | Authentication | Default model | Catalog/readiness notes |
| --- | --- | --- | --- |
| `agy` | OAuth subscription via `agy login` | `gemini-3.7-flash-medium` | Headless CLI; vision and reasoning capable. |
| `codex` | OAuth subscription via `codex login` | `gpt-5.6-terra` | Inventory comes from `codex debug models`. |
| `claude` | OAuth subscription via `claude login` | `claude-opus-5` | Checked-in models are bounded by subscription probes. |
| `deepseek` | `COEUS_DEEPSEEK_API_KEY` | `deepseek-v4-pro` | Fast model: `deepseek-v4-flash`. |
| `alibaba` | `COEUS_ALIBABA_API_KEY` | `qwen3.8-max` | Alibaba Cloud Model Studio endpoint; provider ID is `alibaba`. |
| `openrouter` | `COEUS_OPENROUTER_API_KEY` | `openai/gpt-4.1-nano` | Vision and context are model-dependent. |

`COEUS_DEFAULT_PROVIDER=auto` is the recommended default. In automatic mode, Coeus
selects ready, configured, capability-compatible candidates. A runtime authentication,
availability, timeout, or transport failure may trigger bounded fallback.

Strict provider IDs (`agy`, `codex`, `claude`, `deepseek`, `alibaba`, and `openrouter`)
request one provider and never fall back to another. Direct-key preference aliases
(`deepseek_key`, `alibaba_key`, and `openrouter_key`) put one provider first but remain
fallback-eligible. Supplying an explicit `model` disables fallback, including when
`provider="auto"`.

When fallback occurs, inspect `provider`, `model`, `fallback_from`, `fallback_reason`,
and `fallback_attempts` in the result. `coeus_route` reports the planned route without
calling a provider; `coeus_ask` executes it.

Call `coeus_list_models` for the authoritative provider inventory. A provider entry
contains `status`, `models`, and `complete`. Model records normalize `provider`, `id`,
`raw_id`, `capabilities`, `source`, `discovered_at`, `availability`, `available`,
`deprecated`, and provider-specific `metadata`. Catalog probes are bounded and cached
for `COEUS_PROVIDER_CATALOG_TTL` (60 seconds by default); incomplete or stale catalogs
are not treated as ready routing evidence.

`coeus_healthcheck` reports `configured`, `ready`, `default_model`, and auth details.
OAuth providers include `auth_mode`, `oauth`, `command_available`, and `resolved_path`;
direct providers include `api_key_configured`. When a catalog was observed, health
also includes `catalog_status`, `catalog_source`, `catalog_loaded_at`,
`catalog_age_seconds`, `catalog_complete`, and `catalog_stale`. For the normalized,
secret-safe view, use `coeus_runtime_diagnostics`; its nested `readiness` contains
`configured`, `reachable`, `direct_key`, `oauth`, `catalog`, and `ready`.

`coeus_multi_model_verify` executes one strict provider/model attempt per selected
entry. It reports consensus only when at least two distinct provider/model responses
are substantive.

## Complete tool surface

The registry exposes exactly 55 provider-neutral tools:

`coeus_healthcheck`, `coeus_capabilities`, `coeus_list_models`,
`coeus_runtime_diagnostics`, `coeus_stats`, `coeus_route`, `coeus_ask`,
`coeus_project_intake`, `coeus_review_bundle`, `coeus_counterfactual_review`,
`coeus_debug_playbook`, `coeus_test_strategy`, `coeus_docs_drift_check`,
`coeus_release_readiness`, `coeus_multi_model_verify`, `coeus_wildcard`,
`coeus_design_review_bundle`, `coeus_version`, `coeus_summarize`, `coeus_eval_plan`,
`coeus_review_code`, `coeus_verify_solution`, `coeus_thinkdeep`,
`coeus_project_task_plan`, `coeus_second_opinion`,
`coeus_workflow_automation_plan`, `coeus_frontend_design_brief`,
`coeus_frontend_taste_direction`, `coeus_css_component_creator`,
`coeus_ui_asset_sources`, `coeus_static_asset_plan`, `coeus_critical_debate`,
`coeus_analyze_codebase`, `coeus_codebase_map`, `coeus_design_review`,
`coeus_start_conversation`, `coeus_continue_conversation`,
`coeus_list_conversations`, `coeus_clear_conversation`, `coeus_ai_collaboration`,
`coeus_extract_structured`, `coeus_git_diff_review`, `coeus_content_comparison`,
`coeus_review_pr`, `coeus_web_search`, `coeus_web_fetch`, `coeus_image_generate`,
`coeus_generate_tests`, `coeus_refactor_code`, `coeus_explain_code`,
`coeus_generate_docs`, `coeus_generate_commit`, `coeus_pixel_art_generate`,
`coeus_pixel_art_find`, and `coeus_pixel_palette`.

## Example Workflows

### Repository Intake

```text
Use coeus_project_intake on the current repository with max_depth=3 and max_files=500.
Summarize the stack, key files, risks, and suggested workflows.
```

### Model Routing

```text
Use coeus_route for this task:
"Review a Python diff for correctness, backwards compatibility, and security."
Budget: standard. Speed: balanced. Requires vision: false.
Explain the selected provider, model, and workflow.
```

### Code Review

```text
Use coeus_review_bundle on the current git diff.
Focus on correctness, missing tests, security, and maintainability.
Lead with concrete findings ordered by severity.
```

### Debugging

```text
Use coeus_debug_playbook.
Symptom: The MCP client shows the server but tool calls fail.
Context: Include startup logs and the MCP client configuration.
Return ranked hypotheses and the smallest confirming experiments.
```

### Multi-Provider Verification

```text
Use coeus_multi_model_verify with this prompt:
"Does this implementation preserve provider neutrality? List blocking risks only."
Providers: auto. Temperature: 0.2.
```

### Wildcard Ideation

```text
Use coeus_wildcard for this problem:
How can we reduce CI build times without asking every team to rewrite their tests?

Set mode=chaotic. Return the three wildcard options and the strongman option.
```

Use `mode=practical` when the output needs near-term product or engineering ideas.
Use `mode=moonshot` when the user explicitly wants speculative directions.

### Release Readiness

```text
Use coeus_release_readiness for a public GitHub release.
Include git status and docs drift.
Explain blockers and exact follow-up commands.
```

## Configuration

| Variable | Default | Notes |
| --- | --- | --- |
| `COEUS_DEFAULT_PROVIDER` | `auto` | Automatic routing or one canonical provider ID. |
| `COEUS_PROVIDER_ORDER` | blank | Optional comma-separated provider preference order; capability and readiness checks still apply. |
| `COEUS_DEEPSEEK_API_KEY` | empty | Direct DeepSeek credential. |
| `COEUS_ALIBABA_API_KEY` | empty | Direct Alibaba Cloud Model Studio credential. |
| `COEUS_OPENROUTER_API_KEY` | empty | Direct OpenRouter credential. |
| `COEUS_AGY_COMMAND` | `agy` | OAuth CLI executable. |
| `COEUS_AGY_DEFAULT_MODEL` | `gemini-3.7-flash-medium` | Agy starting model. |
| `COEUS_AGY_STATE_DIR` | `.coeus/state` | Ignored, non-secret Agy runtime profile directory. |
| `COEUS_CODEX_COMMAND` | `codex` | OAuth CLI executable. |
| `COEUS_CODEX_DEFAULT_MODEL` | `gpt-5.6-terra` | Codex starting model. |
| `COEUS_CLAUDE_COMMAND` | `claude` | OAuth CLI executable. |
| `COEUS_CLAUDE_DEFAULT_MODEL` | `claude-opus-5` | Claude starting model. |
| `COEUS_DEEPSEEK_DEFAULT_MODEL` | `deepseek-v4-pro` | DeepSeek starting model. |
| `COEUS_DEEPSEEK_FAST_MODEL` | `deepseek-v4-flash` | DeepSeek fast model. |
| `COEUS_ALIBABA_DEFAULT_MODEL` | `qwen3.8-max` | Alibaba starting model. |
| `COEUS_OPENROUTER_DEFAULT_MODEL` | `openai/gpt-4.1-nano` | OpenRouter starting model. |
| `COEUS_PROVIDER_TIMEOUT` | `120` | Per-provider execution budget in seconds. |
| `COEUS_PROVIDER_MAX_OUTPUT_BYTES` | `1048576` | Bounded CLI output capture. |
| `COEUS_PROVIDER_CATALOG_TTL` | `60` | Model catalog cache lifetime in seconds. |
| `COEUS_TOOL_PROFILE` | `standard` | Tool profile label returned by capabilities. |
| `COEUS_ENABLE_DESIGN_TOOLS` | `true` | Design capability pack flag. |
| `COEUS_ENABLE_PIXEL_TOOLS` | `true` | Pixel capability pack flag. |
| `COEUS_ENABLE_WEB_TOOLS` | `true` | Web capability pack flag. |
| `COEUS_ENABLE_EXPERIMENTAL_TOOLS` | `false` | Experimental workflow flag. |

Startup does not require every provider to be configured. Missing keys, missing CLI
binaries, missing OAuth sessions, and missing dependencies are reported by
`coeus_healthcheck`.

## Development

Run the built-in unittest suite:

```bash
python3 -m unittest discover -v
```

Run pytest when dev dependencies are installed:

```bash
python -m pytest
```

The default suite is offline and never requires provider credentials. Bounded
live release probes are opt-in and make one independent request per canonical
provider:

```bash
COEUS_LIVE_PROVIDER_TESTS=1 ./.venv/bin/python -m pytest \
  tests/test_live_provider_smoke.py -q -rs
```

Each probe uses a tiny prompt and token budget, does not use fallback, and
records the requested and actual model. Outcomes are reported separately:
`passed` means the request returned a substantive response; `failed` means a
configured provider returned another error; `not_configured` means its API
credential or OAuth CLI is unavailable; and `authentication_required` means a
configured provider rejected the authentication. The latter two outcomes are
skips, never passes. Without `COEUS_LIVE_PROVIDER_TESTS=1`, all six provider
probes skip before constructing the server or making a network/provider call.

Useful local smoke check:

```bash
python - <<'PY'
from mcp_server import CoeusMCPServer

server = CoeusMCPServer()
print(len(server.list_tools()))
print(server.call_tool("coeus_docs_drift_check", {"include_legacy": False}))
PY
```

## Troubleshooting

Start with health and capability checks:

```bash
python - <<'PY'
from mcp_server import CoeusMCPServer

server = CoeusMCPServer()
print(server.call_tool("coeus_healthcheck", {"probe_network": False}))
print(server.call_tool("coeus_capabilities", {})["providers"])
PY
```

Common issues:

- `mcp dependency is not importable`: activate the virtualenv and run
  `python -m pip install -e ".[dev]"`.
- No provider is ready: run the relevant OAuth login or configure one of the three
  direct Coeus API keys, then rerun `coeus_healthcheck`.
- A CLI is unavailable: install the CLI or set its `COEUS_*_COMMAND` path.
- A provider is configured but not ready: inspect catalog status and staleness in
  `coeus_runtime_diagnostics`.
- Tool calls work in a shell but not a desktop client: use an absolute `command` path
  and restart the client.
- `coeus_multi_model_verify` returns no attempts: no provider is configured and ready
  for the requested verification.

This release has a breaking provider-neutral tool surface. Existing configurations
must migrate to `coeus-ai` and the `coeus_*` names; the exact old-to-new workflow map
is in [docs/migrations/vnext-provider-migration.md](docs/migrations/vnext-provider-migration.md).