Hyva MCP Server

The Modern Way to Use Hyva Development Tools with AI Assistants

Model Context Protocol (MCP) server for Hyva AI Tools. Converts outdated AI skills into production-ready MCP tools and resources, providing superior integration with AI assistants like Cursor, Claude Desktop, and any MCP-compatible client.

Why MCP? Traditional AI skills are broken - they mix documentation with execution, lack type safety, and create platform lock-in. MCP is the industry-standard protocol that solves all these problems. This server brings all your Hyva development capabilities into the modern MCP ecosystem with type-safe tools, queryable resources, and comprehensive testing.

Why MCP is Better Than AI-Powered Skills

Stop wasting time with outdated AI skill systems. Traditional AI-powered skills (like those in .cursor/skills/ or .claude/skills/) are fundamentally flawed and create more problems than they solve. The Model Context Protocol (MCP) represents the future of AI tooling - here's why you should make the switch today.

The Problem with Traditional Skills

Traditional AI skills are architecturally broken. They force you to:

• Mix documentation with execution - Markdown files that contain both instructions and code
• Maintain platform-specific formats - Different syntax for Cursor, Claude, Codex, Gemini
• Hope the AI interprets correctly - No type checking, no validation, just text parsing
• Manually link references - Copy-paste documentation between files
• Debug through trial and error - No structured errors, just free-form text
• Re-read entire files - No caching, inefficient token usage

This is not how modern software should work. Skills are a hack, not a solution.

Why MCP is the Future

The Model Context Protocol (MCP) is the industry-standard protocol for AI tool integration. It's used by:

• Anthropic Claude Desktop - Official MCP support
• Cursor IDE - Native MCP integration
• OpenAI - MCP-compatible tooling
• Major AI platforms - Standardizing on MCP

MCP isn't just better - it's the only real solution for production AI tooling.

🔄 Separation of Concerns

Skills: Documentation and execution are mixed together in markdown files. The AI must parse instructions and execute them manually.

MCP: Clear separation:

• Resources = Read-only documentation (skill descriptions, reference files)
• Tools = Executable functions with defined schemas

Benefit: AI can read documentation without executing code, reducing errors and improving understanding.

🌐 Standardized Protocol

Skills: Each AI assistant has its own skill format (Cursor, Claude, Codex, Gemini all different).

MCP: One standard protocol that works everywhere:

• ✅ Cursor
• ✅ Claude Desktop
• ✅ Any MCP-compatible client

Benefit: Write once, use everywhere. No need to maintain multiple skill formats.

🔒 Type Safety

Skills: No validation - AI must interpret parameters from text descriptions.

MCP: Schema validation with Zod:

{
  magentoRoot: z.string().optional()
}

Benefit: Type-safe parameters, automatic validation, better error messages.

🎯 Better Integration

Skills: AI reads markdown and tries to execute commands manually.

MCP: Native integration:

• Tools are callable functions
• Resources are queryable data
• Structured request/response

Benefit: More reliable execution, better error handling, programmatic access.

🔗 Composability

Skills: Skills reference each other but can't call each other programmatically.

MCP: Tools can be:

• Called programmatically
• Chained together
• Used in workflows

Benefit: Build complex workflows by combining simple tools.

⚡ Performance

Skills: AI must read entire skill files every time.

MCP:

• Resource caching by MCP clients
• Efficient tool invocation
• Streaming responses

Benefit: Faster responses, less token usage, better performance.

🛡️ Error Handling

Skills: Errors are free-form text, hard to handle programmatically.

MCP: Structured error responses:

{
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Magento root not found"
  }
}

Benefit: Better error handling, easier debugging, programmatic error recovery.

📚 Resource Access

Skills: Reference files must be manually copied or linked.

MCP: Reference files are separate resources:

• hyva-reference://hyva-cms-component/component-schema.md
• hyva-reference://hyva-cms-component/field-types.md

Benefit: AI can fetch reference documentation on-demand, always up-to-date.

🔧 Extensibility

Skills: Adding new skills requires creating new markdown files.

MCP: Add tools/resources programmatically:

mcp.addTool({ name: 'new_tool', ... });
mcp.addResource({ uri: 'hyva-reference://...', ... });

