@alps-asd/mcp

@alps-asd/mcp

Model Context Protocol (MCP) server for ALPS profile development. Provides AI assistants with tools to validate and generate diagrams from ALPS profiles.

Requirements

• Node.js 20 or higher

Installation

npm install @alps-asd/mcp

Usage with Claude Desktop

Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "alps": {
      "command": "npx",
      "args": ["@alps-asd/mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "alps": {
      "command": "alps-mcp"
    }
  }
}

Troubleshooting

If you encounter errors, first verify your Node.js version:

node --version  # Should be v20.0.0 or higher
which npx       # Verify npx is in your PATH

If using nvm, ensure the correct version is active:

nvm use 20

Available Tools

validate_alps

Validate an ALPS profile and get detailed error feedback.

Parameters:

• alps_content (required): ALPS profile content (XML or JSON format)

Example prompt:

"Validate this ALPS profile and tell me if there are any errors"

Response includes:

• Errors (E-codes): Must be fixed for valid profile
• Warnings (W-codes): Best practice violations
• Suggestions (S-codes): Optional improvements

alps2svg

Generate an SVG state diagram from an ALPS profile.

Parameters:

• alps_content: ALPS profile content (XML or JSON format)
• alps_path: Path to ALPS profile file (alternative to alps_content)

Example prompt:

"Generate a state diagram from my ALPS profile at ./api.json"

alps_guide

Get ALPS best practices and reference guide.

Parameters: None

Example prompt:

"Show me ALPS best practices for naming transitions"

Example Workflow

• Ask the AI to validate your ALPS profile:

  "Validate the ALPS profile in ./my-api.json"

• Fix any reported errors

• Generate a diagram:

  "Create an SVG diagram from ./my-api.json"

• Get guidance on improvements:

  "How should I name my transitions in ALPS?"

Validation Codes

Code	Severity	Description
E001	Error	Missing id or href
E002	Error	Missing rt for transition
E003	Error	Invalid type value
E004	Error	Broken reference
E005	Error	Duplicate id
E008	Error	Missing alps property
E009	Error	Missing descriptor array
E011	Error	Tag must be string
W001	Warning	Missing title
W002	Warning	Safe transition should start with "go"
W003	Warning	Unsafe/idempotent should start with "do"
S001	Suggestion	Consider adding doc to transition

See Validation Reference for detailed explanations.

Dependencies

• @modelcontextprotocol/sdk - MCP SDK
• @alps-asd/app-state-diagram - ALPS parser, validator, and generator

License

MIT