@mosvera/mcp 0.1.1

package/dist/tools/list-templates.d.ts

@@ -0,0 +1,6 @@
+import type { Registry } from "@mosvera/runtime";
+import type { TemplateSummary, ToolContext } from "../types.ts";
+export interface ListTemplatesArgs {
+    registry?: Registry;
+}
+export declare function runListTemplates(ctx: ToolContext, args: ListTemplatesArgs): TemplateSummary[];

package/dist/tools/list-templates.js

@@ -0,0 +1,15 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// list_templates tool handler. Enumerates templates in the effective registry
+// (loaded project merged with an optional inline override), reporting each
+// template's id and its $extends parent if present.
+import { mergeRegistry } from "../registry/strategies.js";
+export function runListTemplates(ctx, args) {
+    const reg = mergeRegistry(ctx.project.registry, args.registry);
+    const templates = reg.templates ?? {};
+    return Object.keys(templates).map((name) => {
+        const doc = templates[name];
+        const parent = doc["$extends"];
+        return typeof parent === "string" ? { name, extends: parent } : { name };
+    });
+}

package/dist/tools/resolve-composition.d.ts

@@ -0,0 +1,8 @@
+import { type MergeStrategies, type Registry } from "@mosvera/runtime";
+import type { ResolveResult, ToolContext } from "../types.ts";
+export interface ResolveArgs {
+    composition: object | string;
+    registry?: Registry;
+    merge_strategies?: MergeStrategies;
+}
+export declare function runResolveComposition(ctx: ToolContext, args: ResolveArgs): ResolveResult;

package/dist/tools/resolve-composition.js

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// resolve_composition tool handler. Validates the composition, builds effective
+// merge strategies (schema+project base, then inline override), pre-flights
+// references (emitting unknown_reference before the runtime), then resolves to
+// the canonical model. Runtime ResolutionErrors map to the taxonomy.
+import { parse, resolveComposition, } from "@mosvera/runtime";
+import { invalidDocument, isResolutionError, mapResolutionError, toolError } from "../errors.js";
+import { collectMissingReferences } from "../registry/preflight.js";
+import { composeStrategies, mergeRegistry } from "../registry/strategies.js";
+export function runResolveComposition(ctx, args) {
+    let composition;
+    try {
+        composition = parse(args.composition);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return invalidDocument([{ path: "", message: `parse error: ${message}` }]);
+    }
+    const v = ctx.validator.validate(composition, "composition");
+    if (!v.valid)
+        return invalidDocument(v.errors);
+    const registry = mergeRegistry(ctx.project.registry, args.registry);
+    const missing = collectMissingReferences(composition, registry);
+    if (missing.length > 0) {
+        return toolError("unknown_reference", { missing });
+    }
+    const strategies = composeStrategies(ctx.baseStrategies, args.merge_strategies);
+    try {
+        const canonical = resolveComposition(composition, registry, strategies);
+        return { canonical };
+    }
+    catch (e) {
+        if (isResolutionError(e))
+            return mapResolutionError(e);
+        throw e;
+    }
+}

package/dist/tools/validate-schema.d.ts

@@ -0,0 +1,6 @@
+import { type DocumentKind, type Validator, type ValidationResult } from "@mosvera/runtime";
+export interface ValidateArgs {
+    document: object | string;
+    kind: DocumentKind;
+}
+export declare function runValidateSchema(validator: Validator, args: ValidateArgs): ValidationResult;

package/dist/tools/validate-schema.js

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// validate_schema tool handler. Validates a document against a canonical
+// schema kind. A validation failure is a SUCCESSFUL call returning
+// { valid:false, errors }, not an error result.
+import { parse } from "@mosvera/runtime";
+export function runValidateSchema(validator, args) {
+    let doc;
+    try {
+        doc = parse(args.document);
+    }
+    catch (e) {
+        const message = e instanceof Error ? e.message : String(e);
+        return { valid: false, errors: [{ path: "", message: `parse error: ${message}` }] };
+    }
+    return validator.validate(doc, args.kind);
+}

package/dist/types.d.ts

