FrameIO Server

Model Context Protocol (MCP) server for FrameIO module and plugin creation and validation. This server provides tools, resources, and prompts to help LLMs consistently build FrameIO modules and plugins.

Features

• Code Generation: Generate complete module/plugin scaffolding and entity definitions
• Validation: Validate module structure, code, and conventions
• Examples: Access real-world examples from existing modules and plugins
• Documentation: Comprehensive framework documentation and best practices
• Guidance: Step-by-step prompts for module and plugin creation

Installation

cd tools/frameio-mcp
npm install
npm run build

Configuration

Cursor Configuration

Add to your Cursor MCP settings (.cursor/mcp.json or Cursor settings):

{
  "mcpServers": {
    "frameio": {
      "command": "node",
      "args": ["tools/frameio-mcp/dist/server.js"],
      "cwd": "."
    }
  }
}

VS Code / Other Clients

Configure your MCP client to run:

node tools/frameio-mcp/dist/server.js

Available Tools

1. generate_module

Generate complete module scaffolding.

Parameters:

• moduleId (string, required): Kebab-case module identifier
• displayName (string, required): Human-readable module name
• description (string, required): Module description
• entities (array, optional): Array of entity definitions
• includeNavigation (boolean, default: true): Generate navigation items
• includeCommands (boolean, default: true): Generate command palette entries

Returns: Complete module code structure including package.json, index.ts, tsconfig.json, and registry entry

2. generate_entity

Generate entity definition code.

Parameters:

• entityKey (string, required): Format {module-id}.{entity-name}
• name (string, required): Singular entity name
• pluralName (string, required): Plural entity name
• description (string, required): Entity description
• fields (array, required): Array of field definitions
• icon (string, optional): Lucide icon name
• views (array, optional): View configurations

Returns: Complete entity definition code using defineEntity() builder

3. validate_module

Validate module structure and code.

Parameters (choose one mode):

• Local: modulePath (string): Path to module directory (relative to the process cwd, usually the FrameIO repo root).
• Remote / hosted MCP: files (object): Map of relative paths to UTF-8 file text. Must include at least package.json and src/index.ts. Optional moduleId if the package name is non-standard; optional registryContent with the full text of modules/.registry.ts to verify registration.
• strict (boolean, default: false): Enable strict validation

Returns: Validation results with errors, warnings, and checks

4. get_example_module

Fetch example module source. If the MCP process has a FrameIO checkout, examples are read from modules/. Otherwise (e.g. Railway-hosted MCP) the server returns bundled samples (rewards, bom, calendar-demo).

Parameters:

• moduleId (string, optional): Specific module to fetch
• feature (string, optional): Specific feature (entities, navigation, commands, etc.)
• pattern (string, optional): Pattern to match (e.g., "reference-field", "kanban-view")

Returns: Example code snippets from existing modules

5. validate_plugin

Validate plugin structure, route contract, and build contract.

Parameters:

• pluginPath (string, required): Path to plugin directory (e.g. plugins/my-plugin)
• strict (boolean, default: false): Enable strict validation

Returns: Validation results with checks for structure, exports, route contract (createRouter(deps), no registerRoutes), build contract (tsconfig.build.json), and registry

Available Resources

1. frameio://architecture

Design philosophy and platform architecture (canonical reference for modules and plugins):

• Registration-based design; no domain in core
• Modules vs plugins (strict split): modules = UI + metadata; plugins = API + UI + widget data
• Core: generic only; permissions from registry; widget data from plugin providers only
• Plugin route contract: createRouter(deps: PluginApiDeps); build contract: tsconfig.build.json, types from @frameio/sdk

Read this first when creating modules or plugins so generated code aligns with the platform.

2. frameio://framework-guide

Comprehensive framework documentation covering:

• Module structure and conventions
• Entity definition patterns
• Field types and options
• Navigation, commands, stat cards, quick links
• Custom pages
• Best practices

3. frameio://field-types

Complete reference of all available field types:

• String, text, number, decimal fields
• Boolean, date, datetime fields
• Email, phone, URL fields
• Select, multiselect fields
• Reference, location fields
• Currency, percentage, JSON fields

Each with options, validation rules, and examples.

4. frameio://examples/{module-id}

Example code from specific modules:

• frameio://examples/pos-bom - BOM module example
• frameio://examples/module-rewards - Comprehensive feature example
• frameio://examples/pos-inventory - Inventory module example

5. frameio://best-practices

Best practices guide:

• Naming conventions
• Entity design patterns
• Field selection guidelines
• Module organization
• Common patterns

Available Prompts

1. module_creation_guide

Step-by-step guidance for creating a new module.

Arguments:

• moduleId (optional): Module ID
• displayName (optional): Display name
• description (optional): Description

2. entity_design_guide

Guidance for designing entities.

Arguments:

