user-majico-mcp 0.7.5

package/README.md

@@ -0,0 +1,144 @@
+# user-majico MCP server
+
+MCP server for [Majico.xyz](https://majico.xyz): read (and limited write) tools so coding agents can pull brand guidelines, design tokens, studio canvas, and export manifests.
+
+**Requirements:** Majico account with tokens. Cursor humans connect via **OAuth** (no API key in `mcp.json`). API keys are for automation/stdio only.
+
+## Install
+
+```bash
+npx -y user-majico-mcp@0.4.1
+```
+
+## Environment variables (v0.2+)
+
+Set once in MCP config — tools do not require `projectId` / `apiKey` on every call:
+
+| Variable            | Description                                                                     |
+| ------------------- | ------------------------------------------------------------------------------- |
+| `MAJICO_API_URL`    | API base (default `http://localhost:3000`; production `https://api.majico.xyz`) |
+| `MAJICO_PROJECT_ID` | Project UUID                                                                    |
+| `MAJICO_API_KEY`    | Project API key                                                                 |
+
+Per-call overrides in tool arguments still work.
+
+## Tools
+
+| Tool                       | Description                                                                                           |
+| -------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `get_brand_profile`        | Archetypes, niche intent                                                                              |
+| `get_design_tokens`        | Palette and fonts                                                                                     |
+| `get_logo_svg`             | Selected logo SVG                                                                                     |
+| `get_guidelines`           | Markdown + LLM prompt                                                                                 |
+| `get_design_md`            | DESIGN.md markdown                                                                                    |
+| `get_studio_canvas`        | Studio canvas snapshot                                                                                |
+| `get_export_manifest`      | Export file list                                                                                      |
+| `download_export_zip`      | Full BRAND.md / DESIGN.md / tokens ZIP (base64 in MCP response)                                       |
+| `submit_brief`             | Submit product brief + enqueue niche research                                                         |
+| `update_studio_html_frame` | Patch one `htmlFrame` (requires `elementId`, `html`)                                                  |
+| `generate_asset`           | Enqueue harness jobs (`landing-page`, `investor-pack`, `investor-one-pager`, `investor-data-room`, …) |
+| `get_asset_status`         | Poll harness job status                                                                               |
+
+### Cursor agent example: `generate_asset` for investor pack
+
+After brand chain, palette, GTM, team, and traction are ready:
+
+```json
+{
+  "tool": "generate_asset",
+  "arguments": {
+    "skillId": "investor-pack",
+    "params": {
+      "team": {
+        "members": [
+          { "name": "Alex Kim", "role": "CEO", "bio": "ex-Stripe PM" }
+        ]
+      },
+      "traction": {
+        "metrics": [{ "label": "Waitlist", "value": "1,200" }]
+      },
+      "includeSlides": ["financials"]
+    }
+  }
+}
+```
+
+Poll with `get_asset_status({ jobId })`. Preflight failures return HTTP 422 with `code: "investor_pack_preflight_blocked"` and a `blocked` reason (`brand`, `gtm`, `team`, `traction`, …).
+
+### Phase 2: one-pager and data room (after deck exists on canvas)
+
+```json
+{
+  "tool": "generate_asset",
+  "arguments": {
+    "skillId": "investor-one-pager"
+  }
+}
+```
+
+```json
+{
+  "tool": "generate_asset",
+  "arguments": {
+    "skillId": "investor-data-room"
+  }
+}
+```
+
+Both require a `harness-investor-pack` element on the Studio canvas (generate `investor-pack` first). Without a deck, jobs return a stub with `canvasUrl` pointing to finish the deck.
+
+## Cursor `.cursor/mcp.json` (OAuth — preferred)
+
+```json
+{
+  "mcpServers": {
+    "majico": {
+      "url": "https://api.majico.xyz/mcp"
+    }
+  }
+}
+```
+
+Complete **Connect** in Cursor Settings → MCP. Use `list_projects` and pass `projectId` on tool calls to switch scope.
+
+## Cursor `.cursor/mcp.json` (stdio — automation / local)
+
+```json
+{
+  "mcpServers": {
+    "majico": {
+      "command": "npx",
+      "args": ["-y", "user-majico-mcp@0.4.1"],
+      "env": {
+        "MAJICO_API_URL": "https://api.majico.xyz",
+        "MAJICO_PROJECT_ID": "<uuid>",
+        "MAJICO_API_KEY": "<key>"
+      }
+    }
+  }
+}
+```
+
+## HTTP MCP (hosted)
+
+**OAuth (Cursor humans):** `https://api.majico.xyz/mcp` — Connect in Cursor; no headers in `mcp.json`.
+
+**API key (automation only):**
+
+```
+Authorization: Bearer <project_api_key>
+X-Majico-Project-Id: <uuid>
+```
+
+## Development
+
+```bash
+cd packages/user-majico-mcp
+npm install
+npm run build
+npm test
+```
+
+## License
+
+MIT

package/dist/agent-bootstrap.d.ts

@@ -0,0 +1,8 @@
+export declare function readAgentEnv(): {
+    baseUrl: string;
+    agentSecret: string;
+} | null;
+export declare function bootstrapProjectViaAgent(name: string): Promise<{
+    project: Awaited<ReturnType<import("../../majico-sdk/dist/resources/agent-projects.js").AgentProjectsResource["bootstrap"]>>;
+    client: import("@majico/sdk").MajicoClient | null;
+}>;

package/dist/agent-bootstrap.js

@@ -0,0 +1,21 @@
+import { MajicoAgentClient } from "@majico/sdk";
+export function readAgentEnv() {
+    const agentSecret = process.env.MAJICO_AGENT_API_SECRET?.trim();
+    const baseUrl = process.env.MAJICO_API_URL?.trim() ||
+        process.env.MAJICO_AGENT_API_URL?.trim() ||
+        "https://majico.d3bu7.com";
+    if (!agentSecret)
+        return null;
+    return { baseUrl: baseUrl.replace(/\/$/, ""), agentSecret };
+}
+export async function bootstrapProjectViaAgent(name) {
+    const env = readAgentEnv();
+    if (!env) {
+        throw new Error("MAJICO_AGENT_API_SECRET is required for bootstrap_project (set in MCP env).");
+    }
+    const agent = new MajicoAgentClient({
+        baseUrl: env.baseUrl,
+        agentSecret: env.agentSecret,
+    });
+    return agent.bootstrapProject(name);
+}

package/dist/auth-prompt.d.ts

@@ -0,0 +1,13 @@
+/** Agent-facing copy for Majico MCP OAuth connect and plan gates. */
+export declare const MAJICO_MCP_CONNECT_PROMPT = "Majico is not connected. Ask the user to open Cursor Settings \u2192 MCP \u2192 majico \u2192 Connect and complete sign-in in the browser.";
+export declare const MAJICO_MCP_PLAN_REQUIRED_PROMPT = "Majico is connected, but this action needs more tokens. Ask the user to add tokens at https://majico.xyz/account/billing (Pro one-time or Creator subscription).";
+export declare const MAJICO_MCP_AUTH_AGENT_INSTRUCTIONS = "Display the message field verbatim to the user. Do not call other Majico tools until ping returns ok: true without authRequired.";
+export declare const AUTH_FIRST_STEP = " First call ping to verify auth. If ping fails, returns authRequired, or tools are unavailable, stop and ask the user to Connect in Cursor Settings \u2192 MCP \u2192 majico (call mcp_auth for the exact prompt).";
+export type McpAuthAction = "connect_oauth" | "upgrade_plan";
+export type McpAuthRequiredPayload = {
+    authRequired: true;
+    action: McpAuthAction;
+    message: string;
+    agentInstructions: string;
+};
+export declare function buildMcpAuthRequiredPayload(action: McpAuthAction, message?: string): McpAuthRequiredPayload;

package/dist/auth-prompt.js

@@ -0,0 +1,15 @@
+/** Agent-facing copy for Majico MCP OAuth connect and plan gates. */
+export const MAJICO_MCP_CONNECT_PROMPT = "Majico is not connected. Ask the user to open Cursor Settings → MCP → majico → Connect and complete sign-in in the browser.";
+export const MAJICO_MCP_PLAN_REQUIRED_PROMPT = "Majico is connected, but this action needs more tokens. Ask the user to add tokens at https://majico.xyz/account/billing (Pro one-time or Creator subscription).";
+export const MAJICO_MCP_AUTH_AGENT_INSTRUCTIONS = "Display the message field verbatim to the user. Do not call other Majico tools until ping returns ok: true without authRequired.";
+export const AUTH_FIRST_STEP = " First call ping to verify auth. If ping fails, returns authRequired, or tools are unavailable, stop and ask the user to Connect in Cursor Settings → MCP → majico (call mcp_auth for the exact prompt).";
+export function buildMcpAuthRequiredPayload(action, message = action === "upgrade_plan"
+    ? MAJICO_MCP_PLAN_REQUIRED_PROMPT
+    : MAJICO_MCP_CONNECT_PROMPT) {
+    return {
+        authRequired: true,
+        action,
+        message,
+        agentInstructions: MAJICO_MCP_AUTH_AGENT_INSTRUCTIONS,
+    };
+}

package/dist/client-disconnect.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Returns true when the client closed the MCP HTTP connection mid-request.
+ */
+export declare function isMcpClientDisconnectError(error: unknown): boolean;

package/dist/client-disconnect.js

@@ -0,0 +1,17 @@
+/**
+ * Returns true when the client closed the MCP HTTP connection mid-request.
+ */
+export function isMcpClientDisconnectError(error) {
+    if (!error || typeof error !== "object")
+        return false;
+    const err = error;
+    if (err.name === "AbortError")
+        return true;
+    if (err.code === "ECONNRESET" ||
+        err.code === "EPIPE" ||
+        err.code === "ERR_STREAM_PREMATURE_CLOSE") {
+        return true;
+    }
+    const message = typeof err.message === "string" ? err.message : "";
+    return message === "aborted" || message === "The operation was aborted";
+}

package/dist/credentials.d.ts

@@ -0,0 +1,40 @@
+import { MajicoClient } from "@majico/sdk";
+import { type McpAuthRequiredPayload } from "./auth-prompt.js";
+export type ResolvedCredentials = {
+    projectId: string;
+    apiKey: string;
+    baseUrl?: string;
+};
+export type CredentialSource = {
+    projectId?: string;
+    apiKey?: string;
+    /** Internal API base (e.g. http://127.0.0.1:3000) for server-side SDK calls */
+    baseUrl?: string;
+    /** Public origin for browser + preview links in interactive MCP results */
+    publicBaseUrl?: string;
+    /** Origin for MCP serverInfo icon URLs (defaults to publicBaseUrl; prod uses app host). */
+    iconBaseUrl?: string;
+    /** How the MCP session authenticated (set by HTTP transport). */
+    auth?: "oauth" | "api_key";
+    /** Authenticated Supabase user id when available (OAuth or derived from API key). */
+    userId?: string;
+    /** Include admin-only bootstrap tools in tools/list (requires agent secret). */
+    includeAdminTools?: boolean;
+    /** OAuth-only: resolve delegated project scope server-side without exposing API keys. */
+    resolveOAuthProject?: (projectId: string) => Promise<{
+        projectId: string;
+        apiKey: string;
+    } | {
+        error: string;
+    }>;
+    /** OAuth session is valid but the bound project lacks Pro/Creator MCP access. */
+    planRequired?: boolean;
+};
+export declare function readEnvCredentials(): CredentialSource;
+export type CredentialResolutionError = (McpAuthRequiredPayload & {
+    error: string;
+}) | {
+    error: string;
+};
+export declare function resolveCredentials(args?: CredentialSource, env?: CredentialSource): Promise<ResolvedCredentials | CredentialResolutionError>;
+export declare function createClientFromCredentials(creds: ResolvedCredentials): MajicoClient;

package/dist/credentials.js

@@ -0,0 +1,60 @@
+import { MajicoClient } from "@majico/sdk";
+import { buildMcpAuthRequiredPayload, MAJICO_MCP_CONNECT_PROMPT, MAJICO_MCP_PLAN_REQUIRED_PROMPT, } from "./auth-prompt.js";
+const ENV_PROJECT_ID = "MAJICO_PROJECT_ID";
+const ENV_API_KEY = "MAJICO_API_KEY";
+const ENV_API_URL = "MAJICO_API_URL";
+export function readEnvCredentials() {
+    return {
+        projectId: process.env[ENV_PROJECT_ID]?.trim() || undefined,
+        apiKey: process.env[ENV_API_KEY]?.trim() || undefined,
+        baseUrl: process.env[ENV_API_URL]?.trim() || undefined,
+    };
+}
+export async function resolveCredentials(args, env = readEnvCredentials()) {
+    const requestedProjectId = args?.projectId?.trim() || env.projectId;
+    const apiKey = args?.apiKey?.trim() || env.apiKey;
+    const baseUrl = args?.baseUrl?.trim() || env.baseUrl;
+    if (env.planRequired) {
+        return {
+            ...buildMcpAuthRequiredPayload("upgrade_plan"),
+            error: MAJICO_MCP_PLAN_REQUIRED_PROMPT,
+        };
+    }
+    if (env.resolveOAuthProject &&
+        requestedProjectId &&
+        env.projectId &&
+        requestedProjectId !== env.projectId &&
+        !args?.apiKey) {
+        const delegated = await env.resolveOAuthProject(requestedProjectId);
+        if ("error" in delegated)
+            return delegated;
+        return {
+            projectId: delegated.projectId,
+            apiKey: delegated.apiKey,
+            baseUrl,
+        };
+    }
+    if (!requestedProjectId || !apiKey) {
+        const oauthSession = env.auth === "oauth" || Boolean(env.resolveOAuthProject);
+        if (oauthSession) {
+            return {
+                ...buildMcpAuthRequiredPayload("connect_oauth"),
+                error: MAJICO_MCP_CONNECT_PROMPT,
+            };
+        }
+        return {
+            ...buildMcpAuthRequiredPayload("connect_oauth"),
+            error: MAJICO_MCP_CONNECT_PROMPT,
+        };
+    }
+    return { projectId: requestedProjectId, apiKey, baseUrl };
+}
+export function createClientFromCredentials(creds) {
+    const config = {
+        apiKey: creds.apiKey,
+        projectId: creds.projectId,
+        baseUrl: creds.baseUrl,
+        retry: { max: 2, retryOn: [429, 503] },
+    };
+    return new MajicoClient(config);
+}

package/dist/http-handler.d.ts

@@ -0,0 +1,6 @@
+import type { CredentialSource } from "./credentials.js";
+/**
+ * Stateless Streamable HTTP handler for Next.js / edge runtimes.
+ * Credentials from HTTP headers override env defaults for tool calls.
+ */
+export declare function handleMcpHttpRequest(request: Request, headerCredentials?: CredentialSource): Promise<Response>;

package/dist/http-handler.js

@@ -0,0 +1,28 @@
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { isMcpClientDisconnectError } from "./client-disconnect.js";
+import { createMajicoMcpServer } from "./server.js";
+/**
+ * Stateless Streamable HTTP handler for Next.js / edge runtimes.
+ * Credentials from HTTP headers override env defaults for tool calls.
+ */
+export async function handleMcpHttpRequest(request, headerCredentials) {
+    const transport = new WebStandardStreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+    });
+    const server = createMajicoMcpServer(headerCredentials);
+    await server.connect(transport);
+    try {
+        return await transport.handleRequest(request);
+    }
+    catch (error) {
+        if (isMcpClientDisconnectError(error) || request.signal.aborted) {
+            return new Response(null, { status: 499 });
+        }
+        throw error;
+    }
+    finally {
+        await transport.close().catch(() => undefined);
+        await server.close().catch(() => undefined);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * user-majico MCP server (stdio): brand profile, design tokens, logo, guidelines, studio.
+ * Set MAJICO_API_URL, MAJICO_PROJECT_ID, MAJICO_API_KEY once; per-call overrides still work.
+ */
+export { createMajicoMcpServer } from "./server.js";
+export { handleMcpHttpRequest } from "./http-handler.js";
+export { handleMajicoToolCall, listMcpTools, classifyMcpTool, MCP_LLM_TOOL_NAMES, partitionMcpToolNames, MAJICO_TOOLS, MAJICO_USER_TOOLS, MAJICO_ADMIN_BOOTSTRAP_TOOLS, MCP_SERVER_VERSION, } from "./tools.js";
+export type { McpToolKind } from "./tools.js";
+export { readEnvCredentials, resolveCredentials, createClientFromCredentials, } from "./credentials.js";
+export { AUTH_FIRST_STEP, MAJICO_MCP_AUTH_AGENT_INSTRUCTIONS, MAJICO_MCP_CONNECT_PROMPT, MAJICO_MCP_PLAN_REQUIRED_PROMPT, buildMcpAuthRequiredPayload, } from "./auth-prompt.js";
+export type { McpAuthAction, McpAuthRequiredPayload } from "./auth-prompt.js";

package/dist/index.js

@@ -0,0 +1,22 @@
+#!/usr/bin/env node
+/**
+ * user-majico MCP server (stdio): brand profile, design tokens, logo, guidelines, studio.
+ * Set MAJICO_API_URL, MAJICO_PROJECT_ID, MAJICO_API_KEY once; per-call overrides still work.
+ */
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { readEnvCredentials } from "./credentials.js";
+import { createMajicoMcpServer } from "./server.js";
+export { createMajicoMcpServer } from "./server.js";
+export { handleMcpHttpRequest } from "./http-handler.js";
+export { handleMajicoToolCall, listMcpTools, classifyMcpTool, MCP_LLM_TOOL_NAMES, partitionMcpToolNames, MAJICO_TOOLS, MAJICO_USER_TOOLS, MAJICO_ADMIN_BOOTSTRAP_TOOLS, MCP_SERVER_VERSION, } from "./tools.js";
+export { readEnvCredentials, resolveCredentials, createClientFromCredentials, } from "./credentials.js";
+export { AUTH_FIRST_STEP, MAJICO_MCP_AUTH_AGENT_INSTRUCTIONS, MAJICO_MCP_CONNECT_PROMPT, MAJICO_MCP_PLAN_REQUIRED_PROMPT, buildMcpAuthRequiredPayload, } from "./auth-prompt.js";
+async function main() {
+    const transport = new StdioServerTransport();
+    const server = createMajicoMcpServer(readEnvCredentials());
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/present-interactive.d.ts

@@ -0,0 +1,92 @@
+import type { McpContentBlock, PresentContext } from "./present-types.js";
+export type { McpContentBlock, PresentContext } from "./present-types.js";
+type PaletteOptionRow = {
+    optionId: string;
+    label: string;
+    isSelected: boolean;
+    swatches: {
+        light: string[];
+        dark: string[];
+    };
+    previewTokens?: {
+        light: Record<string, string>;
+        dark: Record<string, string>;
+    };
+};
+type PaletteCandidatesPayload = {
+    options?: PaletteOptionRow[];
+    selectedOptionId: string | null;
+    paletteTokens: {
+        light: Record<string, string>;
+        dark: Record<string, string>;
+    } | null;
+    headingFont?: string | null;
+    bodyFont?: string | null;
+    agentInstructions?: string;
+    projectId?: string | null;
+    projectName?: string | null;
+    previewToken?: string | null;
+    previewPickerUrl?: string | null;
+};
+type LogoCandidateRow = {
+    id: string;
+    kind: string;
+    previewSvg: string;
+    templateId?: string | null;
+    userRating?: string | null;
+};
+type LogoCandidatesPayload = {
+    selectedLogoTemplateId: string | null;
+    logoSvg: string | null;
+    logoFavorites: unknown[];
+    shortlistCount: number;
+    candidates: LogoCandidateRow[];
+    emptyReason?: string | null;
+    guidance?: string | null;
+    projectId?: string | null;
+    projectName?: string | null;
+    previewToken?: string | null;
+    previewPickerUrl?: string | null;
+};
+type CursorHandoffPayload = {
+    event: string;
+    browserUrl: string;
+    chatPrompt: string;
+};
+type CursorHandoffPayloadResponse = {
+    pending: boolean;
+    handoff: CursorHandoffPayload | null;
+};
+type TweetDraftsPayload = {
+    drafts?: Array<{
+        draftId: string;
+        text: string;
+    }>;
+    agentInstructions?: string;
+};
+export declare function pickPaletteOptionsForDisplay<T extends PaletteOptionRow>(options: T[], max?: number): T[];
+export declare function scoreReeldemoPaletteMatch(option: PaletteOptionRow): number;
+export declare function isReeldemoPaletteContext(ctx: PresentContext): boolean;
+export declare function buildPalettePreviewCardSvg(args: {
+    label: string;
+    index: number;
+    tokens: {
+        bg: string;
+        bgMuted: string;
+        text: string;
+        accent: string;
+    };
+    headingFont: string;
+    bodyFont: string;
+    width?: number;
+    height?: number;
+}): string;
+/**
+ * Rewrite absolute URLs whose host is bind-all onto the session public base,
+ * preserving path + query.
+ */
+export declare function rewritePreviewUrlOntoPublicBase(url: string, publicBaseUrl: string): string;
+export declare function presentLogoCandidates(data: LogoCandidatesPayload, ctx: PresentContext): Promise<McpContentBlock[]>;
+export declare function presentPaletteOptions(data: PaletteCandidatesPayload, ctx: PresentContext): Promise<McpContentBlock[]>;
+export declare function presentTweetDrafts(data: TweetDraftsPayload): McpContentBlock[];
+export declare function presentCursorHandoff(data: CursorHandoffPayloadResponse): McpContentBlock[];