# Ribbon

> ACP client for Office

- **Type:** MCP server
- **Install:** `agentstack add mcp-gmaynez-ribbon`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [gmaynez](https://agentstack.voostack.com/s/gmaynez)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [gmaynez](https://github.com/gmaynez)
- **Source:** https://github.com/gmaynez/ribbon

## Install

```sh
agentstack add mcp-gmaynez-ribbon
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Ribbon

Ribbon brings installable ACP coding agents into Microsoft Office. Excel, Word, and PowerPoint each use a thin VSTO add-in, while one shared local broker manages the ACP Registry, agent processes, conversations, permissions, and a unified Office MCP server.

The result is one agent experience across Office without forcing Excel to automate the other applications.

## Current vertical slice

- Browse the public ACP Registry from the Office task pane.
- Install Windows binary and `npx` agent distributions. Ribbon provisions a private Node.js LTS runtime when needed and verifies the official Node archive checksum.
- Launch ACP v1 agents, authenticate them, create sessions, and render message chunks, plans, thoughts, and tool progress inline while a turn runs.
- Persist theme-independent conversation transcripts with generated titles, agent/model metadata, document binding, New chat, history browsing, and deletion. Ribbon restores native agent context through capability-gated ACP `session/resume` or `session/load`; unavailable and cross-document conversations remain safely reviewable.
- Gate every destructive Office MCP tool in Ribbon as well as relaying ACP permission requests, with an option to remember an approval for that action during the active agent session. A per-session Auto-approve toggle in the task pane lets you pre-authorize document changes and agent requests for one session; it is off by default, resets to Ask on new conversations or restart, and logs every auto-approved action in the transcript.
- Capture a local document checkpoint before each prompt and restore an earlier turn from the task pane; Ribbon saves a safety checkpoint first and restarts the agent session after restore.
- Populate an agent-driven model selector from ACP session configuration options and keep it synchronized when the agent changes configuration.
- Give every agent a local stdio MCP server named `ribbon-office`.
- Compose MCP guidance from the tools currently connected to that agent session, with the launching Office host's workflow first.
- Route MCP calls over a current-user named pipe to every connected Office host.
- Use a shared host-branded task pane: **Ribbon Grid for Excel**, **Ribbon Quill for Word**, and **Ribbon Deck for PowerPoint**.
- Reopen a closed task pane from the **Ribbon** group on the Office **Home** tab.
- Match the Windows/Office light or dark appearance with a shared DPI-aware visual system.

Included Office tools:

| Host | Tools |
| --- | --- |
| Excel | context, list sheets, read/write values and formulas, clear/format ranges, add sheets, create tables and charts |
| Word | context, bounded reads, headings, text edits, find/replace, formatting, lists, tables, comments, page breaks |
| PowerPoint | context, structured slide reads, slide lifecycle, text and shapes, formatting, images, tables, charts, notes, backgrounds, find/replace |

### Excel agent tools

The Excel adapter exposes task-oriented tools rather than a thin mirror of the COM object model:

| Tool | Purpose |
| --- | --- |
| `excel_get_context` | Resolve the active workbook, sheet, cell, selection, and used range. |
| `excel_list_sheets` | List worksheet names, visibility, and used ranges. |
| `excel_read_range` | Read bounded values, formulas, and optional number formats. |
| `excel_write_range` | Write a rectangular matrix of values. Formula-like strings remain literal. |
| `excel_write_formulas` | Write a rectangular matrix of explicit A1-style formulas. |
| `excel_clear_range` | Clear contents, formats, or the complete range state. |
| `excel_format_range` | Patch fonts, fills, number formats, alignment, borders, dimensions, and AutoFit. |
| `excel_add_sheet` | Add a validated worksheet at a deliberate workbook position. |
| `excel_create_table` | Turn an existing data range into a named, styled Excel table. |
| `excel_create_chart` | Create and position an embedded chart from an inspected source range. |

Range reads default to 20,000 cells and are hard-limited to 100,000 cells per call. Writes have the same 100,000-cell hard limit. This keeps agent context bounded and encourages targeted inspection.

### Word agent tools

Word operations use document character positions so an agent can inspect structure, make a targeted change, and verify the result:

| Tool | Purpose |
| --- | --- |
| `word_get_context` | Inspect the active document, selection, story, and document statistics. |
| `word_read_document` | Read a bounded slice of the main document story. |
| `word_list_headings` | Discover headings with outline levels and character positions. |
| `word_replace_selection` | Replace the current selection, including deletion with empty text. |
| `word_append_text` | Append text before the document's final paragraph mark. |
| `word_insert_text` | Insert text around the selection or at document boundaries. |
| `word_replace_range` | Replace or delete an exact span using inspected character positions. |
| `word_find_replace` | Perform bounded literal replacement with matching options. |
| `word_format_range` | Patch styles, fonts, paragraph layout, and highlighting. |
| `word_insert_heading` | Insert a paragraph using a built-in Heading 1–9 style. |
| `word_insert_list` | Insert structured bulleted or numbered items. |
| `word_insert_table` | Insert and populate a styled table from a rectangular matrix. |
| `word_add_comment` | Attach a review comment to the selection or explicit positions. |
| `word_insert_page_break` | Insert a page break at a deliberate document position. |

Document reads are limited to 200,000 characters per call. Character positions are snapshots: agents should refresh context or headings after mutations before making another position-based change.

### PowerPoint agent tools

Deck exposes presentation tasks and structured slide state instead of arbitrary COM dispatch:

| Capability | Tools |
| --- | --- |
| Inspect | `powerpoint_get_context`, `powerpoint_list_slides`, `powerpoint_read_slide` |
| Slide lifecycle | `powerpoint_add_slide`, `powerpoint_duplicate_slide`, `powerpoint_move_slide`, `powerpoint_delete_slide` |
| Text and diagrams | `powerpoint_set_slide_title`, `powerpoint_add_textbox`, `powerpoint_add_shape`, `powerpoint_format_shape`, `powerpoint_delete_shape` |
| Data and media | `powerpoint_add_table`, `powerpoint_add_chart`, `powerpoint_add_image` |
| Presentation details | `powerpoint_set_speaker_notes`, `powerpoint_set_slide_background`, `powerpoint_find_replace` |

PowerPoint coordinates and dimensions are measured in points. Use one-based slide numbers from a recent context/list result and target shapes by the returned `shape_name`. Shape formatting is patch-based, so omitted properties are preserved. Local images must already exist at an absolute path; Deck does not perform downloads inside PowerPoint.

## Architecture

```mermaid
flowchart LR
    E["Excel VSTO"] -->|"current-user pipe"| B["Ribbon Broker"]
    W["Word VSTO"] -->|"current-user pipe"| B
    P["PowerPoint VSTO"] -->|"current-user pipe"| B
    B -->|"ACP over stdio"| A["Installed ACP agent"]
    A -->|"MCP over stdio"| M["Ribbon Office MCP proxy"]
    M -->|"current-user pipe"| B
    B --> R["ACP Registry"]
```

The add-ins contain only UI and application-specific COM operations. The .NET 10 broker owns everything process-oriented, including agent installation and ACP/MCP transport. See [docs/architecture.md](docs/architecture.md) for protocol and security details.

## Build

Requirements:

- Windows with desktop Excel, Word, and PowerPoint
- Visual Studio with **Office/SharePoint development** tools
- .NET Framework 4.8 targeting pack
- .NET 10 runtime for the broker

Build the complete solution from a Visual Studio developer shell:

```powershell
msbuild Ribbon.slnx /t:Build /p:Configuration=Debug /m
```

The VSTO builds include `Ribbon.Broker.exe` and its runtime files in each deployment manifest. During repository development the shared client can also locate the broker under `Ribbon.Broker/bin`; `RIBBON_BROKER_PATH` overrides this lookup.

Signed GitHub Releases are created from semantic-version tags such as `v1.2.0` when the tagged commit belongs to `main`. See [docs/releasing.md](docs/releasing.md) for signing-secret setup, release steps, artifact contents, and the Microsoft Marketplace distribution constraint for VSTO add-ins.

To try Ribbon, set `Grid`, `Quill`, or `Deck` as the startup project and press **F5**. In the corresponding host-branded Ribbon task pane:

1. Select **Agents**.
2. Install a compatible agent such as OpenCode or Codex.
3. Select it from the agent list and enter a prompt. Use **Ctrl+Enter** to send.

Agent state is stored under `%LOCALAPPDATA%\Ribbon`:

- `agents` — downloaded binary agents
- `runtimes` — Ribbon-managed runtimes such as Node.js
- `sessions` — isolated ACP working directories and Office guidance
- `Conversations` — persistent Ribbon-owned transcript and session metadata, limited to the newest 200 conversations
- `Checkpoints` — temporary per-host snapshots used by active task panes; removed when that Office host shuts down
- `cache` — cached ACP Registry document
- `logs` — broker diagnostics

## Project layout

- `Ribbon.Contracts` — versioned broker wire contracts shared by .NET Framework and .NET 10
- `Ribbon.Broker` — ACP client, registry installer, session manager, Office MCP proxy, and host router
- `Ribbon.Vsto` — reusable named-pipe client, agent manager, permission UI, and task pane
- `Grid` — Excel host adapter
- `Quill` — Word host adapter
- `Deck` — PowerPoint host adapter

## Scope and next work

This is a working architectural slice, not yet a production installer. The next useful increments are tracked-changes and image/section support for Word, conditional formatting and sorting for Excel, a selectable authentication-method dialog, a production installer with Authenticode-signed binaries and a .NET runtime prerequisite or self-contained broker, and automated integration tests with a fake ACP agent.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [gmaynez](https://github.com/gmaynez)
- **Source:** [gmaynez/ribbon](https://github.com/gmaynez/ribbon)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-gmaynez-ribbon
- Seller: https://agentstack.voostack.com/s/gmaynez
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.