user-majico-mcp 0.7.5

package/dist/tools/handle-tool-call-pre.js

@@ -0,0 +1,47 @@
+import { bootstrapProjectViaAgent } from "../agent-bootstrap.js";
+import { buildUiUxSkillsHandoffPayload, renderUiUxSkillsHandoffMarkdown, } from "../ui-ux-skills.js";
+import { buildMcpAuthRequiredPayload } from "../auth-prompt.js";
+import { toolError, toolJson, buildStableBrandMarkdown, clientFromArgs, } from "./tool-call-helpers.js";
+/** Pre-client tools and plan gate checks. */
+export async function handlePreClientToolCall(name, args, defaultCredentials) {
+    if (name === "bootstrap_project") {
+        if (!defaultCredentials?.includeAdminTools) {
+            return toolError("bootstrap_project is admin-only. Use create_project or list_projects after OAuth login, or pass X-Majico-Agent-Secret for server automation.");
+        }
+        const projectName = args?.name;
+        if (!projectName?.trim())
+            return toolError("name is required.");
+        const { project } = await bootstrapProjectViaAgent(projectName.trim());
+        return toolJson(project);
+    }
+    if (name === "generate_brand_md") {
+        return buildStableBrandMarkdown(args);
+    }
+    if (name === "get_ui_ux_skills") {
+        const clientOrError = await clientFromArgs(args, defaultCredentials);
+        if ("content" in clientOrError) {
+            return toolJson({
+                ...buildUiUxSkillsHandoffPayload(),
+                markdown: renderUiUxSkillsHandoffMarkdown(),
+                source: "static",
+                message: "Connect Majico MCP with project scope for DB-backed editable skills.",
+            });
+        }
+        const { client } = clientOrError;
+        return toolJson(await client.cursorSkills.list());
+    }
+    if (name === "mcp_auth") {
+        return toolJson(buildMcpAuthRequiredPayload("connect_oauth"));
+    }
+    if ((name === "ping" || name === "health") &&
+        defaultCredentials?.planRequired) {
+        return toolJson({
+            ok: false,
+            ...buildMcpAuthRequiredPayload("upgrade_plan"),
+            auth: defaultCredentials.auth ?? "oauth",
+            userId: defaultCredentials.userId ?? null,
+            projectId: defaultCredentials.projectId ?? null,
+        });
+    }
+    return null;
+}

package/dist/tools/handle-tool-call.d.ts

@@ -0,0 +1,3 @@
+import type { CredentialSource } from "../credentials.js";
+import { type ToolCallResult } from "./tool-call-helpers.js";
+export declare function handleMajicoToolCall(name: string, args: Record<string, unknown> | undefined, defaultCredentials?: CredentialSource): Promise<ToolCallResult>;

package/dist/tools/handle-tool-call.js

