# mcp-cli-tools

MCP server that gives AI coding agents (Claude Code, Cursor, Cline, etc.) safe access to multiple AI models through [Antigravity CLI](https://antigravity.codes) and [OpenAI Codex CLI](https://github.com/openai/codex).

Think of it as a **local Fugu-style orchestrator**: your AI agent can consult Gemini, GPT, and other models mid-conversation, compare answers, ask for adversarial review, and run scoped code reviews without leaving the editor.

## What it does

| Tool | Backend | Capability |
|------|---------|------------|
| `fugu_orchestrate` | Antigravity CLI (`agy`) | Fugu-style single entry point: fast routing or ultra workflow with subtasks, `model_id`, `access_list`, shared memory, and synthesis |
| `consult_model` | Antigravity CLI (`agy`) | Ask one external model for a second opinion |
| `compare_models` | Antigravity CLI (`agy`) | Ask 2-4 models in parallel and synthesize agreement/disagreement |
| `adversarial_check` | Antigravity CLI (`agy`) | Ask a model to attack a proposal, plan, or implementation idea |
| `review_workspace` | OpenAI Codex CLI | Run scoped code review on uncommitted changes, a base branch, or a commit |
| `security_audit` | OpenAI Codex CLI | Run a security-focused Codex review prompt |
| `run_antigravity` | Antigravity CLI (`agy`) | Compatibility wrapper with safe subcommands only |
| `run_codex` | OpenAI Codex CLI | Compatibility wrapper for `codex review` only |

Your AI agent gains the ability to:
- Get a **second opinion** from a different model family
- Use a **single Fugu-style tool** that hides routing, decomposition, worker calls, and final synthesis
- Compare multiple external answers in one tool call
- Run **code reviews** via Codex without leaving the conversation
- Do **adversarial verification** (one model checks another's work)
- **Route by expertise** — Gemini for analysis, GPT for code review
- Receive structured metadata for each call: command, cwd, exit code, timeout, duration, stdout, stderr

## Prerequisites

- [Antigravity CLI](https://antigravity.codes) installed as `agy`
- [OpenAI Codex CLI](https://github.com/openai/codex) installed as `codex`
- Node.js 18+

## Install

```bash
git clone https://github.com/Marcelo-Henry/mcp-cli-tools.git
cd mcp-cli-tools
npm install
npm run build
```

## Configure in Claude Code

Add to `~/.claude/settings.json` under `mcpServers`:

```json
{
  "mcpServers": {
    "cli-tools": {
      "command": "node",
      "args": ["/path/to/mcp-cli-tools/dist/index.js"]
    }
  }
}
```

## Usage

### fugu_orchestrate

Use this as the main entry point when you want behavior closest to Fugu/Fugu-Ultra.

Fast mode selects one worker for lower latency:

```
fugu_orchestrate(
  task: "Explain this TypeScript error and suggest the smallest fix",
  mode: "fast",
  effort: "standard",
  cwd: "/path/to/repo"
)
```

Ultra mode builds and executes a workflow with `model_id`, subtasks, `access_list`, critique, and synthesis:

```
fugu_orchestrate(
  task: "Create a local task dashboard from scratch with persistence, tests, and a polished UI",
  mode: "ultra",
  effort: "max",
  sharedMemoryKey: "taskpulse",
  cwd: "/path/to/repo"
)
```

Restrict the worker pool when privacy, cost, or compliance matters:

```
fugu_orchestrate(
  task: "Analyze this architecture",
  mode: "ultra",
  excludeModels: ["gpt-oss-120b"]
)
```

> `fugu_orchestrate` is a local deterministic orchestration layer inspired by the public Fugu/Fugu-Ultra workflow shape. It is not Sakana's learned orchestrator model.

### consult_model

Ask one external model:

```
consult_model(prompt: "Analyze this architecture", model: "gemini-3.1-pro", cwd: "/path/to/repo")
```

### compare_models

Ask multiple models in parallel:

```
compare_models(
  prompt: "Which migration strategy is safest for this repo?",
  models: ["gemini-3.5-flash", "gemini-3.1-pro"]
)
```

### adversarial_check

Ask an external model to find flaws in a proposal:

```
adversarial_check(
  proposal: "Move all orchestration policy into CLAUDE.md",
  context: "MCP server for Claude Code + GPT/Gemini collaboration"
)
```

### review_workspace

Review uncommitted changes:

```
review_workspace(scope: "uncommitted", cwd: "/path/to/repo")
```

Review against a branch:

```
review_workspace(scope: "base", base: "main", cwd: "/path/to/repo")
```

Review a commit:

```
review_workspace(scope: "commit", commit: "abc123", cwd: "/path/to/repo")
```

### security_audit

Run a security-focused review:

```
security_audit(instructions: "Focus on command execution and path traversal", cwd: "/path/to/repo")
```

### Compatibility tools

`run_antigravity` and `run_codex` remain available for existing Claude rules, but they are intentionally narrower now.

#### run_antigravity

Query any model available in Antigravity CLI:

```
run_antigravity(promptContext: "Analyze this architecture", model: "gemini-3.1-pro")
```

List available models:
```
run_antigravity(subcommand: "models")
```

Run safe subcommands:
```
run_antigravity(subcommand: "help")
run_antigravity(subcommand: "changelog")
```

Allowed subcommands are `models`, `help`, and `changelog`. Plugin/install/update operations are blocked by design.

#### run_codex

Review uncommitted changes:
```
run_codex(action: "review", flags: ["--uncommitted"], cwd: "/path/to/repo")
```

Review with a specific prompt:
```
run_codex(action: "review", prompt: "Focus on security vulnerabilities")
```

Review against a branch:
```
run_codex(action: "review", flags: ["--base", "main"], cwd: "/path/to/repo")
```

Use a specific model:
```
run_codex(action: "review", prompt: "Audit this code", model: "gpt-5", cwd: "/path/to/repo")
```

> **Notes:**
> - `prompt` e `flags` são mutuamente exclusivos e agora são validados pelo MCP.
> - Use `cwd` quando o comando depender do contexto de um repositório específico.
> - `action` agora aceita apenas `review`.
> - `flags` aceita apenas `--uncommitted`, `--base`, `--commit`, `--title` e `--strict-config`.

### Error handling

Os tools retornam:
- comando executado
- `cwd` usado
- `exit_code`
- `duration_ms`
- `stdout` e `stderr`
- `structuredContent` com metadata da chamada

Se o processo sair com código diferente de zero, receber sinal ou estourar timeout, o resultado é marcado como erro no protocolo MCP.

## Available Models

### Via Antigravity

| Model | Best for |
|-------|----------|
| `gemini-3.5-flash` | Fast exploration, brainstorming (default) |
| `gemini-3.1-pro` | Deep analysis, architecture, large context |
| `gpt-oss-120b` | Independent perspective, diverse opinion |

### Via Codex

Codex models depend on your local Codex CLI configuration. Pass the model explicitly when needed:

```
review_workspace(scope: "uncommitted", model: "gpt-5", cwd: "/path/to/repo")
security_audit(model: "gpt-5", cwd: "/path/to/repo")
```

## Making your AI agent orchestrate automatically

Add orchestration rules to your global `~/.claude/CLAUDE.md` to make Claude Code call these tools proactively. See [ORCHESTRATION.md](ORCHESTRATION.md) for a full guide with triggers and patterns.

## License

MIT