AQ Content MCP

A Model Context Protocol (MCP) server for connecting to Sitecore and other core business systems. Currently supports read-only access to Sitecore content via GraphQL API and optional JIRA integration.

Features

• Read-only Sitecore Integration: Query Sitecore content through GraphQL API
• Optional JIRA Integration: Retrieve JIRA issue details (when configured)
• 8 Sitecore Tools: Comprehensive set of tools for querying Sitecore content
• 1 JIRA Tool: Get JIRA issue information
• MCP Resources: Direct access to Sitecore items via resource URIs
• TypeScript: Fully typed implementation
• Extensible Architecture: Designed to easily add support for additional systems

Prerequisites

• Node.js 18.17.0 or higher
• Sitecore instance with GraphQL API enabled (or Sitecore Edge)
• Sitecore API key with read permissions
• (Optional) JIRA instance with API access for JIRA features

Quick Start

For End Users

1. Install the package:

   npm install -g aq-content-mcp

2. Configure your MCP client (e.g., Claude Desktop). Add to your MCP configuration file:

   macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
   Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
     "mcpServers": {
       "aq-content-mcp": {
         "command": "aq-content-mcp",
         "env": {
           "SITECORE_API_HOST": "https://your-sitecore-instance",
           "SITECORE_API_KEY": "your-api-key-here"
         }
       }
     }
   }

3. Restart your MCP client to load the new server configuration.

4. Test the connection - Ask your AI assistant to list available tools or query Sitecore content.

For Developers

1. Clone and install:

   git clone <repository-url>
   cd aq-content-mcp
   npm install

2. Create .env.local file:

   SITECORE_API_HOST=https://your-sitecore-instance
   SITECORE_API_KEY=your-api-key-here

3. Build and test:

   npm run build
   npm run test:mcp

Installation

Install the package globally (recommended for MCP clients):

npm install -g aq-content-mcp

Or install locally in your project:

npm install aq-content-mcp

Configuration

Sitecore Configuration

The server requires Sitecore configuration to function. Configure via environment variables in your MCP client configuration or .env.local file for local development.

Supported Sitecore Deployments:

• Sitecore Edge (default): Uses /sitecore/api/graph/edge endpoint
• Sitecore On-Premise: Uses /sitecore/api/graph/preview or your custom GraphQL endpoint path

Configuration Options: You can configure the endpoint in two ways:

1. Simple (Recommended): Use SITECORE_GRAPHQL_ENDPOINT to provide the full endpoint URL
2. Flexible: Use SITECORE_API_HOST + SITECORE_GRAPHQL_PATH to construct the endpoint

Required Environment Variables

| Variable | Description | Example | |----------|-------------|---------| | SITECORE_GRAPHQL_ENDPOINT OR SITECORE_API_HOST | Full GraphQL endpoint URL, or Sitecore instance host URL (must include protocol) | https://edge.sitecorecloud.io/api/graphql/v1 or https://edge.your-sitecore-instance.com | | SITECORE_API_KEY | Your Sitecore API key for authentication | your-api-key-here |

Note: If SITECORE_GRAPHQL_ENDPOINT is provided, it will be used directly. If it's just a host (no path), it will be combined with SITECORE_GRAPHQL_PATH. Otherwise, use SITECORE_API_HOST + SITECORE_GRAPHQL_PATH.

Optional Environment Variables

| Variable | Description | Default | Example | |----------|-------------|---------|---------| | SITECORE_GRAPHQL_PATH | The GraphQL API path (used with SITECORE_API_HOST or when SITECORE_GRAPHQL_ENDPOINT is just a host) | /sitecore/api/graph/edge | /sitecore/api/graph/edge (Edge) or /api/graphql/v1 (Edge Cloud) | | SITECORE_LANGUAGE | Default language for content queries | en | en, es, fr |

The full GraphQL endpoint is constructed as:

