# Gemini CLI Extension

Connect Gemini CLI to Miro boards using the MCP extension.

## Overview

The Gemini CLI extension provides Miro MCP integration, enabling Gemini to:

- Read board content and context
- Create diagrams, documents, and tables
- Generate code from board designs

## Extension Files

The repository root **is** the Gemini extension. Per [Gemini CLI's extension model](https://geminicli.com/docs/extensions/reference/), the manifest lives at the extension root and bundled skills are auto-discovered from `<extension-root>/skills/`. When users `gemini extensions install miroapp/miro-ai`, the repo root becomes the extension directory.

```
miro-ai/
├── gemini-extension.json   # Extension manifest (auto-generated)
└── skills/                 # 7 skills, byte-identical to the source plugin
```

Both files are auto-generated by `bun run convert` from `claude-plugins/miro/`. Example `gemini-extension.json`:

```json
{
  "name": "miro",
  "version": "x.y.z",
  "description": "Secure access to Miro boards...",
  "mcpServers": {
    "miro": {
      "httpUrl": "https://mcp.miro.com/",
      "oauth": { "enabled": true },
      "headers": { "X-AI-Source": "gemini-extension" }
    }
  }
}
```

## Installation

```bash
gemini extensions install https://github.com/miroapp/miro-ai
```

Gemini CLI clones the repo into `~/.gemini/extensions/miro/`, reads `gemini-extension.json` to register the Miro MCP server, and discovers the 7 skills under `skills/` as Extension Skills. Restart Gemini CLI and authenticate when prompted.

For local development, see [CONTRIBUTING.md](../../CONTRIBUTING.md#gemini-cli-extensions).

## Available Extensions

| Extension | Description |
|-----------|-------------|
| miro | Core MCP integration with bundled skills (browse, code-review, code-spec, code-explain-on-board, diagram, doc, table) |

### Authentication

On first use:
1. Gemini will prompt you to authenticate with Miro
2. Sign in to your Miro account
3. Select the team containing your target boards
4. Authorize the connection

## Available Capabilities

The extension provides access to all Miro MCP tools:

### Content Creation
- Create flowcharts, mind maps, UML diagrams
- Generate markdown documents on boards
- Create tables with typed columns

### Content Reading
- List board items by type
- Extract documentation from frames
- Read table data with filtering

### Context Extraction
- Generate project summaries
- Extract design specifications
- Get technical requirements

## Usage Examples

Once configured, you can interact with Miro boards:

```
# Create a diagram
"Create a flowchart on https://miro.com/app/board/abc= showing the user registration process"

# Read board content
"What's on my Miro board https://miro.com/app/board/abc=?"

# Generate documentation
"Extract the design requirements from the wireframes on my Miro board"
```

## Configuration Fields

| Field | Description |
|-------|-------------|
| `name` | Extension display name |
| `version` | Extension version |
| `description` | What the extension provides |
| `mcpServers` | MCP server configurations |

### MCP Server Fields

| Field | Description |
|-------|-------------|
| `httpUrl` | MCP server endpoint |
| `oauth.enabled` | Enable OAuth authentication |
| `headers` | Custom HTTP headers |

## Scope

This repository follows a deliberate **skills + MCP only** convention — see [CONTRIBUTING → Scope and Conventions](../../CONTRIBUTING.md#scope-and-conventions). The Gemini extension surface is:

- `gemini-extension.json` (repo root) — extension manifest with the MCP server config
- `skills/*/SKILL.md` (repo root) — copied verbatim from the source plugin, shared with the agent-skills mirror

No commands, agents, hooks, or per-extension README are emitted. The Gemini CLI extension format supports those, but this repo does not use them.

## Differences from the Claude source

| Field | Claude source | Gemini output |
|-------|--------------|---------------|
| Manifest | `.claude-plugin/plugin.json` + `.mcp.json` | Single `gemini-extension.json` at repo root |
| MCP URL field | `url` | `httpUrl` |
| OAuth | Implicit | `oauth: { enabled: true }` for HTTP servers |
| MCP `X-AI-Source` header | `claude-code-plugin` | `gemini-extension` |
| Skills | `skills/*/SKILL.md` | Identical — copied verbatim |

Gemini extensions are auto-generated from Claude plugins via `bun run convert`. See [Claude Code](../claude-code/overview.md) for the canonical plugin source.

## Troubleshooting

### Authentication Issues

- Ensure OAuth is enabled in your configuration
- Try re-authenticating if tokens expire
- Verify you selected the correct team

### Connection Issues

- Check network access to `https://mcp.miro.com/`
- Verify the extension file is valid JSON
- Ensure Gemini CLI supports MCP extensions

## Related

- [MCP Setup Guide](../getting-started/mcp-setup.md) - General MCP configuration
- [Tools Reference](../mcp/tools-reference.md) - Available MCP tools
- [Tutorials](../mcp/tutorials.md) - Example workflows