# @aegisx/mcp
[](https://www.npmjs.com/package/@aegisx/mcp)
[](https://www.npmjs.com/package/@aegisx/mcp)
[](https://github.com/aegisx-platform/aegisx-mcp/blob/main/LICENSE)
MCP (Model Context Protocol) server for the AegisX platform. Provides AI assistants with access to AegisX UI components, CRUD generator commands, development patterns, and API contract discovery.
## Features
- **UI Components Reference** - Browse and search 78+ AegisX UI components with full API documentation
- **CRUD Generator Commands** - Build and execute CRUD generation commands with 23 supported options (100% CLI alignment)
- **Development Patterns** - Access best practices, code templates, and architecture patterns
- **API Contract Discovery** - List, search, and validate API contracts across your codebase
- **API Testing & Authentication** - Login, test protected endpoints, decode JWT tokens, and track request history
- **Design Tokens** - Reference design tokens for colors, spacing, typography
- **Development Standards** - Access coding standards and guidelines
## Data Synchronization
The component, command, and pattern data files are **auto-generated** from source libraries:
- `src/data/components.ts` - Generated from aegisx-ui components
- `src/data/crud-commands.ts` - Generated from aegisx-cli commands
- `src/data/patterns.ts` - Validated from existing patterns
**⚠️ DO NOT EDIT MANUALLY** - Changes will be overwritten on next sync.
## Installation
### NPM (Global)
```bash
npm install -g @aegisx/mcp
```
### Claude Desktop Configuration
Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):
```json
{
"mcpServers": {
"aegisx": {
"command": "npx",
"args": ["-y", "@aegisx/mcp"]
}
}
}
```
Or if installed globally:
```json
{
"mcpServers": {
"aegisx": {
"command": "aegisx-mcp"
}
}
}
```
## Available Tools
### UI Components
| Tool | Description |
| -------------------------- | ------------------------------------------------------- |
| `aegisx_components_list` | List all UI components, optionally filtered by category |
| `aegisx_components_get` | Get detailed info about a specific component |
| `aegisx_components_search` | Search components by name or description |
**Example:**
```
Use aegisx_components_get with name="Card" to see the Card component API.
```
### CRUD Generator
| Tool | Description |
| --------------------------- | ---------------------------------------------------- |
| `aegisx_crud_build_command` | Build a CRUD generation command with options |
| `aegisx_crud_packages` | View available packages (standard, enterprise, full) |
| `aegisx_crud_files` | See what files will be generated |
| `aegisx_crud_troubleshoot` | Get help with common issues |
| `aegisx_crud_workflow` | Get complete workflow for a feature |
**Example:**
```
Use aegisx_crud_build_command with tableName="products" and withImport=true to get the command.
```
### Development Patterns
| Tool | Description |
| ------------------------- | ---------------------------------- |
| `aegisx_patterns_list` | List all patterns by category |
| `aegisx_patterns_get` | Get a specific pattern with code |
| `aegisx_patterns_search` | Search patterns |
| `aegisx_patterns_suggest` | Get pattern suggestions for a task |
**Example:**
```
Use aegisx_patterns_suggest with task="create API endpoint" to get relevant patterns.
```
### API Contract Tools
| Tool | Description |
| --------------------- | ------------------------------------------------------ |
| `aegisx_api_list` | List all API endpoints, optionally filtered by feature |
| `aegisx_api_search` | Search endpoints by keyword across paths and methods |
| `aegisx_api_get` | Get detailed contract for a specific endpoint |
| `aegisx_api_validate` | Validate implementation matches documented contracts |
**Examples:**
```
# List all endpoints
Use aegisx_api_list to see all documented APIs.
# Search for budget-related APIs
Use aegisx_api_search with query="budget" to find budget endpoints.
# Get contract details
Use aegisx_api_get with path="/api/profile" to see the full contract.
# Validate a feature
Use aegisx_api_validate with feature="user-profile" to check for mismatches.
```
### API Testing & Authentication Tools
| Tool | Description |
| -------------------------- | ------------------------------------------------------------- |
| `aegisx_auth_login` | Login to API and store access token (default: localhost:3000) |
| `aegisx_auth_status` | Check authentication status and token info |
| `aegisx_auth_decode_jwt` | Decode JWT token to view header, payload, and expiry details |
| `aegisx_auth_logout` | Logout and clear authentication session |
| `aegisx_api_request` | Make authenticated HTTP requests (GET/POST/PUT/PATCH/DELETE) |
| `aegisx_api_history` | View request/response history with filtering |
| `aegisx_api_clear_history` | Clear request history |
**Examples:**
```
# Login to API
Use aegisx_auth_login with email and password to authenticate and store token.
# Check authentication status
Use aegisx_auth_status to see current user info and token expiry.
# Decode JWT token
Use aegisx_auth_decode_jwt to inspect token claims and expiration.
# Test protected endpoint
Use aegisx_api_request with method="GET" and path="/api/profile" to call authenticated endpoints.
# View request history
Use aegisx_api_history to see recent API calls with status codes and response times.
```
**Features:**
- ✅ Automatic token management and storage
- ✅ Request/response history (last 50 requests)
- ✅ JWT token decoding and validation
- ✅ Support for custom headers and query parameters
- ✅ Configurable base URL (default: http://localhost:3000)
- ✅ Environment variable support (AEGISX_API_URL)
## Available Resources
| Resource | Description |
| -------------------------------- | ------------------------------------------- |
| `aegisx://design-tokens` | Design tokens (colors, spacing, typography) |
| `aegisx://development-standards` | Coding standards and guidelines |
| `aegisx://api-reference` | Backend API conventions |
| `aegisx://project-structure` | Monorepo structure guide |
| `aegisx://quick-start` | Getting started guide |
## Component Categories
- **data-display** - Badge, Card, Avatar, KPI Card, Stats Card, List, Timeline, Progress
- **forms** - Date Picker, Input OTP, Knob, Popup Edit, Scheduler, Time Slots
- **feedback** - Alert, Loading Bar, Inner Loading, Splash Screen, Skeleton
- **navigation** - Breadcrumb, Command Palette, Navbar, Launcher
- **layout** - Classic Layout, Compact Layout, Enterprise Layout, Empty Layout
- **auth** - Login Form, Register Form, Reset Password Form, Social Login
- **advanced** - Calendar, Gridster, File Upload, Theme Builder, Theme Switcher
- **overlays** - Drawer
## CRUD Packages
| Package | Features |
| -------------- | ------------------------------------------- |
| **standard** | Basic CRUD, pagination, search, soft delete |
| **enterprise** | Standard + Excel/CSV import |
| **full** | Enterprise + WebSocket events |
## Development
### Sync Data from Source
The sync tool automatically updates data files from source libraries. This runs before each build via the `prebuild` hook.
```bash
cd libs/aegisx-mcp
pnpm run sync # Update data files
pnpm run sync:dry-run # Preview changes without writing
pnpm run sync:verbose # See detailed progress
```
**Note:** The sync process extracts component metadata from `libs/aegisx-ui`, command definitions from `libs/aegisx-cli`, and validates existing patterns. Manual edits to generated data files will be overwritten on next sync.
### Build
```bash
cd libs/aegisx-mcp
pnpm install
pnpm run build
```
The build process automatically runs `pnpm run sync` before compilation to ensure data files are up to date.
### Test Locally
```bash
node dist/index.js
```
### Debug
Set `DEBUG=mcp:*` environment variable for verbose logging.
## License
MIT
