@seed-ship/mcp-ui-spec 1.0.14 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +90 -12
- package/README.md +237 -21
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -1,17 +1,101 @@
|
|
|
1
|
-
# @mcp-ui
|
|
1
|
+
# @seed-ship/mcp-ui-spec Changelog
|
|
2
2
|
|
|
3
3
|
All notable changes to this project will be documented in this file.
|
|
4
4
|
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
|
|
6
|
+
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [1.1.0] - 2025-11-25
|
|
9
|
+
|
|
10
|
+
### Documentation
|
|
11
|
+
- **Comprehensive README Rewrite**: Complete documentation overhaul
|
|
12
|
+
- Fixed npm scope from `@mcp-ui/spec` to `@seed-ship/mcp-ui-spec`
|
|
13
|
+
- Documented all 10 exported Zod schemas
|
|
14
|
+
- Documented all 11 component types with renderer mappings
|
|
15
|
+
- Added full registry format specification
|
|
16
|
+
- Added Grid Positioning, Security Constraints, Performance Constraints docs
|
|
17
|
+
- Added deprecation and versioning documentation
|
|
18
|
+
- Included complete example registry JSON
|
|
19
|
+
|
|
20
|
+
### Notes
|
|
21
|
+
- This minor version bump marks a documentation milestone
|
|
22
|
+
- No schema changes - all validation identical to v1.0.15
|
|
23
|
+
|
|
24
|
+
## [1.0.15] - 2025-11-24
|
|
25
|
+
|
|
26
|
+
### Changed
|
|
27
|
+
- Version bump (synchronized with mcp-ui-solid v1.0.26, mcp-ui-cli v1.0.14)
|
|
28
|
+
|
|
29
|
+
## [1.0.14] - 2025-11-23
|
|
30
|
+
|
|
31
|
+
### Changed
|
|
32
|
+
- Version bump (synchronized with mcp-ui-solid v1.0.25, mcp-ui-cli v1.0.13)
|
|
33
|
+
|
|
34
|
+
## [1.0.12] - 2025-11-23
|
|
35
|
+
|
|
36
|
+
### Changed
|
|
37
|
+
- Version bump for npm publication with updated token
|
|
38
|
+
- Synchronized with mcp-ui-solid v1.0.23, mcp-ui-cli v1.0.11
|
|
39
|
+
|
|
40
|
+
## [1.0.11] - 2025-11-23
|
|
41
|
+
|
|
42
|
+
### Changed
|
|
43
|
+
- Version bump (synchronized with mcp-ui-solid v1.0.22, mcp-ui-cli v1.0.10)
|
|
44
|
+
|
|
45
|
+
## [1.0.10] - 2025-11-23
|
|
46
|
+
|
|
47
|
+
### Added
|
|
48
|
+
- **Validation Enhancements**: Extended Zod schemas for new component types
|
|
49
|
+
- Action component validation
|
|
50
|
+
- Artifact component validation
|
|
51
|
+
- Carousel component validation
|
|
52
|
+
- Footer component validation
|
|
53
|
+
|
|
54
|
+
### Changed
|
|
55
|
+
- Synchronized with mcp-ui-solid v1.0.21, mcp-ui-cli v1.0.9
|
|
56
|
+
|
|
57
|
+
## [1.0.8] - 2025-11-22
|
|
58
|
+
|
|
59
|
+
### Changed
|
|
60
|
+
- Version bump (synchronized with mcp-ui-solid v1.0.18, mcp-ui-cli v1.0.8)
|
|
61
|
+
|
|
62
|
+
## [1.0.7] - 2025-11-22
|
|
63
|
+
|
|
64
|
+
### Changed
|
|
65
|
+
- Version bump
|
|
66
|
+
|
|
67
|
+
## [1.0.5] - 2025-11-22
|
|
68
|
+
|
|
69
|
+
### Added
|
|
70
|
+
- **New Component Types**: Added Zod schemas for iframe, image, link components
|
|
71
|
+
- `IframeComponentSchema` with src and sandbox validation
|
|
72
|
+
- `ImageComponentSchema` with src, alt, dimensions
|
|
73
|
+
- `LinkComponentSchema` with href and text
|
|
74
|
+
|
|
75
|
+
### Changed
|
|
76
|
+
- Version bump for npm publication
|
|
77
|
+
|
|
78
|
+
## [1.0.2] - 2025-11-17
|
|
79
|
+
|
|
80
|
+
### Changed
|
|
81
|
+
- Migrate to `@seed-ship` npm scope
|
|
82
|
+
- Updated package name from `@mcp-ui/spec` to `@seed-ship/mcp-ui-spec`
|
|
83
|
+
|
|
84
|
+
## [1.0.1] - 2025-11-16
|
|
85
|
+
|
|
86
|
+
### Fixed
|
|
87
|
+
- Add type definitions generation for all packages
|
|
88
|
+
|
|
5
89
|
## [1.0.0] - 2025-01-14
|
|
6
90
|
|
|
7
91
|
### Added
|
|
8
|
-
- Initial release of `@mcp-ui
|
|
92
|
+
- Initial release of `@seed-ship/mcp-ui-spec` package
|
|
9
93
|
- JSON Schema v7 specification for component registries
|
|
10
94
|
- Zod validation schemas with TypeScript types
|
|
11
|
-
- Comprehensive example registry with
|
|
12
|
-
- quickchart-bar (Bar chart visualization)
|
|
13
|
-
- metric-card (KPI metric card)
|
|
14
|
-
- data-table (Tabular data display)
|
|
95
|
+
- Comprehensive example registry with components:
|
|
96
|
+
- `quickchart-bar` (Bar chart visualization)
|
|
97
|
+
- `metric-card` (KPI metric card)
|
|
98
|
+
- `data-table` (Tabular data display)
|
|
15
99
|
- Security constraints specification:
|
|
16
100
|
- Authentication requirements
|
|
17
101
|
- Domain whitelisting
|
|
@@ -29,9 +113,3 @@ All notable changes to this project will be documented in this file.
|
|
|
29
113
|
- **Type Safety**: Complete TypeScript definitions
|
|
30
114
|
- **Examples**: Working examples for each component type
|
|
31
115
|
- **Extensible**: Easy to add new component types
|
|
32
|
-
- **Validation**: Built-in validation for security and performance
|
|
33
|
-
|
|
34
|
-
### Documentation
|
|
35
|
-
- Complete JSON Schema with descriptions
|
|
36
|
-
- Example registry with real-world use cases
|
|
37
|
-
- TypeScript types for all schema entities
|
package/README.md
CHANGED
|
@@ -1,67 +1,283 @@
|
|
|
1
|
-
# @mcp-ui
|
|
1
|
+
# @seed-ship/mcp-ui-spec
|
|
2
2
|
|
|
3
|
-
Component registry specification and
|
|
3
|
+
Component registry specification and validation schemas for MCP UI. Part of the MCP UI ecosystem.
|
|
4
|
+
|
|
5
|
+
[](https://www.npmjs.com/package/@seed-ship/mcp-ui-spec)
|
|
6
|
+
[](https://opensource.org/licenses/MIT)
|
|
7
|
+
|
|
8
|
+
## Overview
|
|
9
|
+
|
|
10
|
+
`@seed-ship/mcp-ui-spec` provides the schema definitions and validation utilities for MCP UI component registries. It includes both Zod schemas for runtime validation and JSON Schema for tooling integration.
|
|
4
11
|
|
|
5
12
|
## Installation
|
|
6
13
|
|
|
7
14
|
```bash
|
|
8
|
-
pnpm add @mcp-ui
|
|
15
|
+
pnpm add @seed-ship/mcp-ui-spec
|
|
9
16
|
```
|
|
10
17
|
|
|
11
|
-
##
|
|
18
|
+
## Quick Start
|
|
19
|
+
|
|
20
|
+
### Zod Validation (Recommended)
|
|
21
|
+
|
|
22
|
+
```typescript
|
|
23
|
+
import { ComponentRegistrySchema, ComponentSchema } from '@seed-ship/mcp-ui-spec'
|
|
24
|
+
|
|
25
|
+
// Validate a full registry
|
|
26
|
+
const result = ComponentRegistrySchema.safeParse(myRegistry)
|
|
27
|
+
if (!result.success) {
|
|
28
|
+
console.error('Validation errors:', result.error.issues)
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
// Validate a single component
|
|
32
|
+
const componentResult = ComponentSchema.safeParse(myComponent)
|
|
33
|
+
```
|
|
12
34
|
|
|
13
|
-
###
|
|
35
|
+
### JSON Schema Validation
|
|
14
36
|
|
|
15
37
|
```typescript
|
|
16
|
-
import
|
|
38
|
+
import registrySchema from '@seed-ship/mcp-ui-spec/schemas/component-registry-v1.json'
|
|
17
39
|
import Ajv from 'ajv'
|
|
18
40
|
|
|
19
41
|
const ajv = new Ajv()
|
|
20
42
|
const validate = ajv.compile(registrySchema)
|
|
21
43
|
|
|
22
|
-
|
|
23
|
-
if (!valid) {
|
|
44
|
+
if (!validate(myRegistry)) {
|
|
24
45
|
console.error(validate.errors)
|
|
25
46
|
}
|
|
26
47
|
```
|
|
27
48
|
|
|
28
|
-
|
|
49
|
+
## Exported Schemas
|
|
50
|
+
|
|
51
|
+
### Zod Schemas (10 total)
|
|
52
|
+
|
|
53
|
+
| Schema | Description |
|
|
54
|
+
|--------|-------------|
|
|
55
|
+
| `ComponentRegistrySchema` | Root registry object with version and components |
|
|
56
|
+
| `ComponentSchema` | Individual component definition |
|
|
57
|
+
| `ComponentExampleSchema` | Working example for a component |
|
|
58
|
+
| `GridPositionSchema` | 12-column grid positioning |
|
|
59
|
+
| `SecurityConstraintsSchema` | Security configuration (auth, domains, sandbox) |
|
|
60
|
+
| `PerformanceConstraintsSchema` | Performance limits (render time, data size) |
|
|
61
|
+
| `ComponentTypeSchema` | Enum of supported component types |
|
|
62
|
+
| `SandboxFlagSchema` | Iframe sandbox permissions |
|
|
63
|
+
| `RegistryMetadataSchema` | Optional registry metadata |
|
|
64
|
+
| `ComponentSchemaSchema` | JSON Schema definition for component params |
|
|
65
|
+
|
|
66
|
+
### TypeScript Types
|
|
67
|
+
|
|
68
|
+
All schemas export inferred TypeScript types:
|
|
29
69
|
|
|
30
70
|
```typescript
|
|
31
|
-
import {
|
|
71
|
+
import type {
|
|
72
|
+
ComponentRegistry,
|
|
73
|
+
Component,
|
|
74
|
+
ComponentExample,
|
|
75
|
+
GridPosition,
|
|
76
|
+
SecurityConstraints,
|
|
77
|
+
PerformanceConstraints,
|
|
78
|
+
ComponentType,
|
|
79
|
+
SandboxFlag,
|
|
80
|
+
RegistryMetadata
|
|
81
|
+
} from '@seed-ship/mcp-ui-spec'
|
|
82
|
+
```
|
|
32
83
|
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
84
|
+
## Component Types
|
|
85
|
+
|
|
86
|
+
The spec supports **11 component types**:
|
|
87
|
+
|
|
88
|
+
| Type | Description | Renderer |
|
|
89
|
+
|------|-------------|----------|
|
|
90
|
+
| `chart` | Data visualizations (bar, line, pie, etc.) | ChartRenderer |
|
|
91
|
+
| `table` | Tabular data display | TableRenderer |
|
|
92
|
+
| `metric` | KPI cards with trends | MetricRenderer |
|
|
93
|
+
| `text` | Markdown text blocks | TextRenderer |
|
|
94
|
+
| `composite` | Nested component layouts | UIResourceRenderer |
|
|
95
|
+
| `image` | Image display with captions | ImageRenderer |
|
|
96
|
+
| `link` | External link cards | LinkRenderer |
|
|
97
|
+
| `iframe` | Sandboxed embedded content | IframeRenderer |
|
|
98
|
+
| `action` | Interactive buttons | ActionRenderer |
|
|
99
|
+
| `artifact` | Downloadable files | ArtifactRenderer |
|
|
100
|
+
| `carousel` | Scrollable component list | CarouselRenderer |
|
|
101
|
+
| `footer` | Metadata display | FooterRenderer |
|
|
102
|
+
|
|
103
|
+
## Registry Format
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
interface ComponentRegistry {
|
|
107
|
+
version: '1.0.0'
|
|
108
|
+
metadata?: {
|
|
109
|
+
name?: string
|
|
110
|
+
description?: string
|
|
111
|
+
author?: string
|
|
112
|
+
repository?: string // URL format
|
|
113
|
+
}
|
|
114
|
+
components: Component[] // At least 1 required
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
interface Component {
|
|
118
|
+
id: string // kebab-case: /^[a-z0-9-]+$/
|
|
119
|
+
type: ComponentType // One of 11 types
|
|
120
|
+
name: string
|
|
121
|
+
description?: string
|
|
122
|
+
schema: { // JSON Schema for params
|
|
123
|
+
type: 'object'
|
|
124
|
+
required: string[]
|
|
125
|
+
properties: Record<string, unknown>
|
|
126
|
+
additionalProperties?: boolean
|
|
127
|
+
}
|
|
128
|
+
examples: ComponentExample[] // At least 1 required
|
|
129
|
+
security?: SecurityConstraints
|
|
130
|
+
performance?: PerformanceConstraints
|
|
131
|
+
tags?: string[] // kebab-case tags
|
|
132
|
+
version?: string // semver: /^\d+\.\d+\.\d+$/
|
|
133
|
+
deprecated?: boolean
|
|
134
|
+
deprecationMessage?: string
|
|
36
135
|
}
|
|
37
136
|
```
|
|
38
137
|
|
|
39
|
-
##
|
|
138
|
+
## Features
|
|
139
|
+
|
|
140
|
+
### Grid Positioning (12-column)
|
|
141
|
+
|
|
142
|
+
Components support a responsive 12-column grid layout:
|
|
143
|
+
|
|
144
|
+
```typescript
|
|
145
|
+
interface GridPosition {
|
|
146
|
+
colStart: number // 1-12: starting column
|
|
147
|
+
colSpan: number // 1-12: columns to span
|
|
148
|
+
rowStart?: number // Row start (optional)
|
|
149
|
+
rowSpan?: number // Rows to span (default: 1)
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
// Example: Full-width component
|
|
153
|
+
{ colStart: 1, colSpan: 12 }
|
|
154
|
+
|
|
155
|
+
// Example: Two-column layout
|
|
156
|
+
{ colStart: 1, colSpan: 6 } // Left half
|
|
157
|
+
{ colStart: 7, colSpan: 6 } // Right half
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
### Security Constraints
|
|
161
|
+
|
|
162
|
+
Configure security requirements per component:
|
|
163
|
+
|
|
164
|
+
```typescript
|
|
165
|
+
interface SecurityConstraints {
|
|
166
|
+
requiresAuth?: boolean // Default: false
|
|
167
|
+
allowedDomains?: string[] // Domain whitelist
|
|
168
|
+
maxIframeDepth?: number // 0-3, default: 1
|
|
169
|
+
sandboxFlags?: SandboxFlag[] // Iframe permissions
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
type SandboxFlag =
|
|
173
|
+
| 'allow-scripts'
|
|
174
|
+
| 'allow-same-origin'
|
|
175
|
+
| 'allow-forms'
|
|
176
|
+
| 'allow-popups'
|
|
177
|
+
| 'allow-modals'
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
### Performance Constraints
|
|
181
|
+
|
|
182
|
+
Set performance limits per component:
|
|
183
|
+
|
|
184
|
+
```typescript
|
|
185
|
+
interface PerformanceConstraints {
|
|
186
|
+
maxRenderTime?: number // Milliseconds, min: 100, default: 5000
|
|
187
|
+
maxDataSize?: number // Bytes, min: 1024, default: 102400 (100KB)
|
|
188
|
+
}
|
|
189
|
+
```
|
|
190
|
+
|
|
191
|
+
### Component Deprecation
|
|
192
|
+
|
|
193
|
+
Mark components as deprecated with optional migration messages:
|
|
194
|
+
|
|
195
|
+
```typescript
|
|
196
|
+
{
|
|
197
|
+
"id": "old-chart",
|
|
198
|
+
"type": "chart",
|
|
199
|
+
"deprecated": true,
|
|
200
|
+
"deprecationMessage": "Use quickchart-bar instead",
|
|
201
|
+
// ...
|
|
202
|
+
}
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### Component Versioning
|
|
206
|
+
|
|
207
|
+
Individual components support semantic versioning:
|
|
208
|
+
|
|
209
|
+
```typescript
|
|
210
|
+
{
|
|
211
|
+
"id": "quickchart-bar",
|
|
212
|
+
"version": "2.1.0",
|
|
213
|
+
// ...
|
|
214
|
+
}
|
|
215
|
+
```
|
|
216
|
+
|
|
217
|
+
## Example Registry
|
|
40
218
|
|
|
41
219
|
```json
|
|
42
220
|
{
|
|
43
221
|
"version": "1.0.0",
|
|
222
|
+
"metadata": {
|
|
223
|
+
"name": "My Component Registry",
|
|
224
|
+
"description": "Custom MCP UI components",
|
|
225
|
+
"author": "Your Name"
|
|
226
|
+
},
|
|
44
227
|
"components": [
|
|
45
228
|
{
|
|
46
229
|
"id": "quickchart-bar",
|
|
47
230
|
"type": "chart",
|
|
48
231
|
"name": "Bar Chart",
|
|
49
|
-
"description": "Renders a bar chart",
|
|
50
|
-
"
|
|
51
|
-
"
|
|
232
|
+
"description": "Renders a bar chart via QuickChart.io",
|
|
233
|
+
"version": "1.0.0",
|
|
234
|
+
"schema": {
|
|
235
|
+
"type": "object",
|
|
236
|
+
"required": ["labels", "data"],
|
|
237
|
+
"properties": {
|
|
238
|
+
"labels": { "type": "array", "items": { "type": "string" } },
|
|
239
|
+
"data": { "type": "array", "items": { "type": "number" } },
|
|
240
|
+
"title": { "type": "string" }
|
|
241
|
+
}
|
|
242
|
+
},
|
|
243
|
+
"examples": [
|
|
244
|
+
{
|
|
245
|
+
"name": "Simple Bar Chart",
|
|
246
|
+
"description": "A basic bar chart example",
|
|
247
|
+
"params": {
|
|
248
|
+
"labels": ["Q1", "Q2", "Q3", "Q4"],
|
|
249
|
+
"data": [100, 150, 120, 180],
|
|
250
|
+
"title": "Quarterly Revenue"
|
|
251
|
+
},
|
|
252
|
+
"position": { "colStart": 1, "colSpan": 6 }
|
|
253
|
+
}
|
|
254
|
+
],
|
|
52
255
|
"security": {
|
|
53
|
-
"requiresAuth":
|
|
256
|
+
"requiresAuth": false,
|
|
54
257
|
"allowedDomains": ["quickchart.io"]
|
|
55
258
|
},
|
|
56
|
-
"
|
|
259
|
+
"performance": {
|
|
260
|
+
"maxRenderTime": 3000,
|
|
261
|
+
"maxDataSize": 51200
|
|
262
|
+
},
|
|
263
|
+
"tags": ["chart", "visualization", "quickchart"]
|
|
57
264
|
}
|
|
58
265
|
]
|
|
59
266
|
}
|
|
60
267
|
```
|
|
61
268
|
|
|
62
|
-
##
|
|
269
|
+
## Related Packages
|
|
270
|
+
|
|
271
|
+
| Package | Description |
|
|
272
|
+
|---------|-------------|
|
|
273
|
+
| [`@seed-ship/mcp-ui-solid`](../mcp-ui-solid) | SolidJS UI components |
|
|
274
|
+
| [`@seed-ship/mcp-ui-cli`](../mcp-ui-cli) | CLI for validation and type generation |
|
|
275
|
+
|
|
276
|
+
## Versioning
|
|
277
|
+
|
|
278
|
+
This package follows [Semantic Versioning](https://semver.org/). See [CHANGELOG.md](./CHANGELOG.md) for release notes.
|
|
63
279
|
|
|
64
|
-
|
|
280
|
+
**Current Version:** 1.1.0
|
|
65
281
|
|
|
66
282
|
## License
|
|
67
283
|
|