# agy-mcp-server

[![CI](https://github.com/moisesfilho/agy-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/moisesfilho/agy-mcp-server/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/Node.js-20%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/Model%20Context%20Protocol-server-6f42c1)](https://modelcontextprotocol.io/)
[![Platform](https://img.shields.io/badge/platform-Linux%20%7C%20macOS%20%7C%20Windows-blue)](https://github.com/moisesfilho/agy-mcp-server)

**Languages:** [English](README.md) | [Português](README.pt-BR.md)

An MCP server that exposes the Antigravity CLI (`agy`) to MCP clients such as OpenCode. It provides structured tools for planning, code review, test validation, generic prompts, and literal CLI commands.

The server is intentionally restricted to Google Gemini models and defaults to `gemini-3.7-flash-medium`.

> **Important:** This project requires the official `agy` CLI to be installed and authenticated. It does not provide or redistribute Antigravity credentials or the CLI itself.

## Features

- MCP server over stdio for local clients
- `agy_plan` for architecture and implementation plans
- `agy_review` for technical and security-oriented code review
- `agy_validate_tests` for test quality and coverage analysis
- `agy_exec` for general-purpose Antigravity prompts
- `agy_command` for literal slash commands such as `/usage`
- Strict allowlist for Google Gemini models
- Safe argument passing through `spawn`, without shell interpolation
- Configurable project context through `directory`
- Five-minute execution timeout with graceful termination and force-kill fallback
- English tool descriptions and error messages

## Requirements

- Node.js 20 or later
- npm
- The `agy` CLI installed and authenticated
- An MCP-compatible client

By default, the server looks for `agy` at `~/.local/bin/agy`. Set `AGY_BIN_PATH` when it is installed elsewhere.

## Installation

```bash
git clone https://github.com/moisesfilho/agy-mcp-server.git
cd agy-mcp-server
npm ci
npm run build
```

## OpenCode Configuration

Add the following entry to `~/.config/opencode/opencode.json`:

```json
{
  "mcp": {
    "agy-proxy": {
      "type": "local",
      "command": [
        "node",
        "/absolute/path/to/agy-mcp-server/dist/index.js"
      ]
    }
  }
}
```

For a local installation in the standard project directory, use:

```json
{
  "mcp": {
    "agy-proxy": {
      "type": "local",
      "command": [
        "node",
        "/home/moises/Projetos/agy-mcp-server/dist/index.js"
      ]
    }
  }
}
```

Restart the MCP client after changing its configuration.

## Available Models

Every tool accepts an optional `model` argument. Only the following models are accepted:

| Model | Default |
| --- | --- |
| `gemini-3.7-flash-medium` | Yes |
| `gemini-3.7-flash-high` | No |
| `gemini-3.7-flash-low` | No |
| `gemini-3.8-flash-high` | No |
| `gemini-3.8-flash-medium` | No |
| `gemini-3.8-flash-low` | No |
| `gemini-3.6-flash-high` | No |
| `gemini-3.6-flash-medium` | No |
| `gemini-3.6-flash-low` | No |
| `gemini-3.1-pro-high` | No |
| `gemini-3.1-pro-low` | No |

The model suffix controls the reasoning effort. The server does not send a separate `--effort` flag because the `agy` CLI rejects conflicting combinations.

## Usage

Ask the MCP client to use a tool. Examples:

### Create a plan

```text
Use agy_plan to create an implementation plan for adding PostgreSQL caching to this project.
```

Tool arguments:

```json
{
  "prompt": "Create an implementation plan for adding PostgreSQL caching.",
  "directory": "/home/moises/Projetos/my-project",
  "model": "gemini-3.7-flash-medium"
}
```

### Review code

```text
Use agy_review to inspect the current changes for security issues and regressions.
```

### Validate tests

```text
Use agy_validate_tests to identify missing edge cases in the current test suite.
```

### Run a direct CLI command

Use `agy_command` when the input must reach `agy` literally, without an LLM interpreting it:

```json
{
  "command": "/usage"
}
```

This is equivalent to:

```bash
agy -p /usage --output-format text
```

Other slash commands can be sent in the same way, provided they are supported by the installed `agy` version.

### Run a general prompt

```json
{
  "prompt": "Analyze the current architecture and identify the three largest reliability risks.",
  "mode": "plan",
  "directory": "/home/moises/Projetos/my-project",
  "model": "gemini-3.7-flash-high"
}
```

## Configuration

| Variable | Default | Description |
| --- | --- | --- |
| `AGY_BIN_PATH` | `~/.local/bin/agy` | Absolute path to the `agy` executable |

The server does not store credentials. Authentication is handled by the local `agy` installation and its own configuration.

## Security Notes

- The server passes arguments directly to the child process and does not invoke a shell.
- `agy` is started with `--dangerously-skip-permissions`, as required for unattended MCP calls. Review prompts and workspace permissions before using `agy_exec` with edit-capable modes.
- Directory paths are supplied as process arguments and used as the child working directory.
- Model validation rejects non-Gemini model names before starting `agy`.
- Do not commit `agy` credentials, local configuration files, or environment secrets.

## Project Structure

```text
src/
├── config.ts                 # Binary resolution and Gemini allowlist
├── index.ts                  # MCP stdio server entry point
├── runner.ts                 # agy process lifecycle and timeout handling
└── tools/
    ├── command.ts            # Literal slash commands
    ├── exec.ts               # Generic prompts
    ├── plan.ts               # Technical planning
    ├── review.ts             # Code review
    └── validate-tests.ts     # Test analysis
```

## Development

```bash
npm install
npm run typecheck
npm run build
npm start
```

The server communicates through stdin/stdout using MCP JSON-RPC. Diagnostic messages are written to stderr.

## License

This project is licensed under the MIT License. See [LICENSE](LICENSE).