@aas-ai-editor/mcp-server

MCP (Model Context Protocol) server for AI-assisted editing of Asset Administration Shell (AAS) packages. This server enables Claude and other AI assistants to read, validate, and modify AASX files through a standardized protocol.

What is AAS/AASX?

Asset Administration Shell (AAS) is the standardized digital twin format for Industry 4.0. It provides a unified way to describe industrial assets (machines, devices, components) with:

• Submodels: Structured data like Nameplate, Documentation, Technical Data
• Semantic IDs: References to ECLASS, IDTA templates for interoperability
• Supplementary files: PDFs, images, CAD files bundled in the package

AASX files are ZIP-based packages containing AAS data (JSON/XML) plus attachments.

Learn more: Industrial Digital Twin Association (IDTA)

Features

• 23 MCP Tools for document lifecycle, querying, editing, validation, and AI chat
• AI-powered assistant with automatic tool calling (requires Anthropic API key)
• Self-correcting validation with automatic fix suggestions
• Patch-based editing with full undo/redo support
• IDTA template validation for industry-standard submodels
• Session management with security hardening

Quick Start

Get up and running in 3 steps:

# 1. Run the server
npx @aas-ai-editor/mcp-server

# 2. The server starts on http://localhost:3001
#    Health check: curl http://localhost:3001/health

# 3. Connect your AI client (see Claude integration below)

Installation

npm (Recommended)

# Run directly with npx
npx @aas-ai-editor/mcp-server

# Or install globally
npm install -g @aas-ai-editor/mcp-server
aas-mcp-server

Docker

docker pull hadijannat/aas-mcp-server
docker run -p 3001:3001 hadijannat/aas-mcp-server

Claude Code Integration

Add to your Claude Code configuration:

claude mcp add aas-editor npx @aas-ai-editor/mcp-server

Or manually edit ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "aas-editor": {
      "command": "npx",
      "args": ["@aas-ai-editor/mcp-server"]
    }
  }
}

Example Conversations

Once connected, you can have natural conversations with Claude about your AASX files:

You: Load the file at /path/to/pump-device.aasx

Claude: I've loaded the AASX file. It contains:
- 1 Asset Administration Shell: "PumpAAS"
- 3 Submodels: Nameplate, TechnicalData, Documentation
- 47 total elements

You: What's the manufacturer name?

Claude: Looking at the Nameplate submodel, the ManufacturerName is "Bosch Rexroth AG".

You: Change it to "Siemens AG"

Claude: I'll update the ManufacturerName property. Here's the proposed change:
- Path: /submodels/0/submodelElements/0/value
- Old value: "Bosch Rexroth AG"
- New value: "Siemens AG"

[Change applied]

You: Validate the document

Claude: Running validation... Found 2 issues:
1. Warning: Missing semanticId on Property "CustomField"
2. Error: Invalid date format in "ManufacturingDate"

You: Fix these issues automatically

Claude: I'll generate fixes for these issues:
1. Added semanticId reference to CustomField
2. Corrected date format to ISO 8601

[2 fixes applied]

You: Save the file

Claude: Document saved to /path/to/pump-device.aasx

Claude Desktop Integration

Add to your Claude Desktop configuration file:

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

Using npx (Recommended)

{
  "mcpServers": {
    "aas-editor": {
      "command": "npx",
      "args": ["@aas-ai-editor/mcp-server"],
      "env": {
        "MCP_PORT": "3001",
        "MCP_ALLOWED_PATHS": "/Users/yourname/aasx-files"
      }
    }
  }
}

Using Docker

