@genseo/cli 0.1.0

package/README.md

@@ -0,0 +1,166 @@
+# Genseo CLI and MCP
+
+This package provides:
+
+- `genseo`: command-line client for the Genseo Public API
+- `genseo-mcp`: stdio MCP server for Claude, Cursor, Codex, and other MCP clients
+
+## Install
+
+After the package is published to npm:
+
+```bash
+npm install -g @genseo/cli
+```
+
+Or run without a global install:
+
+```bash
+npx -y --package @genseo/cli genseo me
+```
+
+Requirements:
+
+- Node.js 20 or newer
+- A Genseo project
+- Either browser login with `genseo login` or a project-bound API key from the API / Developer settings tab
+
+## CLI
+
+Login with the browser-based Device Flow:
+
+```bash
+genseo login
+```
+
+The CLI opens `https://app.genseo.co/developer/device`, waits for approval, then stores the returned project-bound API key in `~/.genseo/config.json`.
+
+Manual API-key login is also supported:
+
+```bash
+genseo login --api-key gs_live_...
+```
+
+You can also use environment variables:
+
+```bash
+export GENSEO_API_BASE=https://api.genseo.co/v1
+export GENSEO_API_KEY=gs_live_...
+```
+
+Common commands:
+
+```bash
+genseo me
+genseo project get
+genseo project create --domain example.com --name "Example" --generate-keywords
+genseo keywords list
+genseo keywords add "seo automation software"
+genseo keywords generate
+genseo posts list
+genseo posts create --title "SEO Automation Workflow"
+genseo posts generate <postId>
+genseo posts publish <postId>
+genseo integrations list
+genseo webhooks create --target-url https://example.com/hook
+```
+
+## MCP
+
+Run the MCP server with a key after global install:
+
+```bash
+GENSEO_API_KEY=gs_live_... GENSEO_API_BASE=https://api.genseo.co/v1 genseo-mcp
+```
+
+Example MCP client config with global install:
+
+```json
+{
+  "mcpServers": {
+    "genseo": {
+      "command": "genseo-mcp",
+      "env": {
+        "GENSEO_API_BASE": "https://api.genseo.co/v1",
+        "GENSEO_API_KEY": "gs_live_..."
+      }
+    }
+  }
+}
+```
+
+Example MCP client config without global install:
+
+```json
+{
+  "mcpServers": {
+    "genseo": {
+      "command": "npx",
+      "args": ["-y", "--package", "@genseo/cli", "genseo-mcp"],
+      "env": {
+        "GENSEO_API_BASE": "https://api.genseo.co/v1",
+        "GENSEO_API_KEY": "gs_live_..."
+      }
+    }
+  }
+}
+```
+
+Available tools include:
+
+- `genseo_me`
+- `genseo_project_get`
+- `genseo_project_create`
+- `genseo_keywords_list`
+- `genseo_keywords_create`
+- `genseo_keywords_generate`
+- `genseo_keyword_metrics`
+- `genseo_posts_list`
+- `genseo_posts_create_draft`
+- `genseo_posts_get`
+- `genseo_posts_update`
+- `genseo_posts_generate`
+- `genseo_posts_publish`
+- `genseo_integrations_list`
+- `genseo_integration_fields`
+- `genseo_integration_connect_url`
+- `genseo_integration_mapping_save`
+- `genseo_webhooks_list`
+- `genseo_webhooks_create`
+- `genseo_webhooks_delete`
+
+Agents should call `genseo_me` first, use only the returned project, create drafts before publishing, and ask the user before calling `genseo_posts_publish` unless autonomous publishing is explicitly enabled.
+
+## Errors
+
+The CLI prints API errors with their stable code, for example:
+
+- `invalid_api_key`: missing, malformed, or unknown API key
+- `project_forbidden`: API key does not belong to the requested project
+- `insufficient_scope`: API key is missing the required scope
+- `key_revoked`: API key was revoked
+- `key_expired`: API key expired
+- `resource_not_found`: requested resource is missing or belongs to another project
+- `integration_not_configured`: publishing was requested but no publishing integration is connected
+
+Agents should treat `403` errors as final, `429` errors with backoff, and `202` responses as async accepted.
+
+## Publishing This Package
+
+Release checklist for Genseo maintainers:
+
+1. Confirm production API routing works:
+   `https://api.genseo.co/v1/me` rewrites to the app's `/api/v1/me`.
+2. Confirm OAuth Device Flow routing works:
+   `https://api.genseo.co/oauth/device/code` rewrites to `/api/oauth/device/code`.
+3. Set production environment variables:
+   `NEXT_PUBLIC_API_HOST=api.genseo.co`,
+   `NEXT_PUBLIC_API_URL=https://api.genseo.co/v1`,
+   `NEXT_PUBLIC_APP_URL=https://app.genseo.co`,
+   `PUBLIC_API_KEY_ENCRYPTION_KEY=...`.
+4. Run tests:
+   `npm run test` and `npm run test:cli` from the `web` workspace.
+5. Dry-run the npm package:
+   `npm pack --dry-run` from `web/packages/genseo-cli`.
+6. Publish:
+   `npm publish --access public` from `web/packages/genseo-cli`.