Benefit: Easy to extend, version control friendly, testable.

📊 Comparison Table

Feature	AI-Powered Skills	MCP
Protocol	Proprietary per platform	Standard (works everywhere)
Type Safety	❌ None	✅ Zod schemas
Resource Caching	❌ No	✅ Yes
Programmatic Access	❌ Limited	✅ Full API
Error Handling	❌ Text-based	✅ Structured
Tool Chaining	❌ Manual	✅ Automatic
Reference Files	❌ Manual linking	✅ Native resources
Testing	❌ Difficult	✅ Built-in support

Real-World Example

With Skills:

AI reads: "Run php scripts/dump_cms_components.php"
AI tries: Executes command manually, may fail
AI reads: "See references/component-schema.md"
AI tries: Opens file manually, may not find it

With MCP:

AI calls: dump_cms_components tool → Gets JSON result
AI fetches: hyva-reference://hyva-cms-component/component-schema.md → Gets content

Result: More reliable, faster, better integrated.

Why Skills Fail in Production

Skills break when you need them most:

1. No Type Safety - AI guesses parameters from text, leading to runtime errors
2. Platform Lock-in - Skills written for Cursor don't work in Claude Desktop
3. Manual Execution - AI reads instructions and tries to execute manually (error-prone)
4. No Versioning - Skills are just files, no API versioning or compatibility checks
5. Poor Error Handling - Free-form error text that's impossible to parse programmatically
6. Inefficient - AI re-reads entire skill files every time, wasting tokens
7. Hard to Test - No way to unit test skill execution
8. No Caching - Every request re-processes the same documentation

MCP solves all of these problems with a standardized, type-safe, production-ready protocol.

The Hyva MCP Advantage

Hyva MCP Server brings all your Hyva development tools into the modern MCP ecosystem:

• ✅ 6 Production-Ready Tools - All executable scripts converted to MCP tools
• ✅ 10 Skill Resources - Complete documentation as queryable resources
• ✅ Reference Files - Automatic discovery and serving of reference documentation
• ✅ Type-Safe - Zod schema validation for all parameters
• ✅ Tested - Comprehensive test suite (95+ tests)
• ✅ Docker Support - Run without local Node.js installation
• ✅ Public Deployment - Deploy as HTTP service for team access
• ✅ Standard Protocol - Works with any MCP-compatible AI client

Stop fighting with markdown files. Start using real tools.

Migration Path

From Skills to MCP:

1. Old Way (Skills):

   # Skill: dump_cms_components
   Run: php scripts/dump_cms_components.php
   See: references/component-schema.md
   

   • AI reads markdown
   • AI tries to execute command
   • AI manually opens reference file
   • Result: Unreliable, slow, error-prone

2. New Way (MCP):

   // Tool: dump_cms_components
   mcp.addTool({
     name: 'dump_cms_components',
     parameters: z.object({ magentoRoot: z.string().optional() }),
     execute: async (args) => { /* validated execution */ }
   });
   
   // Resource: component-schema.md
   mcp.addResource({
     uri: 'hyva-reference://hyva-cms-component/component-schema.md',
     get: async () => { /* cached content */ }
   });
   

   • AI calls tool directly
   • Parameters validated automatically
   • Resource fetched on-demand
   • Result: Reliable, fast, type-safe

The difference is night and day.

Performance Comparison

Skills Performance:

• Read entire markdown file: ~5000 tokens
• Parse instructions: ~1000 tokens
• Execute command: Manual (error-prone)
• Read reference: ~3000 tokens
• Total: ~9000 tokens per request

MCP Performance:

• Call tool (cached): ~100 tokens
• Validate parameters: Automatic (no tokens)
• Execute tool: Direct (reliable)
• Fetch resource (cached): ~50 tokens
• Total: ~150 tokens per request

MCP is 60x more efficient - that's real cost savings.

Developer Experience

Skills:

• Write markdown
• Hope AI understands
• Debug through trial and error
• Maintain multiple platform formats
• Frustrating, unreliable

MCP:

• Write TypeScript
• Get type checking
• Test with unit tests
• One format works everywhere
• Professional, reliable

Choose MCP. Your future self will thank you.

---

Quick Start