• If SITECORE_GRAPHQL_ENDPOINT is provided: Used directly (or combined with SITECORE_GRAPHQL_PATH if it's just a host)
• Otherwise: ${SITECORE_API_HOST}${SITECORE_GRAPHQL_PATH}

Example MCP Configuration (Sitecore Edge - Simple)

Using SITECORE_GRAPHQL_ENDPOINT (recommended):

{
  "mcpServers": {
    "aq-content-mcp": {
      "command": "aq-content-mcp",
      "env": {
        "SITECORE_GRAPHQL_ENDPOINT": "https://edge.sitecorecloud.io/api/graphql/v1",
        "SITECORE_API_KEY": "your-api-key-here",
        "SITECORE_LANGUAGE": "en"
      }
    }
  }
}

Or using host + path:

{
  "mcpServers": {
    "aq-content-mcp": {
      "command": "aq-content-mcp",
      "env": {
        "SITECORE_GRAPHQL_ENDPOINT": "https://edge.sitecorecloud.io",
        "SITECORE_GRAPHQL_PATH": "/api/graphql/v1",
        "SITECORE_API_KEY": "your-api-key-here",
        "SITECORE_LANGUAGE": "en"
      }
    }
  }
}

Example MCP Configuration (Sitecore Edge - Traditional)

{
  "mcpServers": {
    "aq-content-mcp": {
      "command": "aq-content-mcp",
      "env": {
        "SITECORE_API_HOST": "https://edge.your-sitecore-instance.com",
        "SITECORE_API_KEY": "your-api-key-here",
        "SITECORE_GRAPHQL_PATH": "/sitecore/api/graph/edge",
        "SITECORE_LANGUAGE": "en"
      }
    }
  }
}

Example MCP Configuration (Sitecore On-Premise)

{
  "mcpServers": {
    "aq-content-mcp": {
      "command": "aq-content-mcp",
      "env": {
        "SITECORE_API_HOST": "https://your-sitecore-instance.com",
        "SITECORE_API_KEY": "your-api-key-here",
        "SITECORE_GRAPHQL_PATH": "/sitecore/api/graph/preview",
        "SITECORE_LANGUAGE": "en"
      }
    }
  }
}

JIRA Configuration (Optional)

JIRA integration is optional. If not configured, JIRA tools will not be available. The server will start successfully without JIRA configuration.

Authentication Methods

JIRA supports two authentication methods:

Method 1: Personal Access Token (PAT) (Recommended)

• Requires: JIRA_PAT and either JIRA_HOST or JIRA_CLOUD_ID

Method 2: API Token

• Requires: JIRA_EMAIL + JIRA_API_TOKEN and either JIRA_HOST or JIRA_CLOUD_ID

Host Configuration

You can configure JIRA using either:

• JIRA_HOST: Your JIRA site URL (e.g., https://yourcompany.atlassian.net)
• JIRA_CLOUD_ID: Your JIRA Cloud ID (for unified API access)

Environment Variables

| Variable | Required | Description | Example | |----------|----------|-------------|---------| | JIRA_HOST or JIRA_CLOUD_ID | Yes* | JIRA site URL or Cloud ID | https://yourcompany.atlassian.net | | JIRA_PAT | Yes* | Personal Access Token | your-pat-token | | JIRA_EMAIL | Yes* | Email for API token auth | [email protected] | | JIRA_API_TOKEN | Yes* | API token (use with email) | your-api-token |

*Either PAT or Email+Token required. Either HOST or CLOUD_ID required.

Example MCP Configuration (Sitecore + JIRA)

{
  "mcpServers": {
    "aq-content-mcp": {
      "command": "aq-content-mcp",
      "env": {
        "SITECORE_API_HOST": "https://your-sitecore-instance.com",
        "SITECORE_API_KEY": "your-api-key-here",
        "JIRA_HOST": "https://yourcompany.atlassian.net",
        "JIRA_PAT": "your-jira-pat-token"
      }
    }
  }
}

Getting JIRA Credentials

Personal Access Token (PAT):

1. Go to Atlassian Account Settings
2. Create a new API token
3. Use this token as JIRA_PAT

API Token (Alternative):

1. Go to Atlassian Account Settings
2. Create an API token
3. Use your email as JIRA_EMAIL and the token as JIRA_API_TOKEN

Cloud ID (if using unified API):

1. Find your Cloud ID in your JIRA instance settings
2. Use as JIRA_CLOUD_ID instead of JIRA_HOST

Available Tools

Sitecore Tools

get_sitecore_site_collections

Retrieve all site collections in the Sitecore instance. Site collections are the top-level content items directly under /sitecore/content (e.g., "Northrop Grumman").

Parameters:

• language (optional, string): Language version (default: "en")

Example:

{
  "name": "get_sitecore_site_collections",
  "arguments": {
    "language": "en"
  }
}

Response:

{
  "siteCollections": [
    {
      "id": "{GUID}",
      "name": "Northrop Grumman",
      "path": "/sitecore/content/Northrop Grumman",
      "displayName": "Northrop Grumman"
    }
  ],
  "count": 1
}

get_sitecore_sites

Retrieve all actual sites in the Sitecore instance. Sites are one level below site collections. Optionally filter by a specific site collection path.

Parameters:

• siteCollectionPath (optional, string): Path to a specific site collection (e.g., "/sitecore/content/Northrop Grumman"). If not provided, returns sites from all site collections.
• language (optional, string): Language version (default: "en")

Example:

{
  "name": "get_sitecore_sites",
  "arguments": {
    "siteCollectionPath": "/sitecore/content/Northrop Grumman",
    "language": "en"
  }
}

Response:

{
  "sites": [
    {
      "id": "{GUID}",
      "name": "website",
      "path": "/sitecore/content/Northrop Grumman/website",
      "displayName": "Website"
    }
  ],
  "count": 1,
  "siteCollectionPath": "/sitecore/content/Northrop Grumman"
}

get_sitecore_template_by_id

Retrieve a Sitecore template by its ID. Returns template details including fields and metadata.

Parameters:

• id (required, string): The Sitecore template ID (e.g., "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}")

Example:

{
  "name": "get_sitecore_template_by_id",
  "arguments": {
    "id": "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}"
  }
}

Response:

{
  "item": {
    "id": "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}",
    "name": "Article",
    "path": "/sitecore/templates/Article",
    "displayName": "Article",
    "template": {
      "id": "{template-id}",
      "name": "Template"
    },
    "fields": [...]
  }
}

get_sitecore_page

Retrieve a Sitecore page by site name and URL. Returns page rendering data including placeholders and components.

Parameters:

• site (required, string): The Sitecore site name (e.g., "website" or "site-name")
• url (required, string): The URL path of the page (e.g., "/home" or "/products/item"). Leading/trailing slashes are optional.

Example:

{
  "name": "get_sitecore_page",
  "arguments": {
    "site": "website",
    "url": "/home"
  }
}

Response:

{
  "site": {
    "name": "website"
  },
  "item": {
    "id": "{GUID}",
    "name": "Home",
    "path": "/sitecore/content/Site/Home"
  },
  "placeholders": [...],
  "components": [...]
}

get_sitecore_sitemap

Retrieve the sitemap (list of all routes/pages) for a Sitecore site. Returns all page paths in the site.

Parameters:

• site (required, string): The Sitecore site name (e.g., "website" or "site-name")
• limit (optional, number): Maximum number of routes to return per page (default: 100). The tool automatically paginates to fetch all routes.

Example:

{
  "name": "get_sitecore_sitemap",
  "arguments": {
    "site": "website",
    "limit": 100
  }
}

Response:

{
  "site": "website",
  "routes": [
    "/",
    "/home",
    "/about",
    "/products"
  ],
  "total": 4
}

get_sitecore_rendering_definition

Retrieve a Sitecore rendering's configuration including datasource settings, parameters, and component mapping. Returns rendering details such as datasource template, datasource location, parameters template, and component name.

Parameters:

• renderingId (required, string): The rendering item ID or path (e.g., "/sitecore/layout/Renderings/MyComponent" or just "MyComponent")
• language (optional, string): Language version (default: "en")

Example:

{
  "name": "get_sitecore_rendering_definition",
  "arguments": {
    "renderingId": "/sitecore/layout/Renderings/MyComponent",
    "language": "en"
  }
}

Response:

{
  "rendering": {
    "id": "{GUID}",
    "name": "MyComponent",
    "path": "/sitecore/layout/Renderings/MyComponent",
    "displayName": "My Component",
    "template": {...},
    "componentName": "MyComponent",
    "datasourceTemplate": "{template-id}",
    "datasourceLocation": "/sitecore/content",
    "parametersTemplate": "{template-id}",
    "componentGraphQLQuery": "...",
    "allFields": [...]
  }
}

get_sitecore_item

Retrieve a specific Sitecore item's field values by path or ID. Useful for checking content state.

Parameters:

• path (optional, string): Item path like "/sitecore/content/Site/Home/Articles/my-article". Either path or id is required.
• id (optional, string): Item GUID (e.g., "{GUID-GUID-GUID-GUID}"). Either path or id is required.
• language (optional, string): Language version (default: "en")

Example:

{
  "name": "get_sitecore_item",
  "arguments": {
    "path": "/sitecore/content/Site/Home/Articles/my-article",
    "language": "en"
  }
}

Response:

{
  "item": {
    "id": "{GUID}",
    "name": "my-article",
    "path": "/sitecore/content/Site/Home/Articles/my-article",
    "displayName": "My Article",
    "template": {
      "id": "{template-id}",
      "name": "Article"
    },
    "created": "2024-01-01T00:00:00Z",
    "updated": "2024-01-15T00:00:00Z",
    "version": 1,
    "fields": [
      {
        "name": "Title",
        "value": "My Article Title",
        "jsonValue": null
      }
    ]
  }
}

search_sitecore_items

Search for Sitecore items by template, path, or keyword. Essential for questions like "what articles exist" or "find all items using this template."

Parameters:

• rootPath (optional, string): Starting path for search (e.g., "/sitecore/content/Site/Home"). Defaults to "/sitecore/content".
• templateId (optional, string): Filter by template ID or name (e.g., "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}").
• keyword (optional, string): Search term for item names or content.
• language (optional, string): Language version (default: "en").
• limit (optional, number): Maximum number of results (default: 20).

Example:

{
  "name": "search_sitecore_items",
  "arguments": {
    "rootPath": "/sitecore/content/Site/Home",
    "templateId": "{76036F5E-CBCE-46D1-AF0A-4143F9B557AA}",
    "keyword": "article",
    "limit": 10
  }
}

Response:

{
  "items": [
    {
      "id": "{GUID}",
      "name": "article-1",
      "path": "/sitecore/content/Site/Home/Articles/article-1",
      "displayName": "Article 1",
      "template": {
        "id": "{template-id}",
        "name": "Article"
      },
      "fields": [...]
    }
  ],
  "total": 25,
  "count": 10,
  "hasMore": true
}

JIRA Tools

get_jira_issue

Retrieve a JIRA issue by its key (e.g., "PROJ-123"). Returns issue details including fields, status, assignee, and other metadata.

Note: This tool is only available when JIRA is configured. If JIRA is not configured, calling this tool will return an error.

Parameters:

• issueKey (required, string): The JIRA issue key (e.g., "PROJ-123" or "TEST-456")

Example:

{
  "name": "get_jira_issue",
  "arguments": {
    "issueKey": "PROJ-123"
  }
}

Response:

{
  "id": "12345",
  "key": "PROJ-123",
  "fields": {
    "summary": "Issue Summary",
    "description": "Issue description...",
    "status": {
      "name": "In Progress"
    },
    "assignee": {
      "displayName": "John Doe"
    },
    "created": "2024-01-01T00:00:00.000Z",
    "updated": "2024-01-15T00:00:00.000Z"
  }
}

Available Resources

MCP resources provide direct access to Sitecore data via resource URIs. Resources can be accessed through MCP-compatible clients.

sitecore://sites

Access all sites in the Sitecore instance.

URI: sitecore://sites

MIME Type: application/json

Example Response:

{
  "sites": [
    {
      "id": "{GUID}",
      "name": "website",
      "path": "/sitecore/content/Site/website",
      "displayName": "Website"
    }
  ],
  "count": 1
}

Usage Examples

Example 1: Find All Articles

Use the search tool to find all items with a specific template:

Use get_sitecore_sites to list available sites, then use search_sitecore_items 
with templateId "{Article-Template-ID}" to find all articles.

Example 2: Get Page Rendering Data

Retrieve the complete rendering structure for a page:

Use get_sitecore_page with site "website" and url "/home" to get the page 
rendering data including all placeholders and components.

Example 3: Explore Site Structure

Start from site collections and drill down:

1. Use get_sitecore_site_collections to see top-level collections
2. Use get_sitecore_sites with a siteCollectionPath to see sites
3. Use get_sitecore_item to explore specific content items

Example 4: Get JIRA Issue Details

Retrieve JIRA issue information (requires JIRA configuration):

Use get_jira_issue with issueKey "PROJ-123" to get issue details including 
status, assignee, and description.

Testing & Verification

Test the MCP Server Locally

After building the project, you can test the server using the included test script:

npm run build
npm run test:mcp

This will:

1. Start the MCP server
2. Initialize the connection
3. List available tools
4. Call a sample tool (get_sitecore_sites)
5. List available resources
6. Read a sample resource (sitecore://sites)

Use MCP Inspector

The MCP Inspector provides a visual interface to test and explore the server:

npm run build
npm run inspect

This opens an interactive interface where you can:

• Browse available tools
• Test tool calls with parameters
• View resources
• See request/response details

Verify in MCP Client

After configuring your MCP client:

1. Restart your MCP client (e.g., Claude Desktop)
2. Ask your AI assistant to list available tools:
   • "What tools are available from the Sitecore MCP server?"
   • "List all MCP tools"
3. Test a simple query:
   • "Get all sites from Sitecore"
   • "What site collections exist in Sitecore?"

Check Server Logs

The server logs important information to stderr. Check your MCP client's logs or console output for:

• Sitecore MCP server started - Server initialized successfully
• Configuration errors - Missing or invalid environment variables
• Connection errors - Issues connecting to Sitecore or JIRA

Troubleshooting

Common Issues

"Item not found" Error

Problem: Tool returns "Item not found" even though the item exists in Sitecore.

Solutions:

• Item may not be published to Edge: Sitecore Edge only exposes published content. Ensure the item is published.
• Check the path: Verify the item path is correct. Paths are case-sensitive.
• Check language: Ensure the item exists in the specified language (default: en).
• Verify API permissions: Ensure your API key has read permissions for the content.

Configuration Validation Errors

Problem: Server fails to start with configuration errors.

Solutions:

• Check required variables: Ensure SITECORE_API_HOST and SITECORE_API_KEY are set.
• Verify URL format: SITECORE_API_HOST must include protocol (https:// or http://).
• Check API key: Ensure the API key is valid and has not expired.
• Environment variable names: Variable names are case-sensitive. Use exact names as documented.

JIRA Tools Not Available

Problem: JIRA tools are not listed or return "JIRA is not configured" error.

Solutions:

• JIRA is optional: The server works without JIRA. This is expected if JIRA is not configured.
• Check JIRA configuration: Ensure all required JIRA environment variables are set.
• Verify authentication: Ensure either PAT or Email+Token are correctly configured.
• Check host configuration: Ensure either JIRA_HOST or JIRA_CLOUD_ID is set.

Connection Timeout or Network Errors

Problem: Server cannot connect to Sitecore or JIRA.

Solutions:

• Check network connectivity: Ensure the server can reach the Sitecore/JIRA instance.
• Verify URLs: Ensure host URLs are correct and accessible.
• Check firewall/proxy: Ensure network policies allow connections.
• Test API directly: Use curl or Postman to test the GraphQL endpoint directly.

"Unknown tool" Error

Problem: Tool name is not recognized.

Solutions:

• Check tool name spelling: Tool names are exact (e.g., get_sitecore_item not get_sitecore_items).
• List available tools: Use tools/list to see all available tools.
• Check JIRA tools: JIRA tools only appear if JIRA is configured.

MCP Client Not Recognizing Server

Problem: MCP client doesn't see the server or tools.

Solutions:

• Restart MCP client: Restart Claude Desktop or your MCP client after configuration changes.
• Check configuration file location: Ensure the MCP configuration file is in the correct location for your platform.
• Verify command path: If installed globally, ensure aq-content-mcp is in PATH. If local, use full path.
• Check server logs: Look for startup errors in the MCP client logs.

Debug Mode

For detailed debugging, check the server's stderr output. The server logs:

• Startup messages
• Configuration validation errors
• Connection errors
• Tool execution errors

MCP Client Compatibility

This server is compatible with any MCP-compatible client. Known compatible clients include:

• Claude Desktop - Official Anthropic MCP client
• Cline - VS Code extension with MCP support
• Other MCP clients - Any client implementing the MCP protocol

Platform-Specific Configuration

macOS/Linux:

• Configuration file: ~/Library/Application Support/Claude/claude_desktop_config.json (Claude Desktop)
• Ensure Node.js is in PATH

Windows:

• Configuration file: %APPDATA%\Claude\claude_desktop_config.json (Claude Desktop)
• Ensure Node.js is in PATH or use full path to aq-content-mcp

Response Format

All tools return JSON responses with the following structure:

Success Response

{
  "content": [
    {
      "type": "text",
      "text": "<JSON string of the actual response data>"
    }
  ]
}

The text field contains a JSON string that, when parsed, contains the actual response data (as shown in the tool examples above).

Error Response

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\": \"Error message here\"}"
    }
  ],
  "isError": true
}

Limitations

• Read-only Access: This server provides read-only access to Sitecore content. Write operations are not supported.
• Edge Publishing Required: Items must be published to Sitecore Edge to be accessible via the GraphQL API.
• Language Support: Language support depends on your Sitecore configuration. Default language is en.
• Performance: Large result sets may take time to retrieve. Use limit parameters to paginate results.
• JIRA Optional: JIRA integration is optional. The server functions without JIRA configuration.

Development

Development Commands

• npm run build - Compile TypeScript to JavaScript
• npm run start - Run the compiled server
• npm run dev - Watch mode for development (auto-rebuild on changes)
• npm run type-check - Type check without building
• npm run lint - Run ESLint to check for code issues
• npm run lint:fix - Run ESLint and automatically fix issues
• npm run format - Format code with Prettier
• npm run format:check - Check if code is properly formatted
• npm run check - Run type-check, lint, and format check (all validation)
• npm test - Run test suite
• npm run test:watch - Run tests in watch mode
• npm run test:mcp - Test MCP server with test client
• npm run inspect - Launch MCP Inspector for interactive testing

Architecture

The project follows a modular architecture:

• src/clients/ - Client wrappers for external APIs (Sitecore, JIRA)
• src/tools/ - MCP tool definitions and handlers
• src/resources/ - MCP resource definitions and handlers
• src/queries/ - GraphQL query definitions
• src/types/ - TypeScript type definitions
• src/utils/ - Utility functions (configuration, etc.)
• src/server.ts - MCP server setup and configuration
• src/index.ts - Application entry point

Development Workflow (GitFlow)

This project uses GitFlow with Semantic Versioning and automatic changelog generation.

Branching Strategy

• main: Production-ready code (auto-releases on merge)
• develop: Integration branch for features
• feature/*: New features (branch from develop)
• release/*: Preparing releases (branch from develop)
• hotfix/*: Critical production fixes (branch from main)

See CONTRIBUTING.md for detailed workflow instructions.

Commit Messages

We follow Conventional Commits specification:

feat: add new feature          # Minor version bump (1.0.0 → 1.1.0)
fix: resolve bug               # Patch version bump (1.0.0 → 1.0.1)
feat!: breaking change         # Major version bump (1.0.0 → 2.0.0)

Git hooks (via Husky) automatically enforce:

• ✅ Commit message format
• ✅ Branch naming conventions
• ✅ Code quality checks before commit
• ✅ Tests before push

See HUSKY_SETUP.md for details.

Automated Releases

• Merges to main: Automatically creates releases with semantic versioning
• Merges to beta: Creates beta prereleases (e.g., 1.1.0-beta.1)
• Merges to alpha: Creates alpha prereleases (e.g., 1.1.0-alpha.1)

The release process automatically:

1. Analyzes commits to determine version bump
2. Generates CHANGELOG.md
3. Updates package.json version
4. Creates Git tag
5. Publishes to npm (if NPM_TOKEN is configured)
6. Creates GitHub release

CI/CD

This project uses GitHub Actions for continuous integration:

• CI Workflow (.github/workflows/ci.yml): Runs on every push and PR

  • Tests on Node.js 18.17, 20, and 22
  • Runs type checking, linting, and formatting checks
  • Runs test suite with coverage
  • Builds the project
  • Uploads coverage reports

• Release Workflow (.github/workflows/release.yml): Automated releases

  • Triggers on pushes to main
  • Runs semantic-release to publish new versions
  • Requires NPM_TOKEN secret (optional, only needed for npm publishing)

• Prerelease Workflow (.github/workflows/prerelease.yml): Beta/alpha releases

  • Triggers on pushes to beta or alpha branches
  • Creates prerelease versions

Setting up GitHub Secrets

For automated npm publishing:

1. Go to your repository → Settings → Secrets and variables → Actions
2. Add a new secret named NPM_TOKEN
3. Get your token from npmjs.com (create an "Automation" token)

Note: GITHUB_TOKEN is automatically provided by GitHub Actions for creating releases and tags.

Dry Run Releases

Test releases locally without publishing:

npm run release:dry-run

License

ISC

Contributing

See CONTRIBUTING.md for contribution guidelines.

Support

For issues, questions, or contributions, please open an issue on the GitHub repository.