@@ -0,0 +1,58 @@
+import type { CapabilityManifest, CompileWarning, JsonObject, MergeStrategies, RegistryDiagnostic, Registry, Validator } from "@mosvera/runtime";
+import type { EmissionResult, ProviderAdapter } from "@mosvera/provider-base";
+/** A loaded aesthetic-system "project" directory. */
+export interface LoadedProject {
+    registry: Registry;
+    manifests: Record<string, CapabilityManifest>;
+    /** Project-declared aesthetic-field strategies (merge-strategies.json). */
+    strategies: MergeStrategies;
+}
+/** Per-server context passed to every pure tool handler. */
+export interface ToolContext {
+    /** Absolute registry directory currently loaded by the server. */
+    registryDir: string;
+    /** True when persistence tools may write into registryDir. */
+    registryWritable: boolean;
+    /** True when write tools are intentionally suppressed. */
+    readOnlyMode: boolean;
+    /** True when the packaged examples were used because the configured registry could not be loaded. */
+    fallbackRegistry: boolean;
+    fallbackReason?: string;
+    loadDiagnostics: RegistryDiagnostic[];
+    project: LoadedProject;
+    validator: Validator;
+    /** schema-derived defaults composed with the project's strategies. */
+    baseStrategies: MergeStrategies;
+    /** Optional provider adapters for deterministic payload emission. */
+    adapters?: Record<string, ProviderAdapter>;
+}
+/** Closed MCP-layer error taxonomy (D2/D7 in the design spec). */
+export type ToolErrorCode = "invalid_document" | "unknown_reference" | "unknown_provider" | "unsafe_filename" | "schema_failure" | "write_disabled" | "registry_unwritable" | "inheritance_cycle" | "reference_cycle" | "multiple_inheritance_unsupported";
+export interface ToolError {
+    error: ToolErrorCode;
+    detail?: JsonObject | string;
+}
+export type ResolveResult = {
+    canonical: JsonObject;
+} | ToolError;
+export interface TemplateSummary {
+    name: string;
+    extends?: string;
+}
+export type CompileOk = {
+    status: "compiled";
+    warnings: CompileWarning[];
+    canonical: JsonObject;
+};
+export type CompileEmitOk = {
+    status: "compiled";
+    canonical: JsonObject;
+    emission: EmissionResult;
+};
+export type CompileHardError = {
+    status: "error";
+    error: "required_unsupported";
+    construct: string;
+    canonical: JsonObject;
+};
+export type CompileResultMcp = CompileOk | CompileEmitOk | CompileHardError | ToolError;

package/dist/types.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: Apache-2.0
+//
+// MCP-layer shared types. The MCP surface is a thin orchestration layer over
+// @mosvera/runtime; these types describe the loaded project and the structured
+// results/errors the pure tool handlers return (never thrown across the MCP
+// boundary).
+export {};

package/examples/README.md

@@ -0,0 +1,16 @@
+<!--
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+# MCP Examples
+
+`demo-aesthetics/` is the default registry seed used by `@mosvera/mcp`.
+On first run, the server copies those public-safe aesthetics into the user's
+local registry directory.
+
+`cinematic-editorial/` is retained as a compact provider-compilation fixture
+for tests and advanced examples.
+
+The public MCP surface is documented in the repository README. Use
+`server_status` first when debugging an install; it reports the active registry
+path, write mode, versions, document counts, and diagnostics.

package/examples/cinematic-editorial/README.md

@@ -0,0 +1,22 @@
+<!--
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+# Example: Cinematic Editorial
+
+A worked Mosvera aesthetic system expressed entirely in schema-valid documents.
+It demonstrates single inheritance (`noir` extends `cinematic-editorial-base`),
+modifier composition (`golden-hour`, `high-contrast`), an inline override, and a
+project-level `merge-strategies.json` declaring that the open aesthetic field
+`lights` merges by the `name` key (MEP-0001 `merge_by`). The composition also
+includes the Phase 4 image-generation fields (`subject`, `aspect_ratio`,
+`quality`, `safety`, and `palette.accent`) used by the provider adapters.
+
+`manifests/illustrative-image.manifest.json` is an **illustrative** capability
+manifest used only to exercise the MEP-0003 compilation contract end-to-end. It
+is NOT a real provider adapter. The real reference adapters live in
+[`mosvera/providers`](https://github.com/mosvera/providers).
+
+This directory is retained as a compact provider-compilation fixture. The
+default first-run registry seed for the public MCP server is
+[`../demo-aesthetics/`](../demo-aesthetics/).

package/examples/cinematic-editorial/composition.json

@@ -0,0 +1,14 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/composition",
+  "id": "editorial-noir-golden",
+  "base": "noir",
+  "modifiers": ["golden-hour", "high-contrast"],
+  "overrides": {
+    "subject": "a lighthouse on a basalt cliff at dusk",
+    "medium": "cinematic",
+    "palette": { "accent": "#c8943f" },
+    "aspect_ratio": "3:2",
+    "quality": "high",
+    "safety": "standard"
+  }
+}