@@ -0,0 +1,56 @@
+import { buildMcpAuthRequiredPayload } from "../auth-prompt.js";
+import { toolError, toolAuthRequired, clientFromArgs, presentContext, } from "./tool-call-helpers.js";
+import { handlePreClientToolCall } from "./handle-tool-call-pre.js";
+import { dispatchBrandingStudioTool } from "./dispatch-branding-studio.js";
+import { dispatchPulseBlogTool } from "./dispatch-pulse-blog.js";
+import { dispatchResearchAssetsTool } from "./dispatch-research-assets.js";
+import { mcpSdkSurfaceError } from "../sdk-surface.js";
+function isMajicoErrorLike(err) {
+    if (!err || typeof err !== "object")
+        return false;
+    const e = err;
+    return (e.name === "MajicoError" &&
+        (typeof e.status === "number" || typeof e.code === "string"));
+}
+export async function handleMajicoToolCall(name, args, defaultCredentials) {
+    try {
+        const pre = await handlePreClientToolCall(name, args, defaultCredentials);
+        if (pre)
+            return pre;
+        const clientOrError = await clientFromArgs(args, defaultCredentials);
+        if ("content" in clientOrError)
+            return clientOrError;
+        const { client, creds } = clientOrError;
+        const sdkError = mcpSdkSurfaceError(client);
+        if (sdkError)
+            return toolError(sdkError);
+        const ctx = presentContext(creds, defaultCredentials);
+        const branding = await dispatchBrandingStudioTool(name, args, client, creds, ctx, defaultCredentials);
+        if (branding)
+            return branding;
+        const pulseBlog = await dispatchPulseBlogTool(name, args, client);
+        if (pulseBlog)
+            return pulseBlog;
+        const research = await dispatchResearchAssetsTool(name, args, client);
+        if (research)
+            return research;
+        return toolError(`Unknown tool: ${name}`);
+    }
+    catch (err) {
+        if (isMajicoErrorLike(err)) {
+            if (err.code === "plan_required" || err.code === "INSUFFICIENT_TOKENS") {
+                return toolAuthRequired(buildMcpAuthRequiredPayload("upgrade_plan"));
+            }
+            if (err.body?.code === "INSUFFICIENT_TOKENS") {
+                return toolAuthRequired(buildMcpAuthRequiredPayload("upgrade_plan"));
+            }
+            if (err.code === "auth_invalid_key" ||
+                err.code === "auth_missing" ||
+                err.status === 401) {
+                return toolAuthRequired(buildMcpAuthRequiredPayload("connect_oauth"));
+            }
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return toolError(message.replace(/Bearer\s+\S+/gi, "Bearer [REDACTED]"));
+    }
+}

package/dist/tools/tool-call-helpers.d.ts

@@ -0,0 +1,22 @@
+import type { MajicoClient } from "@majico/sdk";
+import { type CredentialSource, type ResolvedCredentials } from "../credentials.js";
+import type { McpAuthRequiredPayload } from "../auth-prompt.js";
+import type { McpContentBlock, PresentContext } from "../present-interactive.js";
+export type ToolCallResult = {
+    content: McpContentBlock[];
+    isError?: boolean;
+};
+export declare function toolJson(data: unknown): ToolCallResult;
+export declare function toolPresent(content: McpContentBlock[]): ToolCallResult;
+export declare function requireStringArg(args: Record<string, unknown> | undefined, key: string): string | null;
+/** Build stable markdown for local-contract brand scaffolding tests and handoff. */
+export declare function buildStableBrandMarkdown(args: Record<string, unknown> | undefined): ToolCallResult;
+export declare function presentContext(creds: ResolvedCredentials, defaults?: CredentialSource): PresentContext;
+export declare function toolError(message: string): ToolCallResult;
+export declare function toolAuthRequired(payload: McpAuthRequiredPayload): ToolCallResult;
+type ClientContext = ToolCallResult | {
+    client: MajicoClient;
+    creds: ResolvedCredentials;
+};
+export declare function clientFromArgs(args: Record<string, unknown> | undefined, defaultCredentials?: CredentialSource): Promise<ClientContext>;
+export {};

package/dist/tools/tool-call-helpers.js

@@ -0,0 +1,104 @@
+import { createClientFromCredentials, readEnvCredentials, resolveCredentials, } from "../credentials.js";
+export function toolJson(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+    };
+}
+export function toolPresent(content) {
+    return { content };
+}
+export function requireStringArg(args, key) {
+    const value = args?.[key];
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+/** Build stable markdown for local-contract brand scaffolding tests and handoff. */
+export function buildStableBrandMarkdown(args) {
+    const productName = requireStringArg(args, "productName");
+    const positioningConcept = requireStringArg(args, "positioningConcept");
+    const audience = requireStringArg(args, "audience");
+    const tone = requireStringArg(args, "tone");
+    if (!productName || !positioningConcept || !audience || !tone) {
+        return toolError("productName, positioningConcept, audience, and tone are required.");
+    }
+    return toolJson({
+        productName,
+        sections: ["product_name", "positioning_concept", "audience", "tone"],
+        markdown: [
+            `# ${productName}`,
+            "",
+            "## Product Name",
+            productName,
+            "",
+            "## Positioning / Concept",
+            positioningConcept,
+            "",
+            "## Audience",
+            audience,
+            "",
+            "## Tone",
+            tone,
+            "",
+        ].join("\n"),
+    });
+}
+export function presentContext(creds, defaults) {
+    const candidates = [
+        defaults?.publicBaseUrl?.trim(),
+        process.env.MAJICO_PUBLIC_BASE_URL?.trim(),
+        creds.baseUrl?.trim(),
+        "https://majico.xyz",
+    ];
+    const publicBaseUrl = candidates.find((url) => {
+        if (!url)
+            return false;
+        try {
+            const host = new URL(url).hostname;
+            return host !== "0.0.0.0" && host !== "::" && host !== "[::]";
+        }
+        catch {
+            return false;
+        }
+    }) ?? "https://majico.xyz";
+    return { projectId: creds.projectId, publicBaseUrl };
+}
+export function toolError(message) {
+    return {
+        content: [{ type: "text", text: `Error: ${message}` }],
+        isError: true,
+    };
+}
+export function toolAuthRequired(payload) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+        isError: true,
+    };
+}
+function credentialErrorResult(resolved) {
+    if ("authRequired" in resolved &&
+        resolved.authRequired &&
+        resolved.action &&
+        resolved.message) {
+        return toolAuthRequired({
+            authRequired: true,
+            action: resolved.action,
+            message: resolved.message,
+            agentInstructions: resolved.agentInstructions,
+        });
+    }
+    return toolError(resolved.error);
+}
+export function clientFromArgs(args, defaultCredentials) {
+    const envDefaults = {
+        ...readEnvCredentials(),
+        ...defaultCredentials,
+    };
+    return resolveCredentials({
+        projectId: args?.projectId,
+        apiKey: args?.apiKey,
+        baseUrl: defaultCredentials?.baseUrl,
+    }, envDefaults).then((resolved) => {
+        if ("error" in resolved)
+            return credentialErrorResult(resolved);
+        return { client: createClientFromCredentials(resolved), creds: resolved };
+    });
+}

