ionic-frame-mcp

MCP server for Ionic UI wireframe scaffolding.

ionic-frame-mcp gives AI agents structured, machine-readable knowledge of Ionic components and UI patterns, plus tools to scaffold, validate, and preview JSON wireframes.

Features

• Ionic component knowledge base from data/components/*.json
• Pattern library from data/patterns/*.json
• Wireframe schema discovery tool for agent bootstrapping
• Natural-language wireframe scaffolding
• Container composition helpers
• Wireframe validation (schema + composability checks)
• Ionicons keyword search
• HTML preview generation for wireframes

Tech stack

• Node.js + TypeScript
• @modelcontextprotocol/sdk
• zod for runtime schema validation
• tsup for build output
• vitest for tests

Project structure

• src/index.ts — stdio MCP entrypoint
• src/server.ts — server setup and registration
• src/tools/ — MCP tools
• src/resources/ — MCP resources
• src/engine/ — wireframe builder/layout/validation/rendering logic
• src/knowledge/ — component/pattern stores backed by data/
• src/schemas/ — Zod schemas
• scripts/ingest/ — data ingestion and enrichment pipeline
• data/ — generated and curated knowledge base files
• test/ — Vitest test suite

Setup

VS Code / GitHub Copilot

Add the following to your .vscode/mcp.json (workspace-level) or User Settings JSON under "mcp":

{
  "servers": {
    "ionic-frame": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/ionic-frame/src/index.ts"],
      "env": {}
    }
  }
}

Or, if you have built the project first (npm run build):

{
  "servers": {
    "ionic-frame": {
      "command": "node",
      "args": ["/absolute/path/to/ionic-frame/dist/index.js"],
      "env": {}
    }
  }
}

Cursor

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "ionic-frame": {
      "command": "npx",
      "args": ["tsx", "/absolute/path/to/ionic-frame/src/index.ts"]
    }
  }
}

Or with the built output:

{
  "mcpServers": {
    "ionic-frame": {
      "command": "node",
      "args": ["/absolute/path/to/ionic-frame/dist/index.js"]
    }
  }
}

Replace /absolute/path/to/ionic-frame with the actual path where you cloned this repo.

---

MCP tools

Tool	Description
get-wireframe-schema	Returns the wireframe JSON schema so the agent knows the expected format
list-components	Lists Ionic components (optional category filter)
query-component	Returns full/summary/syntax/semantics for a component
search-components	Keyword search across names, descriptions, and use cases
scaffold-wireframe	Generates a wireframe from a natural-language description (element, container, or page)
compose-container	Combines components into a layout (stack, grid, flex, …)
get-pattern	Retrieves a UI pattern, optionally a specific variation
list-patterns	Lists available UI patterns (optional category filter)
validate-wireframe	Validates a wireframe against the schema and composability rules
search-icons	Searches Ionicons by keyword
preview-wireframe	Renders a wireframe to a standalone HTML page

MCP resources

URI	Description
ionic://components	Full list of all Ionic components
ionic://schema/component	Ionic component JSON schema
ionic://schema/wireframe	Wireframe JSON schema
ionic://patterns	Full list of UI patterns

---

Example prompts

Below are ready-to-use prompts you can paste into Copilot Chat, Cursor, or any MCP-enabled AI client once the server is connected.

Scaffold a full login page

Scaffold a login page wireframe using Ionic components. It should have a header with the app title, email and password inputs, a "Sign In" button, and a "Forgot password?" link.

Build a settings screen

Create a settings page wireframe with toggle switches for notifications, dark mode, and location services. Use ion-list with ion-item rows and ion-toggle at the end of each row.

Design tab navigation

Scaffold a page wireframe with bottom tab navigation. Include three tabs: Home, Search, and Profile. Each tab should have an icon and a label.

Compose a product card

Use compose-container to lay out an ion-card containing an ion-img, ion-card-header with a title and subtitle, ion-card-content with a description, and an ion-button labelled "Add to Cart".

Create a search interface

Scaffold a container wireframe for a search UI: an ion-searchbar at the top, followed by an ion-list of ion-item results each showing an ion-avatar, a label, and a note.

Build a registration form

Scaffold a page wireframe for user registration. Include inputs for name, email, phone number, and password, a terms-and-conditions checkbox, and a "Create Account" button. Validate the wireframe afterwards.

Preview any wireframe

Scaffold a wireframe for a profile page with an avatar, user name, bio, and a list of recent activity. Then preview it as HTML so I can see what it looks like.

Discover components and icons

Search for Ionic components related to "date picker". Also search for calendar-related icons I can use alongside them.

---

Typical agent workflow

1. Learn the format — call get-wireframe-schema
2. Explore components — call list-components or search-components
3. Scaffold — call scaffold-wireframe with a description
4. Validate — call validate-wireframe on the result
5. Preview — call preview-wireframe to render HTML

---

Development

npm install          # install dependencies
npm run dev          # run in watch mode
npm run build        # production build
npm test             # run tests
npm run lint         # lint
npm run format       # format
npm run inspect      # open MCP Inspector

Data pipeline

Rebuild the knowledge base from upstream Ionic docs:

npx tsx scripts/ingest/fetch-core-json.ts      # download core.json
npx tsx scripts/ingest/build-knowledge-base.ts  # build component files
npx tsx scripts/ingest/enrich-semantics.ts      # add semantic metadata
npx tsx scripts/ingest/validate-kb.ts           # validate output

Outputs land in data/components/*.json, data/index.json, and data/raw/core.json.
search-icons requires data/icons/ionicons-index.json (tools degrade gracefully when data is missing).

License

No license file is currently present in this repository.