package/examples/cinematic-editorial/manifests/illustrative-image.manifest.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/capability-manifest",
+  "provider": "illustrative-image",
+  "adapter_version": "0.0.0-illustrative",
+  "constructs": {
+    "subject": { "lowering_action": "native" },
+    "medium": { "lowering_action": "native" },
+    "aspect_ratio": { "lowering_action": "native" },
+    "quality": { "lowering_action": "native" },
+    "safety": { "lowering_action": "unsupported", "note": "ILLUSTRATIVE ONLY — no tunable moderation control." },
+    "lighting": { "lowering_action": "approximate", "note": "ILLUSTRATIVE ONLY — not a real provider. lighting scheme/mood folded into a prompt phrase." },
+    "color_grade": { "lowering_action": "approximate", "note": "ILLUSTRATIVE ONLY — contrast/saturation folded into prompt adjectives." },
+    "palette": { "lowering_action": "approximate", "note": "ILLUSTRATIVE ONLY — accent color folded into prompt phrase." },
+    "lights": { "lowering_action": "emulate", "note": "ILLUSTRATIVE ONLY — named lights emulated via descriptive prompt clauses." }
+  }
+}

package/examples/cinematic-editorial/merge-strategies.json

@@ -0,0 +1,3 @@
+{
+  "lights": { "strategy": "merge_by", "key": "name" }
+}

package/examples/cinematic-editorial/modifier.golden-hour.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/modifier",
+  "id": "golden-hour",
+  "lighting": { "mood": "warm" },
+  "lights": [
+    { "name": "fill", "power": 5 },
+    { "name": "rim", "power": 2 }
+  ],
+  "color_temperature": "warm"
+}

package/examples/cinematic-editorial/modifier.high-contrast.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/modifier",
+  "id": "high-contrast",
+  "color_grade": { "contrast": "very_high" }
+}

package/examples/cinematic-editorial/palette.editorial-warm.json

@@ -0,0 +1,10 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/palette",
+  "id": "editorial-warm",
+  "roles": {
+    "background": "#1a1410",
+    "foreground": "#f5e6d3",
+    "accent": "#c8943f",
+    "shadow": "#0a0805"
+  }
+}

package/examples/cinematic-editorial/template.base.json

@@ -0,0 +1,11 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/template",
+  "id": "cinematic-editorial-base",
+  "medium": "photographic",
+  "lighting": { "scheme": "three_point", "mood": "neutral" },
+  "lights": [
+    { "name": "key", "power": 6 },
+    { "name": "fill", "power": 3 }
+  ],
+  "color_grade": { "contrast": "medium", "saturation": "natural" }
+}

package/examples/cinematic-editorial/template.noir.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/template",
+  "id": "noir",
+  "$extends": "cinematic-editorial-base",
+  "lighting": { "mood": "moody" },
+  "color_grade": { "contrast": "high", "saturation": "desaturated" }
+}

package/examples/demo-aesthetics/README.md

@@ -0,0 +1,11 @@
+<!--
+SPDX-License-Identifier: CC-BY-4.0
+-->
+
+# Demo Aesthetics
+
+Default local registry seed for the Mosvera MCP server. On first run, the
+server copies these public-safe documents into the user's registry directory
+and then reads/writes only that user-owned copy.
+
+These examples mirror the four live `mosvera.io` demonstrator aesthetics.

package/examples/demo-aesthetics/composition.cinematic-lab.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/composition",
+  "base": "cinematic-lab-base",
+  "id": "cinematic-lab"
+}

package/examples/demo-aesthetics/composition.claymation-playful-builder.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/composition",
+  "base": "claymation-playful-builder-base",
+  "id": "claymation-playful-builder"
+}

package/examples/demo-aesthetics/composition.quiet-editorial.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/composition",
+  "base": "quiet-editorial-base",
+  "id": "quiet-editorial"
+}

package/examples/demo-aesthetics/composition.technical-manual.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/composition",
+  "base": "technical-manual-base",
+  "id": "technical-manual"
+}