package/dist/tools/tool-catalog.d.ts

@@ -0,0 +1,14 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const MAJICO_USER_TOOLS: Tool[];
+/** Admin-only bootstrap tools — not listed unless X-Majico-Agent-Secret is present. */
+export declare const MAJICO_ADMIN_BOOTSTRAP_TOOLS: Tool[];
+/** Full tool catalog including admin bootstrap (documentation / stdio with agent env). */
+export declare const MAJICO_TOOLS: Tool[];
+/**
+ * Tools exposed on tools/list for a given MCP session.
+ * Bootstrap tools require admin agent secret — never shown to normal OAuth/API-key users.
+ */
+export declare function listMcpTools(options?: {
+    includeAdminTools?: boolean;
+}): Tool[];
+export { classifyMcpTool, MCP_LLM_TOOL_NAMES, partitionMcpToolNames, type McpToolKind, } from "./tool-matrix.js";

package/dist/tools/tool-catalog.js

@@ -0,0 +1,54 @@
+import { MCP_AUTH_TOOL_DESCRIPTION, withBrandingAuthStep, } from "./constants.js";
+import { BRANDING_TOOL_DEFINITIONS } from "./tool-definitions-branding.js";
+import { STUDIO_PULSE_TOOL_DEFINITIONS } from "./tool-definitions-studio-pulse.js";
+import { BLOG_GIT_TOOL_DEFINITIONS } from "./tool-definitions-blog-git.js";
+import { RESEARCH_ALIAS_TOOL_DEFINITIONS } from "./tool-definitions-research-aliases.js";
+const MAJICO_USER_TOOLS_RAW = [
+    ...BRANDING_TOOL_DEFINITIONS,
+    ...STUDIO_PULSE_TOOL_DEFINITIONS,
+    ...BLOG_GIT_TOOL_DEFINITIONS,
+    ...RESEARCH_ALIAS_TOOL_DEFINITIONS,
+];
+export const MAJICO_USER_TOOLS = [
+    {
+        name: "mcp_auth",
+        description: MCP_AUTH_TOOL_DESCRIPTION,
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    ...MAJICO_USER_TOOLS_RAW.map(withBrandingAuthStep),
+];
+/** Admin-only bootstrap tools — not listed unless X-Majico-Agent-Secret is present. */
+export const MAJICO_ADMIN_BOOTSTRAP_TOOLS = [
+    {
+        name: "bootstrap_project",
+        description: "Admin automation: create or reuse a project via Agent API (server MAJICO_AGENT_API_SECRET + X-Majico-Agent-Secret). Not for normal Cursor branding workflows.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                name: {
+                    type: "string",
+                    description: "Project display name, e.g. klaut.pro portal",
+                },
+            },
+            required: ["name"],
+        },
+    },
+];
+/** Full tool catalog including admin bootstrap (documentation / stdio with agent env). */
+export const MAJICO_TOOLS = [
+    ...MAJICO_USER_TOOLS,
+    ...MAJICO_ADMIN_BOOTSTRAP_TOOLS,
+];
+/**
+ * Tools exposed on tools/list for a given MCP session.
+ * Bootstrap tools require admin agent secret — never shown to normal OAuth/API-key users.
+ */
+export function listMcpTools(options) {
+    if (options?.includeAdminTools)
+        return MAJICO_TOOLS;
+    return MAJICO_USER_TOOLS;
+}
+export { classifyMcpTool, MCP_LLM_TOOL_NAMES, partitionMcpToolNames, } from "./tool-matrix.js";

package/dist/tools/tool-definitions-blog-git.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const BLOG_GIT_TOOL_DEFINITIONS: Tool[];

package/dist/tools/tool-definitions-blog-git.js