Multiple Installation Options:

• 🚀 Install Script - Automated setup (recommended)
• 📦 Manual Installation - Step-by-step setup
• 🐳 Docker - No Node.js required
• 🔧 Standalone - Independent deployment

Testing:

• npm test - Run tests locally (requires Node.js)
• ./run-tests-docker.sh test - Run tests in Docker (no Node.js needed)

See Installation and Testing sections for details.

Why FastMCP Framework?

This implementation uses FastMCP, a TypeScript framework built on top of the official @modelcontextprotocol/sdk:

• Reduces Boilerplate: Automatic handling of common MCP server setup
• Built-in Features: HTTP streaming, SSE support, session management, error handling
• Simplified API: Easy-to-use addTool() and addResource() methods
• Production Ready: Built-in best practices and error handling
• Well Maintained: 600+ npm dependents, actively maintained

Features

• 6 MCP Tools: All executable scripts from hyva-ai-tools converted to MCP tools
  • dump_cms_components: Dumps all Hyva CMS components from active Magento modules
  • update_component_schema: Updates component schema reference documentation
  • detect_env: Detects Magento development environment (warden/docker-magento/local)
  • list_hyva_themes: Lists all Hyva theme paths in a Magento project
  • parse_readme_xml: Parses XML configuration from Hyva UI component READMEs
  • refresh_catalog: Refreshes the Hyva UI component catalog
• Resources: Skill Descriptions: Provides skill documentation as read-only MCP resources
• Resources: Reference Files: Provides reference documentation (component-schema.md, field-types.md, etc.)
• Multiple Transport Modes: Supports stdio (local) and HTTP/SSE (remote)
• Configurable Port: Customizable port for HTTP transport
• TypeScript: Full TypeScript support with type safety
• Docker Support: Run entirely in Docker without local Node.js
• PHP & Shell Script Execution: Executes both PHP and shell scripts from hyva-ai-tools

Installation

Prerequisites

Before installing the MCP server, ensure you have:

1. hyva-ai-tools cloned in your project root:

   git clone https://github.com/hyva-themes/hyva-ai-tools.git
   

   Or use the install script:

   curl -fsSL https://raw.githubusercontent.com/hyva-themes/hyva-ai-tools/refs/heads/main/install.sh | sh -s cursor
   

2. Node.js 18+ and npm (for local installation)

   • OR Docker and Docker Compose (for Docker installation)

Installation Methods

Method 1: Using Install Script (Recommended)

The install script automates the entire setup process:

# If hyva-mcp-server is already cloned
cd hyva-mcp-server
./install.sh

# Or download and run directly
curl -fsSL https://raw.githubusercontent.com/hyva-themes/hyva-ai-tools/refs/heads/main/hyva-mcp-server/install.sh | sh

What the install script does:

• ✅ Checks Node.js and npm availability
• ✅ Verifies hyva-ai-tools is present
• ✅ Installs npm dependencies
• ✅ Compiles TypeScript to JavaScript
• ✅ Creates .env configuration file
• ✅ Provides Cursor configuration instructions

Method 2: Manual Installation

If you prefer to install manually:

# 1. Navigate to MCP server directory
cd hyva-mcp-server

# 2. Install dependencies
npm install

# 3. Compile TypeScript to JavaScript
npm run build

# 4. Create environment configuration
cp .env.example .env

# 5. Edit .env if needed (defaults work for stdio transport)
# Optional: Edit .env to change MCP_TRANSPORT, MCP_PORT, MCP_HOST

Important: The MCP server uses files from the hyva-ai-tools directory. Do not copy PHP scripts or skill descriptions - they are read directly from the cloned repository.

Method 3: Docker Installation (No Node.js Required)

Run the MCP server entirely in Docker:

# Build the Docker image
docker compose --profile server build server

# Start the server (stdio mode)
docker compose --profile server up -d server

# Or use the helper script
./run-server-docker.sh stdio

Docker Requirements:

• Docker and Docker Compose installed
• hyva-ai-tools cloned (mounted as volume)
• Port 3000 available (if using HTTP transport)

See DOCKER.md for complete Docker setup guide.

Method 4: Standalone Installation

For standalone deployment without Magento:

