mcp

# `@shipeasy/mcp` — unified Model Context Protocol server

> Replaces [packages/mcp-server/](../mcp-server/). One MCP server, one npm package, covers **both** subsystems:
>
> 1. **Experimentation** — gates, configs, experiments, metrics, events (from [experiment-platform/10-mcp-server.md](../../experiment-platform/10-mcp-server.md)).
> 2. **String manager / i18n** — label profiles, keys, drafts, translations, publish, codemods (from [string-manager-platform/plan.md](../../string-manager-platform/plan.md) § MCP server).
>
> AI assistants (Claude Code, Cursor, Copilot, Windsurf, Claude Desktop, Continue) talk to one server and get the full platform.

📖 **Docs:** [docs.shipeasy.ai/get-started/mcp](https://docs.shipeasy.ai/get-started/mcp) — setup guide · [full tool reference](https://docs.shipeasy.ai/get-started/mcp-reference) (auto-generated from the tool catalog).

---

## Status / migration

- **New location:** `packages/mcp/` (this doc).
- **Old location:** `packages/mcp-server/` — will be deleted once this ships. The npm package rename (`@shipeasy/mcp-server` → `@shipeasy/mcp`) is a **breaking change**; the old name publishes one final version that re-exports the new package as a deprecation shim.
- **Binary rename:** `shipeasy-mcp` (unchanged — the old binary name is preserved so existing `.claude/settings.json` entries keep working).

---

## Install / run

Two steps: **(1)** register the server with your AI assistant, **(2)** authenticate once with `shipeasy-mcp install`. Step 2 is required before any mutating tool will work — it runs a browser-based PKCE device flow against `/auth/device/*` and writes the token to `~/.config/shipeasy/config.json` (shared with `@shipeasy/cli`).

### Step 1 — register

**npx (recommended for AI assistant configs)**

```json
// ~/.claude/settings.json  |  .cursor/mcp.json  |  .windsurf/mcp.json  |  .mcp.json (project-local)
{
  "mcpServers": {
    "shipeasy": {
      "command": "npx",
      "args": ["-y", "@shipeasy/mcp@latest"]
    }
  }
}
```

**Global install**

```bash
npm i -g @shipeasy/mcp
# or
pnpm add -g @shipeasy/mcp
```

```json
{ "mcpServers": { "shipeasy": { "command": "shipeasy-mcp" } } }
```

**Through the CLI** (if `@shipeasy/cli` is already installed)

```bash
shipeasy mcp install     # auto-writes ~/.claude/settings.json + .cursor/mcp.json
shipeasy mcp start       # run stdio server (same binary, different entry)
```

### Step 2 — authenticate

Run this once per machine:

```bash
shipeasy-mcp install
```

What happens:

1. The CLI generates a PKCE verifier + challenge.
2. It calls `POST {api_base}/auth/device/start` to open a session; the worker returns a `state`.
3. Your default browser opens at `{app_base}/cli-auth?state=…&code_challenge=…&source=mcp`. Sign in with your existing Shipeasy account (GitHub, Google, or magic link — same as the dashboard).
4. The UI page calls `POST {api_base}/auth/device/complete` with `project_id` + PKCE verifier.
5. The CLI polls `GET {api_base}/auth/device/poll?state=…` (header `X-Code-Verifier`) every ~2 s until it receives `{ token, project_id }`.
6. Token is written to `~/.config/shipeasy/config.json` with `chmod 600`. The directory is created `chmod 700`.

Flags:

| Flag             | Effect                                                                                    |
| ---------------- | ----------------------------------------------------------------------------------------- |
| `--force`        | Overwrite an existing session instead of aborting.                                        |
| `--no-browser`   | Print the auth URL; useful on remote / headless machines (paste it into a local browser). |

Other subcommands:

```bash
shipeasy-mcp whoami      # prints { project_id, user_email, config_path }
shipeasy-mcp logout      # deletes ~/.config/shipeasy/config.json
shipeasy-mcp --help      # usage
shipeasy-mcp --version
```

### Why is this a CLI subcommand instead of an MCP tool?

The MCP stdio transport runs inside the AI assistant — it can't block for a browser round-trip, spawn new windows, or receive a browser-delivered callback. Browser-based auth has to run in a terminal the user owns. Once the token is written, **every** MCP server instance on the machine (Claude Code, Cursor, Windsurf, MCP Inspector, etc.) reads the same `~/.config/shipeasy/config.json` — one install, many clients.

The in-process `auth_login` MCP tool therefore always returns a pointer back to the CLI command rather than trying to launch a browser itself.

### Manual stdio invocation (for testing)

```bash
npx -y @shipeasy/mcp
# or pipe it through MCP Inspector:
npx @modelcontextprotocol/inspector npx -y @shipeasy/mcp
```

---

## Protocol surface

Transport: **stdio** (JSON-RPC 2.0 framed by Content-Length headers per MCP spec).
Capabilities advertised on initialize:

```json
{
  "tools": { "listChanged": true },
  "prompts": { "listChanged": false },
  "resources": { "subscribe": true, "listChanged": true },
  "logging": {}
}
```

- **Tools** — actions the assistant can invoke (the full catalog below).
- **Prompts** — named, parameterized workflow playbooks (see _Prompts_ section).
- **Resources** — read-only views of project state the assistant can pull in as context (see _Resources_ section).
- **Logging** — structured progress and error notifications via `notifications/message`.

---

## Authentication

Every mutating tool requires a Shipeasy session. Credentials live in `~/.config/shipeasy/config.json` and are shared between `@shipeasy/mcp` and `@shipeasy/cli` — whichever tool the user authenticates in first, both pick up the same session.

1. `shipeasy-mcp install` (terminal) completes the PKCE device flow and writes the config file (see _Step 2 — authenticate_ above).
2. The MCP stdio server's `auth_check` tool reads the file on every call — no cached state in the server process.
3. `auth_login` invoked over MCP always returns an actionable error asking the human to run `shipeasy-mcp install` in a terminal (stdio can't open a browser safely).
4. `auth_logout` removes the file; the CLI equivalent works too.

```
~/.config/shipeasy/config.json          (mode 0600, parent dir 0700)
  {
    "project_id":   "proj_…",
    "cli_token":    "sdk_admin_…",      ← scoped to admin Route Handlers; 90-day rotation
    "api_base_url": "https://api.shipeasy.ai",
    "app_base_url": "https://shipeasy.ai",
    "user_email":   "you@example.com",
    "created_at":   "2026-04-16T…Z"
  }
```

Tool-level auth policy:

| Category                                        | Requires session | Notes                                                  |
| ----------------------------------------------- | ---------------- | ------------------------------------------------------ |
| `detect_*`                                      | No               | Pure filesystem inspection, no network.                |
| `auth_*`                                        | — / triggers it  |                                                        |
| `list_*`, `get_*`                               | Yes              | Read-only GETs against `apps/ui` admin Route Handlers. |
| `create_*`, `update_*`, `delete_*`, `publish_*` | Yes              | Mutations — the CLI enforces `checkLimit` server-side. |
| `i18n_scan_code`, `i18n_codemod_*`              | No               | Local-only AST tools.                                  |

---

## Tool catalog

Tools are namespaced by subsystem: `exp_*` (experimentation), `i18n_*` (string manager), unprefixed (shared: auth, project detection, resource listing, SDK snippets).

### Shared tools

#### `detect_project`

Inspects the working directory and returns the language, framework, package manager, installed shipeasy packages, and i18n presence signals.

**Input** (all optional):

```json
{ "path": "string (defaults to cwd; sandboxed via realpath to refuse escapes)" }
```

**Output**:

```json
{
  "language":       "typescript | javascript | python | ruby | go | java | php | swift | kotlin | unknown",
  "frameworks":     ["nextjs","react","tailwind", ...],
  "package_manager":"npm | pnpm | yarn | bun | pip | poetry | bundler | go | maven | gradle | composer | swiftpm",
  "entry_points":   ["src/app/layout.tsx", "src/main.tsx"],
  "test_files":     ["src/app/page.test.tsx"],

  "shipeasy": {
    "experimentation_sdk": { "installed": true, "version": "^1.3.0", "configured": true, "subentry": "shipeasy/react" },
    "i18n_sdk":            { "installed": true, "version": "^1.1.0", "configured": true, "profile": "en:prod" },
    "loader_script_tag":   { "present": true, "data_key": "sdk_client_…", "data_profile": "en:prod" },
    "env_keys_detected":   ["SHIPEASY_SERVER_KEY","NEXT_PUBLIC_SHIPEASY_CLIENT_KEY"],
    "template_warning":    "Installed SDK version 0.9.x is incompatible with MCP templates >=1.0.0."
  }
}
```

**Security**: `realpath` sandbox (see [10-mcp-server.md § detect_project](../../experiment-platform/10-mcp-server.md)). All reads go through `safeRead()` which refuses symlinks pointing outside the requested root.

---

#### `auth_check`

```json
// input
{}

// output
{ "authenticated": true, "project_id": "…", "base_url": "…", "user_email": "…" }
```

#### `auth_login`

Spawns `shipeasy login`, which opens the browser and blocks until the device-auth flow completes. Uses `spawn` (not `execSync`) so the MCP event loop stays responsive. The AI assistant should surface a "waiting for browser…" message — the CLI session polls for up to 5 minutes.

```json
// input
{}
// output — same shape as auth_check after success
```

#### `auth_logout`

Deletes `~/.config/shipeasy/config.json`. No network call.

---

#### `list_resources`

Unified listing across both subsystems.

```json
// input
{
  "kind": "gates|configs|experiments|events|metrics|universes|attributes|profiles|chunks|keys|drafts|sdk_keys|all",
  "limit": 50,
  "search": "checkout" // optional name filter
}
```

Hits the matching `apps/ui` admin Route Handler (e.g. `/api/ad