@@ -0,0 +1,207 @@
+import { ASK_USER_PROJECT_SCOPE, optionalCredentialProps, } from "./constants.js";
+export const BLOG_GIT_TOOL_DEFINITIONS = [
+    {
+        name: "list_blog_posts",
+        description: "List SEO blog drafts for this project (slug, status, generation_status). Start here for blog workflow.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                limit: { type: "number", description: "Max posts (default 20)" },
+            },
+        },
+    },
+    {
+        name: "get_blog_post",
+        description: "Fetch one blog draft with outline, sections, dossier, and body_md when assembled.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                postId: { type: "string" },
+            },
+            required: ["postId"],
+        },
+    },
+    {
+        name: "get_blog_seo_handoff",
+        description: "SEO + implementation handoff for blog agents. Returns live SEO gate rules, MCP workflow, technical SEO (sitemap/robots/schema/OG/nginx), and optional per-post checklist. Call before drafting/implementing or when assemble fails the SEO gate.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                postId: {
+                    type: "string",
+                    description: "Optional draft id — includes live score/checklist/fixes",
+                },
+            },
+        },
+    },
+    {
+        name: "suggest_blog_opportunities",
+        description: "Suggest research-backed SEO article ideas from project ICP + GTM context. First step for new articles.",
+        inputSchema: {
+            type: "object",
+            properties: { ...optionalCredentialProps },
+        },
+    },
+    {
+        name: "run_blog_research",
+        description: "Deep research + dossier for a blog concept (from suggest_blog_opportunities). Required before generate_blog_outline.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                concept: {
+                    type: "object",
+                    description: "BlogConcept: id, question, primaryKeyword, workingTitle, pillar, intent",
+                },
+                articleType: { type: "string" },
+                postId: { type: "string", description: "Optional existing draft id" },
+            },
+            required: ["concept"],
+        },
+    },
+    {
+        name: "generate_blog_outline",
+        description: "Generate whole-article SEO outline from concept + dossier. Present sections; user must approve before drafting.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                concept: { type: "object" },
+                dossier: { type: "object" },
+                articleType: { type: "string" },
+                postId: { type: "string" },
+            },
+            required: ["concept", "dossier"],
+        },
+    },
+    {
+        name: "approve_blog_outline",
+        description: "Approve outline gate (≥3 sections) before generate_blog_section. Call after user confirms outline.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                postId: { type: "string" },
+            },
+            required: ["postId"],
+        },
+    },
+    {
+        name: "generate_blog_section",
+        description: "Draft one section body (token-billed). Requires approved outline. Pass sectionId from outline.sections.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                postId: { type: "string" },
+                sectionId: { type: "string" },
+                approve: {
+                    type: "boolean",
+                    description: "Mark section approved after user confirms text",
+                },
+            },
+            required: ["postId", "sectionId"],
+        },
+    },
+    {
+        name: "assemble_blog_post",
+        description: "Assemble approved sections into body_md + FAQ. Runs SEO gate unless skipSeoGate.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                postId: { type: "string" },
+                skipSeoGate: { type: "boolean" },
+            },
+            required: ["postId"],
+        },
+    },
+    {
+        name: "publish_blog_post",
+        description: "Publish assembled post. scope project (default) or platform (Creator required).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                postId: { type: "string" },
+                scope: { type: "string", enum: ["project", "platform"] },
+                force: { type: "boolean" },
+            },
+            required: ["postId"],
+        },
+    },
+    {
+        name: "push_design_tokens_to_figma",
+        description: "Push compiled design tokens to Figma Variables (Enterprise + connected Figma account).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                fileKey: {
+                    type: "string",
+                    description: "Figma file key (or set projects.figma_variables_file_key)",
+                },
+            },
+        },
+    },
+    {
+        name: "sync_project_assets_to_figma",
+        description: "Incremental Figma sync — import new assets, update changed, skip unchanged. Returns REST results + MCP instructions for raster/markdown.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                fileKey: {
+                    type: "string",
+                    description: "Figma file key (or set projects.figma_variables_file_key)",
+                },
+            },
+        },
+    },
+    {
+        name: "import_repo",
+        description: "Import brand context from a connected GitHub or GitLab repository into this project (enqueue repo_import)." +
+            ASK_USER_PROJECT_SCOPE,
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                owner: { type: "string", description: "Repository owner or org" },
+                repo: { type: "string", description: "Repository name" },
+                ref: { type: "string", description: "Branch or ref (default main)" },
+                provider: { type: "string", enum: ["github", "gitlab"] },
+            },
+            required: ["owner", "repo"],
+        },
+    },
+    {
+        name: "publish_landing_page",
+        description: "Publish htmlFrame landing content to Git (new repo, existing repo PR/MR, or org landing path).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                ...optionalCredentialProps,
+                target: {
+                    type: "string",
+                    enum: ["new_repo", "existing_repo", "org_landing"],
+                },
+                provider: { type: "string", enum: ["github", "gitlab"] },
+                elementId: {
+                    type: "string",
+                    description: "htmlFrame element id (defaults to first htmlFrame)",
+                },
+                html: {
+                    type: "string",
+                    description: "Optional HTML override (otherwise read from canvas)",
+                },
+                owner: { type: "string" },
+                repo: { type: "string" },
+                branch: { type: "string" },
+                orgLandingPath: { type: "string" },
+            },
+        },
+    },
+];

package/dist/tools/tool-definitions-branding.d.ts

@@ -0,0 +1,2 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+export declare const BRANDING_TOOL_DEFINITIONS: Tool[];