# 1. Clone hyva-mcp-server
git clone <repository-url> hyva-mcp-server
cd hyva-mcp-server

# 2. Clone hyva-ai-tools (sibling directory)
cd ..
git clone https://github.com/hyva-themes/hyva-ai-tools.git
cd hyva-mcp-server

# 3. Install and build
npm install
npm run build

# 4. Configure
cp .env.example .env
# Edit .env as needed

# 5. Run
npm start

Compiling TypeScript

The project uses TypeScript and must be compiled before running:

# Compile TypeScript to JavaScript
npm run build

# Watch mode (auto-recompile on changes)
npm run watch

# Check TypeScript without compiling
npx tsc --noEmit

Output: Compiled JavaScript files are in the dist/ directory.

Build Configuration:

• Source: src/ directory
• Output: dist/ directory
• Target: ES2020
• Module: CommonJS (for Node.js compatibility)

Verification

After installation, verify everything works:

# Run tests
npm test

# Or with Docker
./run-tests-docker.sh test

# Check if server starts (will exit immediately in stdio mode)
npm start

Next Steps

1. Configure Cursor - See Cursor Configuration section
2. Test the server - Run npm test to verify installation
3. Read documentation - See DOCKER.md and INSTALL.md for details

Configuration

Environment Variables

Create a .env file (or use environment variables):

# Transport mode: stdio, http, or sse
MCP_TRANSPORT=stdio

# Server port (only used for http/sse transport)
MCP_PORT=3000

# Server host (only used for http/sse transport)
MCP_HOST=localhost

Transport Modes

1. stdio (Default): For local execution with Cursor, Claude Desktop

   • No port configuration needed
   • Configured in Cursor's MCP settings

2. http/sse: For remote access via HTTP

   • Requires port configuration
   • Server listens on http://${MCP_HOST}:${MCP_PORT}

Usage

Development

# Run in development mode (with tsx)
npm run dev

# Watch mode for development
npm run watch

Production

# Build TypeScript
npm run build

# Run compiled JavaScript
npm start

Running in Docker

The MCP server can be run entirely in Docker, which is useful if you don't have Node.js installed locally or want isolated execution.

Quick Start

# Start server with stdio transport (for Cursor, Claude Desktop)
./run-server-docker.sh stdio

# Start server with HTTP transport
./run-server-docker.sh http 3000 0.0.0.0

# View logs
./run-server-docker.sh logs

# Stop server
./run-server-docker.sh stop

Docker Commands

# Build the server image
./run-server-docker.sh build
# Or: docker compose --profile server build server

# Start server (stdio mode)
docker compose --profile server up -d server

# Start server (HTTP mode)
MCP_TRANSPORT=http MCP_PORT=3000 docker compose --profile server up -d server

# View logs
docker logs -f hyva-mcp-server

# Stop server
docker compose --profile server stop server

# Restart server
docker compose --profile server restart server

Docker Requirements

• Docker and Docker Compose installed
• hyva-ai-tools directory must be accessible (mounted as volume)
• Port 3000 available (if using HTTP transport)

The Docker setup automatically:

• ✅ Builds the TypeScript project
• ✅ Mounts hyva-ai-tools for reading scripts/descriptions
• ✅ Configures environment variables
• ✅ Exposes ports for HTTP transport
• ✅ Runs in isolated container

Cursor Configuration

After installation, configure Cursor to use the MCP server:

Option 1: Using Local Node.js (Recommended)

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

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

Important: Use the absolute path to dist/index.js (not src/index.ts).

Option 2: Using Docker (stdio mode)

If running the server in Docker with stdio transport:

{
  "mcpServers": {
    "hyva": {
      "command": "docker",
      "args": ["exec", "-i", "hyva-mcp-server", "node", "dist/index.js"]
    }
  }
}

Note: The container must be running before Cursor tries to connect:

docker compose --profile server up -d server

Option 3: Using HTTP Transport

For HTTP transport (local or Docker):

{
  "mcpServers": {
    "hyva": {
      "url": "http://localhost:3000"
    }
  }
}

Start the server with HTTP transport:

# Local
MCP_TRANSPORT=http npm start

# Docker
./run-server-docker.sh http 3000 0.0.0.0