package/bin/genseo-mcp.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runMcpServer } from "../src/mcp-server.mjs";
+
+runMcpServer().catch((error) => {
+  console.error(error instanceof Error ? error.stack || error.message : String(error));
+  process.exit(1);
+});

package/bin/genseo.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { runCli } from "../src/cli.mjs";
+
+runCli(process.argv.slice(2)).catch((error) => {
+  console.error(error instanceof Error ? error.message : String(error));
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@genseo/cli",
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "description": "Genseo CLI and MCP server for the Genseo Public API.",
+  "license": "UNLICENSED",
+  "homepage": "https://genseo.co",
+  "bugs": {
+    "url": "https://genseo.co"
+  },
+  "keywords": [
+    "genseo",
+    "seo",
+    "cli",
+    "mcp",
+    "public-api"
+  ],
+  "bin": {
+    "genseo": "./bin/genseo.mjs",
+    "genseo-mcp": "./bin/genseo-mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node tests/smoke.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/api-client.mjs

@@ -0,0 +1,175 @@
+import { resolveConfig } from "./config.mjs";
+
+export class GenseoApiError extends Error {
+  constructor(message, { status, code, details, response } = {}) {
+    super(message);
+    this.name = "GenseoApiError";
+    this.status = status;
+    this.code = code;
+    this.details = details;
+    this.response = response;
+  }
+}
+
+export async function createClient(overrides = {}) {
+  const config = await resolveConfig(overrides);
+  return new GenseoClient(config);
+}
+
+export class GenseoClient {
+  constructor(config) {
+    this.apiBase = config.apiBase;
+    this.authBase = config.authBase;
+    this.apiKey = config.apiKey;
+  }
+
+  async request(method, path, { body, query, auth = true } = {}) {
+    const url = new URL(`${this.apiBase}${path.startsWith("/") ? path : `/${path}`}`);
+    for (const [key, value] of Object.entries(query || {})) {
+      if (value !== undefined && value !== null && value !== "") {
+        url.searchParams.set(key, String(value));
+      }
+    }
+
+    const headers = { Accept: "application/json" };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    if (auth) {
+      if (!this.apiKey) {
+        throw new GenseoApiError("Missing API key. Run `genseo login` or set GENSEO_API_KEY.", {
+          code: "missing_api_key",
+        });
+      }
+      headers.Authorization = `Bearer ${this.apiKey}`;
+    }
+
+    const response = await fetch(url, {
+      method,
+      headers,
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await response.text();
+    const data = text ? safeJson(text) : null;
+
+    if (!response.ok) {
+      const error = data?.error;
+      throw new GenseoApiError(error?.message || data?.error_description || response.statusText, {
+        status: response.status,
+        code: error?.code || data?.error || "request_failed",
+        details: error?.details || data,
+        response: data,
+      });
+    }
+
+    return data;
+  }
+
+  async authRequest(method, path, { body } = {}) {
+    const url = `${this.authBase}${path.startsWith("/") ? path : `/${path}`}`;
+    const response = await fetch(url, {
+      method,
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+    const text = await response.text();
+    const data = text ? safeJson(text) : null;
+    if (!response.ok) {
+      throw new GenseoApiError(data?.error_description || data?.message || data?.error || response.statusText, {
+        status: response.status,
+        code: data?.error || "request_failed",
+        response: data,
+      });
+    }
+    return data;
+  }
+
+  me() {
+    return this.request("GET", "/me");
+  }
+
+  project(projectId) {
+    return projectId ? this.request("GET", `/projects/${projectId}`) : this.request("GET", "/project");
+  }
+
+  createProject(body) {
+    return this.request("POST", "/projects", { body });
+  }
+
+  listKeywords(projectId, options = {}) {
+    return this.request("GET", `/projects/${projectId}/keywords`, { query: { limit: options.limit } });
+  }
+
+  createKeyword(projectId, body) {
+    return this.request("POST", `/projects/${projectId}/keywords`, { body });
+  }
+
+  generateKeywords(projectId) {
+    return this.request("POST", `/projects/${projectId}/keywords/generate`, { body: {} });
+  }
+
+  keywordMetrics(projectId, keywords) {
+    return this.request("POST", `/projects/${projectId}/keyword-metrics`, { body: { keywords } });
+  }
+
+  listPosts(projectId, options = {}) {
+    return this.request("GET", `/projects/${projectId}/posts`, { query: { limit: options.limit } });
+  }
+
+  createPost(projectId, body) {
+    return this.request("POST", `/projects/${projectId}/posts`, { body });
+  }
+
+  getPost(projectId, postId) {
+    return this.request("GET", `/projects/${projectId}/posts/${postId}`);
+  }
+
+  updatePost(projectId, postId, body) {
+    return this.request("PATCH", `/projects/${projectId}/posts/${postId}`, { body });
+  }
+
+  generatePost(projectId, postId) {
+    return this.request("POST", `/projects/${projectId}/posts/${postId}/generate`, { body: {} });
+  }
+
+  publishPost(projectId, postId) {
+    return this.request("POST", `/projects/${projectId}/posts/${postId}/publish`, { body: {} });
+  }
+
+  listIntegrations(projectId) {
+    return this.request("GET", `/projects/${projectId}/integrations`);
+  }
+
+  integrationFields(projectId, provider) {
+    return this.request("GET", `/projects/${projectId}/integrations/${provider}/fields`);
+  }
+
+  integrationConnectUrl(projectId, provider) {
+    return this.request("POST", `/projects/${projectId}/integrations/${provider}/connect-url`, { body: {} });
+  }
+
+  saveIntegrationMapping(projectId, provider, body) {
+    return this.request("POST", `/projects/${projectId}/integrations/${provider}/mapping`, { body });
+  }
+
+  listWebhooks(projectId) {
+    return this.request("GET", `/projects/${projectId}/webhooks`);
+  }
+
+  createWebhook(projectId, body) {
+    return this.request("POST", `/projects/${projectId}/webhooks`, { body });
+  }
+
+  deleteWebhook(projectId, webhookId) {
+    return this.request("DELETE", `/projects/${projectId}/webhooks/${webhookId}`);
+  }
+}
+
+function safeJson(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,354 @@
+import { spawn } from "node:child_process";
+import { setTimeout as delay } from "node:timers/promises";
+import { clearStoredConfig, DEFAULT_API_BASE, resolveConfig, saveLogin } from "./config.mjs";
+import { createClient, GenseoApiError } from "./api-client.mjs";
+
+const DEFAULT_SCOPES = [
+  "projects:read",
+  "keywords:read",
+  "keywords:write",
+  "keywords:generate",
+  "posts:read",
+  "posts:write",
+  "posts:generate",
+  "posts:publish",
+  "integrations:read",
+  "integrations:write",
+  "webhooks:write",
+];
+
+export async function runCli(argv) {
+  const parsed = parseArgs(argv);
+  if (parsed.flags.help || parsed.positionals.length === 0) return printHelp();
+  if (parsed.flags.version) return console.log("genseo 0.1.0");
+
+  const [command, subcommand, ...rest] = parsed.positionals;
+  const flags = parsed.flags;
+
+  try {
+    if (command === "login") return login(flags);
+    if (command === "logout") return logout();
+    if (command === "me") return printJson(await (await createClient(flagsToConfig(flags))).me());
+    if (command === "project") return project(subcommand, rest, flags);
+    if (command === "keywords") return keywords(subcommand, rest, flags);
+    if (command === "posts") return posts(subcommand, rest, flags);
+    if (command === "integrations") return integrations(subcommand, rest, flags);
+    if (command === "webhooks") return webhooks(subcommand, rest, flags);
+  } catch (error) {
+    if (error instanceof GenseoApiError) {
+      const suffix = error.code ? ` (${error.code})` : "";
+      throw new Error(`Genseo API error${suffix}: ${error.message}`);
+    }
+    throw error;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+async function login(flags) {
+  const apiBase = flags["api-base"] || flags.apiBase || DEFAULT_API_BASE;
+  const config = await resolveConfig({ apiBase });
+  const authBase = flags["auth-base"] || flags.authBase || config.authBase;
+
+  if (flags["api-key"] || flags.apiKey) {
+    const apiKey = flags["api-key"] || flags.apiKey;
+    const client = await createClient({ apiBase, authBase, apiKey });
+    const me = await client.me();
+    await saveLogin({ apiBase: config.apiBase, authBase, apiKey });
+    console.log("API key saved.");
+    console.log(`Project: ${me.project.id}`);
+    return;
+  }
+
+  const client = await createClient({ apiBase, authBase, apiKey: "not-needed" });
+  const scopes = stringList(flags.scopes || flags.scope).length ? stringList(flags.scopes || flags.scope) : DEFAULT_SCOPES;
+  const start = await client.authRequest("POST", "/oauth/device/code", {
+    body: {
+      client_name: flags["client-name"] || flags.clientName || "Genseo CLI",
+      scopes,
+      project_id: flags["project-id"] || flags.projectId,
+    },
+  });
+
+  console.log(`Open this URL to authorize the CLI:\n${start.verification_uri}`);
+  console.log(`Code: ${start.user_code}`);
+  if (!flags["no-open"]) openBrowser(start.verification_uri);
+
+  const intervalMs = Math.max(Number(start.interval || 5), 1) * 1000;
+  const deadline = Date.now() + Math.max(Number(start.expires_in || 600), 60) * 1000;
+
+  while (Date.now() < deadline) {
+    await delay(intervalMs);
+    try {
+      const token = await client.authRequest("POST", "/oauth/device/token", {
+        body: {
+          grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+          device_code: start.device_code,
+        },
+      });
+      await saveLogin({
+        apiBase: token.api_base_url || config.apiBase,
+        authBase,
+        apiKey: token.access_token,
+      });
+      console.log("Login successful.");
+      console.log(`Project: ${token.project_id}`);
+      return;
+    } catch (error) {
+      if (error instanceof GenseoApiError && error.code === "authorization_pending") {
+        process.stdout.write(".");
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  throw new Error("Login expired. Run `genseo login` again.");
+}
+
+async function logout() {
+  await clearStoredConfig();
+  console.log("Logged out.");
+}
+
+async function project(subcommand, _rest, flags) {
+  const client = await createClient(flagsToConfig(flags));
+  const projectId = flags["project-id"] || flags.projectId;
+  if (!subcommand || subcommand === "get") return printJson(await client.project(projectId));
+  if (subcommand === "create") {
+    if (!flags.domain) throw new Error("Usage: genseo project create --domain example.com");
+    return printJson(await client.createProject(compact({
+      domain: flags.domain,
+      name: flags.name,
+      description: flags.description,
+      category: flags.category,
+      business_type: flags["business-type"] || flags.businessType,
+      region: flags.region,
+      language_code: flags["language-code"] || flags.languageCode || flags.language,
+      sitemap_url: flags["sitemap-url"] || flags.sitemapUrl,
+      blog_url: flags["blog-url"] || flags.blogUrl,
+      business_goal: flags["business-goal"] || flags.businessGoal,
+      faqs: jsonFlag(flags["faqs-json"] || flags.faqsJson),
+      competitors: jsonFlag(flags["competitors-json"] || flags.competitorsJson),
+      ctas: jsonFlag(flags["ctas-json"] || flags.ctasJson),
+      generate_keywords: booleanFlag(flags["generate-keywords"] || flags.generateKeywords),
+      issue_api_key: booleanFlag(flags["issue-api-key"] || flags.issueApiKey),
+      api_key_name: flags["api-key-name"] || flags.apiKeyName,
+      api_key_scopes: stringList(flags["api-key-scopes"] || flags.apiKeyScopes),
+    })));
+  }
+  throw new Error(`Unknown project command: ${subcommand}`);
+}
+
+async function keywords(subcommand, rest, flags) {
+  const client = await createClient(flagsToConfig(flags));
+  const projectId = await resolveProjectId(client, flags);
+  if (subcommand === "list") return printJson(await client.listKeywords(projectId, { limit: flags.limit }));
+  if (subcommand === "add") {
+    const keyword = rest.join(" ").trim() || flags.keyword;
+    if (!keyword) throw new Error("Usage: genseo keywords add <keyword>");
+    return printJson(await client.createKeyword(projectId, {
+      keyword,
+      volume: numberOrNull(flags.volume),
+      kd: numberOrNull(flags.kd),
+      intent: flags.intent,
+      source: flags.source || "cli",
+    }));
+  }
+  if (subcommand === "generate") return printJson(await client.generateKeywords(projectId));
+  if (subcommand === "metrics") {
+    const values = rest.length ? rest : stringList(flags.keywords);
+    if (!values.length) throw new Error("Usage: genseo keywords metrics <keyword...>");
+    return printJson(await client.keywordMetrics(projectId, values));
+  }
+  throw new Error(`Unknown keywords command: ${subcommand}`);
+}
+
+async function posts(subcommand, rest, flags) {
+  const client = await createClient(flagsToConfig(flags));
+  const projectId = await resolveProjectId(client, flags);
+  if (subcommand === "list") return printJson(await client.listPosts(projectId, { limit: flags.limit }));
+  if (subcommand === "get") return printJson(await client.getPost(projectId, required(rest[0], "post id")));
+  if (subcommand === "create") {
+    const title = flags.title || rest.join(" ").trim();
+    if (!title) throw new Error("Usage: genseo posts create --title \"Title\"");
+    return printJson(await client.createPost(projectId, {
+      title,
+      keyword_id: flags["keyword-id"] || flags.keywordId,
+      scheduled_date: flags["scheduled-date"] || flags.scheduledDate,
+      status: flags.status,
+      draft_only: flags["draft-only"] !== "false",
+      content: flags["content-json"] ? JSON.parse(flags["content-json"]) : undefined,
+    }));
+  }
+  if (subcommand === "update") {
+    const postId = required(rest[0], "post id");
+    const body = compact({
+      title: flags.title,
+      status: flags.status,
+      scheduled_date: flags["scheduled-date"] || flags.scheduledDate,
+      meta_description: flags["meta-description"] || flags.metaDescription,
+      content: flags["content-json"] ? JSON.parse(flags["content-json"]) : undefined,
+    });
+    return printJson(await client.updatePost(projectId, postId, body));
+  }
+  if (subcommand === "generate") return printJson(await client.generatePost(projectId, required(rest[0], "post id")));
+  if (subcommand === "publish") return printJson(await client.publishPost(projectId, required(rest[0], "post id")));
+  throw new Error(`Unknown posts command: ${subcommand}`);
+}
+
+async function integrations(subcommand, rest, flags) {
+  const client = await createClient(flagsToConfig(flags));
+  const projectId = await resolveProjectId(client, flags);
+  if (subcommand === "list") return printJson(await client.listIntegrations(projectId));
+  if (subcommand === "fields") return printJson(await client.integrationFields(projectId, required(rest[0] || flags.provider, "provider")));
+  if (subcommand === "connect-url") return printJson(await client.integrationConnectUrl(projectId, required(rest[0] || flags.provider, "provider")));
+  if (subcommand === "mapping") {
+    const provider = required(rest[0] || flags.provider, "provider");
+    return printJson(await client.saveIntegrationMapping(projectId, provider, {
+      connection_id: flags["connection-id"] || flags.connectionId,
+      site_id: flags["site-id"] || flags.siteId,
+      collection_id: flags["collection-id"] || flags.collectionId,
+      blog_id: flags["blog-id"] || flags.blogId,
+      field_map: flags["field-map-json"] ? JSON.parse(flags["field-map-json"]) : undefined,
+    }));
+  }
+  throw new Error(`Unknown integrations command: ${subcommand}`);
+}
+
+async function webhooks(subcommand, rest, flags) {
+  const client = await createClient(flagsToConfig(flags));
+  const projectId = await resolveProjectId(client, flags);
+  if (subcommand === "list") return printJson(await client.listWebhooks(projectId));
+  if (subcommand === "create") {
+    const targetUrl = flags["target-url"] || flags.targetUrl || rest[0];
+    if (!targetUrl) throw new Error("Usage: genseo webhooks create --target-url https://example.com/hook");
+    return printJson(await client.createWebhook(projectId, {
+      target_url: targetUrl,
+      event: flags.event,
+      secret: flags.secret,
+    }));
+  }
+  if (subcommand === "delete") return printJson(await client.deleteWebhook(projectId, required(rest[0], "webhook id")));
+  throw new Error(`Unknown webhooks command: ${subcommand}`);
+}
+
+async function resolveProjectId(client, flags) {
+  const projectId = flags["project-id"] || flags.projectId;
+  if (projectId) return projectId;
+  const me = await client.me();
+  return me.project.id;
+}
+
+function parseArgs(argv) {
+  const flags = {};
+  const positionals = [];
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--") {
+      positionals.push(...argv.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const [rawKey, rawValue] = arg.slice(2).split("=", 2);
+      const key = rawKey;
+      if (rawValue !== undefined) {
+        flags[key] = rawValue;
+      } else if (argv[i + 1] && !argv[i + 1].startsWith("--")) {
+        flags[key] = argv[i + 1];
+        i += 1;
+      } else {
+        flags[key] = true;
+      }
+      continue;
+    }
+    positionals.push(arg);
+  }
+  return { flags, positionals };
+}
+
+function flagsToConfig(flags) {
+  return {
+    apiBase: flags["api-base"] || flags.apiBase,
+    authBase: flags["auth-base"] || flags.authBase,
+    apiKey: flags["api-key"] || flags.apiKey,
+  };
+}
+
+function printJson(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+function required(value, name) {
+  if (!value) throw new Error(`Missing ${name}.`);
+  return value;
+}
+
+function compact(obj) {
+  return Object.fromEntries(Object.entries(obj).filter(([, value]) => value !== undefined));
+}
+
+function numberOrNull(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : undefined;
+}
+
+function booleanFlag(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  if (value === true) return true;
+  if (value === false) return false;
+  return !["0", "false", "no", "off"].includes(String(value).toLowerCase());
+}
+
+function jsonFlag(value) {
+  if (value === undefined || value === null || value === "") return undefined;
+  return JSON.parse(String(value));
+}
+
+function stringList(value) {
+  if (!value) return [];
+  if (Array.isArray(value)) return value;
+  return String(value).split(",").map((item) => item.trim()).filter(Boolean);
+}
+
+function openBrowser(url) {
+  const platform = process.platform;
+  const command = platform === "darwin" ? "open" : platform === "win32" ? "cmd" : "xdg-open";
+  const args = platform === "win32" ? ["/c", "start", "", url] : [url];
+  const child = spawn(command, args, { detached: true, stdio: "ignore" });
+  child.unref();
+}
+
+function printHelp() {
+  console.log(`Genseo CLI
+
+Usage:
+  genseo login [--api-base https://api.genseo.co/v1] [--no-open]
+  genseo login --api-key gs_live_...
+  genseo logout
+  genseo me
+  genseo project get
+  genseo project create --domain example.com --name "Example" [--generate-keywords] [--issue-api-key]
+  genseo keywords list [--limit 50]
+  genseo keywords add "keyword" [--volume 100] [--kd 20]
+  genseo keywords generate
+  genseo keywords metrics "keyword one" "keyword two"
+  genseo posts list [--limit 50]
+  genseo posts create --title "Post title" [--keyword-id id]
+  genseo posts get <postId>
+  genseo posts update <postId> [--title "New title"] [--status draft]
+  genseo posts generate <postId>
+  genseo posts publish <postId>
+  genseo integrations list
+  genseo integrations fields <provider>
+  genseo integrations connect-url <provider>
+  genseo integrations mapping <provider> --connection-id id --field-map-json '{"title":"name"}'
+  genseo webhooks list
+  genseo webhooks create --target-url https://example.com/hook [--event post.published]
+  genseo webhooks delete <webhookId>
+
+Auth:
+  Prefer \`genseo login\`, or set GENSEO_API_KEY and GENSEO_API_BASE.
+`);
+}

package/src/config.mjs

@@ -0,0 +1,65 @@
+import { mkdir, readFile, writeFile, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+export const DEFAULT_API_BASE = "https://api.genseo.co/v1";
+export const DEFAULT_AUTH_BASE = "https://api.genseo.co";
+
+function configPath() {
+  return process.env.GENSEO_CONFIG_FILE || join(homedir(), ".genseo", "config.json");
+}
+
+export async function readStoredConfig() {
+  try {
+    return JSON.parse(await readFile(configPath(), "utf8"));
+  } catch {
+    return {};
+  }
+}
+
+export async function writeStoredConfig(config) {
+  const file = configPath();
+  await mkdir(dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+
+export async function clearStoredConfig() {
+  await rm(configPath(), { force: true });
+}
+
+export async function resolveConfig(overrides = {}) {
+  const stored = await readStoredConfig();
+  const apiBase =
+    overrides.apiBase ||
+    process.env.GENSEO_API_BASE ||
+    stored.apiBase ||
+    DEFAULT_API_BASE;
+  const apiKey =
+    overrides.apiKey ||
+    process.env.GENSEO_API_KEY ||
+    stored.apiKey ||
+    "";
+
+  const normalizedApiBase = String(apiBase).replace(/\/$/, "");
+  const authBase =
+    overrides.authBase ||
+    process.env.GENSEO_AUTH_BASE ||
+    stored.authBase ||
+    normalizedApiBase.replace(/\/v1$/, "");
+
+  return {
+    apiBase: normalizedApiBase,
+    authBase: String(authBase).replace(/\/$/, ""),
+    apiKey,
+  };
+}
+
+export async function saveLogin({ apiBase, authBase, apiKey }) {
+  const current = await readStoredConfig();
+  await writeStoredConfig({
+    ...current,
+    apiBase: apiBase.replace(/\/$/, ""),
+    authBase: authBase.replace(/\/$/, ""),
+    apiKey,
+  });
+}

package/src/mcp-server.mjs

@@ -0,0 +1,116 @@
+import { createClient } from "./api-client.mjs";
+import { callTool, tools } from "./mcp-tools.mjs";
+
+export async function runMcpServer() {
+  const transport = new StdioJsonRpcTransport(process.stdin, process.stdout);
+  const client = await createClient();
+
+  transport.onMessage(async (message) => {
+    try {
+      if (message.method === "initialize") {
+        return transport.respond(message.id, {
+          protocolVersion: message.params?.protocolVersion || "2024-11-05",
+          capabilities: { tools: {} },
+          serverInfo: { name: "genseo-mcp", version: "0.1.0" },
+        });
+      }
+
+      if (message.method === "notifications/initialized") {
+        return;
+      }
+
+      if (message.method === "tools/list") {
+        return transport.respond(message.id, { tools });
+      }
+
+      if (message.method === "ping") {
+        return transport.respond(message.id, {});
+      }
+
+      if (message.method === "resources/list") {
+        return transport.respond(message.id, { resources: [] });
+      }
+
+      if (message.method === "prompts/list") {
+        return transport.respond(message.id, { prompts: [] });
+      }
+
+      if (message.method === "tools/call") {
+        const name = message.params?.name;
+        const args = message.params?.arguments || {};
+        const result = await callTool(client, name, args);
+        return transport.respond(message.id, {
+          content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        });
+      }
+
+      return transport.error(message.id, -32601, `Method not found: ${message.method}`);
+    } catch (error) {
+      return transport.respond(message.id, {
+        isError: true,
+        content: [{
+          type: "text",
+          text: error instanceof Error ? error.message : String(error),
+        }],
+      });
+    }
+  });
+
+  transport.start();
+}
+
+class StdioJsonRpcTransport {
+  constructor(input, output) {
+    this.input = input;
+    this.output = output;
+    this.buffer = Buffer.alloc(0);
+    this.handlers = [];
+  }
+
+  onMessage(handler) {
+    this.handlers.push(handler);
+  }
+
+  start() {
+    this.input.on("data", (chunk) => {
+      this.buffer = Buffer.concat([this.buffer, chunk]);
+      this.readMessages();
+    });
+  }
+
+  readMessages() {
+    while (true) {
+      const headerEnd = this.buffer.indexOf("\r\n\r\n");
+      if (headerEnd === -1) return;
+      const header = this.buffer.slice(0, headerEnd).toString("utf8");
+      const match = header.match(/Content-Length:\s*(\d+)/i);
+      if (!match) {
+        this.buffer = this.buffer.slice(headerEnd + 4);
+        continue;
+      }
+      const length = Number(match[1]);
+      const bodyStart = headerEnd + 4;
+      const bodyEnd = bodyStart + length;
+      if (this.buffer.length < bodyEnd) return;
+      const body = this.buffer.slice(bodyStart, bodyEnd).toString("utf8");
+      this.buffer = this.buffer.slice(bodyEnd);
+      const message = JSON.parse(body);
+      for (const handler of this.handlers) void handler(message);
+    }
+  }
+
+  respond(id, result) {
+    if (id === undefined || id === null) return;
+    this.send({ jsonrpc: "2.0", id, result });
+  }
+
+  error(id, code, message) {
+    if (id === undefined || id === null) return;
+    this.send({ jsonrpc: "2.0", id, error: { code, message } });
+  }
+
+  send(message) {
+    const body = JSON.stringify(message);
+    this.output.write(`Content-Length: ${Buffer.byteLength(body, "utf8")}\r\n\r\n${body}`);
+  }
+}

package/src/mcp-tools.mjs

@@ -0,0 +1,257 @@
+export const tools = [
+  {
+    name: "genseo_me",
+    description: "Return API key metadata and the bound Genseo project. Call this first.",
+    inputSchema: objectSchema({}),
+  },
+  {
+    name: "genseo_project_get",
+    description: "Read the bound Genseo project.",
+    inputSchema: objectSchema({ project_id: stringProp("Optional explicit project id. Must match the bound project.") }),
+  },
+  {
+    name: "genseo_project_create",
+    description: "Create a new Genseo project in the same workspace. Requires projects:write and an existing active paid project in the workspace.",
+    inputSchema: objectSchema({
+      domain: stringProp("Project domain, e.g. example.com."),
+      name: stringProp("Optional project name."),
+      description: stringProp("Optional business description."),
+      category: stringProp("Optional category."),
+      business_type: stringProp("Optional business type."),
+      region: stringProp("Optional target region."),
+      language_code: stringProp("Optional language code."),
+      sitemap_url: stringProp("Optional sitemap URL."),
+      blog_url: stringProp("Optional blog URL."),
+      business_goal: stringProp("Optional business goal."),
+      faqs: { type: "array", items: { type: "object", additionalProperties: true }, description: "Optional FAQ objects." },
+      competitors: { type: "array", items: { type: "object", additionalProperties: true }, description: "Optional competitor objects." },
+      ctas: { type: "array", items: { type: "object", additionalProperties: true }, description: "Optional CTA objects." },
+      generate_keywords: { type: "boolean", description: "Start keyword generation after creation." },
+      issue_api_key: { type: "boolean", description: "Issue a new one-time API key for the new project." },
+      api_key_name: stringProp("Name for the new API key."),
+      api_key_scopes: { type: "array", items: { type: "string" }, description: "Scopes for the new API key." },
+    }, ["domain"]),
+  },
+  {
+    name: "genseo_keywords_list",
+    description: "List keywords for the bound project.",
+    inputSchema: objectSchema({ project_id: projectIdProp(), limit: numberProp("Maximum number of keywords.") }),
+  },
+  {
+    name: "genseo_keywords_create",
+    description: "Add one custom keyword to the bound project.",
+    inputSchema: objectSchema({
+      project_id: projectIdProp(),
+      keyword: stringProp("Keyword text."),
+      volume: numberProp("Optional search volume."),
+      kd: numberProp("Optional keyword difficulty 1-100."),
+      intent: stringProp("Optional intent."),
+    }, ["keyword"]),
+  },
+  {
+    name: "genseo_keywords_generate",
+    description: "Start keyword generation for the bound project.",
+    inputSchema: objectSchema({ project_id: projectIdProp() }),
+  },
+  {
+    name: "genseo_keyword_metrics",
+    description: "Read stored keyword metrics for given keywords.",
+    inputSchema: objectSchema({
+      project_id: projectIdProp(),
+      keywords: { type: "array", items: { type: "string" }, description: "Keywords to look up." },
+    }, ["keywords"]),
+  },
+  {
+    name: "genseo_posts_list",
+    description: "List posts in the bound project.",
+    inputSchema: objectSchema({ project_id: projectIdProp(), limit: numberProp("Maximum number of posts.") }),
+  },
+  {
+    name: "genseo_posts_create_draft",
+    description: "Create a draft post. Prefer this before generation or publishing.",
+    inputSchema: objectSchema({
+      project_id: projectIdProp(),
+      title: stringProp("Draft post title."),
+      keyword_id: stringProp("Optional keyword id."),
+      scheduled_date: stringProp("Optional scheduled date."),
+      content: { description: "Optional EditorJS/Tiptap-compatible content JSON." },
+    }, ["title"]),
+  },
+  {
+    name: "genseo_posts_get",
+    description: "Read a single post from the bound project.",
+    inputSchema: objectSchema({ project_id: projectIdProp(), post_id: stringProp("Post id.") }, ["post_id"]),
+  },
+  {
+    name: "genseo_posts_update",
+    description: "Patch a post. Preserve existing user content unless intentionally changing it.",
+    inputSchema: objectSchema({
+      project_id: projectIdProp(),
+      post_id: stringProp("Post id."),
+      title: stringProp("Optional title."),
+      status: stringProp("Optional status."),
+      scheduled_date: stringProp("Optional scheduled date."),
+      meta_description: stringProp("Optional meta description."),
+      content: { description: "Optional content JSON." },
+    }, ["post_id"]),
+  },
+  {
+    name: "genseo_posts_generate",
+    description: "Start async AI generation for a post.",
+    inputSchema: objectSchema({ project_id: projectIdProp(), post_id: stringProp("Post id.") }, ["post_id"]),
+  },
+  {
+    name: "genseo_posts_publish",
+    description: "Publish a post through configured integrations. Ask user before calling unless autonomous publishing is explicitly enabled.",
+    inputSchema: objectSchema({ project_id: projectIdProp(), post_id: stringProp("Post id.") }, ["post_id"]),
+  },
+  {
+    name: "genseo_integrations_list",
+    description: "List integration readiness for the bound project.",
+    inputSchema: objectSchema({ project_id: projectIdProp() }),
+  },
+  {
+    name: "genseo_integration_fields",
+    description: "List mappable fields for a provider.",
+    inputSchema: objectSchema({ project_id: projectIdProp(), provider: providerProp() }, ["provider"]),
+  },
+  {
+    name: "genseo_integration_connect_url",
+    description: "Create a browser URL for connecting a publishing provider.",
+    inputSchema: objectSchema({ project_id: projectIdProp(), provider: providerProp() }, ["provider"]),
+  },
+  {
+    name: "genseo_integration_mapping_save",
+    description: "Save a supported integration field mapping.",
+    inputSchema: objectSchema({
+      project_id: projectIdProp(),
+      provider: providerProp(),
+      connection_id: stringProp("Connection id."),
+      site_id: stringProp("Provider site id."),
+      collection_id: stringProp("Provider collection id."),
+      blog_id: stringProp("Provider blog id."),
+      field_map: { type: "object", additionalProperties: true, description: "Provider field map." },
+    }, ["provider", "connection_id"]),
+  },
+  {
+    name: "genseo_webhooks_list",
+    description: "List webhooks for the bound project.",
+    inputSchema: objectSchema({ project_id: projectIdProp() }),
+  },
+  {
+    name: "genseo_webhooks_create",
+    description: "Create a webhook for the bound project.",
+    inputSchema: objectSchema({
+      project_id: projectIdProp(),
+      target_url: stringProp("Webhook URL."),
+      event: stringProp("Event name, defaults to post.published."),
+      secret: stringProp("Optional webhook secret."),
+    }, ["target_url"]),
+  },
+  {
+    name: "genseo_webhooks_delete",
+    description: "Delete a webhook from the bound project.",
+    inputSchema: objectSchema({ project_id: projectIdProp(), webhook_id: stringProp("Webhook id.") }, ["webhook_id"]),
+  },
+];
+
+export async function callTool(client, name, args = {}) {
+  switch (name) {
+    case "genseo_me":
+      return client.me();
+    case "genseo_project_get":
+      return client.project(args.project_id);
+    case "genseo_project_create":
+      return client.createProject(pick(args, [
+        "domain",
+        "name",
+        "description",
+        "category",
+        "business_type",
+        "region",
+        "language_code",
+        "sitemap_url",
+        "blog_url",
+        "business_goal",
+        "faqs",
+        "competitors",
+        "ctas",
+        "generate_keywords",
+        "issue_api_key",
+        "api_key_name",
+        "api_key_scopes",
+      ]));
+    case "genseo_keywords_list":
+      return client.listKeywords(await resolveProjectId(client, args), { limit: args.limit });
+    case "genseo_keywords_create":
+      return client.createKeyword(await resolveProjectId(client, args), pick(args, ["keyword", "volume", "kd", "intent"]));
+    case "genseo_keywords_generate":
+      return client.generateKeywords(await resolveProjectId(client, args));
+    case "genseo_keyword_metrics":
+      return client.keywordMetrics(await resolveProjectId(client, args), args.keywords || []);
+    case "genseo_posts_list":
+      return client.listPosts(await resolveProjectId(client, args), { limit: args.limit });
+    case "genseo_posts_create_draft":
+      return client.createPost(await resolveProjectId(client, args), {
+        title: args.title,
+        keyword_id: args.keyword_id,
+        scheduled_date: args.scheduled_date,
+        content: args.content,
+        draft_only: true,
+      });
+    case "genseo_posts_get":
+      return client.getPost(await resolveProjectId(client, args), args.post_id);
+    case "genseo_posts_update":
+      return client.updatePost(await resolveProjectId(client, args), args.post_id, pick(args, ["title", "status", "scheduled_date", "meta_description", "content"]));
+    case "genseo_posts_generate":
+      return client.generatePost(await resolveProjectId(client, args), args.post_id);
+    case "genseo_posts_publish":
+      return client.publishPost(await resolveProjectId(client, args), args.post_id);
+    case "genseo_integrations_list":
+      return client.listIntegrations(await resolveProjectId(client, args));
+    case "genseo_integration_fields":
+      return client.integrationFields(await resolveProjectId(client, args), args.provider);
+    case "genseo_integration_connect_url":
+      return client.integrationConnectUrl(await resolveProjectId(client, args), args.provider);
+    case "genseo_integration_mapping_save":
+      return client.saveIntegrationMapping(await resolveProjectId(client, args), args.provider, pick(args, ["connection_id", "site_id", "collection_id", "blog_id", "field_map"]));
+    case "genseo_webhooks_list":
+      return client.listWebhooks(await resolveProjectId(client, args));
+    case "genseo_webhooks_create":
+      return client.createWebhook(await resolveProjectId(client, args), pick(args, ["target_url", "event", "secret"]));
+    case "genseo_webhooks_delete":
+      return client.deleteWebhook(await resolveProjectId(client, args), args.webhook_id);
+    default:
+      throw new Error(`Unknown tool: ${name}`);
+  }
+}
+
+async function resolveProjectId(client, args) {
+  if (args.project_id) return args.project_id;
+  const me = await client.me();
+  return me.project.id;
+}
+
+function pick(obj, keys) {
+  return Object.fromEntries(keys.filter((key) => obj[key] !== undefined).map((key) => [key, obj[key]]));
+}
+
+function objectSchema(properties, required = []) {
+  return { type: "object", properties, required, additionalProperties: false };
+}
+
+function stringProp(description) {
+  return { type: "string", description };
+}
+
+function numberProp(description) {
+  return { type: "number", description };
+}
+
+function projectIdProp() {
+  return stringProp("Optional project id. If omitted, the server calls /me and uses the bound project.");
+}
+
+function providerProp() {
+  return { type: "string", enum: ["webflow", "shopify", "wordpress", "framer", "wix"], description: "Integration provider." };
+}