@mosvera/mcp 0.1.4 → 0.1.6

package/README.md

@@ -9,16 +9,22 @@ Context Protocol server that lets Claude Desktop, editors, and automation
 tools inspect, resolve, compile, draft, save, and delete Mosvera aesthetics in
 a local registry.
 
-The server never calls image providers, never sends provider HTTP requests,
-and does not store API keys or secrets. It turns aesthetic documents into
-canonical Mosvera models, portable design tokens, CSS variables, and
-deterministic provider payloads that other tools can consume.
+The server runs locally. It never executes provider APIs, never sends provider
+HTTP requests, and does not store API keys or secrets. It turns documents in
+your local registry into canonical Mosvera models, portable design tokens,
+CSS variables, deterministic provider payloads, and portable aesthetic packs.
+
+## 10-Minute Quickstart
+
+New users should start with the
+[`10-minute quickstart`](https://github.com/mosvera/spec/blob/main/docs/guides/10-minute-quickstart.md).
+It begins with Claude Desktop, then shows the npm/MCP path and runtime paths.
 
 ## Install In Claude Desktop
 
 The easiest path for non-command-line users is the Mosvera MCP Bundle:
 
-1. Download `mosvera-mcp-0.1.4.mcpb` from the latest
+1. Download `mosvera-mcp-0.1.5.mcpb` from the latest
    [GitHub release](https://github.com/mosvera/mcp/releases).
 2. Double-click the file, drag it into Claude Desktop, or install it from
    Claude Desktop Settings → Extensions → Advanced settings → Install
@@ -106,17 +112,26 @@ Export quiet-editorial as an aesthetic pack.
 Preview importing this aesthetic pack into my registry.
 ```
 
+```text
+Import the claymation-playful-builder sample pack into my registry.
+```
+
 ```text
 Save a new aesthetic called executive-editorial based on quiet-editorial-base with a more compact, board-ready voice.
 ```
 
 The saved documents are deterministic JSON in your local registry directory.
 
+Canonical sample pack:
+<https://raw.githubusercontent.com/mosvera/spec/main/examples/packs/claymation-playful-builder.mosvera.json>
+
 ## Tools
 
 Every tool returns `structuredContent` plus a short text summary. Tools are
-annotated with MCP read/write hints so clients can present normal approval
-flows.
+annotated with MCP read/write/destructive hints so clients can present normal
+approval flows. Read tools do not mutate the registry. Write tools are only
+registered when the active local registry is writable and the server is not in
+read-only mode.
 
 | Tool | Mode | Purpose |
 |------|------|---------|
@@ -130,7 +145,7 @@ flows.
 | `export_aesthetic_pack` | Read | Export a named aesthetic as a portable `.mosvera.json` pack. |
 | `resolve_aesthetic` | Read | Resolve a named or inline aesthetic into canonical Mosvera JSON. |
 | `compile_design_tokens` | Read | Compile canonical output into portable design tokens and CSS variables. |
-| `compile_provider_payload` | Read | Advanced deterministic provider payload compilation; no provider HTTP call. |
+| `compile_provider_payload` | Read | Advanced deterministic provider payload compilation; no provider HTTP call. Supports provider-specific `provider_options` such as HeyGen `avatar_id`/`script`, ElevenLabs `voice_id`, and short-video `duration` settings. |
 | `draft_aesthetic` | Read | Draft a composition document without saving it. |
 | `save_aesthetic` | Write | Create or update a named composition aesthetic. |
 | `save_registry_document` | Write | Advanced create/update for registry documents and manifests. |
@@ -158,6 +173,10 @@ templates, palettes, modifiers, composition documents, and merge strategies.
 They do not carry assets, provider manifests, credentials, remote URLs, or zip
 bundles in v1.
 
+To test import/export without authoring a pack from scratch, use the canonical
+sample pack in
+[`mosvera/spec/examples/packs`](https://github.com/mosvera/spec/tree/main/examples/packs).
+
 IDs must be safe Mosvera references: lowercase letters, numbers, `_`, and `-`,
 starting with a letter. Absolute paths, dotfiles, path traversal, unknown
 kinds, and unsafe filenames are rejected.
@@ -176,7 +195,7 @@ npm run mcpb:inspect
 The MCPB pack step creates:
 
 ```text
-build/mosvera/mosvera-mcp-0.1.4.mcpb
+build/mosvera/mosvera-mcp-0.1.6.mcpb
 ```
 
 ## Package Boundaries
@@ -187,7 +206,23 @@ runtime directly.
 Use the Python package `mosvera` when you want the peer Python runtime.
 
 Use `@mosvera/provider-*` packages when you want direct provider payload
-compilation without MCP.
+compilation without MCP. The MCP package loads optional provider adapters when
+they are installed and always keeps provider calls out of MCP. The current
+compile-only provider ids are:
+
+```text
+openai-gpt-image-1
+bfl-flux-2-pro
+sdxl-replicate
+heygen-avatar-video
+google-gemini-image
+google-veo-video
+runway-gen4-image
+runway-gen45-video
+elevenlabs-tts
+adobe-firefly-image
+meshy-text-to-3d
+```
 
 Use `@mosvera/mcp` when an agent, editor, or automation system should call
 Mosvera through MCP tools.

package/dist/context.d.ts

@@ -1,6 +1,6 @@
 import { type LoadedProject, type RegistryDiagnostic, type Validator } from "@mosvera/runtime";
 import type { ToolContext } from "./types.ts";
-export declare const SERVER_VERSION = "0.1.4";
+export declare const SERVER_VERSION = "0.1.6";
 export interface CliOptions {
     registryDir?: string;
     readOnlyMode: boolean;
@@ -13,6 +13,7 @@ export declare function parseCliOptions(argv: string[]): CliOptions;
 export declare function defaultRegistryDir(platform?: NodeJS.Platform, env?: NodeJS.ProcessEnv): string;
 export declare function packagedRegistryDir(): string;
 export declare function registryDiagnostics(project: LoadedProject, validator: Validator): RegistryDiagnostic[];
+export declare function loadOptionalProviderAdapters(ctx: ToolContext): Promise<void>;
 export declare function reloadContext(ctx: ToolContext): void;
 export declare function buildContext(input?: string | BuildContextOptions): ToolContext;
 export declare function bundleRoot(): string;

package/dist/context.js

@@ -3,16 +3,24 @@
 // Server context loading: choose a user-owned registry directory, seed public
 // examples on first run, and fall back to packaged examples when local writes
 // are unavailable.
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
 import { cpSync, existsSync, mkdirSync, readdirSync, statSync, } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 import { composeStrategies, createValidator, deriveStrategies, validateRegistry, } from "@mosvera/runtime";
 import { loadProject, RegistryProjectError } from "@mosvera/runtime/node";
 import { fluxAdapter } from "@mosvera/provider-flux";
 import { openaiAdapter } from "@mosvera/provider-openai";
 import { sdxlAdapter } from "@mosvera/provider-sdxl";
-export const SERVER_VERSION = "0.1.4";
+export const SERVER_VERSION = "0.1.6";
 function flagValue(argv, name) {
     const direct = argv.find((arg) => arg.startsWith(`${name}=`));
     if (direct !== undefined)
@@ -24,14 +32,23 @@ function flagValue(argv, name) {
 }
 function booleanFlag(argv, name) {
     const direct = argv.find((arg) => arg.startsWith(`${name}=`));
-    if (direct !== undefined)
-        return !["", "0", "false", "no"].includes(direct.slice(name.length + 1).toLowerCase());
+    if (direct !== undefined) {
+        const value = direct.slice(name.length + 1).toLowerCase();
+        if (value.includes("${"))
+            return false;
+        return !["", "0", "false", "no"].includes(value);
+    }
     return argv.includes(name);
 }
+function configValue(value) {
+    if (value === undefined || value.length === 0 || value.includes("${"))
+        return undefined;
+    return value;
+}
 export function parseCliOptions(argv) {
-    const registryArg = flagValue(argv, "--registry");
-    const envRegistry = process.env.MOSVERA_REGISTRY_DIR;
-    const envReadOnly = process.env.MOSVERA_MCP_READ_ONLY ?? process.env.MOSVERA_READ_ONLY;
+    const registryArg = configValue(flagValue(argv, "--registry"));
+    const envRegistry = configValue(process.env.MOSVERA_REGISTRY_DIR);
+    const envReadOnly = configValue(process.env.MOSVERA_MCP_READ_ONLY ?? process.env.MOSVERA_READ_ONLY);
     const parsed = {
         readOnlyMode: booleanFlag(argv, "--read-only") ||
             booleanFlag(argv, "--readonly") ||
@@ -101,6 +118,73 @@ function emptyProject() {
         strategies: {},
     };
 }
+function isProviderAdapter(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const adapter = value;
+    return (typeof adapter.id === "string" &&
+        typeof adapter.version === "string" &&
+        typeof adapter.manifest === "function" &&
+        typeof adapter.emit === "function" &&
+        typeof adapter.execute === "function");
+}
+function packageParts(packageName) {
+    return packageName.split("/");
+}
+function optionalPackageEntrypoint(packageName) {
+    let directory = dirname(fileURLToPath(import.meta.url));
+    const parts = packageParts(packageName);
+    while (true) {
+        const candidate = join(directory, "node_modules", ...parts, "dist", "index.js");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(directory);
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+}
+async function optionalAdapter(packageName, exportName) {
+    const entrypoint = optionalPackageEntrypoint(packageName);
+    if (entrypoint === undefined)
+        return undefined;
+    try {
+        const mod = await import(__rewriteRelativeImportExtension(pathToFileURL(entrypoint).href));
+        const adapter = mod[exportName];
+        return isProviderAdapter(adapter) ? adapter : undefined;
+    }
+    catch (e) {
+        const code = typeof e === "object" && e !== null && "code" in e ? e.code : undefined;
+        if (e instanceof Error &&
+            (code === "MODULE_NOT_FOUND" || code === "ERR_MODULE_NOT_FOUND" || code === "ERR_PACKAGE_PATH_NOT_EXPORTED")) {
+            return undefined;
+        }
+        throw e;
+    }
+}
+function providerAdapters() {
+    return {
+        [openaiAdapter.id]: openaiAdapter,
+        [fluxAdapter.id]: fluxAdapter,
+        [sdxlAdapter.id]: sdxlAdapter,
+    };
+}
+export async function loadOptionalProviderAdapters(ctx) {
+    const optional = await Promise.all([
+        optionalAdapter("@mosvera/provider-heygen", "heygenAdapter"),
+        optionalAdapter("@mosvera/provider-google", "googleGeminiImageAdapter"),
+        optionalAdapter("@mosvera/provider-google", "googleVeoVideoAdapter"),
+        optionalAdapter("@mosvera/provider-runway", "runwayGen4ImageAdapter"),
+        optionalAdapter("@mosvera/provider-runway", "runwayGen45VideoAdapter"),
+        optionalAdapter("@mosvera/provider-elevenlabs", "elevenLabsTtsAdapter"),
+        optionalAdapter("@mosvera/provider-firefly", "fireflyImageAdapter"),
+        optionalAdapter("@mosvera/provider-meshy", "meshyTextTo3DAdapter"),
+    ]);
+    ctx.adapters = {
+        ...(ctx.adapters ?? {}),
+        ...Object.fromEntries(optional.filter((adapter) => adapter !== undefined).map((adapter) => [adapter.id, adapter])),
+    };
+}
 function loadProjectOrEmpty(directory, validator) {
     if (!existsSync(directory))
         return emptyProject();
@@ -119,11 +203,7 @@ function makeContext(registryDir, project, validator, options) {
         project,
         validator,
         baseStrategies: composeStrategies(deriveStrategies(), project.strategies),
-        adapters: {
-            [openaiAdapter.id]: openaiAdapter,
-            [fluxAdapter.id]: fluxAdapter,
-            [sdxlAdapter.id]: sdxlAdapter,
-        },
+        adapters: providerAdapters(),
     };
     if (options.fallbackReason !== undefined)
         ctx.fallbackReason = options.fallbackReason;

package/dist/server.js

@@ -9,7 +9,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { realpathSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { z } from "zod";
-import { buildContext, parseCliOptions, SERVER_VERSION } from "./context.js";
+import { buildContext, loadOptionalProviderAdapters, parseCliOptions, SERVER_VERSION } from "./context.js";
 import { documentKinds, runCompileDesignTokens, runCompileProviderPayload, runDeleteRegistryDocument, runDraftAesthetic, runExportAestheticPack, runGetRegistryDocument, runImportAestheticPack, runListAesthetics, runPreviewAestheticImport, runResolveAesthetic, runSaveAesthetic, runSaveRegistryDocument, runServerStatus, runValidateAestheticPack, runValidateDocument, runValidateRegistry, runWriteMergeStrategies, } from "./tools/aesthetic.js";
 const docArg = z.union([z.string(), z.record(z.any())]);
 const packSourceArg = {
@@ -141,6 +141,7 @@ export function createServer(ctx) {
         inputSchema: {
             aesthetic: z.union([z.string(), z.record(z.any())]),
             provider: z.string(),
+            provider_options: z.record(z.any()).optional(),
             criticality: criticalityArg.optional(),
             merge_strategies: strategiesArg.optional(),
         },
@@ -210,6 +211,7 @@ export function createServer(ctx) {
 async function main() {
     const options = parseCliOptions(process.argv.slice(2));
     const ctx = buildContext(options);
+    await loadOptionalProviderAdapters(ctx);
     const server = createServer(ctx);
     await server.connect(new StdioServerTransport());
 }

package/dist/tools/aesthetic.d.ts

@@ -44,6 +44,7 @@ export declare function runCompileDesignTokens(ctx: ToolContext, args: {
 export declare function runCompileProviderPayload(ctx: ToolContext, args: {
     aesthetic: string | object;
     provider: string;
+    provider_options?: Record<string, unknown>;
     criticality?: Record<string, Criticality>;
     merge_strategies?: MergeStrategies;
 }): CallToolResult;

package/dist/tools/aesthetic.js

@@ -157,6 +157,14 @@ function writeDisabled(ctx) {
 function toolFail(failure) {
     return fail(failure.error, failure.message, failure.detail);
 }
+function topCssVariables(cssVariables, limit = 40) {
+    const entries = Object.entries(cssVariables).sort(([a], [b]) => a.localeCompare(b));
+    if (entries.length === 0)
+        return "No CSS variables were produced.";
+    const visible = entries.slice(0, limit).map(([key, value]) => `${key}: ${value};`);
+    const remaining = entries.length - visible.length;
+    return `${visible.join("\n")}${remaining > 0 ? `\n...and ${remaining} more CSS variable${remaining === 1 ? "" : "s"}.` : ""}`;
+}
 export function runServerStatus(ctx) {
     const diagnostics = [...ctx.loadDiagnostics, ...registryDiagnostics(ctx.project, ctx.validator)];
     const registry = ctx.project.registry;
@@ -167,7 +175,15 @@ export function runServerStatus(ctx) {
         compositions: Object.keys(registry.compositions ?? {}).length,
         manifests: Object.keys(ctx.project.manifests).length,
     };
-    return ok("Mosvera MCP server is ready.", {
+    const message = [
+        "Mosvera MCP server is ready.",
+        `Registry: ${ctx.registryDir}`,
+        `Writable: ${ctx.registryWritable ? "yes" : "no"}`,
+        `Read-only mode: ${ctx.readOnlyMode ? "yes" : "no"}`,
+        `Write tools enabled: ${ctx.registryWritable && !ctx.readOnlyMode ? "yes" : "no"}`,
+        `Loaded: ${counts.compositions} aesthetics, ${counts.templates} templates, ${counts.modifiers} modifiers, ${counts.palettes} palettes, ${counts.manifests} manifests.`,
+    ].join("\n");
+    return ok(message, {
         registry_path: ctx.registryDir,
         registry_writable: ctx.registryWritable,
         read_only_mode: ctx.readOnlyMode,
@@ -287,7 +303,14 @@ export function runCompileDesignTokens(ctx, args) {
         cssOptions.prefix = args.css_prefix;
     const tokens = compileDesignTokens(resolved.canonical, tokenOptions);
     const css_variables = toCssVariables(tokens, cssOptions);
-    return ok("Compiled portable design tokens.", { source: resolved.source, canonical: resolved.canonical, tokens, css_variables });
+    const sections = Object.keys(tokens).sort();
+    const message = [
+        "Compiled portable design tokens.",
+        `Token sections: ${sections.length > 0 ? sections.join(", ") : "none"}.`,
+        "CSS variables:",
+        topCssVariables(css_variables),
+    ].join("\n");
+    return ok(message, { source: resolved.source, canonical: resolved.canonical, tokens, css_variables });
 }
 export function runCompileProviderPayload(ctx, args) {
     const input = { aesthetic: args.aesthetic };
@@ -322,7 +345,10 @@ export function runCompileProviderPayload(ctx, args) {
         });
     }
     try {
-        const emission = adapter.emit(resolved.canonical, { criticality: args.criticality ?? {} });
+        const emitOptions = { criticality: args.criticality ?? {} };
+        if (args.provider_options !== undefined)
+            emitOptions.providerOptions = args.provider_options;
+        const emission = adapter.emit(resolved.canonical, emitOptions);
         return ok(`Compiled deterministic provider payload for "${args.provider}".`, {
             status: "compiled",
             provider: args.provider,

package/dist/tools/compile-generation.d.ts

@@ -7,6 +7,7 @@ export interface CompileArgs {
     manifest?: CapabilityManifest;
     criticality?: Record<string, Criticality>;
     merge_strategies?: MergeStrategies;
+    provider_options?: Record<string, unknown>;
     emit?: boolean;
 }
 export declare function runCompileGeneration(ctx: ToolContext, args: CompileArgs): CompileResultMcp;

package/dist/tools/compile-generation.js

@@ -54,7 +54,14 @@ export function runCompileGeneration(ctx, args) {
             return toolError("unknown_provider", { provider: args.provider, adapter: "missing" });
         }
         try {
-            return { status: "compiled", canonical, emission: adapter.emit(canonical, { criticality: args.criticality ?? {} }) };
+            const emitOptions = { criticality: args.criticality ?? {} };
+            if (args.provider_options !== undefined)
+                emitOptions.providerOptions = args.provider_options;
+            return {
+                status: "compiled",
+                canonical,
+                emission: adapter.emit(canonical, emitOptions),
+            };
         }
         catch (e) {
             if (e instanceof EmissionError) {

package/mcpb/manifest.json

@@ -2,7 +2,7 @@
   "manifest_version": "0.3",
   "name": "mosvera-mcp",
   "display_name": "Mosvera",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Resolve, compile, and save local Mosvera aesthetics from Claude Desktop.",
   "long_description": "Mosvera runs locally against your own aesthetic registry. It lets Claude list named aesthetics, resolve them to canonical Mosvera models, compile portable design tokens and CSS variables, and save registry documents without sending provider requests or storing secrets.",
   "author": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosvera/mcp",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Run Mosvera as local MCP tools for agents, editors, and Claude Desktop.",
   "license": "Apache-2.0",
   "type": "module",
@@ -41,8 +41,8 @@
     "ci": "npm run build && npm run typecheck && npm test",
     "clean": "rm -rf dist",
     "mcpb:stage": "npm run build && node scripts/stage-mcpb.mjs",
-    "mcpb:pack": "npm run mcpb:stage && mcpb pack build/mcpb/mosvera build/mosvera/mosvera-mcp-0.1.4.mcpb",
-    "mcpb:inspect": "node scripts/inspect-mcpb.mjs build/mosvera/mosvera-mcp-0.1.4.mcpb",
+    "mcpb:pack": "npm run mcpb:stage && mcpb pack build/mcpb/mosvera build/mosvera/mosvera-mcp-0.1.6.mcpb",
+    "mcpb:inspect": "node scripts/inspect-mcpb.mjs build/mosvera/mosvera-mcp-0.1.6.mcpb",
     "prepublishOnly": "npm run build && npm run typecheck && npm test",
     "start": "tsx src/server.ts",
     "test": "vitest run",
@@ -64,6 +64,14 @@
     "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.24.1"
   },
+  "optionalDependencies": {
+    "@mosvera/provider-elevenlabs": "^0.1.2",
+    "@mosvera/provider-firefly": "^0.1.2",
+    "@mosvera/provider-google": "^0.1.2",
+    "@mosvera/provider-heygen": "^0.1.1",
+    "@mosvera/provider-meshy": "^0.1.2",
+    "@mosvera/provider-runway": "^0.1.2"
+  },
   "devDependencies": {
     "@anthropic-ai/mcpb": "^2.1.2",
     "typescript": "^5.7.2",