# Rls Slides MCP Server

A Python-based framework for rapidly developing Model Context Protocol (MCP) servers


## ArCo — Configuring Your App for Archipelago and RL Studio

### What is Archipelago?

RL Studio uses **[Archipelago](https://github.com/Mercor-Intelligence/archipelago)**, Mercor's open-source harness for running and evaluating AI agents against RL environments

Your MCP server runs inside an Archipelago environment, where AI agents connect to it via the MCP protocol to complete tasks.

### What is ArCo?

**ArCo** (short for **Archipelago Config**) is the configuration system for deploying your MCP server to Archipelago. It consists of two files that tell Archipelago how to build and run your application.

### Configuration Files

| File | Purpose |
|------|---------|
| `mise.toml` | **How to build and run your app** — lifecycle tasks (install, build, start, test) |
| `arco.toml` | **What infrastructure your app needs** — environment variables, secrets, runtime settings |

### Why ArCo?

Archipelago is deployed to multiple environments with different infrastructure requirements (Docker, Kubernetes, custom orchestrators). Rather than writing Dockerfiles or K8s manifests directly, you declare *what your app needs* in these config files, and RL Studio generates the appropriate deployment artifacts for each proprietary customer "target consumer".

You as a Mercor expert only need to write `mise.toml` and `arco.toml`, we write Dockerfiles, K8s manifests, etc. for you. 

### Mise: The Task Runner

**[Mise](https://mise.jdx.dev/)** is required for development. Install it first:

```bash
curl https://mise.run | sh
```

Mise is a polyglot tool manager -- it reads `mise.toml` and automatically installs the correct versions of Python, uv, and any other tools your project needs. You don't need to install Python or uv yourself.

**Run tasks with mise instead of calling tools directly:**

| Instead of... | Run... |
|---------------|--------|
| `uv sync --all-extras` | `mise run install` |
| `pytest` | `mise run test` |
| `uv run python main.py` | `mise run start` |
| `ruff check .` | `mise run lint` |

### Lifecycle Tasks (`mise.toml`)

The `mise.toml` file defines how to build and run your application:

```toml
[tools]
python = "3.13"
uv = "0.6.10"

[env]
_.python.venv = { path = ".venv", create = true }

[tasks.install]
description = "Install dependencies"
run = "uv sync --all-extras"

[tasks.build]
description = "Build the project"
run = "echo 'No build step required'"

[tasks.start]
description = "Start the MCP server"
run = "uv run python main.py"
depends = ["install"]

[tasks.test]
run = "pytest"

[tasks.lint]
run = "ruff check ."

[tasks.format]
run = "ruff format ."

[tasks.typecheck]
run = "basedpyright"
```

### Infrastructure Config (`arco.toml`)

The `arco.toml` file declares what infrastructure your app needs:

```toml
[arco]
source = "foundry_app"
name = "my-server"
version = "0.1.0"
env_base = "standard"

# Runtime environment: baked into container
[arco.env.runtime]
APP_FS_ROOT = "/filesystem"
INTERNET_ENABLED = "false"

# User-configurable parameters (shown in RL Studio UI)
[arco.env.runtime.schema.INTERNET_ENABLED]
type = "bool"
label = "Internet access"
description = "Allow the MCP server to make outbound network requests"

# Secrets: injected at runtime, never baked
[arco.secrets.host]
GITHUB_TOKEN = "RLS_GITHUB_READ_TOKEN"
```

### Environment Variable Matrix

ArCo uses a 2x3 matrix for environment variables:

| | Host (build orchestration) | Build (container build) | Runtime (container execution) |
|---|---|---|---|
| **Config** | `[arco.env.host]` | `[arco.env.build]` | `[arco.env.runtime]` |
| **Secret** | `[arco.secrets.host]` | `[arco.secrets.build]` | `[arco.secrets.runtime]` |

- **Config** values can be baked into containers
- **Secret** values are always injected at runtime, never baked into images

### Environment Variables: Local vs Production

**Important:** Environment variables must be set in two places — one for local development, one for production. This is current tech debt we're working to simplify.

| File | Purpose | When it's used |
|------|---------|----------------|
| `mise.toml` `[env]` | Local development | When you run `mise run start` locally |
| `arco.toml` `[arco.env.*]` | Production | When RL Studio deploys your container |

**How mise works:** Mise functions like [direnv](https://direnv.net/) — when you `cd` into a directory with a `mise.toml`, it automatically loads environment variables and activates the correct tool versions (Python, uv, etc.). You don't need to manually source anything.

**The rule:** If you add an environment variable, add it to **both files**:

```toml
# mise.toml — for local development
[env]
MY_NEW_VAR = "local_value"
```

```toml
# arco.toml — for production
[arco.env.runtime]
MY_NEW_VAR = "production_value"
```

**Do NOT use `.env` files.** The `mise.toml` + `arco.toml` system replaces `.env` entirely. These are the only two files you need for environment variable management.

### ArCo Environment Stages: host, build, runtime

Unlike `mise.toml` which has a single flat `[env]` section, ArCo separates environment variables into three stages based on *when* they're needed in the deployment pipeline. You must specify the correct stage for each variable.

| Stage | When Used | How It's Consumed | Example Variables |
|-------|-----------|-------------------|-------------------|
| `[arco.env.host]` | Before container build | Read by RL Studio orchestration layer | `REPO_URL`, `REPO_BRANCH`, `REPO_PATH` |
| `[arco.env.build]` | During `docker build` | Exported before install/build commands | `UV_COMPILE_BYTECODE`, `CFLAGS` |
| `[arco.env.runtime]` | When container runs | Baked into Dockerfile as `ENV` | `APP_FS_ROOT`, `INTERNET_ENABLED` |

**Stage Details:**

**Host Stage** (`[arco.env.host]`) — Used by RL Studio's build orchestrator (the "Report Engine") before any Docker commands. These variables tell RL Studio *how to fetch your code*:
- `REPO_URL` — Git repository to clone
- `REPO_BRANCH` — Branch to checkout (optional)
- `REPO_PATH` — Subdirectory containing your app (optional)

These are **never** injected into your container — they're consumed by infrastructure.

**Build Stage** (`[arco.env.build]`) — Available during `docker build` when running your `install` and `build` tasks. Exported as shell variables (via `export VAR=value`) before each command. Use for:
- Compiler flags (`CFLAGS`, `LDFLAGS`)
- Build-time feature toggles (`INSTALL_MEDICINE=true`)
- Package manager configuration (`UV_COMPILE_BYTECODE=1`)

These are **not** baked into the final image as `ENV` — they only exist during build.

**Runtime Stage** (`[arco.env.runtime]`) — Baked into the Dockerfile as `ENV` directives and available when your container runs. This is where most of your app configuration goes:
- `APP_FS_ROOT` — Filesystem root for your app
- `INTERNET_ENABLED` — Network policy flag
- `HAS_STATE` / `STATE_LOCATION` — Stateful app configuration
- Any custom app configuration

**Why the separation matters:** 
- Security: Host/build secrets don't leak into the final container image
- Performance: Build-time vars don't bloat the runtime environment
- Clarity: RL Studio knows exactly which vars to use at each pipeline stage

**Mapping mise.toml to arco.toml:** In local development, `mise.toml` simulates all three stages at once. When adding a new variable, consider which stage it belongs to:

```toml
# mise.toml — flat, everything available locally
[env]
APP_FS_ROOT = "/filesystem"
MY_API_URL = "http://localhost:8000"
```

```toml
# arco.toml — staged for production
[arco.env.runtime]
APP_FS_ROOT = "/filesystem"
MY_API_URL = "https://api.production.com"
```

### Secrets

Use `[arco.secrets.*]` for sensitive values like API keys, tokens, and passwords. Secrets are:
- **Never baked** into Docker images (excluded from Dockerfiles)
- **Masked** in logs and UI
- **Resolved at runtime** from AWS Secrets Manager by the MCP Core team's infrastructure

```toml
# arco.toml
[arco.secrets.runtime]
API_KEY = true              # Secret name matches env var name
DATABASE_URL = "db_password" # Custom secret name in AWS
```

**For local development:** Create a `mise.local.toml` file (gitignored) to set secret values:

```toml
# mise.local.toml — gitignored, never committed
[env]
API_KEY = "your-dev-api-key"
DATABASE_URL = "postgresql://localhost/devdb"
```

**To add a new secret:** Contact the MCP Core team. They will add the secret to AWS Secrets Manager and configure RL Studio to inject it at runtime.

### CI/CD Integration

This repository includes GitHub Actions for ArCo validation:

- **`arco-validate.yml`** — Validates your config on every PR
- **`foundry-service-sync.yml`** — Syncs your config to RL Studio on release

### Keeping Config Updated

| If you... | Update this |
|-----------|-------------|
| Changed install/build/run commands | `[tasks.*]` in `mise.toml` |
| Added a new environment variable | `[env]` in `mise.toml` AND `[arco.env.runtime]` in `arco.toml` |
| Need a new secret | `[arco.secrets.*]` in `arco.toml` |
| Want users to configure a variable | Add `[arco.env.runtime.schema.*]` |

---


## Tools (Default Mode)

These are the individual tools available by default:

### 1. `create_deck`

Create a Presentations presentation from structured slide definitions.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `directory` | string | Yes | Directory path |
| `file_name` | string | Yes | Output filename ending with .pptx |
| `slides` | array[object] | Yes | List of slide definitions |
| `metadata` | object | No | Optional presentation metadata |

---

### 2. `delete_deck`

Delete a Presentations presentation.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | Yes | Path to the .pptx file to delete |

---

### 3. `add_slide`

Add a new slide to a presentation at the specified index.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | Yes | Path to the .pptx file |
| `slide_index` | integer | Yes | Index where to insert the new slide |
| `layout` | string | No | Slide layout type |
| `content` | object | No | Slide content definition |

---

### 4. `edit_slides`

Apply structured edit operations to an existing Presentations presentation.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | Yes | Path to the .pptx file |
| `operations` | array[object] | Yes | List of edit operations |
| `metadata` | object | No | Optional metadata updates |

**Available edit operations:**

| Operation Type | Description | Key Parameters |
|----------------|-------------|----------------|
| `update_slide_title` | Update slide title | `index`, `title` |
| `update_slide_subtitle` | Update slide subtitle | `index`, `subtitle` |
| `set_bullets` | Set bullet points | `index`, `placeholder`, `items` |
| `append_bullets` | Append bullet points | `index`, `placeholder`, `items` |
| `clear_placeholder` | Clear placeholder content | `index`, `placeholder` |
| `replace_text` | Find and replace text | `search`, `replace`, `match_case` |
| `append_table` | Append a table | `index`, `placeholder`, `rows`, `header` |
| `update_table_cell` | Update table cell text | `index`, `table_idx`, `row`, `column`, `text` |
| `delete_slide` | Delete a slide | `index` |
| `duplicate_slide` | Duplicate a slide | `index`, `position` |
| `set_notes` | Set speaker notes | `index`, `notes` |
| `apply_text_formatting` | Apply text formatting | `index`, `placeholder`, `bold`, `italic`, `font_size`, `font_color` |
| `add_hyperlink` | Add clickable URL to text | `index`, `placeholder`, `url`, `paragraph_index`, `run_index` |
| `format_table_cell` | Format table cell styling | `index`, `table_idx`, `row`, `column`, `bg_color`, `font_color`, `bold` |

**add_hyperlink operation:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | Must be "add_hyperlink" |
| `index` | integer | Yes | Slide index (0-based) |
| `placeholder` | string | No | Placeholder: title, body, left, right. Default: "body" |
| `url` | string | Yes | The URL to link to |
| `paragraph_index` | integer | No | Paragraph index to add link to |
| `run_index` | integer | No | Run index within paragraph |

**format_table_cell operation:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `type` | string | Yes | Must be "format_table_cell" |
| `index` | integer | Yes | Slide index (0-based) |
| `table_idx` | integer | Yes | Table index on the slide (0-based) |
| `row` | integer | Yes | Row index (0-based) |
| `column` | integer | Yes | Column index (0-based) |
| `bold` | boolean | No | Make text bold |
| `italic` | boolean | No | Make text italic |
| `underline` | boolean | No | Underline text |
| `font_size` | number | No | Font size in points |
| `font_color` | string | No | Font color as hex (e.g., "FF0000") |
| `bg_color` | string | No | Background color as hex (e.g., "FFFF00") |

---

### 5. `add_image`

Add an image to a slide at the specified position.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | Yes | Path to the .pptx file |
| `image_path` | string | Yes | Path to the image file |
| `slide_index` | integer | Yes | Slide index |
| `x` | number | No | X position in inches. Default: 1.0 |
| `y` | number | No | Y position in inches. Default: 1.5 |
| `width` | number | No | Image width in inches |
| `height` | number | No | Image height in inches |

---

### 6. `modify_image`

Modify an existing image in a slide (rotate, flip, brightness, contrast, crop).

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | Yes | Path to the .pptx file |
| `slide_index` | integer | Yes | Slide index |
| `image_index` | integer | Yes | Image index on the slide |
| `operation` | string | Yes | Operation type: rotate, flip, brightness, contrast, crop |
| `rotation` | integer | No | Rotation degrees (0-360). Required for rotate operation |
| `flip` | string | No | Flip direction: horizontal, vertical. Required for flip operation |
| `brightness` | number | No | Brightness factor (positive number, 1.0=unchanged). Required for brightness operation |
| `contrast` | number | No | Contrast factor (positive number, 1.0=unchanged). Required for contrast operation |
| `crop_left` | integer | No | Left crop boundary in pixels. Required for crop operation |
| `crop_top` | integer | No | Top crop boundary in pixels. Required for crop operation |
| `crop_right` | integer | No | Right crop boundary in pixels. Required for crop operation |
| `crop_bottom` | integer | No | Bottom crop boundary in pixels. Required for crop operation |

---

### 7. `insert_chart`

Insert a chart into a slide from spreadsheet data.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `presentation_path` | string | Yes | Path to the .pptx file |
| `slide_index` | integer | Yes | Slide index |
| `spreadsheet_path` | string | Yes | Path to source spreadsheet |
| `sheet_name` | string | Yes | Source sheet name |
| `data_range` | string | Yes | Data range (e.g., "A1:D10") |
| `chart_type` | string | No | Chart type: bar, line, pie, area, scatter, doughnut, radar. Default: "bar" |
| `title` | string | No | Chart title |
| `position` | string | No | Position on slide. Default: "body" |
| `include_header` | boolean | No | Include header row. Default: true |

---

### 8. `insert_table`

Insert a table into a slide.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | Yes | Path to the .pptx file |
| `slide_index` | integer | Yes | Slide index |
| `rows` | array[array] | Yes | Table data as 2D array |
| `header` | boolean | No | First row is header. Default: true |
| `x` | number | No | X position in inches. Default: 0.5 |
| `y` | number | No | Y position in inches. Default: 1.5 |
| `width` | number | No | Table width in inches. Default: 9.0 |
| `height` | number | No | Table height in inches. Default: 5.0 |

---

### 9. `add_shape`

Add a shape to a slide with optional fill, line, and text styling.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | Yes | Path to the .pptx file |
| `slide_index` | integer | Yes | Slide index |
| `shape_type` | string | Yes | Shape type (see below) |
| `x` | number | No | X position in inches. Default: 1.0 |
| `y` | number | No | Y position in inches. Default: 1.0 |
| `width` | number | No | Shape width in inches. Default: 2.0 |
| `height` | number | No | Shape height in inches. Default: 2.0 |
| `fill_color` | string | No | Fill color as hex (e.g., "FF0000") |
| `line_color` | string | No | Line color as hex (e.g., "000000") |
| `line_width` | number | No | Line width in points |
| `text` | string | No | Text to add inside the shape |
| `text_color` | string | No | Text color as hex (e.g., "000000") |
| `font_size` | number | No | Font size in points |

**Available shape types:**
- `rectangle`, `rounded_rectangle`, `oval`, `triangle`
- `right_arrow`, `left_arrow`, `up_arrow`, `down_arrow`
- `pentagon`, `hexagon`, `star`, `heart`
- `lightning_bolt`, `cloud`

---

### 10. `read_slides`

Read a character range from a Presentations presentation's text content.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | Yes | Path to the .pptx file |
| `start` | integer | No | Start character index |
| `end` | integer | No | End character index |

---

### 11. `read_completedeck`

Read all slides from a presentation and return overview with indices.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | Yes | Path to the .pptx file |

---

### 12. `read_individualslide`

Read detailed information about a single slide including components and images.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | Yes | Path to the .pptx file |
| `slide_index` | integer | Yes | Slide index to read |

---

### 13. `read_image`

Retrieve a cached image extracted by read_slide using its annotation key.

**Parameters:**
| Name | Type | Required | Description |
|------|------|----------|-------------|
| `file_path` | string | Yes | Path to the presentation file |
| `annotation` | string | Yes | Image annotation key |

---

## Consolidated Tools

When using consolidated mode, these meta-tools combine multiple operations:

### 1. `slides_schema`

Get JSON schemas for slides tool input/output models.

**Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| `schema_name` | string? | null | Name of specific schema to retrieve. If not provided, returns all schema names. |

---

### 2. `slides`

Unified interface for all Presentations presentation operations.

**Parameters:**
| Name | Type | Default | Description |
|------|------|---------|-------------|
| `action` | enum['create', 'delete', 'add_slide', 'edit', 'add_image', 'modify_image', 'insert_chart', 'insert_table', 'add_shape', 'read_range', 'read_deck', 'read_slide', 'read_image'] | Ellipsis | The action to perform |
| `file_path` | string? | null | Path to the .pptx file (required for most actions) |
| `directory` | string? | null | Directory path. REQUIRED for list/create operations. |
| `file_name` | string? | null | Filename with extension. REQUIRED for create/save. |
| `slides` | array[object[string, Any]]? | null | Slide definitions for create |
| `metadata` | object[string, Any]? | null | Presentation metadata (title, subject, author, comments) |
| `input_data` | object[string, Any]? | null | Input data for add_slide action |
| `operations` | array[object[string, Any]]? | null | Edit operations to apply |
| `image_path` | string? | null | Path to image file |
| `slide_index` | integer? | null | Slide index (0-based) |
| `x` | number? | null | X position in inches |
| `y` | number? | null | Y position in inches |
| `width` | number? | null | Width in pixels. Optional for export. |
| `height` | number? | null | Height in pixels. Optional for export. |
| `image_index` | integer? | null | Image index on slide (0-based) |
| `operation` | string? | null | Operation: rotate, flip, brightness, contrast, crop |
| `rotation` | integer? | null | Rotation angle (0-360) |
| `flip` | string? | null | Flip direction: horizontal, vertical |
| `brightness` | number? | null | Brightness factor (0.0-2.0). 1.0=unchanged. |
| `contrast` | number? | null | Contrast factor (0.0-2.0). 1.0=unchanged. |
| `crop_left` | integer? | null | Left crop boundary in pixels |
| `crop_top` | integer? | null | Top crop boundary in pixels |
| `crop_right` | integer? | null | Right crop boundary in pixels |
| `crop_bottom` | integer? | null | Bottom crop boundary in pixels |
| `spreadsheet_path` | string? | null | Path to source spreadsheet |
| `sheet_name` | string? | null | Sheet name in spreadsheet |
| `data_range` | string? | null | Cell range (e.g., 'A1:D5') |
| `chart_type` | string? | null | Chart type filter. Optional. |
| `title` | string? | null | Title for the entity. REQUIRED for create. |
| `position` | string? | null | Position: body, left, right |
| `include_header` | boolean? | null | Whether first row is header |
| `rows` | array[array[Any]]? | null | Table rows data |
| `header` | boolean? | null | Bold first row as header |
| `start` | integer? | null | Start character position |
| `end` | integer? | null | End character position |
| `annotation` | string? | null | Image annotation key from cache |
| `shape_type` | string? | null | Shape type for add_shape action |
| `fill_color` | string? | null | Fill color as hex (e.g., "FF0000") |
| `line_color` | string? | null | Line color as hex (e.g., "000000") |
| `line_width` | number? | null | Line width in points |
| `text` | string? | null | Text to add inside the shape |
| `text_color` | string? | null | Text color as hex (e.g., "000000") |
| `font_size` | number? | null | Font size in points |

---