• entityName (optional): Name of the entity
• moduleId (optional): Module ID

3. validation_checklist

Checklist for validating a module.

Arguments:

• moduleId (optional): Module ID to validate

Usage Examples

Generate a Module

Use the generate_module tool with:
- moduleId: "my-module"
- displayName: "My Module"
- description: "A sample module"

Generate an Entity

Use the generate_entity tool with:
- entityKey: "my-module.product"
- name: "Product"
- pluralName: "Products"
- description: "Product catalog items"
- fields: [
    { type: "string", key: "name", name: "Name", options: { required: true } },
    { type: "number", key: "price", name: "Price", options: { required: true } }
  ]

Validate a Module

Use the validate_module tool with:
- modulePath: "modules/my-module"
- strict: true

Validate a Plugin

Use the validate_plugin tool with:
- pluginPath: "plugins/my-plugin"
- strict: false

Validates structure, route contract (createRouter(deps), no registerRoutes), build contract (tsconfig.build.json), and registry.

Get Examples

Use the get_example_module tool with:
- pattern: "kanban-view"

Development

Building

npm run build

Development Mode

npm run dev  # Watch mode

Running

npm start

Project Structure

tools/frameio-mcp/
├── src/
│   ├── server.ts              # MCP server entry point
│   ├── tools/                 # Tool implementations
│   │   ├── generate-module.ts
│   │   ├── generate-entity.ts
│   │   ├── validate-module.ts
│   │   └── get-example-module.ts
│   ├── resources/             # Resource implementations
│   │   ├── framework-guide.ts
│   │   ├── field-types.ts
│   │   ├── examples.ts
│   │   └── best-practices.ts
│   ├── prompts/               # Prompt templates
│   │   ├── module-creation.ts
│   │   ├── entity-design.ts
│   │   └── validation-checklist.ts
│   └── utils/                  # Utility functions
│       ├── code-generator.ts
│       ├── validator.ts
│       └── example-loader.ts
├── package.json
├── tsconfig.json
└── README.md

Integration with FrameIO Framework

This MCP server integrates with:

• Module Registry: Reads from modules/.registry.ts (auto-updated by CLI)
• Plugin Registry: Reads from plugins/.registry.ts (auto-updated by CLI)
• Existing Modules: Scans modules/ directory for examples
• Existing Plugins: Scans plugins/ directory for examples (Data Orchestrator, OAuth, Integrations)
• SDK Types: Uses types from platform/sdk/
• CLI Tools: Leverages code from tools/frameio-cli/ (which auto-registers modules/plugins)
• Dynamic Module/Plugin Loading: Modules and plugins are discovered and loaded at runtime
• Storybook: Component development environment available at port 6006
• Migration System: Versioned database migrations with rollback support

Plugin System

FrameIO includes a powerful plugin system that allows extending the platform's core functionality:

Built-in Plugins

Plugin	Description
data-orchestrator	Visual data flow builder for connecting modules and orchestrating data pipelines
oauth	OAuth authentication providers (Google, GitHub, Azure, etc.)
integration	Third-party API access management with client credentials or API keys

Plugin Capabilities

Plugins can:

• Modify Core UI: Add items to sidebar, header, and login page
• Register Routes: Create new pages within the application
• Define Permissions: Introduce new permission keys for access control
• Add Backend Logic: Register custom API endpoints and database tables
• Theme Integration: Automatically adapt to light/dark themes

Plugin Structure

plugins/
├── .registry.ts          # Plugin registration
├── data-orchestrator/    # Visual data flow builder
│   ├── src/
│   │   ├── index.ts      # Plugin definition
│   │   ├── components/   # React components
│   │   └── types/        # TypeScript types
│   └── package.json
├── oauth/                # OAuth authentication
└── integration/          # Third-party integrations

Creating a Plugin

1. Create directory: plugins/my-plugin/src
2. Add package.json with @frameio/sdk dependency
3. Create src/index.ts with plugin registration using createPlugin()
4. Add components in src/components/
5. Register in plugins/.registry.ts
6. Run npm run dev - imports are auto-generated!

Troubleshooting

Module Not Found

If examples aren't loading:

• Ensure modules exist in modules/ directory
• Check that src/index.ts exists in each module
• Verify file permissions

Plugin Not Found

If plugin examples aren't loading:

• Ensure plugins exist in plugins/ directory
• Check that src/index.ts exists in each plugin
• Verify plugin is registered in plugins/.registry.ts

Validation Errors

If validation fails:

• Check module structure matches conventions
• Verify export names follow camelCase convention
• Ensure entity keys follow format
• Check registry entry exists

MCP Server Not Starting

If server won't start:

• Verify Node.js version >= 20.0.0
• Run npm install to install dependencies
• Run npm run build to compile TypeScript
• Check MCP client configuration

License

Part of the FrameIO framework.