package/examples/demo-aesthetics/template.cinematic-lab-base.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/template",
+  "id": "cinematic-lab-base",
+  "imagery": {
+    "alt": "Spotlit high-contrast Mosvera tesserae arranged for a cinematic lab surface.",
+    "blend": "screen",
+    "contrast": "1.22",
+    "saturation": "1.08",
+    "src": "/assets/aesthetics/hero-cinematic-lab.webp",
+    "treatment": "spotlit"
+  },
+  "layout": {
+    "density": "spacious",
+    "max_width": "1240px",
+    "radius": "8px",
+    "shadow": "0 28px 80px rgba(0, 0, 0, 0.42)"
+  },
+  "motion": {
+    "duration": "320ms",
+    "pace": "cinematic"
+  },
+  "palette": {
+    "accent": "#e05b45",
+    "accent_2": "#7cc9d8",
+    "background": "#12100f",
+    "border": "#4c3b39",
+    "code_bg": "#080707",
+    "code_ink": "#f8e6c8",
+    "ink": "#f6eee6",
+    "muted": "#c7b8aa",
+    "surface": "#1e1a18",
+    "surface_alt": "#2f2524"
+  },
+  "typography": {
+    "body": "Hanken Grotesk",
+    "display": "Fraunces",
+    "mono": "IBM Plex Mono",
+    "scale": "large"
+  },
+  "voice": {
+    "body": "Cinematic Lab pushes contrast, scale, and image presence while the same composition, schema, and token panes stay readable.",
+    "eyebrow": "Visual research mode",
+    "headline": "The standard can carry drama without losing structure."
+  }
+}

package/examples/demo-aesthetics/template.claymation-playful-builder-base.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/template",
+  "id": "claymation-playful-builder-base",
+  "imagery": {
+    "alt": "Tactile clay-like Mosvera tesserae under warm builder-table light.",
+    "blend": "normal",
+    "contrast": "0.96",
+    "saturation": "1.12",
+    "src": "/assets/aesthetics/hero-claymation-playful-builder.webp",
+    "treatment": "tabletop_model"
+  },
+  "layout": {
+    "density": "roomy",
+    "max_width": "1160px",
+    "radius": "8px",
+    "shadow": "0 18px 0 rgba(96, 63, 39, 0.26)"
+  },
+  "motion": {
+    "duration": "260ms",
+    "pace": "bouncy"
+  },
+  "palette": {
+    "accent": "#d45f3f",
+    "accent_2": "#2f8f9d",
+    "background": "#f6e7cc",
+    "border": "#c99a68",
+    "code_bg": "#2b2119",
+    "code_ink": "#ffe3bc",
+    "ink": "#2a2118",
+    "muted": "#695946",
+    "surface": "#fff3dc",
+    "surface_alt": "#ead2ad"
+  },
+  "typography": {
+    "body": "Hanken Grotesk",
+    "display": "Fraunces",
+    "mono": "IBM Plex Mono",
+    "scale": "friendly"
+  },
+  "voice": {
+    "body": "This mode keeps the spec serious while the surface becomes handmade, constructive, and a little mischievous.",
+    "eyebrow": "Tactile builder mode",
+    "headline": "Same architecture, built out of warm clay and shop light."
+  }
+}

package/examples/demo-aesthetics/template.quiet-editorial-base.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/template",
+  "id": "quiet-editorial-base",
+  "imagery": {
+    "alt": "Warm paper-toned Mosvera tesserae arranged as a calm editorial composition.",
+    "blend": "normal",
+    "contrast": "1.02",
+    "saturation": "0.92",
+    "src": "/assets/aesthetics/hero-quiet-editorial.webp",
+    "treatment": "paper_field"
+  },
+  "layout": {
+    "density": "comfortable",
+    "max_width": "1160px",
+    "radius": "6px",
+    "shadow": "0 18px 55px rgba(58, 38, 21, 0.16)"
+  },
+  "motion": {
+    "duration": "220ms",
+    "pace": "steady"
+  },
+  "palette": {
+    "accent": "#bd5838",
+    "accent_2": "#2e6b5f",
+    "background": "#f7f2e7",
+    "border": "#d8c8b6",
+    "code_bg": "#181513",
+    "code_ink": "#f5ebdd",
+    "ink": "#211b16",
+    "muted": "#665c50",
+    "surface": "#fffaf0",
+    "surface_alt": "#eee3d4"
+  },
+  "typography": {
+    "body": "Hanken Grotesk",
+    "display": "Fraunces",
+    "mono": "IBM Plex Mono",
+    "scale": "editorial"
+  },
+  "voice": {
+    "body": "Mosvera turns aesthetic intent into typed, portable, reviewable artifacts that teams can run inside their own platforms.",
+    "eyebrow": "Canonical public home",
+    "headline": "Aesthetic infrastructure you can inspect."
+  }
+}

package/examples/demo-aesthetics/template.technical-manual-base.json