Finding the Correct Path

To find the absolute path to your MCP server:

# From hyva-mcp-server directory
pwd
# Output: /home/user/project/hyva-mcp-server
# Use: /home/user/project/hyva-mcp-server/dist/index.js

Or use the install script - it will show you the exact path to use.

Available Tools

dump_cms_components

Dumps all Hyva CMS components from active Magento modules.

Parameters:

• magentoRoot (optional): Path to Magento root directory. If not provided, searches from current directory.

Returns: JSON string containing merged CMS component definitions.

Example:

{
  "text_block": {
    "label": "Text Block",
    "category": "Content",
    "template": "Hyva_CmsBase::elements/text-block.phtml"
  }
}

update_component_schema

Updates component schema reference documentation. Reads the Hyva CMS JSON schema files and generates the component-schema.md reference file.

Parameters:

• magentoRoot (optional): Path to Magento root directory. If not provided, searches from current directory.

Returns: Success message or updated schema content.

detect_env

Detects Magento development environment type. Outputs: warden, docker-magento, or local.

Parameters:

• magentoRoot (optional): Path to Magento root directory. If not provided, searches from current directory.

Returns: Environment type string (warden, docker-magento, or local).

Use Case: Other tools can use this to determine the appropriate command wrapper for executing shell commands in the Magento environment.

list_hyva_themes

Lists all Hyva theme paths in a Magento 2 project. Themes are identified by the presence of web/tailwind/package.json.

Parameters:

• magentoRoot (optional): Path to Magento root directory. If not provided, searches from current directory.

Returns: Newline-separated list of theme paths (relative to project root).

Example Output:

app/design/frontend/Example/customTheme
vendor/hyva-themes/magento2-default-theme-csp

parse_readme_xml

Parses XML configuration block from a Hyva UI component README. Extracts <var> elements with their values and inline comments.

Parameters:

• xmlContent (required): XML content to parse (from stdin). Should contain <var> elements with their values and inline comments.
• format (optional): Output format: table (default), md (markdown), or json.

Returns: Parsed XML content in the requested format.

refresh_catalog

Refreshes the Hyva UI component catalog by scanning the installed hyva-ui package.

Parameters:

• magentoRoot (optional): Path to Magento root directory. If not provided, searches from current directory.
• hyvaUiPath (optional): Path to hyva-ui directory (default: vendor/hyva-themes/hyva-ui).
• outputFile (optional): Output markdown file path. If not provided, output will be returned as string.

Returns: Generated catalog markdown content or file path confirmation if outputFile is provided.

Available Resources

Skill Descriptions

Skill descriptions are available as MCP resources with URIs like:

• hyva-skill://hyva-cms-components-dump
• hyva-skill://hyva-create-module
• hyva-skill://hyva-cms-component
• etc.

These resources provide the full skill documentation in Markdown format.

Reference Files

Reference files from skills are also available as MCP resources with URIs like:

• hyva-reference://hyva-cms-component/component-schema.md
• hyva-reference://hyva-cms-component/field-types.md
• hyva-reference://hyva-cms-component/variant-support.md
• hyva-reference://hyva-ui-component/components.md
• hyva-reference://hyva-render-media-image/rendering-images.md
• etc.

These resources provide detailed reference documentation referenced by skills. For example, hyva-cms-component skill references component-schema.md for the complete schema reference.

Note: Reference files are read directly from hyva-ai-tools/skills/{skill-name}/references/ directories.

Public Deployment

Yes, the MCP server can be made publicly available! Both tools and resources work over HTTP transport.

Quick Answer

✅ Tools work: All MCP tools (like dump_cms_components) are fully functional over HTTP
✅ Resources work: All MCP resources (skill descriptions, reference files) are accessible over HTTP
✅ Easy to deploy: Set MCP_TRANSPORT=http and MCP_HOST=0.0.0.0

How Clients Connect

Remote clients connect via URL:

{
  "mcpServers": {
    "hyva": {
      "url": "https://your-domain.com:3000"
    }
  }
}

Clients can then:

• Discover and call tools via tools/list and tools/call
• Discover and read resources via resources/list and resources/read

Quick Start

