@flomenco/claude-plugin-mcp 0.1.0

package/README.md

@@ -0,0 +1,175 @@
+# Flo Claude Plugin MCP Bridge
+
+MCP server that connects Claude to the deployed `interface-agent` runtime for the
+Flo Claude plugin happy path.
+
+It exposes authentication + plugin tools:
+
+- `flo_auth_login`
+- `flo_auth_status`
+- `flo_auth_setup_help`
+- `flo_auth_logout`
+
+- `flo_search`
+- `flo_skill_routing`
+- `flo_qc_logo`
+- `flo_command` (raw passthrough for troubleshooting)
+- `flo_plugin_healthcheck`
+- `flo_happy_path_run`
+
+## Prerequisites
+
+- Node `>=22.13`
+- `pnpm` installed
+- Deployed `interface-agent` invocation URL
+- OAuth client configured for your auth provider (recommended), or static JWT fallback
+
+## Install dependencies
+
+From repo root:
+
+```bash
+pnpm install
+```
+
+## One-command Claude Desktop install
+
+For repo contributors (local checkout):
+
+```bash
+cd /Users/ryan/Dev/github/flo
+# Optional: pick AWS profile used for auto-discovery
+export AWS_PROFILE=469128505698_FlomencoSuperAdmin
+pnpm --filter @flo/claude-plugin-mcp run install:claude-desktop
+```
+
+Uninstall:
+
+```bash
+pnpm --filter @flo/claude-plugin-mcp run uninstall:claude-desktop
+```
+
+## External-user manual install (no repo clone)
+
+After this package is published, users can install via Claude config using `npx`:
+
+```json
+{
+  "mcpServers": {
+    "flo-plugin": {
+      "command": "npx",
+      "args": ["-y", "@flo/claude-plugin-mcp"],
+      "env": {
+        "FLO_INTERFACE_AGENT_INVOCATION_URL": "https://<runtime-host>/invocations",
+        "FLO_OAUTH_AUTHORIZE_URL": "https://<auth-host>/oauth2/authorize",
+        "FLO_OAUTH_TOKEN_URL": "https://<auth-host>/oauth2/token",
+        "FLO_OAUTH_CLIENT_ID": "<public-client-id>",
+        "FLO_OAUTH_REDIRECT_URI": "http://127.0.0.1:8787/callback",
+        "FLO_OAUTH_SCOPES": "openid email profile"
+      }
+    }
+  }
+}
+```
+
+## Environment variables
+
+- `FLO_INTERFACE_AGENT_INVOCATION_URL` (preferred): full invocation endpoint (`.../invocations`)
+- `FLO_INTERFACE_AGENT_URL` (fallback): runtime URL without `/invocations`
+- `FLO_AUTH_TOKEN` (optional fallback): static bearer token for each tool call
+- `FLO_PLUGIN_ENV` (optional): `dev` (default), `stg`, or `prod` for default DNS host selection
+- Default runtime URL if unset:
+  - `dev` -> `https://plugin.dev.floapp.co/invocations`
+  - `stg` -> `https://plugin.stg.floapp.co/invocations`
+  - `prod` -> `https://plugin.floapp.co/invocations`
+
+OAuth (PKCE login) variables:
+
+- `FLO_OAUTH_AUTHORIZE_URL` (required for OAuth)
+- `FLO_OAUTH_TOKEN_URL` (required for OAuth)
+- `FLO_OAUTH_CLIENT_ID` (required for OAuth)
+- `FLO_OAUTH_REDIRECT_URI` (optional, default `http://127.0.0.1:8787/callback`)
+- `FLO_OAUTH_SCOPES` (optional, default `openid email profile`)
+- `FLO_OAUTH_AUDIENCE` (optional)
+- `FLO_OAUTH_TOKEN_CACHE_PATH` (optional local cache path)
+- `FLO_OAUTH_SETTINGS_URL` (optional explicit Flo settings URL)
+
+## Runtime URL and OAuth FAQ
+
+- **Should runtime URL have a DNS short name?**
+  - Yes. This package uses env-specific DNS defaults (`plugin.dev`, `plugin.stg`, `plugin` for prod) and supports overriding via `FLO_INTERFACE_AGENT_INVOCATION_URL`.
+- **Where do users get `FLO_OAUTH_CLIENT_ID`?**
+  - From Flo-distributed install config. For operators, the install script can auto-discover it from Cognito app clients (`flo-dev-claude-plugin`, fallback `flo-dev-spa`) when AWS creds are available.
+- **How can operators generate a shareable config blob?**
+  - Run:
+  - `pnpm --filter @flo/claude-plugin-mcp run print:bootstrap-config`
+- **Why is redirect local (`127.0.0.1`)?**
+  - This is the standard installed-app OAuth pattern (loopback redirect). Browser returns auth code to a short-lived local listener that exchanges it securely (PKCE).
+
+## Claude Desktop config
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "flo-plugin": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/flo/packages/flo-claude-plugin-mcp/src/index.js"],
+      "env": {
+        "FLO_INTERFACE_AGENT_INVOCATION_URL": "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn%3Aaws%3Abedrock-agentcore%3Aus-east-1%3A469128505698%3Aruntime%2Fflo_dev_interface_agent_agent_runtime-vx0ANeHC4Z/invocations",
+        "FLO_OAUTH_AUTHORIZE_URL": "https://flomenco-dev.auth.us-east-1.amazoncognito.com/oauth2/authorize",
+        "FLO_OAUTH_TOKEN_URL": "https://flomenco-dev.auth.us-east-1.amazoncognito.com/oauth2/token",
+        "FLO_OAUTH_CLIENT_ID": "PASTE_SPA_CLIENT_ID_HERE",
+        "FLO_OAUTH_REDIRECT_URI": "http://127.0.0.1:8787/callback",
+        "FLO_OAUTH_SCOPES": "openid email profile"
+      }
+    }
+  }
+}
+```
+
+## Claude Code config
+
+Add to `~/.claude/settings.json` (or workspace `.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "flo-plugin": {
+      "command": "node",
+      "args": ["/ABSOLUTE/PATH/TO/flo/packages/flo-claude-plugin-mcp/src/index.js"],
+      "env": {
+        "FLO_INTERFACE_AGENT_INVOCATION_URL": "https://bedrock-agentcore.us-east-1.amazonaws.com/runtimes/arn%3Aaws%3Abedrock-agentcore%3Aus-east-1%3A469128505698%3Aruntime%2Fflo_dev_interface_agent_agent_runtime-vx0ANeHC4Z/invocations",
+        "FLO_OAUTH_AUTHORIZE_URL": "https://flomenco-dev.auth.us-east-1.amazoncognito.com/oauth2/authorize",
+        "FLO_OAUTH_TOKEN_URL": "https://flomenco-dev.auth.us-east-1.amazoncognito.com/oauth2/token",
+        "FLO_OAUTH_CLIENT_ID": "PASTE_SPA_CLIENT_ID_HERE",
+        "FLO_OAUTH_REDIRECT_URI": "http://127.0.0.1:8787/callback",
+        "FLO_OAUTH_SCOPES": "openid email profile"
+      }
+    }
+  }
+}
+```
+
+## Quick validation
+
+After Claude starts with MCP enabled:
+
+- Run `flo_auth_login` once and complete browser sign-in
+- Check `flo_auth_status` (expect `cachedTokenUsable: true`)
+- Run `flo_auth_setup_help` if you need the Flo settings URL for locating `FLO_OAUTH_CLIENT_ID`
+- Run `flo_plugin_healthcheck` (expect `runtime.reachable: true`)
+- Run `flo_search` with `query="hail mary"`
+- `flo_skill_routing` with an `assetId` from search
+- `flo_qc_logo` with `assetId` and `referenceAssetId`
+
+One-shot E2E:
+
+- `flo_happy_path_run` with `referenceAssetId="<logo_asset_id>"`
+
+Expected output shape:
+
+- search: `status`, `menuItems[]`
+- skill-routing: `status`, `skills[]`, includes `/flo:qc-logo`
+- qc-logo: `status`, `result.overall|summary|assetId|assetUrl|findings`

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@flomenco/claude-plugin-mcp",
+  "version": "0.1.0",
+  "description": "Flo Claude Co-Work plugin bridge for Claude Desktop/Code",
+  "private": false,
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Flomenco-Inc/flo.git",
+    "directory": "packages/flo-claude-plugin-mcp"
+  },
+  "homepage": "https://github.com/Flomenco-Inc/flo",
+  "bugs": {
+    "url": "https://github.com/Flomenco-Inc/flo/issues"
+  },
+  "keywords": [
+    "claude",
+    "mcp",
+    "plugin",
+    "flo"
+  ],
+  "type": "module",
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "bin": {
+    "flo-claude-plugin-mcp": "./src/index.js"
+  },
+  "scripts": {
+    "start": "node ./src/index.js",
+    "install:claude-desktop": "node ./tools/install-claude-desktop.js",
+    "uninstall:claude-desktop": "node ./tools/uninstall-claude-desktop.js",
+    "print:bootstrap-config": "node ./tools/print-bootstrap-config.js"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.17.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.13"
+  }
+}

package/src/index.js

@@ -0,0 +1,982 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  McpError,
+  ErrorCode,
+} from "@modelcontextprotocol/sdk/types.js";
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { spawn } from "node:child_process";
+
+const DEFAULT_TIMEOUT_MS = 60_000;
+const OAUTH_WAIT_TIMEOUT_MS = 180_000;
+const TOKEN_REFRESH_SKEW_SECONDS = 60;
+const DEFAULT_TOKEN_CACHE_PATH = path.join(
+  os.homedir(),
+  ".flo",
+  "claude-plugin-mcp-token.json"
+);
+
+function normalizedPluginEnv() {
+  const raw = (process.env.FLO_PLUGIN_ENV || "dev").trim().toLowerCase();
+  if (raw === "prod" || raw === "production") {
+    return "prod";
+  }
+  if (raw === "stg" || raw === "stage" || raw === "staging") {
+    return "stg";
+  }
+  return "dev";
+}
+
+function defaultInvocationUrlForEnv() {
+  const env = normalizedPluginEnv();
+  if (env === "prod") {
+    return "https://plugin.floapp.co/invocations";
+  }
+  if (env === "stg") {
+    return "https://plugin.stg.floapp.co/invocations";
+  }
+  return "https://plugin.dev.floapp.co/invocations";
+}
+
+function defaultUserPoolNameForEnv() {
+  const env = normalizedPluginEnv();
+  if (env === "prod") {
+    return "flo-prod";
+  }
+  if (env === "stg") {
+    return "flo-stg";
+  }
+  return "flo-dev";
+}
+
+function defaultExpectedClientNameForEnv() {
+  const env = normalizedPluginEnv();
+  if (env === "prod") {
+    return "flo-prod-claude-plugin";
+  }
+  if (env === "stg") {
+    return "flo-stg-claude-plugin";
+  }
+  return "flo-dev-claude-plugin";
+}
+
+function defaultSettingsUrlForEnv() {
+  const env = normalizedPluginEnv();
+  if (env === "prod") {
+    return "https://floapp.co/settings/api";
+  }
+  if (env === "stg") {
+    return "https://stg.floapp.co/settings/api";
+  }
+  return "https://dev.floapp.co/settings/api";
+}
+
+function getInvocationUrl() {
+  const raw =
+    process.env.FLO_INTERFACE_AGENT_INVOCATION_URL ||
+    process.env.FLO_INTERFACE_AGENT_URL ||
+    defaultInvocationUrlForEnv();
+  if (!raw) {
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      "Missing FLO_INTERFACE_AGENT_INVOCATION_URL (or FLO_INTERFACE_AGENT_URL)."
+    );
+  }
+  const trimmed = raw.trim().replace(/\/+$/, "");
+  return trimmed.endsWith("/invocations") ? trimmed : `${trimmed}/invocations`;
+}
+
+function getDefaultAuthToken() {
+  return (process.env.FLO_AUTH_TOKEN || "").trim();
+}
+
+function getOAuthConfig(strict = false) {
+  const authorizeUrl = (process.env.FLO_OAUTH_AUTHORIZE_URL || "").trim();
+  const tokenUrl = (process.env.FLO_OAUTH_TOKEN_URL || "").trim();
+  const clientId = (process.env.FLO_OAUTH_CLIENT_ID || "").trim();
+  const scope = (process.env.FLO_OAUTH_SCOPES || "openid email profile").trim();
+  const redirectUri = (
+    process.env.FLO_OAUTH_REDIRECT_URI || "http://127.0.0.1:8787/callback"
+  ).trim();
+  const audience = (process.env.FLO_OAUTH_AUDIENCE || "").trim();
+  const region = (process.env.AWS_REGION || "us-east-1").trim();
+  const userPoolId = (process.env.FLO_OAUTH_USER_POOL_ID || "").trim();
+  const userPoolName = (
+    process.env.FLO_OAUTH_USER_POOL_NAME || defaultUserPoolNameForEnv()
+  ).trim();
+  const expectedClientName = (
+    process.env.FLO_OAUTH_EXPECTED_CLIENT_NAME || defaultExpectedClientNameForEnv()
+  ).trim();
+  const settingsUrl = (
+    process.env.FLO_OAUTH_SETTINGS_URL ||
+    process.env.FLO_OAUTH_CLIENT_ID_HELP_URL ||
+    defaultSettingsUrlForEnv()
+  ).trim();
+
+  const ready = Boolean(authorizeUrl && tokenUrl && clientId);
+  if (strict && !ready) {
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      "OAuth not configured. Set FLO_OAUTH_AUTHORIZE_URL, FLO_OAUTH_TOKEN_URL, and FLO_OAUTH_CLIENT_ID."
+    );
+  }
+
+  return {
+    ready,
+    authorizeUrl,
+    tokenUrl,
+    clientId,
+    scope,
+    redirectUri,
+    audience,
+    region,
+    userPoolId,
+    userPoolName,
+    expectedClientName,
+    settingsUrl,
+  };
+}
+
+function getTokenCachePath() {
+  return (process.env.FLO_OAUTH_TOKEN_CACHE_PATH || DEFAULT_TOKEN_CACHE_PATH).trim();
+}
+
+function base64Url(input) {
+  const buff = Buffer.isBuffer(input) ? input : Buffer.from(input, "utf8");
+  return buff
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/g, "");
+}
+
+async function readCachedToken() {
+  try {
+    const raw = await readFile(getTokenCachePath(), "utf8");
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== "object") {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+async function writeCachedToken(tokenPayload) {
+  const tokenPath = getTokenCachePath();
+  await mkdir(path.dirname(tokenPath), { recursive: true });
+  await writeFile(tokenPath, JSON.stringify(tokenPayload, null, 2), "utf8");
+}
+
+async function clearCachedToken() {
+  try {
+    await rm(getTokenCachePath(), { force: true });
+  } catch {
+    // Ignore cache-clear failures; callers receive success semantics.
+  }
+}
+
+function tokenIsUsable(tokenPayload) {
+  if (!tokenPayload || typeof tokenPayload.access_token !== "string") {
+    return false;
+  }
+  if (!tokenPayload.expires_at) {
+    return true;
+  }
+  const expiresAt = Number(tokenPayload.expires_at);
+  if (!Number.isFinite(expiresAt)) {
+    return false;
+  }
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  return expiresAt > nowSeconds + TOKEN_REFRESH_SKEW_SECONDS;
+}
+
+async function exchangeToken(params) {
+  const oauth = getOAuthConfig(true);
+  const body = new URLSearchParams(params);
+  const response = await fetch(oauth.tokenUrl, {
+    method: "POST",
+    headers: { "content-type": "application/x-www-form-urlencoded" },
+    body,
+    signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+  });
+  const json = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    throw new McpError(
+      ErrorCode.InternalError,
+      `OAuth token endpoint failed (${response.status}): ${JSON.stringify(json).slice(0, 500)}`
+    );
+  }
+  if (!json.access_token) {
+    throw new McpError(
+      ErrorCode.InternalError,
+      "OAuth token endpoint succeeded but no access_token was returned."
+    );
+  }
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const expiresIn = Number(json.expires_in || 3600);
+  return {
+    access_token: String(json.access_token),
+    refresh_token:
+      json.refresh_token !== undefined ? String(json.refresh_token) : undefined,
+    token_type: json.token_type ? String(json.token_type) : "Bearer",
+    scope: json.scope ? String(json.scope) : undefined,
+    expires_at: nowSeconds + Math.max(1, expiresIn),
+  };
+}
+
+async function refreshAccessTokenIfPossible(cachedToken) {
+  if (!cachedToken?.refresh_token) {
+    return null;
+  }
+  const oauth = getOAuthConfig(false);
+  if (!oauth.ready) {
+    return null;
+  }
+  try {
+    const refreshed = await exchangeToken({
+      grant_type: "refresh_token",
+      refresh_token: String(cachedToken.refresh_token),
+      client_id: oauth.clientId,
+    });
+    if (!refreshed.refresh_token) {
+      refreshed.refresh_token = String(cachedToken.refresh_token);
+    }
+    await writeCachedToken(refreshed);
+    return refreshed;
+  } catch {
+    return null;
+  }
+}
+
+function openBrowser(url) {
+  if (process.env.FLO_OAUTH_SKIP_BROWSER === "true") {
+    return false;
+  }
+  try {
+    if (process.platform === "darwin") {
+      const p = spawn("open", [url], { detached: true, stdio: "ignore" });
+      p.unref();
+      return true;
+    }
+    if (process.platform === "win32") {
+      const p = spawn("cmd", ["/c", "start", "", url], {
+        detached: true,
+        stdio: "ignore",
+      });
+      p.unref();
+      return true;
+    }
+    const p = spawn("xdg-open", [url], { detached: true, stdio: "ignore" });
+    p.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function waitForOAuthCode(redirectUri, expectedState) {
+  const parsed = new URL(redirectUri);
+  if (parsed.protocol !== "http:") {
+    throw new McpError(
+      ErrorCode.InvalidRequest,
+      `Unsupported FLO_OAUTH_REDIRECT_URI protocol: ${parsed.protocol}. Use http://127.0.0.1:<port>/callback`
+    );
+  }
+  const port = Number(parsed.port || "80");
+  const hostname = parsed.hostname;
+  const pathname = parsed.pathname || "/";
+
+  const server = createServer();
+  const code = await new Promise((resolve, reject) => {
+    const onRequest = (req, res) => {
+      try {
+        const reqUrl = new URL(req.url || "/", `http://${req.headers.host}`);
+        if (reqUrl.pathname !== pathname) {
+          res.statusCode = 404;
+          res.end("Not found");
+          return;
+        }
+
+        const oauthError = reqUrl.searchParams.get("error");
+        const returnedCode = reqUrl.searchParams.get("code");
+        const returnedState = reqUrl.searchParams.get("state");
+
+        if (oauthError) {
+          clearTimeout(timer);
+          res.statusCode = 400;
+          res.end("OAuth failed. You can close this window.");
+          reject(new Error(`OAuth provider returned error=${oauthError}`));
+          return;
+        }
+        if (!returnedCode) {
+          clearTimeout(timer);
+          res.statusCode = 400;
+          res.end("Missing code. You can close this window.");
+          reject(new Error("OAuth callback missing code"));
+          return;
+        }
+        if (returnedState !== expectedState) {
+          clearTimeout(timer);
+          res.statusCode = 400;
+          res.end("Invalid state. You can close this window.");
+          reject(new Error("OAuth state mismatch"));
+          return;
+        }
+
+        clearTimeout(timer);
+        res.statusCode = 200;
+        res.setHeader("content-type", "text/html; charset=utf-8");
+        res.end(
+          "<html><body><h3>Flo OAuth complete.</h3><p>You can close this tab and return to Claude.</p></body></html>"
+        );
+        resolve(returnedCode);
+      } catch (err) {
+        clearTimeout(timer);
+        reject(err);
+      }
+    };
+
+    const timeoutMs = Number(process.env.FLO_OAUTH_TIMEOUT_MS || OAUTH_WAIT_TIMEOUT_MS);
+    const timer = setTimeout(() => {
+      reject(
+        new Error("Timed out waiting for OAuth callback. Re-run flo_auth_login.")
+      );
+    }, timeoutMs);
+
+    server.once("error", (err) => {
+      clearTimeout(timer);
+      reject(err);
+    });
+    server.on("request", onRequest);
+    server.listen(port, hostname);
+  }).finally(async () => {
+    await new Promise((done) => server.close(() => done()));
+  });
+
+  return code;
+}
+
+async function runInteractiveOAuthLogin() {
+  const oauth = getOAuthConfig(true);
+  const verifier = base64Url(randomBytes(32));
+  const challenge = base64Url(
+    createHash("sha256").update(verifier, "utf8").digest()
+  );
+  const state = base64Url(randomBytes(24));
+  const authUrl = new URL(oauth.authorizeUrl);
+  authUrl.searchParams.set("response_type", "code");
+  authUrl.searchParams.set("client_id", oauth.clientId);
+  authUrl.searchParams.set("redirect_uri", oauth.redirectUri);
+  authUrl.searchParams.set("scope", oauth.scope);
+  authUrl.searchParams.set("state", state);
+  authUrl.searchParams.set("code_challenge", challenge);
+  authUrl.searchParams.set("code_challenge_method", "S256");
+  if (oauth.audience) {
+    authUrl.searchParams.set("audience", oauth.audience);
+  }
+
+  const opened = openBrowser(authUrl.toString());
+  if (!opened) {
+    throw new McpError(
+      ErrorCode.InternalError,
+      `Unable to auto-open browser. Open this URL manually and re-run flo_auth_login:\n${authUrl.toString()}`
+    );
+  }
+
+  const code = await waitForOAuthCode(oauth.redirectUri, state);
+  const token = await exchangeToken({
+    grant_type: "authorization_code",
+    code,
+    client_id: oauth.clientId,
+    redirect_uri: oauth.redirectUri,
+    code_verifier: verifier,
+  });
+  await writeCachedToken(token);
+  return token;
+}
+
+async function resolveAuthToken(explicitAuthToken, interactive) {
+  const override = explicitAuthToken?.trim();
+  if (override) {
+    return override;
+  }
+
+  const envToken = getDefaultAuthToken();
+  if (envToken) {
+    return envToken;
+  }
+
+  const oauth = getOAuthConfig(false);
+  if (!oauth.ready) {
+    return "";
+  }
+
+  const cachedToken = await readCachedToken();
+  if (tokenIsUsable(cachedToken)) {
+    return cachedToken.access_token;
+  }
+
+  const refreshedToken = await refreshAccessTokenIfPossible(cachedToken);
+  if (tokenIsUsable(refreshedToken)) {
+    return refreshedToken.access_token;
+  }
+
+  if (!interactive) {
+    return "";
+  }
+
+  const freshToken = await runInteractiveOAuthLogin();
+  return freshToken.access_token;
+}
+
+async function buildHeaders(explicitAuthToken, interactiveAuth = true) {
+  const headers = { "content-type": "application/json" };
+  const token = await resolveAuthToken(explicitAuthToken, interactiveAuth);
+  if (token) {
+    headers.Authorization = `Bearer ${token}`;
+  }
+  return headers;
+}
+
+async function invokeInterfaceAgent(prompt, explicitAuthToken, interactiveAuth = true) {
+  const response = await fetch(getInvocationUrl(), {
+    method: "POST",
+    headers: await buildHeaders(explicitAuthToken, interactiveAuth),
+    body: JSON.stringify({ prompt }),
+    signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+  });
+
+  const bodyText = await response.text();
+  if (!response.ok) {
+    throw new McpError(
+      ErrorCode.InternalError,
+      `interface-agent returned HTTP ${response.status}: ${bodyText.slice(0, 500)}`
+    );
+  }
+
+  return bodyText;
+}
+
+function parseMaybeJson(text) {
+  const trimmed = (text || "").trim();
+  if (!trimmed) {
+    return null;
+  }
+  try {
+    return JSON.parse(trimmed);
+  } catch {
+    return null;
+  }
+}
+
+function asTextResult(value) {
+  if (typeof value === "string") {
+    return { content: [{ type: "text", text: value }] };
+  }
+  return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+
+function requireString(value, fieldName) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new McpError(
+      ErrorCode.InvalidParams,
+      `\`${fieldName}\` must be a non-empty string.`
+    );
+  }
+  return value.trim();
+}
+
+function assertSearchPayload(payload) {
+  if (!payload || payload.status !== "ok" || !Array.isArray(payload.menuItems)) {
+    throw new McpError(
+      ErrorCode.InternalError,
+      "Search payload did not match expected contract."
+    );
+  }
+  const first = payload.menuItems[0];
+  if (!first || typeof first.assetId !== "string" || !first.assetId) {
+    throw new McpError(
+      ErrorCode.InternalError,
+      "Search payload missing first menu item assetId."
+    );
+  }
+  return first.assetId;
+}
+
+function assertSkillRoutingPayload(payload) {
+  if (!payload || payload.status !== "ok" || !Array.isArray(payload.skills)) {
+    throw new McpError(
+      ErrorCode.InternalError,
+      "Skill routing payload did not match expected contract."
+    );
+  }
+  const hasQc = payload.skills.some(
+    (s) => s && typeof s === "object" && s.command === "/flo:qc-logo"
+  );
+  if (!hasQc) {
+    throw new McpError(
+      ErrorCode.InternalError,
+      "Skill routing payload missing /flo:qc-logo option."
+    );
+  }
+}
+
+function assertQcPayload(payload) {
+  if (!payload || payload.status !== "ok" || typeof payload.result !== "object") {
+    throw new McpError(
+      ErrorCode.InternalError,
+      "QC payload did not match expected contract."
+    );
+  }
+  const result = payload.result || {};
+  const required = ["overall", "summary", "assetId", "assetUrl", "findings"];
+  for (const key of required) {
+    if (!(key in result)) {
+      throw new McpError(
+        ErrorCode.InternalError,
+        `QC payload missing result.${key}.`
+      );
+    }
+  }
+}
+
+async function probeInvocation(explicitAuthToken) {
+  let url;
+  try {
+    url = getInvocationUrl();
+  } catch (err) {
+    return {
+      configured: false,
+      invocationUrl: null,
+      reachable: false,
+      statusCode: null,
+      responsePreview:
+        err instanceof Error ? err.message : "Missing invocation URL",
+    };
+  }
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: await buildHeaders(explicitAuthToken, false),
+      body: JSON.stringify({ prompt: "healthcheck" }),
+      signal: AbortSignal.timeout(DEFAULT_TIMEOUT_MS),
+    });
+    const text = await response.text();
+    return {
+      configured: true,
+      invocationUrl: url,
+      reachable: true,
+      statusCode: response.status,
+      responsePreview: text.slice(0, 300),
+    };
+  } catch (err) {
+    return {
+      configured: true,
+      invocationUrl: url,
+      reachable: false,
+      statusCode: null,
+      responsePreview: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+const tools = [
+  {
+    name: "flo_auth_login",
+    description:
+      "Start OAuth login (browser PKCE flow), cache token locally, and return auth status.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "flo_auth_status",
+    description: "Show current auth mode and cached OAuth token status.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "flo_auth_setup_help",
+    description:
+      "Show where to find/configure FLO_OAUTH_CLIENT_ID and expected Cognito app client details.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "flo_auth_logout",
+    description: "Clear cached OAuth token from local disk.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "flo_search",
+    description:
+      "Run /flo:search against interface-agent and return plugin menu items.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: { type: "string", minLength: 1 },
+        authToken: {
+          type: "string",
+          description: "Optional bearer token override for this call only.",
+        },
+      },
+      required: ["query"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "flo_skill_routing",
+    description:
+      "Run /flo:skill-routing for an asset and return available plugin skills.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        assetId: { type: "string", minLength: 1 },
+        authToken: {
+          type: "string",
+          description: "Optional bearer token override for this call only.",
+        },
+      },
+      required: ["assetId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "flo_qc_logo",
+    description:
+      "Run /flo:qc-logo using stored-image reference mode for the Claude plugin happy path.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        assetId: { type: "string", minLength: 1 },
+        referenceAssetId: { type: "string", minLength: 1 },
+        includePdf: {
+          type: "boolean",
+          default: false,
+          description: "Whether to include PDF output in qc result.",
+        },
+        authToken: {
+          type: "string",
+          description: "Optional bearer token override for this call only.",
+        },
+      },
+      required: ["assetId", "referenceAssetId"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "flo_command",
+    description:
+      "Run a raw /flo:* slash command against interface-agent for troubleshooting.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        command: { type: "string", minLength: 1 },
+        authToken: {
+          type: "string",
+          description: "Optional bearer token override for this call only.",
+        },
+      },
+      required: ["command"],
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "flo_plugin_healthcheck",
+    description:
+      "Check config/auth/runtime reachability for the Flo Claude Co-Work plugin.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        authToken: {
+          type: "string",
+          description: "Optional bearer token override for this healthcheck.",
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "flo_happy_path_run",
+    description:
+      "Run search -> skill routing -> qc logo in one tool call for end-to-end validation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        query: {
+          type: "string",
+          default: "hail mary",
+          description: "Search query used when assetId is not provided.",
+        },
+        assetId: {
+          type: "string",
+          description: "Optional preselected asset ID; skips search when set.",
+        },
+        referenceAssetId: {
+          type: "string",
+          minLength: 1,
+          description: "Stored image asset ID used as logo reference.",
+        },
+        includePdf: {
+          type: "boolean",
+          default: false,
+          description: "Whether to include PDF output in qc result.",
+        },
+        authToken: {
+          type: "string",
+          description: "Optional bearer token override for this run.",
+        },
+      },
+      required: ["referenceAssetId"],
+      additionalProperties: false,
+    },
+  },
+];
+
+const server = new Server(
+  {
+    name: "flo-claude-plugin-mcp",
+    version: "0.1.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
+
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const name = request.params.name;
+  const args = request.params.arguments || {};
+
+  if (name === "flo_auth_login") {
+    const token = await runInteractiveOAuthLogin();
+    return asTextResult({
+      status: "ok",
+      mode: "oauth",
+      expiresAt: token.expires_at,
+      cachePath: getTokenCachePath(),
+    });
+  }
+
+  if (name === "flo_auth_status") {
+    const oauth = getOAuthConfig(false);
+    const envToken = Boolean(getDefaultAuthToken());
+    const cachedToken = await readCachedToken();
+    return asTextResult({
+      oauthConfigured: oauth.ready,
+      oauthClientIdConfigured: Boolean(oauth.clientId),
+      oauthClientId: oauth.clientId || null,
+      oauthExpectedClientName: oauth.expectedClientName,
+      oauthUserPoolName: oauth.userPoolName,
+      oauthUserPoolId: oauth.userPoolId || null,
+      oauthSettingsUrl: oauth.settingsUrl,
+      envTokenConfigured: envToken,
+      cachePath: getTokenCachePath(),
+      cachedTokenPresent: Boolean(cachedToken?.access_token),
+      cachedTokenUsable: tokenIsUsable(cachedToken),
+      cachedTokenExpiresAt: cachedToken?.expires_at || null,
+    });
+  }
+
+  if (name === "flo_auth_setup_help") {
+    const oauth = getOAuthConfig(false);
+    return asTextResult({
+      status: "ok",
+      pluginEnv: normalizedPluginEnv(),
+      runtimeInvocationUrl: getInvocationUrl(),
+      oauthAuthorizeUrl: oauth.authorizeUrl || null,
+      oauthTokenUrl: oauth.tokenUrl || null,
+      oauthClientIdConfigured: Boolean(oauth.clientId),
+      oauthClientId: oauth.clientId || null,
+      oauthExpectedClientName: oauth.expectedClientName,
+      oauthUserPoolName: oauth.userPoolName,
+      oauthUserPoolId: oauth.userPoolId || null,
+      oauthSettingsUrl: oauth.settingsUrl,
+      message:
+        "Open oauthSettingsUrl, then copy the app client id for oauthExpectedClientName into FLO_OAUTH_CLIENT_ID.",
+    });
+  }
+
+  if (name === "flo_auth_logout") {
+    await clearCachedToken();
+    return asTextResult({
+      status: "ok",
+      message: "OAuth token cache cleared.",
+      cachePath: getTokenCachePath(),
+    });
+  }
+
+  if (name === "flo_search") {
+    const query = requireString(args.query, "query");
+    const prompt = `/flo:search ${query}`;
+    const bodyText = await invokeInterfaceAgent(prompt, args.authToken);
+    return asTextResult(parseMaybeJson(bodyText) || bodyText);
+  }
+
+  if (name === "flo_skill_routing") {
+    const assetId = requireString(args.assetId, "assetId");
+    const prompt = `/flo:skill-routing ${assetId}`;
+    const bodyText = await invokeInterfaceAgent(prompt, args.authToken);
+    return asTextResult(parseMaybeJson(bodyText) || bodyText);
+  }
+
+  if (name === "flo_qc_logo") {
+    const assetId = requireString(args.assetId, "assetId");
+    const referenceAssetId = requireString(args.referenceAssetId, "referenceAssetId");
+    if (args.includePdf !== undefined && typeof args.includePdf !== "boolean") {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        "`includePdf` must be a boolean when provided."
+      );
+    }
+    const payload = {
+      assetId,
+      reference: {
+        source: "stored_image",
+        referenceAssetId,
+      },
+      options: {
+        includePdf: Boolean(args.includePdf),
+      },
+    };
+    const prompt = `/flo:qc-logo ${JSON.stringify(payload)}`;
+    const bodyText = await invokeInterfaceAgent(prompt, args.authToken);
+    return asTextResult(parseMaybeJson(bodyText) || bodyText);
+  }
+
+  if (name === "flo_command") {
+    const command = requireString(args.command, "command");
+    const bodyText = await invokeInterfaceAgent(command, args.authToken);
+    return asTextResult(parseMaybeJson(bodyText) || bodyText);
+  }
+
+  if (name === "flo_plugin_healthcheck") {
+    const oauth = getOAuthConfig(false);
+    const envToken = Boolean(getDefaultAuthToken());
+    const cachedToken = await readCachedToken();
+    const probe = await probeInvocation(args.authToken);
+    return asTextResult({
+      status: "ok",
+      auth: {
+        oauthConfigured: oauth.ready,
+        envTokenConfigured: envToken,
+        cachePath: getTokenCachePath(),
+        cachedTokenPresent: Boolean(cachedToken?.access_token),
+        cachedTokenUsable: tokenIsUsable(cachedToken),
+        cachedTokenExpiresAt: cachedToken?.expires_at || null,
+      },
+      runtime: probe,
+    });
+  }
+
+  if (name === "flo_happy_path_run") {
+    const referenceAssetId = requireString(args.referenceAssetId, "referenceAssetId");
+    if (args.includePdf !== undefined && typeof args.includePdf !== "boolean") {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        "`includePdf` must be a boolean when provided."
+      );
+    }
+
+    let selectedAssetId =
+      typeof args.assetId === "string" && args.assetId.trim()
+        ? args.assetId.trim()
+        : "";
+    const query = typeof args.query === "string" && args.query.trim() ? args.query.trim() : "hail mary";
+    const steps = [];
+
+    if (!selectedAssetId) {
+      const searchPrompt = `/flo:search ${query}`;
+      const searchRaw = await invokeInterfaceAgent(searchPrompt, args.authToken);
+      const searchPayload = parseMaybeJson(searchRaw);
+      if (!searchPayload) {
+        throw new McpError(
+          ErrorCode.InternalError,
+          "Search response was not valid JSON during happy-path run."
+        );
+      }
+      selectedAssetId = assertSearchPayload(searchPayload);
+      steps.push({
+        name: "search",
+        query,
+        selectedAssetId,
+        response: searchPayload,
+      });
+    }
+
+    const skillPrompt = `/flo:skill-routing ${selectedAssetId}`;
+    const skillRaw = await invokeInterfaceAgent(skillPrompt, args.authToken);
+    const skillPayload = parseMaybeJson(skillRaw);
+    if (!skillPayload) {
+      throw new McpError(
+        ErrorCode.InternalError,
+        "Skill-routing response was not valid JSON during happy-path run."
+      );
+    }
+    assertSkillRoutingPayload(skillPayload);
+    steps.push({
+      name: "skill_routing",
+      response: skillPayload,
+    });
+
+    const qcCommandPayload = {
+      assetId: selectedAssetId,
+      reference: {
+        source: "stored_image",
+        referenceAssetId,
+      },
+      options: {
+        includePdf: Boolean(args.includePdf),
+      },
+    };
+    const qcPrompt = `/flo:qc-logo ${JSON.stringify(qcCommandPayload)}`;
+    const qcRaw = await invokeInterfaceAgent(qcPrompt, args.authToken);
+    const qcPayload = parseMaybeJson(qcRaw);
+    if (!qcPayload) {
+      throw new McpError(
+        ErrorCode.InternalError,
+        "QC response was not valid JSON during happy-path run."
+      );
+    }
+    assertQcPayload(qcPayload);
+    steps.push({
+      name: "qc_logo",
+      response: qcPayload,
+    });
+
+    return asTextResult({
+      status: "ok",
+      selectedAssetId,
+      steps,
+    });
+  }
+
+  throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+});
+
+const transport = new StdioServerTransport();
+await server.connect(transport);