@scaffold-mcp/define-scaffold

Schema and validation utilities for scaffold server configurations.

Purpose

This package provides Zod schemas and validation functions for:

• server.json - Server configuration files that define available scaffold modules
• Module metadata - YAML frontmatter in module markdown files

Usage

Validating server.json

import { validateServerConfig, ServerConfigSchema } from '@scaffold-mcp/define-scaffold'

const serverConfig = {
  name: 'my-server',
  version: '1.0.0',
  description: 'My scaffold server',
  modules: [
    './core.md'
  ]
}

const result = validateServerConfig(serverConfig)
if (result.success) {
  console.log('Valid server config:', result.data)
} else {
  console.error('Validation errors:', result.errors)
}

Validating module metadata

import { validateModuleMetadata } from '@scaffold-mcp/define-scaffold'

const metadata = {
  name: 'core',
  version: '1.0.0',
  description: 'Core module',
  dependencies: {
    'react': { minVersion: '18.0.0' }
  },
  features: {
    'ssr': 'boolean',
    'routing': 'boolean'
  }
}

const result = validateModuleMetadata(metadata)

Using schemas directly

import { ServerConfigSchema, ModuleMetadataSchema } from '@scaffold-mcp/define-scaffold'

// For JSON Schema generation or other Zod use cases
const serverSchema = ServerConfigSchema
const moduleSchema = ModuleMetadataSchema

Querying servers and checking compatibility

import { 
  loadScaffoldConfig, 
  queryServer, 
  checkCompatibility,
  getInstalledModules 
} from '@scaffold-mcp/define-scaffold'

// Load user's current configuration
const scaffoldConfig = await loadScaffoldConfig('./scaffold.json')

// Query a server for available modules
const serverResult = await queryServer('https://example.com/tanstack-start')
if (serverResult.success) {
  console.log('Available modules:', serverResult.modules)
}

// Check compatibility between user's config and server
const compatibility = await checkCompatibility(scaffoldConfig, 'https://example.com/tanstack-start')
console.log('Installed modules:', compatibility.installedModules)
console.log('Available to install:', compatibility.availableModules)

// Get list of installed modules
const installed = getInstalledModules(scaffoldConfig)

Schema Structure

ServerConfig

• name - Server identifier
• version - Server version
• description - Human-readable description
• modules - Array of relative paths to module markdown files

ModuleMetadata (YAML frontmatter)

• name - Module name (defined in the markdown file)
• version - Module version
• description - Module description
• dependencies - Optional dependencies on other modules
• features - Optional feature flags with types

ScaffoldConfig (scaffold.json)

• modules - Object mapping installed module names to their configuration

InstalledModule

• version - Installed version of the module
• server - Server URL or path where the module was installed from
• features - Optional object mapping feature names to their enabled values

Dependencies Format

Dependencies are only for internal module dependencies within the scaffold system:

dependencies:
  other-module-name:
    server: optional-server-name  # defaults to same server
    minVersion: "1.0.0"           # optional minimum version

External package dependencies (like react, typescript) are not managed by this system.

Features Format

features:
  feature-name: boolean  # or 'string' or 'number'

Example scaffold.json

{
  "modules": {
    "tanstack-start/core": {
      "version": "1.0.0",
      "server": "https://example.com/tanstack-start",
      "features": {
        "router": true,
        "ssr": false
      }
    },
    "tanstack-start/react-query": {
      "version": "1.0.0",
      "server": "https://example.com/tanstack-start",
      "features": {
        "devtools": true,
        "persistence": false,
        "optimistic": true
      }
    }
  }
}

Testing

Run tests with:

bun run test

License

MIT