@@ -0,0 +1,45 @@
+{
+  "$schema": "https://mosvera.io/schema/0.1/template",
+  "id": "technical-manual-base",
+  "imagery": {
+    "alt": "High-key schematic Mosvera tesserae rendered like a technical reference plate.",
+    "blend": "multiply",
+    "contrast": "1.14",
+    "saturation": "0.72",
+    "src": "/assets/aesthetics/hero-technical-manual.webp",
+    "treatment": "schematic"
+  },
+  "layout": {
+    "density": "compact",
+    "max_width": "1220px",
+    "radius": "2px",
+    "shadow": "0 1px 0 rgba(16, 33, 28, 0.24)"
+  },
+  "motion": {
+    "duration": "120ms",
+    "pace": "quick"
+  },
+  "palette": {
+    "accent": "#17745f",
+    "accent_2": "#5847a6",
+    "background": "#f2f5f1",
+    "border": "#b9c8c0",
+    "code_bg": "#07130f",
+    "code_ink": "#d9f7ea",
+    "ink": "#10211c",
+    "muted": "#50615b",
+    "surface": "#ffffff",
+    "surface_alt": "#dfe8e2"
+  },
+  "typography": {
+    "body": "Hanken Grotesk",
+    "display": "IBM Plex Mono",
+    "mono": "IBM Plex Mono",
+    "scale": "compact"
+  },
+  "voice": {
+    "body": "This mode compresses the interface, raises structure, and makes the underlying Mosvera artifacts feel like a spec you can build from.",
+    "eyebrow": "Implementation reference",
+    "headline": "Same site, compiled as a technical surface."
+  }
+}

package/mcpb/manifest.json

@@ -0,0 +1,73 @@
+{
+  "manifest_version": "0.3",
+  "name": "mosvera-mcp",
+  "display_name": "Mosvera",
+  "version": "0.1.1",
+  "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": {
+    "name": "Mosvera",
+    "email": "nic@niclydon.io",
+    "url": "https://mosvera.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mosvera/mcp"
+  },
+  "homepage": "https://mosvera.io",
+  "documentation": "https://github.com/mosvera/mcp#readme",
+  "support": "https://github.com/mosvera/mcp/issues",
+  "icon": "icon.png",
+  "server": {
+    "type": "node",
+    "entry_point": "server/dist/server.js",
+    "mcp_config": {
+      "command": "node",
+      "args": [
+        "${__dirname}/server/dist/server.js",
+        "--registry=${user_config.registry_directory}",
+        "--read-only=${user_config.read_only_mode}"
+      ]
+    }
+  },
+  "tools": [
+    { "name": "server_status", "description": "Show registry path, write mode, versions, counts, and diagnostics." },
+    { "name": "list_aesthetics", "description": "List named aesthetics in the active local registry." },
+    { "name": "get_registry_document", "description": "Fetch a template, modifier, palette, composition, or capability manifest." },
+    { "name": "validate_document", "description": "Validate one Mosvera document against a schema kind." },
+    { "name": "validate_registry", "description": "Validate the active local registry." },
+    { "name": "resolve_aesthetic", "description": "Resolve a named or inline aesthetic to the canonical Mosvera model." },
+    { "name": "compile_design_tokens", "description": "Compile an aesthetic into portable design tokens and CSS variables." },
+    { "name": "compile_provider_payload", "description": "Compile a deterministic provider payload without making provider HTTP calls." },
+    { "name": "draft_aesthetic", "description": "Draft a valid composition document without saving it." },
+    { "name": "save_aesthetic", "description": "Create or update a named aesthetic in the active local registry." },
+    { "name": "save_registry_document", "description": "Create or update an advanced registry document." },
+    { "name": "delete_registry_document", "description": "Delete a registry document from the active local registry." },
+    { "name": "write_merge_strategies", "description": "Replace merge-strategies.json with deterministic JSON." }
+  ],
+  "keywords": ["mosvera", "aesthetic-infrastructure", "mcp", "design-tokens"],
+  "license": "Apache-2.0",
+  "privacy_policies": [],
+  "compatibility": {
+    "claude_desktop": ">=0.10.0",
+    "platforms": ["darwin", "win32", "linux"],
+    "runtimes": {
+      "node": ">=20.0.0"
+    }
+  },
+  "user_config": {
+    "registry_directory": {
+      "type": "directory",
+      "title": "Mosvera Registry Directory",
+      "description": "Optional local folder for your Mosvera aesthetic registry. Leave empty to use the platform default.",
+      "required": false
+    },
+    "read_only_mode": {
+      "type": "boolean",
+      "title": "Read-only mode",
+      "description": "Hide registry-writing tools and use Mosvera only for inspection and compilation.",
+      "default": false,
+      "required": false
+    }
+  }
+}