{
  "mcpServers": {
    "aas-editor": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-p", "3001:3001",
        "-v", "/path/to/aasx-files:/data",
        "-e", "MCP_ALLOWED_PATHS=/data",
        "aas-ai-editor/mcp-server"
      ]
    }
  }
}

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | ANTHROPIC_API_KEY | Anthropic API key for AI features | - | | MCP_SERVER_PORT | Server port | 3001 | | MCP_SERVER_HOST | Server host binding | 0.0.0.0 | | MCP_API_KEY | Single API key for client authentication | - | | MCP_API_KEYS | Comma-separated API keys | - | | MCP_ALLOWED_PATHS | Allowed directories for file operations | - | | MCP_SESSION_TIMEOUT_MS | Session timeout in milliseconds | 1800000 | | AI_MODEL | Claude model to use | claude-sonnet-4-20250514 | | AI_MAX_TOKENS | Maximum response tokens | 4096 | | CORS_ALLOWED_ORIGINS | Allowed CORS origins | http://localhost:5173 | | NODE_ENV | Environment mode | development |

Anthropic API Key

The AI chat feature requires an Anthropic API key. You can provide it in three ways:

1. Environment variable (recommended for servers):

   ANTHROPIC_API_KEY=sk-ant-... npx @aas-ai-editor/mcp-server

2. Claude Desktop config:

   {
     "mcpServers": {
       "aas-editor": {
         "env": { "ANTHROPIC_API_KEY": "sk-ant-..." }
       }
     }
   }

3. Request header (for web clients):

   X-Anthropic-Api-Key: sk-ant-...

Get your API key at: https://console.anthropic.com/settings/keys

Available Tools

Document Lifecycle

• document_load - Load an AASX file
• document_save - Save changes to file
• document_create - Create new AAS environment
• document_undo / document_redo - Undo/redo operations

Query Tools

• query_list_submodels - List all submodels
• query_find_by_semantic_id - Find elements by semantic ID
• query_get_by_path - Get element at JSON pointer path
• query_list_elements - List submodel elements
• query_get_pointer - Get JSON pointer for element
• query_diff - Compare environments

Edit Tools

• edit_add - Add new element
• edit_update - Update existing element
• edit_delete - Delete element
• edit_move / edit_copy - Move or copy elements
• edit_batch - Batch multiple operations

Validation Tools

• validate_fast - Quick structural validation
• validate_deep - Full semantic validation (requires validation service)
• validate_summary - Overview of validation status
• validate_template - IDTA template compliance check
• validate_auto_fix - Generate patches to fix validation errors

AI Tools

• ai_chat - Claude-powered assistant with automatic tool calling

Security

For production deployments, configure authentication:

# Set API key(s) for client authentication
export MCP_API_KEY="your-secret-key"
# Or multiple keys
export MCP_API_KEYS="key1,key2,key3"

# Restrict file access to specific directories
export MCP_ALLOWED_PATHS="/data/aasx,/uploads"

# Enable production mode
export NODE_ENV=production

See Deployment Security Guide for complete security configuration.

API Usage

The server exposes MCP over Streamable HTTP:

# Health check
curl http://localhost:3001/health

# MCP endpoint (requires session management)
curl -X POST http://localhost:3001/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-key" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Troubleshooting

Server won't start

# Check if port is in use
lsof -i :3001

# Use a different port
MCP_PORT=3002 npx @aas-ai-editor/mcp-server

Claude can't connect

1. Verify the server is running: curl http://localhost:3001/health
2. Check your config file path and JSON syntax
3. Restart Claude Desktop/Claude Code after config changes

Permission denied errors

Set MCP_ALLOWED_PATHS to include your AASX file directories:

MCP_ALLOWED_PATHS=/Users/yourname/documents,/tmp npx @aas-ai-editor/mcp-server

Deep validation not working

Deep validation requires the Python validation service. For standalone use, validate_fast provides structural validation without additional dependencies.

Web UI

For a visual editing experience, use the companion web application:

# Clone and run
git clone https://github.com/hadijannat/aas-ai-editor.git
cd aas-ai-editor
pnpm install
pnpm dev

Then open http://localhost:5173 for:

• Visual tree editor for AAS documents
• AI chat sidebar for intelligent assistance
• Diff viewer for reviewing changes
• Settings page to configure your API key

Related Packages

• @aas-ai-editor/core - Core AASX parsing and patch operations
• @aas-ai-editor/web-ui - Vue 3 web application
• AAS AI Editor - Full monorepo with all packages

License

MIT