@seed-ship/mcp-ui-spec 1.0.2

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# @mcp-ui/spec Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.0.0] - 2025-01-14
+
+### Added
+- Initial release of `@mcp-ui/spec` package
+- JSON Schema v7 specification for component registries
+- Zod validation schemas with TypeScript types
+- Comprehensive example registry with 3 components:
+  - quickchart-bar (Bar chart visualization)
+  - metric-card (KPI metric card)
+  - data-table (Tabular data display)
+- Security constraints specification:
+  - Authentication requirements
+  - Domain whitelisting
+  - Iframe sandboxing
+  - Maximum nesting depth
+- Performance constraints:
+  - Maximum render time limits
+  - Maximum data size limits
+- Component versioning and deprecation support
+- Grid positioning system (12-column layout)
+
+### Features
+- **JSON Schema**: Industry-standard v7 schema for validation
+- **Zod Integration**: Runtime validation with TypeScript inference
+- **Type Safety**: Complete TypeScript definitions
+- **Examples**: Working examples for each component type
+- **Extensible**: Easy to add new component types
+- **Validation**: Built-in validation for security and performance
+
+### Documentation
+- Complete JSON Schema with descriptions
+- Example registry with real-world use cases
+- TypeScript types for all schema entities

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Gabriel Brument
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# @mcp-ui/spec
+
+Component registry specification and JSON Schemas for MCP UI.
+
+## Installation
+
+```bash
+pnpm add @mcp-ui/spec
+```
+
+## Usage
+
+### Import JSON Schema
+
+```typescript
+import { registrySchema } from '@mcp-ui/spec/schemas'
+import Ajv from 'ajv'
+
+const ajv = new Ajv()
+const validate = ajv.compile(registrySchema)
+
+const valid = validate(myRegistry)
+if (!valid) {
+  console.error(validate.errors)
+}
+```
+
+### Import Zod Schema
+
+```typescript
+import { ComponentRegistrySchema } from '@mcp-ui/spec'
+
+const result = ComponentRegistrySchema.safeParse(myRegistry)
+if (!result.success) {
+  console.error(result.error)
+}
+```
+
+## Registry Format
+
+```json
+{
+  "version": "1.0.0",
+  "components": [
+    {
+      "id": "quickchart-bar",
+      "type": "chart",
+      "name": "Bar Chart",
+      "description": "Renders a bar chart",
+      "schema": { /* JSON Schema */ },
+      "examples": [ /* Working examples */ ],
+      "security": {
+        "requiresAuth": true,
+        "allowedDomains": ["quickchart.io"]
+      },
+      "tags": ["chart", "visualization"]
+    }
+  ]
+}
+```
+
+## Documentation
+
+See the [full documentation](../../docs/features/generative-ui/) for more details.
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,14 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const schemas = require("./schemas.cjs");
+exports.ComponentExampleSchema = schemas.ComponentExampleSchema;
+exports.ComponentRegistrySchema = schemas.ComponentRegistrySchema;
+exports.ComponentSchema = schemas.ComponentSchema;
+exports.ComponentSchemaSchema = schemas.ComponentSchemaSchema;
+exports.ComponentTypeSchema = schemas.ComponentTypeSchema;
+exports.GridPositionSchema = schemas.GridPositionSchema;
+exports.PerformanceConstraintsSchema = schemas.PerformanceConstraintsSchema;
+exports.RegistryMetadataSchema = schemas.RegistryMetadataSchema;
+exports.SandboxFlagSchema = schemas.SandboxFlagSchema;
+exports.SecurityConstraintsSchema = schemas.SecurityConstraintsSchema;
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;;;"}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export * from './schemas';

package/dist/index.js

