@magnolia/mcp-definitions-api-server

Model Context Protocol server that integrates with a running Magnolia CMS instance via the Definitions API. This server enables AI assistants to validate component/page definitions, detect configuration problems, and retrieve JSON schemas in real-time.

Overview

This server complements the @magnolia/mcp-cli-server which handles scaffolding and file-based operations. While the CLI server doesn't require a running Magnolia instance, this server requires an accessible Magnolia Author instance with the magnolia-definitions-api module installed.

Key Features

• Problem Detection: Query the Definitions API to find YAML syntax errors, missing dependencies, or invalid configurations after creating components/pages
• Validation Workflow: Automatically validate generated templates and dialogs against the running Magnolia instance
• Schema Retrieval: Get JSON Schema definitions for templates and dialogs (planned)

Prerequisites

• Node.js 18+
• npm
• Running Magnolia Author instance with magnolia-definitions-api module
• Superuser credentials for REST API access

Install (from source)

git clone <repository-url>
cd magnolia-mcp-definitions-api-server
npm install
npm run build

Run

# Start the server
npm start

# Development mode with watch
npm run dev

Connect from an LLM Client

Add to your MCP client's configuration file (e.g., claude_desktop_config.json, mcp.json):

Using the published package (when available)

{
  "mcpServers": {
    "magnolia-definitions": {
      "command": "npx",
      "args": ["-y", "@magnolia/mcp-definitions-api-server"],
      "env": {
        "MAGNOLIA_AUTHOR_URL": "http://localhost:8080/magnoliaAuthor",
        "MAGNOLIA_SUPERUSER_USERNAME": "superuser",
        "MAGNOLIA_SUPERUSER_PASSWORD": "superuser"
      }
    }
  }
}

Using the local build

{
  "mcpServers": {
    "magnolia-definitions": {
      "command": "node",
      "args": ["/absolute/path/to/magnolia-mcp-definitions-api-server/dist/index.js"],
      "env": {
        "MAGNOLIA_AUTHOR_URL": "http://localhost:8080/magnoliaAuthor",
        "MAGNOLIA_SUPERUSER_USERNAME": "superuser",
        "MAGNOLIA_SUPERUSER_PASSWORD": "superuser"
      }
    }
  }
}

Combined with CLI Server

For the complete Magnolia AI development experience, configure both servers:

{
  "mcpServers": {
    "magnolia-cli": {
      "command": "npx",
      "args": ["-y", "@magnolia/mcp-cli-server"],
      "env": {
        "NEXUS_USERNAME": "your-nexus-username",
        "NEXUS_PASSWORD": "your-nexus-password"
      }
    },
    "magnolia-definitions": {
      "command": "npx",
      "args": ["-y", "@magnolia/mcp-definitions-api-server"],
      "env": {
        "MAGNOLIA_AUTHOR_URL": "http://localhost:8080/magnoliaAuthor",
        "MAGNOLIA_SUPERUSER_USERNAME": "superuser",
        "MAGNOLIA_SUPERUSER_PASSWORD": "superuser"
      }
    }
  }
}

After editing config files, restart the IDE/client so tool definitions reload.

Environment Variables

| Variable | Required | Default | Description | |---------------------------------|----------|----------------------------------------|--------------------------------------------------| | MAGNOLIA_AUTHOR_URL | Yes | http://localhost:8080/magnoliaAuthor | Base URL of the running Magnolia Author instance | | MAGNOLIA_SUPERUSER_USERNAME | Yes | superuser | Username for REST API authentication | | MAGNOLIA_SUPERUSER_PASSWORD | Yes | superuser | Password for REST API authentication | | MAGNOLIA_REQUEST_TIMEOUT | No | 30000 | Request timeout in milliseconds | | MAGNOLIA_DEFINITIONS_API_PATH | No | /.rest/registry-definitions | Base path for definitions API | | MAGNOLIA_PERSISTENCE_API_PATH | No | /.rest/persistence | Base path for persistence/storage API | | LOG_LEVEL | No | info | Winston log level (error, warn, info, debug) |

Available Tools

mgnl_api_check_connection

Verify connectivity to the Magnolia instance and API availability.

Use this to check if the Magnolia server is running before performing other operations.

mgnl_api_get_problems

Retrieve and filter definition problems from the Magnolia instance.

Parameters:

| Parameter | Type | Description | |------------------|--------|----------------------------------------------------------------| | locationFilter | string | Filter by location/details pattern (e.g., light module name) | | severityFilter | enum | Filter by severity: SEVERE, MAJOR, MINOR, DEPRECATED | | typeFilter | enum | Filter by type: RESOLUTION, UNSUPPORTED, IGNORED, DEPENDENCY_RESOLUTION |

Example Response:

{
  "problems": [
    {
      "severityType": "SEVERE",
      "type": "RESOLUTION",
      "location": "/",
      "title": "Incompatible definition type",
      "details": "... move /my-module/templates/components/hero.yaml to proper location."
    }
  ],
  "totalCount": 369,
  "filteredCount": 1,
  "summary": {
    "SEVERE": 1,
    "MAJOR": 0,
    "MINOR": 0,
    "DEPRECATED": 0
  }
}

Typical Workflow

The recommended workflow for AI-assisted Magnolia development:

1. Scaffold (CLI Server): mgnl_run create-component Hero -lm my-module
2. Generate (CLI Server): Use mgnl_collect_generation_context to get context, then generate FTL/YAML
3. Apply (CLI Server): Write generated content with mgnl_apply_figma_template
4. Validate (Definitions Server): Check for problems with mgnl_api_get_problems
5. Fix: If problems found, analyze errors and fix the templates
6. Repeat steps 3-5 until validation passes

Example Prompt

After creating a component:

"Check if there are any definition problems in Magnolia for my-light-module"

The AI will call mgnl_api_get_problems with locationFilter: "my-light-module" and report any issues.

Magnolia Setup

Required Module

The Magnolia instance must have the magnolia-definitions-api module installed. This module exposes:

• /.rest/registry-definitions/definitionProblems - Get all definition problems
• /.rest/registry-definitions/dialog-definition/{templateId} - Get dialog JSON Schema
• /.rest/registry-definitions/template-definition/{templateId} - Get template definition
• /.rest/registry-definitions/templates/available/{path} - Get available templates

Superuser Access

The REST endpoints require authentication. The default superuser account works for local development. For production or shared environments, consider creating a dedicated API user with appropriate permissions.

Logging

Logs are written to ~/.magnolia-mcp-definitions-api-server.log:

# Monitor logs
tail -f ~/.magnolia-mcp-definitions-api-server.log

Set LOG_LEVEL=debug for verbose output.

Troubleshooting

Connection Failed

If mgnl_api_check_connection fails:

1. Verify Magnolia is running: curl http://localhost:8080/magnoliaAuthor/.rest/registry-definitions/definitionProblems -u superuser:superuser
2. Check the URL includes the context path (e.g., /magnoliaAuthor)
3. Verify credentials are correct
4. Check firewall/network settings

No Problems Returned

If mgnl_api_get_problems returns empty but you expect errors:

1. The Magnolia instance caches definitions - try restarting Magnolia or touching the YAML file
2. Check if the light module path is correct in MAGNOLIA_HOME/light-modules/
3. Verify the YAML file syntax with a YAML linter

Contributing

• Follow CLAUDE.md for contributor guidance
• Tests: npm test
• Lint/format: npm run lint, npm run format:write

Related Projects

• @magnolia/mcp-cli-server - CLI scaffolding and file operations
• magnolia-definitions-api - Magnolia module providing the REST API

License

See LICENSE.txt.