@groundfloorcloud/mcp 0.1.0

package/README.md

@@ -0,0 +1,57 @@
+# `@groundfloorcloud/mcp`
+
+MCP for **inspect + guidance**. The **`gf` CLI** takes actions (login, deploy,
+secrets, publish).
+
+They are not replacements. Sign in with `gf`; the MCP reads that session and
+docs so the agent knows *what is in the workspace* and *which `gf` command to
+run*.
+
+## How the MCP gets context
+
+| Source | What it answers |
+|--------|-----------------|
+| `gf login` → `~/.groundfloor` | Who you are, which cell (prod/stage/dev), default workspace. Token refresh is the CLI’s job. |
+| Control Plane (read-only tools) | What exists now: coderunners, apps, dataplane, logs. Tool: `workspace_context`. |
+| [docs.groundfloor.cloud](https://docs.groundfloor.cloud) | How and when: `docs_list` / `docs_get`. |
+| `suggest_cli` | Exact `gf …` command to run (MCP does not deploy). |
+
+Switch workspace: `gf workspaces use <uuid>` (then MCP sees it). Expired session: `gf login` again.
+
+## Cursor config
+
+`gf` must be on `PATH` and you must have run `gf login` (and usually `gf workspaces use`).
+
+```json
+{
+  "mcpServers": {
+    "groundfloor": {
+      "command": "npx",
+      "args": ["-y", "@groundfloorcloud/mcp"]
+    }
+  }
+}
+```
+
+Optional: `"GROUNDFLOOR_API_URL"` only if you are not using the cell from `gf login`. Do not put a JWT in mcp.json.
+
+## Tools
+
+| Tool | Role |
+|------|------|
+| `whoami` / `workspace_context` | Session + live workspace snapshot |
+| `workspaces_list` | List; switch with `gf workspaces use` |
+| `coderunner_list` / `_get_status` / `_get_logs` | Inspect workloads |
+| `apps_list` / `apps_get` | Inspect product Apps |
+| `secrets_list` / `files_list` / `domains_list` / `dataplane_status` | Inspect (no secrets values) |
+| `docs_list` / `docs_get` | Product docs |
+| `suggest_cli` | Command to run: login, deploy, run, … |
+
+Never create `app_kind=coderunner`. Deploy with `gf deploy`.
+
+## Build (from this repo)
+
+```bash
+npm install
+npm run build --workspace=@groundfloorcloud/mcp
+```

package/dist/index.js

@@ -0,0 +1,868 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// ../cli/src/auth/oauth.ts
+import crypto from "crypto";
+import http from "http";
+function endpoints(issuer) {
+  const base = issuer.replace(/\/+$/, "");
+  return {
+    authorization: `${base}/protocol/openid-connect/auth`,
+    token: `${base}/protocol/openid-connect/token`,
+    deviceAuthorization: `${base}/protocol/openid-connect/auth/device`
+  };
+}
+async function postForm(url, form) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams(form).toString()
+  });
+  let body = {};
+  try {
+    body = await res.json();
+  } catch {
+    body = {};
+  }
+  return { ok: res.ok, status: res.status, body };
+}
+function tokenResponseFrom(body) {
+  return {
+    access_token: String(body.access_token ?? ""),
+    refresh_token: typeof body.refresh_token === "string" ? body.refresh_token : void 0,
+    id_token: typeof body.id_token === "string" ? body.id_token : void 0,
+    expires_in: typeof body.expires_in === "number" ? body.expires_in : void 0,
+    token_type: typeof body.token_type === "string" ? body.token_type : void 0
+  };
+}
+async function refreshTokens(opts) {
+  const ep = endpoints(opts.issuer);
+  const { ok, status, body } = await postForm(ep.token, {
+    grant_type: "refresh_token",
+    client_id: opts.clientId,
+    refresh_token: opts.refreshToken
+  });
+  if (!ok) {
+    throw new Error(
+      `Token refresh failed (${status}): ${body.error_description ?? body.error ?? "session expired"}`
+    );
+  }
+  return tokenResponseFrom(body);
+}
+
+// ../cli/src/auth/store.ts
+import { promises as fs } from "fs";
+import os from "os";
+import path from "path";
+var CONFIG_DIR = path.join(os.homedir(), ".groundfloor");
+var AUTH_FILE = path.join(CONFIG_DIR, "auth.json");
+var CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+async function ensureDir() {
+  await fs.mkdir(CONFIG_DIR, { recursive: true, mode: 448 });
+}
+async function readJson(file) {
+  try {
+    const raw = await fs.readFile(file, "utf8");
+    return JSON.parse(raw);
+  } catch (err) {
+    if (err.code === "ENOENT") {
+      return null;
+    }
+    throw err;
+  }
+}
+async function readAuth() {
+  return readJson(AUTH_FILE);
+}
+async function writeAuth(session) {
+  await ensureDir();
+  await fs.writeFile(AUTH_FILE, `${JSON.stringify(session, null, 2)}
+`, {
+    mode: 384
+  });
+  await fs.chmod(AUTH_FILE, 384);
+}
+async function readConfig() {
+  return await readJson(CONFIG_FILE) ?? {};
+}
+
+// ../cli/src/auth/session.ts
+var EXPIRY_SKEW_MS = 3e4;
+var NotLoggedInError = class extends Error {
+  constructor() {
+    super(
+      "Not logged in. Set GROUNDFLOOR_TOKEN, or run `gf login` first."
+    );
+    this.name = "NotLoggedInError";
+  }
+};
+var accessTokenProvider = null;
+function setAccessTokenProvider(provider) {
+  accessTokenProvider = provider;
+}
+function decodeJwt(token) {
+  const parts = token.split(".");
+  if (parts.length < 2) return null;
+  try {
+    const json = Buffer.from(parts[1], "base64url").toString("utf8");
+    return JSON.parse(json);
+  } catch {
+    return null;
+  }
+}
+function sessionFromTokens(tokens, ctx) {
+  const expiresInMs = (tokens.expires_in ?? 300) * 1e3;
+  return {
+    issuer: ctx.issuer,
+    clientId: ctx.clientId,
+    apiUrl: ctx.apiUrl,
+    accessToken: tokens.access_token,
+    refreshToken: tokens.refresh_token,
+    idToken: tokens.id_token,
+    expiresAt: Date.now() + expiresInMs
+  };
+}
+function isFresh(session) {
+  return Date.now() < session.expiresAt - EXPIRY_SKEW_MS;
+}
+async function getValidAccessToken() {
+  if (accessTokenProvider) {
+    return accessTokenProvider();
+  }
+  const session = await readAuth();
+  if (!session || !session.accessToken) {
+    throw new NotLoggedInError();
+  }
+  if (isFresh(session)) {
+    return session.accessToken;
+  }
+  if (!session.refreshToken) {
+    throw new NotLoggedInError();
+  }
+  const refreshed = await refreshTokens({
+    issuer: session.issuer,
+    clientId: session.clientId,
+    refreshToken: session.refreshToken
+  });
+  const next = sessionFromTokens(refreshed, {
+    issuer: session.issuer,
+    clientId: session.clientId,
+    apiUrl: session.apiUrl
+  });
+  if (!next.refreshToken) {
+    next.refreshToken = session.refreshToken;
+  }
+  await writeAuth(next);
+  return next.accessToken;
+}
+
+// ../cli/src/cp.ts
+var CpError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "CpError";
+  }
+  status;
+};
+async function parseError(res) {
+  let detail = res.statusText;
+  try {
+    const body = await res.json();
+    if (body?.detail) detail = String(body.detail);
+  } catch {
+  }
+  return `${res.status} ${detail}`;
+}
+async function cpGet(apiUrl, path2) {
+  const token = await getValidAccessToken();
+  const res = await fetch(`${apiUrl}${path2}`, {
+    headers: {
+      Authorization: `Bearer ${token}`,
+      Accept: "application/json"
+    }
+  });
+  if (!res.ok) {
+    throw new CpError(res.status, await parseError(res));
+  }
+  return await res.json();
+}
+function queryString(params) {
+  const u = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value) u.set(key, value);
+  }
+  const s = u.toString();
+  return s ? `?${s}` : "";
+}
+function listWorkspaces(apiUrl) {
+  return cpGet(apiUrl, "/v1/workspaces");
+}
+async function listCoderunners(apiUrl, workspaceId) {
+  const data = await cpGet(
+    apiUrl,
+    `/v1/workspaces/${encodeURIComponent(workspaceId)}/coderunners`
+  );
+  if (Array.isArray(data)) return data;
+  return data.coderunners ?? [];
+}
+async function getDeployment(apiUrl, workspaceId, coderunnerId) {
+  const token = await getValidAccessToken();
+  const res = await fetch(
+    `${apiUrl}/v1/workspaces/${encodeURIComponent(
+      workspaceId
+    )}/coderunners/${encodeURIComponent(coderunnerId)}/deployment`,
+    {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/json"
+      }
+    }
+  );
+  if (res.status === 204) return null;
+  if (!res.ok) {
+    throw new CpError(res.status, await parseError(res));
+  }
+  return await res.json();
+}
+function getCoderunnerStatus(apiUrl, workspaceId, coderunnerId) {
+  return cpGet(
+    apiUrl,
+    `/v1/workspaces/${encodeURIComponent(
+      workspaceId
+    )}/coderunners/${encodeURIComponent(coderunnerId)}/status`
+  );
+}
+function getCoderunnerLogs(apiUrl, workspaceId, coderunnerId, jobId) {
+  return cpGet(
+    apiUrl,
+    `/v1/workspaces/${encodeURIComponent(
+      workspaceId
+    )}/coderunners/${encodeURIComponent(
+      coderunnerId
+    )}/logs/${encodeURIComponent(jobId)}`
+  );
+}
+function domainsBase(workspaceId, coderunnerId) {
+  return `/v1/workspaces/${encodeURIComponent(
+    workspaceId
+  )}/coderunners/${encodeURIComponent(coderunnerId)}/domains`;
+}
+function listDomains(apiUrl, workspaceId, coderunnerId) {
+  return cpGet(
+    apiUrl,
+    domainsBase(workspaceId, coderunnerId)
+  );
+}
+function wsPath(workspaceId, suffix) {
+  return `/v1/workspaces/${encodeURIComponent(workspaceId)}${suffix}`;
+}
+function listSecrets(apiUrl, workspaceId, environmentId) {
+  return cpGet(
+    apiUrl,
+    `${wsPath(workspaceId, "/secrets")}${queryString({
+      environment_id: environmentId
+    })}`
+  );
+}
+function listFiles(apiUrl, workspaceId) {
+  return cpGet(apiUrl, wsPath(workspaceId, "/files"));
+}
+function listApps(apiUrl, workspaceId) {
+  return cpGet(
+    apiUrl,
+    `${wsPath(workspaceId, "/apps")}${queryString({ kind: "product" })}`
+  );
+}
+function getApp(apiUrl, workspaceId, appId) {
+  return cpGet(
+    apiUrl,
+    wsPath(workspaceId, `/apps/${encodeURIComponent(appId)}`)
+  );
+}
+function getDataplaneStatus(apiUrl, workspaceId) {
+  return cpGet(
+    apiUrl,
+    wsPath(workspaceId, "/dataplane/status")
+  );
+}
+
+// ../cli/src/auth/config.ts
+var CELLS = {
+  production: {
+    apiUrl: "https://platform.groundfloor.cloud",
+    issuer: "https://auth.groundfloor.cloud/realms/groundfloor",
+    clientId: "groundfloor-cli"
+  },
+  stage: {
+    apiUrl: "https://platform.stage.groundfloor.cloud",
+    issuer: "https://auth.stage.groundfloor.cloud/realms/groundfloor_pico_stage-realm",
+    clientId: "groundfloor-cli"
+  },
+  dev: {
+    apiUrl: "https://platform.dev.groundfloor.cloud",
+    issuer: "https://auth.dev.groundfloor.cloud/realms/groundfloor_dev",
+    clientId: "groundfloor-cli"
+  }
+};
+function inferCell(apiUrl, issuer) {
+  const api = apiUrl.replace(/\/+$/, "");
+  const iss = (issuer ?? "").replace(/\/+$/, "");
+  for (const [name, hosts] of Object.entries(CELLS)) {
+    if (api === hosts.apiUrl || iss === hosts.issuer) return name;
+  }
+  return void 0;
+}
+function trimTrailingSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+async function resolveConfig(overrides = {}) {
+  const file = await readConfig();
+  const production = CELLS.production;
+  const issuer = overrides.issuer ?? process.env.GROUNDFLOOR_ISSUER ?? file.issuer ?? production.issuer;
+  const clientId = overrides.clientId ?? process.env.GROUNDFLOOR_CLIENT_ID ?? file.clientId ?? production.clientId;
+  const apiUrl = overrides.apiUrl ?? process.env.GROUNDFLOOR_API_URL ?? file.apiUrl ?? production.apiUrl;
+  const workspaceId = overrides.workspaceId ?? process.env.GROUNDFLOOR_WORKSPACE_ID ?? file.workspaceId;
+  const environment = overrides.environment ?? inferCell(apiUrl, issuer) ?? file.environment;
+  return {
+    issuer: trimTrailingSlash(issuer),
+    clientId,
+    apiUrl: trimTrailingSlash(apiUrl),
+    workspaceId: workspaceId || void 0,
+    environment
+  };
+}
+var defaults = CELLS.production;
+
+// src/config.ts
+function trimSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+var MISSING_TOKEN = "Not signed in. Run `gf login` (or `gf login --stage`) so MCP can use ~/.groundfloor. Do not paste JWTs into Cursor MCP config.";
+var MISSING_WORKSPACE = "No workspace selected. Run `gf workspaces` then `gf workspaces use <uuid>`, or pass workspace_id on this tool.";
+async function resolveMcpConfig(overrides) {
+  const file = await resolveConfig();
+  const apiUrl = trimSlash(
+    process.env.GROUNDFLOOR_API_URL || process.env.CP_API || file.apiUrl || CELLS.production.apiUrl
+  );
+  const workspaceId = overrides?.workspaceId || process.env.GROUNDFLOOR_WORKSPACE_ID || process.env.WORKSPACE_ID || file.workspaceId || "";
+  const envToken = (process.env.GROUNDFLOOR_TOKEN || process.env.TOKEN || "").trim();
+  if (envToken) {
+    setAccessTokenProvider(async () => envToken);
+  } else {
+    setAccessTokenProvider(null);
+  }
+  let token = envToken;
+  if (!token) {
+    try {
+      token = await getValidAccessToken();
+    } catch (err) {
+      if (err instanceof NotLoggedInError) {
+        throw new Error(MISSING_TOKEN);
+      }
+      throw err;
+    }
+  }
+  if (!token) {
+    throw new Error(MISSING_TOKEN);
+  }
+  const requireWorkspace = overrides?.requireWorkspace !== false;
+  if (requireWorkspace && !workspaceId) {
+    throw new Error(MISSING_WORKSPACE);
+  }
+  return { apiUrl, workspaceId, token };
+}
+
+// src/docs.ts
+var DOCS_ORIGIN = "https://docs.groundfloor.cloud";
+var DOC_CATALOG = [
+  {
+    id: "agents",
+    title: "Deploy with agents",
+    path: "/docs/customer-portal/agents",
+    summary: "How agents should deploy Coderunner workloads with gf / MCP."
+  },
+  {
+    id: "developers",
+    title: "Developers (gf CLI)",
+    path: "/docs/customer-portal/developers",
+    summary: "gf login, workspaces, deploy, secrets, files, apps."
+  },
+  {
+    id: "coderunner",
+    title: "Coderunner",
+    path: "/docs/customer-portal/coderunner",
+    summary: "Functions, jobs, schedules, services \u2014 not Apps."
+  },
+  {
+    id: "authentication",
+    title: "API authentication",
+    path: "/docs/api/authentication",
+    summary: "Control Plane Bearer tokens and workspace identity."
+  },
+  {
+    id: "shell",
+    title: "Shell federated apps",
+    path: "/docs/integrations/shell",
+    summary: "Product Apps vs Coderunner deploy."
+  }
+];
+function docUrl(entry) {
+  return `${DOCS_ORIGIN}${entry.path}`;
+}
+function findDoc(query) {
+  const q = query.trim().toLowerCase();
+  if (!q) return DOC_CATALOG;
+  return DOC_CATALOG.filter((d) => {
+    const hay = `${d.id} ${d.title} ${d.summary} ${d.path}`.toLowerCase();
+    return q.split(/\s+/).every((part) => hay.includes(part));
+  });
+}
+function htmlToText(html) {
+  const article = html.match(/<article\b[^>]*>([\s\S]*?)<\/article>/i)?.[1] ?? html.match(/<main\b[^>]*>([\s\S]*?)<\/main>/i)?.[1] ?? html;
+  return article.replace(/<script\b[\s\S]*?<\/script>/gi, " ").replace(/<style\b[\s\S]*?<\/style>/gi, " ").replace(/<nav\b[\s\S]*?<\/nav>/gi, " ").replace(/<footer\b[\s\S]*?<\/footer>/gi, " ").replace(/<[^>]+>/g, " ").replace(/&nbsp;/g, " ").replace(/&amp;/g, "&").replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&#39;/g, "'").replace(/&quot;/g, '"').replace(/\s+/g, " ").trim();
+}
+var MAX_CHARS = 12e3;
+async function fetchDocPage(entry) {
+  const url = docUrl(entry);
+  const res = await fetch(url, {
+    headers: { Accept: "text/html", "User-Agent": "groundfloor-mcp/0.1" },
+    redirect: "follow"
+  });
+  if (!res.ok) {
+    throw new Error(`Docs fetch failed: ${res.status} ${url}`);
+  }
+  const html = await res.text();
+  let body = htmlToText(html);
+  const truncated = body.length > MAX_CHARS;
+  if (truncated) body = `${body.slice(0, MAX_CHARS)}
+\u2026`;
+  return { url, title: entry.title, text: body, truncated };
+}
+
+// src/playbook.ts
+function suggestCli(intent, args) {
+  const ws = args?.workspace ? ` -w ${args.workspace}` : "";
+  const name = args?.name ?? args?.coderunner;
+  switch (intent) {
+    case "login":
+      return {
+        command: args?.cell === "stage" ? "gf login --stage" : args?.cell === "dev" ? "gf login --dev" : "gf login",
+        why: "Creates ~/.groundfloor session (auto-refresh). MCP reads this; do not paste JWTs into mcp.json.",
+        docs: "https://docs.groundfloor.cloud/docs/customer-portal/developers"
+      };
+    case "switch_workspace":
+      return {
+        command: args?.workspace ? `gf workspaces use ${args.workspace}` : "gf workspaces && gf workspaces use <uuid>",
+        why: "Sets the default workspace for gf and MCP.",
+        docs: "https://docs.groundfloor.cloud/docs/customer-portal/developers"
+      };
+    case "deploy":
+      return {
+        command: name ? `gf deploy -n ${name}${ws}` : `gf deploy${ws}`,
+        why: "Package the current (or --path) folder and deploy as a Coderunner. Do not create an App for this.",
+        docs: "https://docs.groundfloor.cloud/docs/customer-portal/coderunner"
+      };
+    case "run":
+      return {
+        command: name ? `gf coderunner run -c ${name}${ws}` : `gf coderunner run -c <id-or-slug>${ws}`,
+        why: "Smoke-invoke a deployed function or job.",
+        docs: "https://docs.groundfloor.cloud/docs/customer-portal/coderunner"
+      };
+    case "status":
+      return {
+        command: name ? `gf coderunner status -c ${name}${ws}` : `gf coderunner ls${ws}`,
+        why: "Inspect build/deploy state.",
+        docs: "https://docs.groundfloor.cloud/docs/customer-portal/coderunner"
+      };
+    case "publish_app":
+      return {
+        command: "gf apps publish --path release.zip",
+        why: "Ship a Shell federated product App (not a Coderunner workload).",
+        docs: "https://docs.groundfloor.cloud/docs/integrations/shell"
+      };
+    case "secrets":
+      return {
+        command: `gf secrets ls${ws}`,
+        why: "Mutations: gf secrets set|get|rm. MCP only lists keys.",
+        docs: "https://docs.groundfloor.cloud/docs/customer-portal/developers"
+      };
+    case "dataplane":
+      return {
+        command: `gf dataplane status${ws}  # provision: gf dataplane provision`,
+        why: "Dataplane is required for vault, files, and secrets.",
+        docs: "https://docs.groundfloor.cloud/docs/customer-portal/developers"
+      };
+    default:
+      return {
+        command: "gf --help",
+        why: `Unknown intent "${intent}". Use login | switch_workspace | deploy | run | status | publish_app | secrets | dataplane.`,
+        docs: "https://docs.groundfloor.cloud/docs/customer-portal/developers"
+      };
+  }
+}
+
+// src/respond.ts
+function text(data) {
+  return {
+    content: [
+      {
+        type: "text",
+        text: typeof data === "string" ? data : JSON.stringify(data, null, 2)
+      }
+    ]
+  };
+}
+function errText(err) {
+  let message;
+  if (err instanceof NotLoggedInError) {
+    message = "Not signed in. Run `gf login` so MCP can use ~/.groundfloor. Tokens refresh with the CLI session.";
+  } else if (err instanceof CpError) {
+    message = `CP error: ${err.message}`;
+  } else if (err instanceof Error) {
+    message = err.message;
+  } else {
+    message = String(err);
+  }
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+
+// src/index.ts
+var wsId = z.string().optional().describe("Override the gf default workspace for this call only");
+async function cfg(workspaceId, requireWorkspace = true) {
+  return resolveMcpConfig({ workspaceId, requireWorkspace });
+}
+async function resolveCoderunnerId(apiUrl, workspaceId, idOrSlug) {
+  const list = await listCoderunners(apiUrl, workspaceId);
+  const match = list.find((c) => c.id === idOrSlug || c.slug === idOrSlug);
+  if (!match) throw new Error(`Coderunner not found: ${idOrSlug}`);
+  return match.id;
+}
+var server = new McpServer({
+  name: "groundfloor",
+  version: "0.1.0"
+});
+server.tool(
+  "whoami",
+  "Show the gf CLI session (identity, cell, selected workspace). Run `gf login` if this fails.",
+  {},
+  async () => {
+    try {
+      const c = await cfg(void 0, false);
+      const claims = decodeJwt(c.token) ?? {};
+      const workspaces = await listWorkspaces(c.apiUrl);
+      return text({
+        email: claims.email || claims.preferred_username || null,
+        sub: claims.sub || null,
+        iss: claims.iss || null,
+        apiUrl: c.apiUrl,
+        workspaceId: c.workspaceId || null,
+        workspace_count: workspaces.length,
+        hint: c.workspaceId ? "Switch with: gf workspaces use <uuid>" : "Select a workspace: gf workspaces && gf workspaces use <uuid>"
+      });
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "workspace_context",
+  "Live context for the selected workspace: session, coderunners, apps, dataplane, and suggested gf commands. This is how the agent knows *what is here*; use docs_get for *how to do it*.",
+  { workspace_id: wsId },
+  async ({ workspace_id }) => {
+    try {
+      const c = await cfg(workspace_id);
+      const claims = decodeJwt(c.token) ?? {};
+      const [coderunners, apps, dataplane] = await Promise.all([
+        listCoderunners(c.apiUrl, c.workspaceId),
+        listApps(c.apiUrl, c.workspaceId).catch(() => ({ apps: [] })),
+        getDataplaneStatus(c.apiUrl, c.workspaceId).catch(() => null)
+      ]);
+      return text({
+        session: {
+          email: claims.email || claims.preferred_username || null,
+          apiUrl: c.apiUrl,
+          workspaceId: c.workspaceId
+        },
+        coderunners: coderunners.map((cr) => ({
+          id: cr.id,
+          name: cr.name ?? cr.slug,
+          slug: cr.slug,
+          status: cr.status
+        })),
+        apps: apps.apps.map((app) => ({
+          id: app.id,
+          name: app.name,
+          slug: app.slug,
+          kind: app.app_kind,
+          status: app.status
+        })),
+        dataplane,
+        actions: {
+          deploy: suggestCli("deploy"),
+          switch_workspace: suggestCli("switch_workspace"),
+          run: suggestCli("run")
+        },
+        docs: DOC_CATALOG.map((d) => ({
+          id: d.id,
+          title: d.title,
+          url: `https://docs.groundfloor.cloud${d.path}`
+        }))
+      });
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "workspaces_list",
+  "List workspaces visible to the current user. To change the default, tell the user to run `gf workspaces use <uuid>` (CLI owns that).",
+  {},
+  async () => {
+    try {
+      const c = await cfg(void 0, false);
+      const workspaces = await listWorkspaces(c.apiUrl);
+      return text({
+        workspaces,
+        selected: c.workspaceId || null,
+        count: workspaces.length,
+        next: suggestCli("switch_workspace", {
+          workspace: c.workspaceId ?? ""
+        })
+      });
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "coderunner_list",
+  "List Coderunners in the workspace (read-only).",
+  { workspace_id: wsId },
+  async ({ workspace_id }) => {
+    try {
+      const c = await cfg(workspace_id);
+      const list = await listCoderunners(c.apiUrl, c.workspaceId);
+      return text({ coderunners: list, count: list.length });
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "coderunner_get_status",
+  "Coderunner lifecycle status + current deployment (read-only).",
+  {
+    workspace_id: wsId,
+    coderunner_id: z.string().min(1).describe("Coderunner id or slug")
+  },
+  async (args) => {
+    try {
+      const c = await cfg(args.workspace_id);
+      const id = await resolveCoderunnerId(
+        c.apiUrl,
+        c.workspaceId,
+        args.coderunner_id
+      );
+      const [status, deployment] = await Promise.all([
+        getCoderunnerStatus(c.apiUrl, c.workspaceId, id),
+        getDeployment(c.apiUrl, c.workspaceId, id)
+      ]);
+      return text({ coderunner_id: id, status, deployment });
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "coderunner_get_logs",
+  "Fetch logs for a job id from a previous `gf coderunner run`.",
+  {
+    workspace_id: wsId,
+    coderunner_id: z.string().min(1),
+    job_id: z.string().min(1)
+  },
+  async (args) => {
+    try {
+      const c = await cfg(args.workspace_id);
+      const id = await resolveCoderunnerId(
+        c.apiUrl,
+        c.workspaceId,
+        args.coderunner_id
+      );
+      return text(await getCoderunnerLogs(c.apiUrl, c.workspaceId, id, args.job_id));
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "apps_list",
+  "List product Apps (Shell / standalone). Workloads are Coderunners, not Apps.",
+  { workspace_id: wsId },
+  async ({ workspace_id }) => {
+    try {
+      const c = await cfg(workspace_id);
+      return text(await listApps(c.apiUrl, c.workspaceId));
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "apps_get",
+  "Get one product App by id or slug.",
+  { workspace_id: wsId, app_id: z.string().min(1) },
+  async (args) => {
+    try {
+      const c = await cfg(args.workspace_id);
+      const listed = await listApps(c.apiUrl, c.workspaceId);
+      const match = listed.apps.find(
+        (app) => app.id === args.app_id || app.slug === args.app_id
+      );
+      return text(match ?? await getApp(c.apiUrl, c.workspaceId, args.app_id));
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "secrets_list",
+  "List secret keys (values are not shown). To set/delete, use `gf secrets`.",
+  { workspace_id: wsId, environment_id: z.string().optional() },
+  async (args) => {
+    try {
+      const c = await cfg(args.workspace_id);
+      return text(
+        await listSecrets(c.apiUrl, c.workspaceId, args.environment_id)
+      );
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "files_list",
+  "List workspace files (read-only). Upload/download with `gf files`.",
+  { workspace_id: wsId },
+  async ({ workspace_id }) => {
+    try {
+      const c = await cfg(workspace_id);
+      return text(await listFiles(c.apiUrl, c.workspaceId));
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "domains_list",
+  "List custom domains for a Coderunner service. Add/verify with `gf domains`.",
+  { workspace_id: wsId, coderunner_id: z.string().min(1) },
+  async (args) => {
+    try {
+      const c = await cfg(args.workspace_id);
+      const id = await resolveCoderunnerId(
+        c.apiUrl,
+        c.workspaceId,
+        args.coderunner_id
+      );
+      return text(await listDomains(c.apiUrl, c.workspaceId, id));
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "dataplane_status",
+  "Dataplane setup status. Provision with `gf dataplane provision`.",
+  { workspace_id: wsId },
+  async ({ workspace_id }) => {
+    try {
+      const c = await cfg(workspace_id);
+      return text(await getDataplaneStatus(c.apiUrl, c.workspaceId));
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "docs_list",
+  "Catalog of Groundfloor product docs (docs.groundfloor.cloud) the MCP can fetch.",
+  { query: z.string().optional() },
+  async ({ query }) => {
+    const hits = findDoc(query ?? "");
+    return text({
+      origin: "https://docs.groundfloor.cloud",
+      docs: hits.map((d) => ({
+        id: d.id,
+        title: d.title,
+        url: `https://docs.groundfloor.cloud${d.path}`,
+        summary: d.summary
+      }))
+    });
+  }
+);
+server.tool(
+  "docs_get",
+  "Fetch a product doc page from docs.groundfloor.cloud (how/when to use CLI). Pass id from docs_list (agents, developers, coderunner, authentication, shell).",
+  {
+    id: z.string().min(1).describe("Catalog id, e.g. agents | developers | coderunner")
+  },
+  async ({ id }) => {
+    try {
+      const entry = DOC_CATALOG.find((d) => d.id === id);
+      if (!entry) {
+        return errText(
+          new Error(
+            `Unknown doc id "${id}". Use docs_list. Known: ${DOC_CATALOG.map((d) => d.id).join(", ")}`
+          )
+        );
+      }
+      return text(await fetchDocPage(entry));
+    } catch (e) {
+      return errText(e);
+    }
+  }
+);
+server.tool(
+  "suggest_cli",
+  "Return the gf command the developer (or agent terminal) should run. MCP does not execute mutations.",
+  {
+    intent: z.enum([
+      "login",
+      "switch_workspace",
+      "deploy",
+      "run",
+      "status",
+      "publish_app",
+      "secrets",
+      "dataplane"
+    ]),
+    workspace: z.string().optional(),
+    name: z.string().optional().describe("Coderunner name/id for deploy/run/status"),
+    cell: z.enum(["production", "stage", "dev"]).optional()
+  },
+  async (args) => {
+    return text(
+      suggestCli(args.intent, {
+        workspace: args.workspace ?? "",
+        name: args.name ?? "",
+        coderunner: args.name ?? "",
+        cell: args.cell ?? ""
+      })
+    );
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("groundfloor MCP running on stdio (inspect + docs; actions via gf)");
+}
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@groundfloorcloud/mcp",
+  "version": "0.1.0",
+  "description": "Groundfloor MCP — inspect workspace state and docs; take actions with the gf CLI.",
+  "type": "module",
+  "bin": {
+    "groundfloor-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@bitbucket.org/codementeam/groundfloor-client-portal.git",
+    "directory": "packages/mcp"
+  },
+  "homepage": "https://docs.groundfloor.cloud/docs/customer-portal/agents",
+  "keywords": [
+    "groundfloor",
+    "mcp",
+    "coderunner"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsup --silent",
+    "start": "node dist/index.js",
+    "clean": "rm -rf dist *.tsbuildinfo .turbo",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8.3.0",
+    "typescript": "^5"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  }
+}