# Start server with HTTP transport
MCP_TRANSPORT=http MCP_PORT=3000 MCP_HOST=0.0.0.0 npm start

# Or with Docker
./run-server-docker.sh http 3000 0.0.0.0

⚠️ Security: Always use HTTPS in production and consider adding authentication.

For detailed deployment instructions, security considerations, reverse proxy setup, and platform-specific guides, see PUBLIC_DEPLOYMENT.md.

Testing

Using npm (requires Node.js)

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run only unit tests (tools and resources)
npm run test:unit

# Run only integration tests
npm run test:integration

# Run PHP script execution tests
npm run test:php

Test Coverage

All MCP tools have comprehensive unit tests:

• ✅ dump_cms_components - Unit tests + integration tests
• ✅ update_component_schema - Unit tests
• ✅ detect_env - Unit tests
• ✅ list_hyva_themes - Unit tests
• ✅ parse_readme_xml - Unit tests
• ✅ refresh_catalog - Unit tests

See tests/tools/README.md for detailed test documentation.

Using Docker (no Node.js required)

Run tests entirely in Docker - no local Node.js installation needed:

# Run all tests
./run-tests-docker.sh test
# Or: docker compose run --rm test

# Run tests in watch mode
./run-tests-docker.sh watch

# Run tests with coverage
./run-tests-docker.sh coverage

# Run only integration tests
./run-tests-docker.sh integration

# Run PHP script execution tests
docker compose run --rm test npm run test:php

# Build test image
./run-tests-docker.sh build

# Clean up Docker resources
./run-tests-docker.sh clean

Docker Testing Benefits:

• ✅ No Node.js required locally
• ✅ Isolated test environment
• ✅ PHP 8.4 included for script execution tests
• ✅ Automatic dependency installation
• ✅ Coverage reports generated in ./coverage

Test Coverage: 61 tests covering configuration, tools, resources, PHP scripts, and server initialization.

See TESTING.md for detailed testing documentation.

Project Structure

hyva-mcp-server/
├── src/
│   ├── index.ts              # Main MCP server entry point
│   ├── config.ts             # Configuration management
│   ├── tools/
│   │   └── dumpCmsComponents.ts  # CMS dump tool
│   └── resources/
│       └── skillDescriptions.ts   # Skill description resources
├── install.sh                # Installation script
├── tests/                    # Test files
├── dist/                     # Compiled JavaScript (gitignored)
├── package.json
├── tsconfig.json
└── README.md

Note: PHP scripts and skill descriptions are read directly from the hyva-ai-tools directory (sibling to this project). They are not copied or duplicated. See INSTALL.md for details.

Build & Compilation

TypeScript Configuration

The project uses TypeScript with:

• Target: ES2020
• Module: CommonJS (for Node.js compatibility)
• Output: dist/ directory
• Source: src/ directory

Build Process

1. Install dependencies: npm install
2. Compile TypeScript: npm run build
3. Run server: node dist/index.js

Requirements

For Local Execution

• Node.js >= 18.0.0
• PHP (for executing dump_cms_components.php script from hyva-ai-tools)
• Magento 2 project (for CMS component dumping)
• hyva-ai-tools cloned in project root (scripts and skill descriptions are read from there)

For Docker Execution

• Docker and Docker Compose
• hyva-ai-tools cloned in project root (mounted as volume)
• Port 3000 available (if using HTTP transport)

Quick Start

1. Clone hyva-ai-tools (if not already done):

   git clone https://github.com/hyva-themes/hyva-ai-tools.git
   

2. Install MCP server:

   cd hyva-mcp-server
   ./install.sh
   

3. Configure Cursor (see Cursor Configuration)

4. Restart Cursor and start using Hyva MCP tools!

Documentation

• INSTALLATION_QUICK_REFERENCE.md - Quick installation commands
• INSTALL.md - Detailed installation guide with troubleshooting
• DOCKER.md - Complete guide for running in Docker
• TESTING.md - Testing documentation and test suite details
• REFERENCE_FILES.md - Reference files documentation
• PUBLIC_DEPLOYMENT.md - Guide for deploying MCP server publicly over HTTP

License

OSL-3.0

---

Copyright © Hyva Themes https://hyva.io. All rights reserved.