# MCP Servers

Four servers in `.mcp.json` (optionally six with Chrome MCP + hosting, DO NOT commit):

| Server | Purpose | Command |
|--------|---------|---------|
| **fluent-mcp** | Official Fluent CLI MCP (workflows, GraphQL) | `fluent mcp server --stdio` |
| **fluent-mcp-extn** | Extension server (45 tools: events, batch, metrics, entities, workflows, settings, schema, cache) | `node .../fluent-mcp-extn/dist/index.js` |
| **chrome-devtools** | Browser automation for UI testing | `npx -y chrome-devtools-mcp@latest` |
| **chrome-manual** | Chrome MCP Extension for manual debugging (optional, opt-in) | `npx -y mcp-chrome-bridge http://127.0.0.1:12306/mcp` |
| **bitbucket** | Bitbucket code repository access | `npx -y @nexus2520/bitbucket-mcp-server` |
| **vercel** (optional) | Hosting/deployment for frontend assets (S3, Netlify, etc. also work) | `https://mcp.vercel.com` (remote HTTP + OAuth) |

First three auto-configured by `fluent-ai-skills install --profile <PROFILE>`. Chrome MCP Extension added with `--with-chrome` flag (requires Chrome extension from https://github.com/hangwin/mcp-chrome). Bitbucket requires manual configuration. Hosting MCP (Vercel/S3/etc.) is optional — see [Optional Hosting MCP Servers](#optional-hosting-mcp-servers) below. Auth: `FLUENT_PROFILE` (recommended) → OAuth → Token Command → Static Token. Never put secrets in `.mcp.json` — use environment variables. `FLUENT_UI_BASE_URL` points to target Fluent UX app; set via `--browser-url` or `--no-browser` to skip.

## Click Telemetry (Visual Click Highlights)

Chrome DevTools MCP clicks are programmatic — no visible cursor appears. Click Telemetry injects JavaScript highlights (pulsing red border + label badge) around elements before interactions. This makes screenshots and screencast recordings self-documenting. Implemented in `/fluent-ui-test` (Phase 4) and `/fluent-ui-record` (full protocol). See `chrome-devtools-mcp-reference.md` (in `@fluentcommerce/ai-skills` docs) for full browser MCP reference.

**Token optimization:** Both skills inject a `__fcTest` helper library once per session (see `BROWSER_OPTIMIZATIONS.md` in the `fluent-ui-test` skill). This replaces `take_snapshot` (~30K tokens) with `pageSummary()` (~500 tokens) for page verification, `scanComponents()` (~400 tokens) for custom component detection, and one-line `highlight()`/`annotate()` calls (~100 tokens each) instead of inline 40-line JS blocks. ~90% token reduction per test session. Component compatibility matrix covers OOTB Mystique components AND custom SDK components.

## Setting & Manifest Fetch — Tool Routing

Choose the right tool based on payload size and purpose:

| Need | Tool | Why |
|------|------|-----|
| **Download manifest/large setting** | MCP `setting.get` + `outputFile` | Writes 10-120KB to disk, returns ~200 bytes metadata. Saves 30-100K tokens per call. |
| **Existence check (does setting exist?)** | MCP `setting.get` (no outputFile) | Returns metadata inline. Do NOT request `lobValue` in GraphQL fallback. |
| **Bulk discovery (all manifests)** | MCP `setting.get` with `name: "fc.mystique.manifest.%"` + `outputFile` (directory) | One call discovers all, saves each to file. |
| **GraphQL with large response** | Official CLI MCP `graphql_execute` (no response budget) | Fallback when `setting.get` unavailable. |
| **Small GraphQL queries** | MCP extension `graphql_query` | Fine for queries under 50K chars response. |
| **Workflow download** | CLI `fluent workflow download` or MCP `workflow.get` with `outputFile` | Keeps 50K+ workflow JSON out of context. |

**NEVER use MCP extension `graphql_query` for manifest settings** — the 50K `FLUENT_RESPONSE_BUDGET_CHARS` silently truncates them. Use `setting.get` + `outputFile` (preferred) or official CLI MCP `graphql_execute` (fallback).

## Setting & Manifest Write — Tool Routing

Choose the right tool for **writing** settings based on payload size:

| Need | Tool | Why |
|------|------|-----|
| **Deploy large setting (>4KB)** | CLI `fluent module install --include settings --force` | Reads JSON from local file — zero LLM context cost. Recommended for manifest fragments (10-120KB). Package in `assets/settings/manifests.json` as JSON array. |
| **Deploy multiple settings at once** | CLI `fluent module install --include settings --force` | One command, all settings in one `manifests.json` array. Atomic deploy. |
| **Quick update small setting (<4KB)** | MCP `setting.upsert` | Inline in tool params. Fine for root manifests, feature flags, small configs. Always set `valueType: "JSON"` for manifests. |
| **CI/CD pipeline deploy** | CLI `fluent module install --include settings` | Versioned, supports `[[token]]` config placeholders, audit trail. |
| **GraphQL fallback** | `updateSetting` mutation via CLI MCP `graphql_execute` | When CLI module install unavailable. No response budget limit. |

**NEVER use MCP `setting.upsert` for large settings (manifests >4KB)** — stuffing 10-120KB into a tool parameter wastes LLM context tokens. Use CLI `fluent module install` which reads from disk.

**CLI deploy pattern for settings:**
```bash
DEPLOY=$(mktemp -d)
mkdir -p "$DEPLOY/assets/settings"
# manifests.json = JSON array of setting objects
cat > "$DEPLOY/assets/settings/manifests.json" << 'SETTINGS'
[{ "name": "fc.mystique.manifest.oms.fragment.ordermanagement",
   "valueType": "JSON", "context": "ACCOUNT", "contextId": 0,
   "lobValue": <content-from-local-file> }]
SETTINGS
echo '{"_schema":"1.0.0","name":"settings-deploy","version":"1.0.0"}' > "$DEPLOY/module.json"
echo '{}' > "$DEPLOY/module.config.json"
fluent module install "$DEPLOY" -p <PROFILE> -r <RETAILER> --include settings --force
rm -rf "$DEPLOY"
```

## Optional Hosting MCP Servers

An optional hosting MCP server can deploy frontend assets (Mystique SDK bundles, static files) to CDN/hosting platforms. **Not required** for core Fluent Commerce work — only needed when you host custom frontend components.

| Provider | MCP URL / Package | Auth |
|----------|-------------------|------|
| **Vercel** | `https://mcp.vercel.com` (remote HTTP) | OAuth (browser) |
| **AWS S3** | Community MCP servers (e.g., `mcp-server-s3`) | AWS credentials |
| **Netlify** | Community MCP servers | API token |
| **Cloudflare** | Community MCP servers | API token |

### Vercel Setup

Add to `.mcp.json`:
```json
{ "mcpServers": { "vercel": { "type": "http", "url": "https://mcp.vercel.com" } } }
```

For project-specific access: `"url": "https://mcp.vercel.com/<teamSlug>/<projectSlug>"`. Authenticate via `/mcp` in Claude Code (opens browser OAuth). Find slugs: Vercel Dashboard or `vercel projects ls`.

### S3 Setup

```json
{ "mcpServers": { "s3": { "type": "stdio", "command": "npx", "args": ["-y", "mcp-server-s3"],
  "env": { "AWS_ACCESS_KEY_ID": "<from env>", "AWS_SECRET_ACCESS_KEY": "<from env>", "AWS_REGION": "ap-southeast-2", "S3_BUCKET": "your-bucket-name" } } } }
```

**Notes:** Hosting MCP is optional and gitignored. Each developer configures their own provider. The installer does NOT auto-configure hosting MCPs. Never put secrets in `.mcp.json`.