@@ -0,0 +1,14 @@
+import { ComponentExampleSchema, ComponentRegistrySchema, ComponentSchema, ComponentSchemaSchema, ComponentTypeSchema, GridPositionSchema, PerformanceConstraintsSchema, RegistryMetadataSchema, SandboxFlagSchema, SecurityConstraintsSchema } from "./schemas.js";
+export {
+  ComponentExampleSchema,
+  ComponentRegistrySchema,
+  ComponentSchema,
+  ComponentSchemaSchema,
+  ComponentTypeSchema,
+  GridPositionSchema,
+  PerformanceConstraintsSchema,
+  RegistryMetadataSchema,
+  SandboxFlagSchema,
+  SecurityConstraintsSchema
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/schemas.cjs

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const zod = require("zod");
+const GridPositionSchema = zod.z.object({
+  colStart: zod.z.number().int().min(1).max(12),
+  colSpan: zod.z.number().int().min(1).max(12),
+  rowStart: zod.z.number().int().min(1).optional(),
+  rowSpan: zod.z.number().int().min(1).default(1).optional()
+});
+const ComponentTypeSchema = zod.z.enum(["chart", "table", "metric", "text", "composite"]);
+const SandboxFlagSchema = zod.z.enum([
+  "allow-scripts",
+  "allow-same-origin",
+  "allow-forms",
+  "allow-popups",
+  "allow-modals"
+]);
+const SecurityConstraintsSchema = zod.z.object({
+  requiresAuth: zod.z.boolean().default(false).optional(),
+  allowedDomains: zod.z.array(zod.z.string()).optional(),
+  maxIframeDepth: zod.z.number().int().min(0).max(3).default(1).optional(),
+  sandboxFlags: zod.z.array(SandboxFlagSchema).optional()
+});
+const PerformanceConstraintsSchema = zod.z.object({
+  maxRenderTime: zod.z.number().int().min(100).default(5e3).optional(),
+  maxDataSize: zod.z.number().int().min(1024).default(102400).optional()
+});
+const ComponentSchemaSchema = zod.z.object({
+  type: zod.z.literal("object"),
+  required: zod.z.array(zod.z.string()).optional(),
+  properties: zod.z.record(zod.z.unknown()),
+  additionalProperties: zod.z.boolean().optional()
+});
+const ComponentExampleSchema = zod.z.object({
+  name: zod.z.string().min(1),
+  description: zod.z.string().optional(),
+  params: zod.z.record(zod.z.unknown()),
+  position: GridPositionSchema.optional()
+});
+const ComponentSchema = zod.z.object({
+  id: zod.z.string().regex(/^[a-z0-9-]+$/),
+  type: ComponentTypeSchema,
+  name: zod.z.string().min(1),
+  description: zod.z.string().optional(),
+  schema: ComponentSchemaSchema,
+  examples: zod.z.array(ComponentExampleSchema).min(1),
+  security: SecurityConstraintsSchema.optional(),
+  performance: PerformanceConstraintsSchema.optional(),
+  tags: zod.z.array(zod.z.string().regex(/^[a-z0-9-]+$/)).optional(),
+  version: zod.z.string().regex(/^\d+\.\d+\.\d+$/).optional(),
+  deprecated: zod.z.boolean().default(false).optional(),
+  deprecationMessage: zod.z.string().optional()
+});
+const RegistryMetadataSchema = zod.z.object({
+  name: zod.z.string().optional(),
+  description: zod.z.string().optional(),
+  author: zod.z.string().optional(),
+  repository: zod.z.string().url().optional()
+});
+const ComponentRegistrySchema = zod.z.object({
+  version: zod.z.literal("1.0.0"),
+  metadata: RegistryMetadataSchema.optional(),
+  components: zod.z.array(ComponentSchema).min(1)
+});
+exports.ComponentExampleSchema = ComponentExampleSchema;
+exports.ComponentRegistrySchema = ComponentRegistrySchema;
+exports.ComponentSchema = ComponentSchema;
+exports.ComponentSchemaSchema = ComponentSchemaSchema;
+exports.ComponentTypeSchema = ComponentTypeSchema;
+exports.GridPositionSchema = GridPositionSchema;
+exports.PerformanceConstraintsSchema = PerformanceConstraintsSchema;
+exports.RegistryMetadataSchema = RegistryMetadataSchema;
+exports.SandboxFlagSchema = SandboxFlagSchema;
+exports.SecurityConstraintsSchema = SecurityConstraintsSchema;
+//# sourceMappingURL=schemas.cjs.map

package/dist/schemas.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.cjs","sources":["../src/schemas/index.ts"],"sourcesContent":["/**\n * Zod validation schemas for component registry\n */\n\nimport { z } from 'zod'\n\n// Grid position schema\nexport const GridPositionSchema = z.object({\n  colStart: z.number().int().min(1).max(12),\n  colSpan: z.number().int().min(1).max(12),\n  rowStart: z.number().int().min(1).optional(),\n  rowSpan: z.number().int().min(1).default(1).optional(),\n})\n\n// Component types\nexport const ComponentTypeSchema = z.enum(['chart', 'table', 'metric', 'text', 'composite'])\n\n// Sandbox flags\nexport const SandboxFlagSchema = z.enum([\n  'allow-scripts',\n  'allow-same-origin',\n  'allow-forms',\n  'allow-popups',\n  'allow-modals',\n])\n\n// Security constraints\nexport const SecurityConstraintsSchema = z.object({\n  requiresAuth: z.boolean().default(false).optional(),\n  allowedDomains: z.array(z.string()).optional(),\n  maxIframeDepth: z.number().int().min(0).max(3).default(1).optional(),\n  sandboxFlags: z.array(SandboxFlagSchema).optional(),\n})\n\n// Performance constraints\nexport const PerformanceConstraintsSchema = z.object({\n  maxRenderTime: z.number().int().min(100).default(5000).optional(),\n  maxDataSize: z.number().int().min(1024).default(102400).optional(),\n})\n\n// Component schema (JSON Schema definition)\nexport const ComponentSchemaSchema = z.object({\n  type: z.literal('object'),\n  required: z.array(z.string()).optional(),\n  properties: z.record(z.unknown()),\n  additionalProperties: z.boolean().optional(),\n})\n\n// Component example\nexport const ComponentExampleSchema = z.object({\n  name: z.string().min(1),\n  description: z.string().optional(),\n  params: z.record(z.unknown()),\n  position: GridPositionSchema.optional(),\n})\n\n// Component definition\nexport const ComponentSchema = z.object({\n  id: z.string().regex(/^[a-z0-9-]+$/),\n  type: ComponentTypeSchema,\n  name: z.string().min(1),\n  description: z.string().optional(),\n  schema: ComponentSchemaSchema,\n  examples: z.array(ComponentExampleSchema).min(1),\n  security: SecurityConstraintsSchema.optional(),\n  performance: PerformanceConstraintsSchema.optional(),\n  tags: z.array(z.string().regex(/^[a-z0-9-]+$/)).optional(),\n  version: z\n    .string()\n    .regex(/^\\d+\\.\\d+\\.\\d+$/)\n    .optional(),\n  deprecated: z.boolean().default(false).optional(),\n  deprecationMessage: z.string().optional(),\n})\n\n// Registry metadata\nexport const RegistryMetadataSchema = z.object({\n  name: z.string().optional(),\n  description: z.string().optional(),\n  author: z.string().optional(),\n  repository: z.string().url().optional(),\n})\n\n// Component registry\nexport const ComponentRegistrySchema = z.object({\n  version: z.literal('1.0.0'),\n  metadata: RegistryMetadataSchema.optional(),\n  components: z.array(ComponentSchema).min(1),\n})\n\n// Export types inferred from schemas\nexport type ComponentRegistry = z.infer<typeof ComponentRegistrySchema>\nexport type Component = z.infer<typeof ComponentSchema>\nexport type ComponentExample = z.infer<typeof ComponentExampleSchema>\nexport type GridPosition = z.infer<typeof GridPositionSchema>\nexport type SecurityConstraints = z.infer<typeof SecurityConstraintsSchema>\nexport type PerformanceConstraints = z.infer<typeof PerformanceConstraintsSchema>\nexport type ComponentType = z.infer<typeof ComponentTypeSchema>\nexport type SandboxFlag = z.infer<typeof SandboxFlagSchema>\n"],"names":["z"],"mappings":"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"}

package/dist/schemas.d.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+
+export declare const GridPositionSchema: z.ZodObject<{
+  colStart: z.ZodNumber;
+  colSpan: z.ZodNumber;
+  rowStart: z.ZodOptional<z.ZodNumber>;
+  rowSpan: z.ZodOptional<z.ZodNumber>;
+}>;
+
+export declare const ComponentTypeSchema: z.ZodEnum<['chart', 'table', 'metric', 'text', 'composite']>;
+export declare const SandboxFlagSchema: z.ZodEnum<['allow-scripts', 'allow-same-origin', 'allow-forms', 'allow-popups', 'allow-modals']>;
+
+export declare const SecurityConstraintsSchema: z.ZodObject<{
+  requiresAuth: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+  allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  maxIframeDepth: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+  sandboxFlags: z.ZodOptional<z.ZodArray<typeof SandboxFlagSchema>>;
+}>;
+
+export declare const PerformanceConstraintsSchema: z.ZodObject<{
+  maxRenderTime: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+  maxDataSize: z.ZodOptional<z.ZodDefault<z.ZodNumber>>;
+}>;
+
+export declare const ComponentSchemaSchema: z.ZodObject<{
+  type: z.ZodLiteral<'object'>;
+  required: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  properties: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  additionalProperties: z.ZodOptional<z.ZodBoolean>;
+}>;
+
+export declare const ComponentExampleSchema: z.ZodObject<{
+  name: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  params: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+  position: z.ZodOptional<typeof GridPositionSchema>;
+}>;
+
+export declare const ComponentSchema: z.ZodObject<{
+  id: z.ZodString;
+  type: typeof ComponentTypeSchema;
+  name: z.ZodString;
+  description: z.ZodOptional<z.ZodString>;
+  schema: typeof ComponentSchemaSchema;
+  examples: z.ZodArray<typeof ComponentExampleSchema>;
+  security: z.ZodOptional<typeof SecurityConstraintsSchema>;
+  performance: z.ZodOptional<typeof PerformanceConstraintsSchema>;
+  tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+  version: z.ZodOptional<z.ZodString>;
+  deprecated: z.ZodOptional<z.ZodDefault<z.ZodBoolean>>;
+  deprecationMessage: z.ZodOptional<z.ZodString>;
+}>;
+
+export declare const RegistryMetadataSchema: z.ZodObject<{
+  name: z.ZodOptional<z.ZodString>;
+  description: z.ZodOptional<z.ZodString>;
+  author: z.ZodOptional<z.ZodString>;
+  repository: z.ZodOptional<z.ZodString>;
+}>;
+
+export declare const ComponentRegistrySchema: z.ZodObject<{
+  version: z.ZodLiteral<'1.0.0'>;
+  metadata: z.ZodOptional<typeof RegistryMetadataSchema>;
+  components: z.ZodArray<typeof ComponentSchema>;
+}>;
+
+export type ComponentRegistry = z.infer<typeof ComponentRegistrySchema>;
+export type Component = z.infer<typeof ComponentSchema>;
+export type ComponentExample = z.infer<typeof ComponentExampleSchema>;
+export type ComponentSchema = z.infer<typeof ComponentSchemaSchema>;
+export type GridPosition = z.infer<typeof GridPositionSchema>;
+export type SecurityConstraints = z.infer<typeof SecurityConstraintsSchema>;
+export type PerformanceConstraints = z.infer<typeof PerformanceConstraintsSchema>;
+export type ComponentType = z.infer<typeof ComponentTypeSchema>;
+export type SandboxFlag = z.infer<typeof SandboxFlagSchema>;
+export type RegistryMetadata = z.infer<typeof RegistryMetadataSchema>;

package/dist/schemas.js

@@ -0,0 +1,75 @@
+import { z } from "zod";
+const GridPositionSchema = z.object({
+  colStart: z.number().int().min(1).max(12),
+  colSpan: z.number().int().min(1).max(12),
+  rowStart: z.number().int().min(1).optional(),
+  rowSpan: z.number().int().min(1).default(1).optional()
+});
+const ComponentTypeSchema = z.enum(["chart", "table", "metric", "text", "composite"]);
+const SandboxFlagSchema = z.enum([
+  "allow-scripts",
+  "allow-same-origin",
+  "allow-forms",
+  "allow-popups",
+  "allow-modals"
+]);
+const SecurityConstraintsSchema = z.object({
+  requiresAuth: z.boolean().default(false).optional(),
+  allowedDomains: z.array(z.string()).optional(),
+  maxIframeDepth: z.number().int().min(0).max(3).default(1).optional(),
+  sandboxFlags: z.array(SandboxFlagSchema).optional()
+});
+const PerformanceConstraintsSchema = z.object({
+  maxRenderTime: z.number().int().min(100).default(5e3).optional(),
+  maxDataSize: z.number().int().min(1024).default(102400).optional()
+});
+const ComponentSchemaSchema = z.object({
+  type: z.literal("object"),
+  required: z.array(z.string()).optional(),
+  properties: z.record(z.unknown()),
+  additionalProperties: z.boolean().optional()
+});
+const ComponentExampleSchema = z.object({
+  name: z.string().min(1),
+  description: z.string().optional(),
+  params: z.record(z.unknown()),
+  position: GridPositionSchema.optional()
+});
+const ComponentSchema = z.object({
+  id: z.string().regex(/^[a-z0-9-]+$/),
+  type: ComponentTypeSchema,
+  name: z.string().min(1),
+  description: z.string().optional(),
+  schema: ComponentSchemaSchema,
+  examples: z.array(ComponentExampleSchema).min(1),
+  security: SecurityConstraintsSchema.optional(),
+  performance: PerformanceConstraintsSchema.optional(),
+  tags: z.array(z.string().regex(/^[a-z0-9-]+$/)).optional(),
+  version: z.string().regex(/^\d+\.\d+\.\d+$/).optional(),
+  deprecated: z.boolean().default(false).optional(),
+  deprecationMessage: z.string().optional()
+});
+const RegistryMetadataSchema = z.object({
+  name: z.string().optional(),
+  description: z.string().optional(),
+  author: z.string().optional(),
+  repository: z.string().url().optional()
+});
+const ComponentRegistrySchema = z.object({
+  version: z.literal("1.0.0"),
+  metadata: RegistryMetadataSchema.optional(),
+  components: z.array(ComponentSchema).min(1)
+});
+export {
+  ComponentExampleSchema,
+  ComponentRegistrySchema,
+  ComponentSchema,
+  ComponentSchemaSchema,
+  ComponentTypeSchema,
+  GridPositionSchema,
+  PerformanceConstraintsSchema,
+  RegistryMetadataSchema,
+  SandboxFlagSchema,
+  SecurityConstraintsSchema
+};
+//# sourceMappingURL=schemas.js.map

package/dist/schemas.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.js","sources":["../src/schemas/index.ts"],"sourcesContent":["/**\n * Zod validation schemas for component registry\n */\n\nimport { z } from 'zod'\n\n// Grid position schema\nexport const GridPositionSchema = z.object({\n  colStart: z.number().int().min(1).max(12),\n  colSpan: z.number().int().min(1).max(12),\n  rowStart: z.number().int().min(1).optional(),\n  rowSpan: z.number().int().min(1).default(1).optional(),\n})\n\n// Component types\nexport const ComponentTypeSchema = z.enum(['chart', 'table', 'metric', 'text', 'composite'])\n\n// Sandbox flags\nexport const SandboxFlagSchema = z.enum([\n  'allow-scripts',\n  'allow-same-origin',\n  'allow-forms',\n  'allow-popups',\n  'allow-modals',\n])\n\n// Security constraints\nexport const SecurityConstraintsSchema = z.object({\n  requiresAuth: z.boolean().default(false).optional(),\n  allowedDomains: z.array(z.string()).optional(),\n  maxIframeDepth: z.number().int().min(0).max(3).default(1).optional(),\n  sandboxFlags: z.array(SandboxFlagSchema).optional(),\n})\n\n// Performance constraints\nexport const PerformanceConstraintsSchema = z.object({\n  maxRenderTime: z.number().int().min(100).default(5000).optional(),\n  maxDataSize: z.number().int().min(1024).default(102400).optional(),\n})\n\n// Component schema (JSON Schema definition)\nexport const ComponentSchemaSchema = z.object({\n  type: z.literal('object'),\n  required: z.array(z.string()).optional(),\n  properties: z.record(z.unknown()),\n  additionalProperties: z.boolean().optional(),\n})\n\n// Component example\nexport const ComponentExampleSchema = z.object({\n  name: z.string().min(1),\n  description: z.string().optional(),\n  params: z.record(z.unknown()),\n  position: GridPositionSchema.optional(),\n})\n\n// Component definition\nexport const ComponentSchema = z.object({\n  id: z.string().regex(/^[a-z0-9-]+$/),\n  type: ComponentTypeSchema,\n  name: z.string().min(1),\n  description: z.string().optional(),\n  schema: ComponentSchemaSchema,\n  examples: z.array(ComponentExampleSchema).min(1),\n  security: SecurityConstraintsSchema.optional(),\n  performance: PerformanceConstraintsSchema.optional(),\n  tags: z.array(z.string().regex(/^[a-z0-9-]+$/)).optional(),\n  version: z\n    .string()\n    .regex(/^\\d+\\.\\d+\\.\\d+$/)\n    .optional(),\n  deprecated: z.boolean().default(false).optional(),\n  deprecationMessage: z.string().optional(),\n})\n\n// Registry metadata\nexport const RegistryMetadataSchema = z.object({\n  name: z.string().optional(),\n  description: z.string().optional(),\n  author: z.string().optional(),\n  repository: z.string().url().optional(),\n})\n\n// Component registry\nexport const ComponentRegistrySchema = z.object({\n  version: z.literal('1.0.0'),\n  metadata: RegistryMetadataSchema.optional(),\n  components: z.array(ComponentSchema).min(1),\n})\n\n// Export types inferred from schemas\nexport type ComponentRegistry = z.infer<typeof ComponentRegistrySchema>\nexport type Component = z.infer<typeof ComponentSchema>\nexport type ComponentExample = z.infer<typeof ComponentExampleSchema>\nexport type GridPosition = z.infer<typeof GridPositionSchema>\nexport type SecurityConstraints = z.infer<typeof SecurityConstraintsSchema>\nexport type PerformanceConstraints = z.infer<typeof PerformanceConstraintsSchema>\nexport type ComponentType = z.infer<typeof ComponentTypeSchema>\nexport type SandboxFlag = z.infer<typeof SandboxFlagSchema>\n"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@seed-ship/mcp-ui-spec",
+  "version": "1.0.2",
+  "description": "Component registry specification and JSON Schemas for MCP UI",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs",
+      "types": "./dist/index.d.ts"
+    },
+    "./schemas": {
+      "import": "./dist/schemas/index.js",
+      "require": "./dist/schemas/index.cjs",
+      "types": "./dist/schemas/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "schemas",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^6.15.0",
+    "@typescript-eslint/parser": "^6.15.0",
+    "eslint": "^8.56.0",
+    "typescript": "^5.3.3",
+    "vite": "^5.0.10",
+    "vitest": "^1.1.0"
+  },
+  "keywords": [
+    "mcp",
+    "ui",
+    "specification",
+    "json-schema",
+    "component-registry"
+  ],
+  "author": "Gabriel Brument",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/theseedship/mcp-ui.git",
+    "directory": "mcp-ui-spec"
+  },
+  "homepage": "https://github.com/theseedship/mcp-ui#readme",
+  "bugs": {
+    "url": "https://github.com/theseedship/mcp-ui/issues"
+  },
+  "scripts": {
+    "build": "vite build && node ./scripts/generate-dts.js",
+    "dev": "vite build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/schemas/component-registry-v1.json

@@ -0,0 +1,227 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://mcp-ui.dev/schemas/component-registry-v1.json",
+  "title": "MCP UI Component Registry",
+  "description": "Schema for defining UI components that can be rendered by MCP UI renderers",
+  "type": "object",
+  "required": ["version", "components"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "1.0.0",
+      "description": "Schema version (semver)"
+    },
+    "metadata": {
+      "type": "object",
+      "description": "Optional registry metadata",
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Registry name"
+        },
+        "description": {
+          "type": "string",
+          "description": "Registry description"
+        },
+        "author": {
+          "type": "string",
+          "description": "Registry author"
+        },
+        "repository": {
+          "type": "string",
+          "format": "uri",
+          "description": "Repository URL"
+        }
+      }
+    },
+    "components": {
+      "type": "array",
+      "description": "Array of component definitions",
+      "items": {
+        "$ref": "#/definitions/Component"
+      },
+      "minItems": 1
+    }
+  },
+  "definitions": {
+    "Component": {
+      "type": "object",
+      "required": ["id", "type", "name", "schema", "examples"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z0-9-]+$",
+          "description": "Unique component identifier (kebab-case)",
+          "examples": ["quickchart-bar", "metric-card", "data-table"]
+        },
+        "type": {
+          "type": "string",
+          "enum": ["chart", "table", "metric", "text", "composite"],
+          "description": "Component category"
+        },
+        "name": {
+          "type": "string",
+          "description": "Human-readable component name",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "description": "Component description for documentation"
+        },
+        "schema": {
+          "type": "object",
+          "description": "JSON Schema for component params validation",
+          "required": ["type", "properties"],
+          "properties": {
+            "type": {
+              "const": "object"
+            },
+            "required": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "properties": {
+              "type": "object",
+              "additionalProperties": true
+            }
+          }
+        },
+        "examples": {
+          "type": "array",
+          "description": "Working examples for testing and documentation",
+          "items": {
+            "$ref": "#/definitions/Example"
+          },
+          "minItems": 1
+        },
+        "security": {
+          "type": "object",
+          "description": "Security constraints for the component",
+          "properties": {
+            "requiresAuth": {
+              "type": "boolean",
+              "default": false,
+              "description": "Whether component requires authentication"
+            },
+            "allowedDomains": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "format": "hostname"
+              },
+              "description": "Whitelisted domains for external resources"
+            },
+            "maxIframeDepth": {
+              "type": "integer",
+              "minimum": 0,
+              "maximum": 3,
+              "default": 1,
+              "description": "Maximum iframe nesting depth"
+            },
+            "sandboxFlags": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "enum": [
+                  "allow-scripts",
+                  "allow-same-origin",
+                  "allow-forms",
+                  "allow-popups",
+                  "allow-modals"
+                ]
+              },
+              "description": "Iframe sandbox flags"
+            }
+          }
+        },
+        "performance": {
+          "type": "object",
+          "description": "Performance constraints",
+          "properties": {
+            "maxRenderTime": {
+              "type": "integer",
+              "minimum": 100,
+              "default": 5000,
+              "description": "Maximum render time in milliseconds"
+            },
+            "maxDataSize": {
+              "type": "integer",
+              "minimum": 1024,
+              "default": 102400,
+              "description": "Maximum data size in bytes (100KB default)"
+            }
+          }
+        },
+        "tags": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9-]+$"
+          },
+          "description": "Tags for categorization and search"
+        },
+        "version": {
+          "type": "string",
+          "pattern": "^\\d+\\.\\d+\\.\\d+$",
+          "description": "Component version (semver)"
+        },
+        "deprecated": {
+          "type": "boolean",
+          "default": false,
+          "description": "Whether component is deprecated"
+        },
+        "deprecationMessage": {
+          "type": "string",
+          "description": "Deprecation message and migration guide"
+        }
+      }
+    },
+    "Example": {
+      "type": "object",
+      "required": ["name", "params"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "description": "Example name",
+          "minLength": 1
+        },
+        "description": {
+          "type": "string",
+          "description": "Example description"
+        },
+        "params": {
+          "type": "object",
+          "description": "Component params for this example"
+        },
+        "position": {
+          "type": "object",
+          "description": "Optional grid position for example",
+          "properties": {
+            "colStart": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 12
+            },
+            "colSpan": {
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 12
+            },
+            "rowStart": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "rowSpan": {
+              "type": "integer",
+              "minimum": 1,
+              "default": 1
+            }
+          },
+          "required": ["colStart", "colSpan"]
+        }
+      }
+    }
+  }
+}