@eui/mcp 1.0.3 → 1.3.0

package/README.md

@@ -1,846 +1,220 @@
-# EUI Compodoc MCP Server
+# Quick Start Guide
 
-A Model Context Protocol (MCP) server that exposes Angular component library metadata from Compodoc's `documentation.json` to AI assistants.
+Get the EUI Compodoc MCP Server running in 5 minutes.
 
-## Overview
-
-This MCP server provides efficient access to Angular component documentation by leveraging Compodoc's pre-generated `documentation.json` file. Instead of parsing TypeScript files on-the-fly, it uses the structured JSON as a knowledge base, offering fast queries for component inputs, outputs, examples, and other metadata.
-
-The server implements the [Model Context Protocol](https://modelcontextprotocol.io/), enabling AI assistants like Claude, Kiro, and others to discover and understand Angular components through standardized tool calls.
-
-## Features
-
-- **Fast Component Discovery**: List all available components with filtering options
-- **Detailed Documentation**: Retrieve complete component metadata including inputs, outputs, and examples
-- **Smart Search**: Search components by name, description, or functionality with relevance ranking
-- **Property-Based Testing**: Comprehensive test coverage using fast-check
-- **File Watching**: Automatic reloading when documentation.json changes
-- **Type-Safe**: Built with TypeScript and strict type checking
-- **Error Resilient**: Graceful error handling with meaningful error messages
-- **Zero Configuration**: Works out of the box with sensible defaults
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quick Start](#quick-start)
-- [Configuration](#configuration)
-- [MCP Tools Reference](#mcp-tools-reference)
-- [Usage Examples](#usage-examples)
-- [Development](#development)
-- [CI/CD Pipeline](#cicd-pipeline)
-- [Architecture](#architecture)
-- [Testing](#testing)
-- [Troubleshooting](#troubleshooting)
-- [Contributing](#contributing)
-- [License](#license)
-
-## Installation
-
-### Prerequisites
+## Prerequisites
 
 - Node.js 18 or higher
-- npm or yarn package manager
-- A Compodoc-generated `documentation.json` file
+- An MCP client (Kiro CLI, Claude Desktop, etc.)
 
-### Install Dependencies
+## Step 1: Get EUI Documentation URL
 
-```bash
-npm install
-```
-
-### Build the Project
+The EUI library documentation is available at:
 
-```bash
-npm run build
 ```
-
-## Quick Start
-
-See the [QUICKSTART.md](./QUICKSTART.md) guide for a step-by-step tutorial on getting started.
-
-### Basic Usage
-
-1. **Generate Compodoc documentation** for your Angular project:
-
-```bash
-npx @compodoc/compodoc -p tsconfig.json -e json -d ./docs
+https://euidev.ecdevops.eu/eui-docs-eui-21.x/json/documentation.json
 ```
 
-2. **Create a configuration file** (`config.json`):
+You can use this URL directly (recommended) or download it locally:
 
-```json
-{
-  "documentation": {
-    "path": "./docs/documentation.json"
-  }
-}
+```bash
+# Optional: Download locally
+curl -o documentation.json https://euidev.ecdevops.eu/eui-docs-eui-21.x/json/documentation.json
 ```
 
-3. **Start the MCP server**:
+## Step 2: Configure Your MCP Client
 
-```bash
-npm start -- --config ./config.json
-```
+### For Kiro CLI
 
-4. **Configure your MCP client** (e.g., in Kiro's `mcp.json`):
+Add to `.kiro/settings/mcp.json`:
 
 ```json
 {
   "mcpServers": {
     "eui-compodoc": {
-      "command": "node",
-      "args": ["/path/to/eui-compodoc-mcp/dist/main.js", "--config", "/path/to/config.json"]
+      "command": "npx",
+      "args": [
+        "-y",
+        "@eui/mcp",
+        "--doc-path",
+        "https://euidev.ecdevops.eu/eui-docs-eui-21.x/json/documentation.json"
+      ]
     }
   }
 }
 ```
 
-## Configuration
+### For Claude Desktop
 
-### Configuration File Format
+Add to Claude Desktop configuration:
 
-The server accepts a JSON configuration file with the following structure:
+**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
-  "server": {
-    "name": "eui-compodoc-mcp",
-    "version": "1.0.0"
-  },
-  "documentation": {
-    "path": "./documentation.json",
-    "watchForChanges": true,
-    "reloadDebounce": 1000
-  },
-  "search": {
-    "maxResults": 50,
-    "minQueryLength": 2
-  },
-  "logging": {
-    "level": "info",
-    "format": "json"
+  "mcpServers": {
+    "eui-compodoc": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@eui/mcp",
+        "--doc-path",
+        "https://euidev.ecdevops.eu/eui-docs-eui-21.x/json/documentation.json"
+      ]
+    }
   }
 }
 ```
 
-### Configuration Options
-
-#### Server Configuration
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `server.name` | string | `"eui-compodoc-mcp"` | Server name for MCP identification |
-| `server.version` | string | `"1.0.0"` | Server version |
+## Step 3: Restart Your MCP Client
 
-#### Documentation Configuration
+- **Kiro CLI**: Restart your terminal session
+- **Claude Desktop**: Quit and reopen the application
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `documentation.path` | string | `"./documentation.json"` | Path to Compodoc documentation.json file |
-| `documentation.watchForChanges` | boolean | `true` | Enable file watching for hot reloading |
-| `documentation.reloadDebounce` | number | `1000` | Debounce time (ms) for file change events |
+## Step 4: Test the Integration
 
-#### Search Configuration
+Ask your AI assistant:
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `search.maxResults` | number | `50` | Maximum search results to return |
-| `search.minQueryLength` | number | `2` | Minimum query length for searches |
+> "List 5 components from the EUI library"
 
-#### Logging Configuration
+You should see component names and descriptions.
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `logging.level` | string | `"info"` | Log level: `"debug"`, `"info"`, `"warn"`, `"error"` |
-| `logging.format` | string | `"json"` | Log format: `"json"` or `"text"` |
+## Alternative: Local Setup
 
-### Environment Variables
+If you prefer to run from source or use a local documentation file:
 
-You can override configuration using environment variables:
-
-- `COMPODOC_MCP_CONFIG`: Path to configuration file
-- `COMPODOC_MCP_DOC_PATH`: Override documentation.json path
-- `COMPODOC_MCP_LOG_LEVEL`: Override log level
-
-Example:
+### 1. Clone and Build
 
 ```bash
-COMPODOC_MCP_DOC_PATH=./my-docs/documentation.json npm start
-```
-
-## MCP Tools Reference
-
-The server exposes six MCP tools for querying component documentation:
-
-### 1. list-components
-
-Lists all available components, directives, pipes, and services.
-
-**Parameters:**
-
-```typescript
-{
-  includeDeprecated?: boolean;  // Include deprecated items (default: false)
-  type?: 'component' | 'directive' | 'pipe' | 'service' | 'all';  // Filter by type (default: 'all')
-  limit?: number;  // Max results (default: 50, max: 1000)
-  offset?: number;  // Pagination offset (default: 0)
-}
-```
-
-**Returns:**
-
-```typescript
-{
-  items: Array<{
-    name: string;
-    type: string;
-    selector?: string;
-    description: string;
-    deprecated: boolean;
-  }>;
-  total: number;
-  hasMore: boolean;
-  offset: number;
-  limit: number;
-}
-```
-
-### 2. get-component-docs
-
-Retrieves detailed documentation for a specific component.
-
-**Parameters:**
-
-```typescript
-{
-  name: string;  // Component name (required)
-}
-```
-
-**Returns:**
-
-```typescript
-{
-  name: string;
-  type: string;
-  selector?: string;
-  description: string;
-  inputs: Array<{
-    name: string;
-    type: string;
-    required: boolean;
-    description: string;
-    defaultValue?: string;
-  }>;
-  outputs: Array<{
-    name: string;
-    type: string;
-    description: string;
-  }>;
-  methods: Array<{
-    name: string;
-    signature: string;
-    description: string;
-    parameters: Array<{
-      name: string;
-      type: string;
-      optional: boolean;
-    }>;
-    returnType: string;
-  }>;
-  examples: Array<{
-    title: string;
-    description: string;
-    code: string;
-    language: string;
-  }>;
-  deprecated: boolean;
-  deprecationMessage?: string;
-  standalone?: boolean;
-  imports?: string[];
-}
-```
-
-### 3. search-components
-
-Searches for components by keyword or functionality.
-
-**Parameters:**
-
-```typescript
-{
-  query: string;  // Search query (required)
-  types?: Array<'component' | 'directive' | 'pipe' | 'service'>;  // Filter by types
-  includeDeprecated?: boolean;  // Include deprecated items (default: false)
-  limit?: number;  // Max results (default: 50)
-}
-```
-
-**Returns:**
-
-```typescript
-{
-  items: Array<{
-    name: string;
-    type: string;
-    selector?: string;
-    description: string;
-    deprecated: boolean;
-    relevanceScore: number;
-  }>;
-  total: number;
-  query: string;
-}
-```
-
-### 4. get-component-inputs
-
-Retrieves input properties for a specific component.
-
-**Parameters:**
-
-```typescript
-{
-  name: string;  // Component name (required)
-}
-```
-
-**Returns:**
-
-```typescript
-{
-  componentName: string;
-  inputs: Array<{
-    name: string;
-    type: string;
-    required: boolean;
-    description: string;
-    defaultValue?: string;
-  }>;
-}
-```
-
-### 5. get-component-outputs
-
-Retrieves output events for a specific component.
-
-**Parameters:**
-
-```typescript
-{
-  name: string;  // Component name (required)
-}
-```
-
-**Returns:**
-
-```typescript
-{
-  componentName: string;
-  outputs: Array<{
-    name: string;
-    type: string;
-    description: string;
-  }>;
-}
-```
-
-### 6. get-component-examples
-
-Retrieves usage examples for a specific component.
-
-**Parameters:**
-
-```typescript
-{
-  name: string;  // Component name (required)
-}
-```
-
-**Returns:**
-
-```typescript
-{
-  componentName: string;
-  examples: Array<{
-    title: string;
-    description: string;
-    code: string;
-    language: string;
-  }>;
-}
+git clone <repository-url>
+cd eui-compodoc-mcp
+npm install
+npm run build
 ```
 
-## Usage Examples
+### 2. Create config.json
 
-### Example 1: List All Components
-
-```typescript
-// Request
+```json
 {
-  "tool": "list-components",
-  "params": {
-    "type": "component",
-    "limit": 10
+  "documentation": {
+    "path": "https://euidev.ecdevops.eu/eui-docs-eui-21.x/json/documentation.json"
   }
 }
-
-// Response
-{
-  "items": [
-    {
-      "name": "ButtonComponent",
-      "type": "component",
-      "selector": "eui-button",
-      "description": "A customizable button component",
-      "deprecated": false
-    },
-    // ... more components
-  ],
-  "total": 150,
-  "hasMore": true,
-  "offset": 0,
-  "limit": 10
-}
 ```
 
-### Example 2: Get Component Details
+Or for local file:
 
-```typescript
-// Request
+```json
 {
-  "tool": "get-component-docs",
-  "params": {
-    "name": "ButtonComponent"
+  "documentation": {
+    "path": "/absolute/path/to/documentation.json"
   }
 }
-
-// Response
-{
-  "name": "ButtonComponent",
-  "type": "component",
-  "selector": "eui-button",
-  "description": "A customizable button component with various styles and sizes",
-  "inputs": [
-    {
-      "name": "label",
-      "type": "string",
-      "required": true,
-      "description": "Button label text"
-    },
-    {
-      "name": "disabled",
-      "type": "boolean",
-      "required": false,
-      "description": "Whether the button is disabled",
-      "defaultValue": "false"
-    }
-  ],
-  "outputs": [
-    {
-      "name": "click",
-      "type": "EventEmitter<MouseEvent>",
-      "description": "Emitted when button is clicked"
-    }
-  ],
-  "examples": [
-    {
-      "title": "Basic Button",
-      "description": "A simple button with a label",
-      "code": "<eui-button label=\"Click Me\"></eui-button>",
-      "language": "html"
-    }
-  ],
-  "deprecated": false,
-  "standalone": true
-}
 ```
 
-### Example 3: Search Components
-
-```typescript
-// Request
-{
-  "tool": "search-components",
-  "params": {
-    "query": "button",
-    "types": ["component"],
-    "limit": 5
-  }
-}
+### 3. Update MCP Configuration
 
-// Response
+```json
 {
-  "items": [
-    {
-      "name": "ButtonComponent",
-      "type": "component",
-      "selector": "eui-button",
-      "description": "A customizable button component",
-      "deprecated": false,
-      "relevanceScore": 100
-    },
-    {
-      "name": "IconButtonComponent",
-      "type": "component",
-      "selector": "eui-icon-button",
-      "description": "Button with icon support",
-      "deprecated": false,
-      "relevanceScore": 80
+  "mcpServers": {
+    "eui-compodoc": {
+      "command": "node",
+      "args": [
+        "/absolute/path/to/eui-compodoc-mcp/dist/main.js",
+        "--config",
+        "/absolute/path/to/config.json"
+      ]
     }
-  ],
-  "total": 2,
-  "query": "button"
-}
-```
-
-## Development
-
-### Project Structure
-
-```
-eui-compodoc-mcp/
-├── src/
-│   ├── config/          # Configuration loading and validation
-│   ├── loader/          # Documentation file loading and watching
-│   ├── mcp/             # MCP server implementation
-│   ├── query/           # Query engine and search functionality
-│   ├── tools/           # MCP tool handlers
-│   ├── types/           # TypeScript type definitions
-│   ├── utils/           # Utility functions and logging
-│   └── main.ts          # Application entry point
-├── dist/                # Compiled JavaScript output
-├── coverage/            # Test coverage reports
-├── config.json          # Configuration file (example)
-├── package.json
-├── tsconfig.json
-└── jest.config.js
-```
-
-### Development Commands
-
-```bash
-# Install dependencies
-npm install
-
-# Build the project
-npm run build
-
-# Development mode with auto-rebuild
-npm run dev
-
-# Run tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run tests with coverage
-npm run test:coverage
-
-# Lint code
-npm run lint
-```
-
-### Adding a New Tool
-
-1. Create a new file in `src/tools/` (e.g., `my-new-tool.ts`)
-2. Implement the tool class with `execute()` and `getToolDefinition()` methods
-3. Export the tool from `src/tools/index.ts`
-4. Register the tool in `src/mcp/server.ts`
-5. Add tests in `src/tools/__tests__/`
-
-Example tool structure:
-
-```typescript
-export class MyNewTool {
-  constructor(private query: ComponentQuery, private formatter: ResultFormatter) {}
-
-  execute(params: MyParams): MyResult {
-    // Tool implementation
-  }
-
-  static getToolDefinition() {
-    return {
-      name: 'my-new-tool',
-      description: 'Description of what the tool does',
-      inputSchema: {
-        type: 'object',
-        properties: {
-          // Parameter definitions
-        },
-      },
-    };
   }
 }
 ```
 
-## CI/CD Pipeline
-
-This project includes a comprehensive GitLab CI/CD pipeline for automated releases.
-
-### Pipeline Stages
-
-1. **Build**: Compiles TypeScript to JavaScript
-2. **Test**: Runs unit and property-based tests
-3. **Version**: Bumps version, creates Git tags, generates changelog
-4. **Publish**: Publishes package to npm registry (with approval gate)
-5. **Release**: Creates GitLab release with artifacts and notes
-
-### Required Setup
-
-To use the CI/CD pipeline, you need to configure the following:
-
-1. **CI/CD Variables**:
-   - `NPM_TOKEN` (required): npm authentication token
-   - `GITLAB_TOKEN` (optional): GitLab API token
+## Available Tools
 
-2. **Protected Branches**:
-   - Protect the `main` branch
-   - Protect version tags (`v*` pattern)
+Once configured, you can:
 
-3. **Variable Masking**:
-   - All credentials are automatically masked in logs
-   - Uses credential masking utilities to prevent exposure
+- **list-components** - List all components, directives, pipes, services
+- **get-component-docs** - Get detailed documentation for a component
+- **search-components** - Search components by keyword
+- **get-component-inputs** - Get input properties
+- **get-component-outputs** - Get output events
+- **get-component-examples** - Get usage examples
+- **get-library-version** - Get current library version
+- **list-deprecated** - List deprecated items
+- **get-deprecation-info** - Get deprecation details
 
-### Quick Start
+## Example Questions
 
-1. Configure required CI/CD variables in GitLab project settings
-2. Ensure `main` branch is protected
-3. Trigger a release by running the `version` job manually
-4. Approve the publish step for production releases
+Try asking:
 
-For detailed setup instructions, security best practices, and troubleshooting, see the [CI/CD Setup Guide](./docs/CI_CD_SETUP.md).
+- "What components are available for forms?"
+- "Show me the ButtonComponent documentation"
+- "What inputs does ModalComponent accept?"
+- "List all deprecated components"
+- "Search for table components"
 
-### Manual Release Process
-
-```bash
-# 1. Ensure all changes are merged to main
-# 2. Go to CI/CD → Pipelines in GitLab
-# 3. Click play button on 'version' job
-# 4. Set RELEASE_TYPE variable (patch, minor, major)
-# 5. Approve publish step when prompted
-# 6. Verify release on npm and GitLab
-```
-
-## Architecture
-
-### High-Level Architecture
-
-```
-┌─────────────┐
-│ MCP Client  │ (Kiro, Claude, etc.)
-└──────┬──────┘
-       │ MCP Protocol (stdio)
-       ▼
-┌─────────────────────────────────┐
-│   CompodocMcpServer             │
-│   - Tool Registration           │
-│   - Request Routing             │
-│   - Error Handling              │
-└──────┬──────────────────────────┘
-       │
-       ▼
-┌─────────────────────────────────┐
-│   Tool Handlers                 │
-│   - list-components             │
-│   - get-component-docs          │
-│   - search-components           │
-│   - get-component-inputs        │
-│   - get-component-outputs       │
-│   - get-component-examples      │
-└──────┬──────────────────────────┘
-       │
-       ▼
-┌─────────────────────────────────┐
-│   Query Engine                  │
-│   - ComponentQuery              │
-│   - SearchEngine                │
-│   - ResultFormatter             │
-└──────┬──────────────────────────┘
-       │
-       ▼
-┌─────────────────────────────────┐
-│   In-Memory Index               │
-│   - Name lookup (Map)           │
-│   - Selector lookup (Map)       │
-│   - Search index (inverted)     │
-│   - Type-based indexes          │
-└──────┬──────────────────────────┘
-       │
-       ▼
-┌─────────────────────────────────┐
-│   DocumentationLoader           │
-│   - File reading                │
-│   - JSON parsing                │
-│   - File watching               │
-│   - Index building              │
-└──────┬──────────────────────────┘
-       │
-       ▼
-┌─────────────────────────────────┐
-│   documentation.json            │
-│   (Compodoc output)             │
-└─────────────────────────────────┘
-```
-
-### Key Design Principles
-
-1. **Single Source of Truth**: `documentation.json` is the only data source
-2. **In-Memory Index**: Fast lookups using Map-based indexes
-3. **Stateless Tools**: Each tool execution is independent
-4. **Error Resilience**: Graceful error handling at every layer
-5. **Hot Reloading**: Automatic index updates when documentation changes
-
-## Testing
-
-### Test Coverage
-
-The project uses a dual testing approach:
-
-1. **Unit Tests**: Test individual functions and classes
-2. **Property-Based Tests**: Verify universal properties using fast-check
+## Troubleshooting
 
-### Running Tests
+### Server won't start
 
 ```bash
-# Run all tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run tests with coverage
-npm run test:coverage
-
-# Run specific test file
-npm test -- src/tools/__tests__/list-components.test.ts
+# Test manually
+npx -y @eui/mcp --doc-path https://euidev.ecdevops.eu/eui-docs-eui-21.x/json/documentation.json
 ```
 
-### Property-Based Testing
-
-The project includes comprehensive property-based tests that verify correctness properties such as:
+### Can't reach documentation URL
 
-- Complete component listing
-- Pagination consistency
-- Search result relevance
-- Type information preservation
-- Round-trip serialization
-
-Each property test runs 100+ iterations with randomly generated test data.
-
-## Troubleshooting
+Check your network connection and firewall settings. If the URL is blocked, download the file locally and use a file path instead.
 
-### Common Issues
+### MCP client doesn't see the tools
 
-#### Server Won't Start
+1. Verify the configuration file syntax is valid JSON
+2. Restart your MCP client completely
+3. Check client logs for connection errors
 
-**Problem**: Server fails to start with configuration error
+## Advanced Configuration
 
-**Solution**: Check that your `config.json` is valid JSON and includes required fields:
+### Enable File Watching (Local Files Only)
 
 ```json
 {
   "documentation": {
-    "path": "./documentation.json"
+    "path": "/path/to/documentation.json",
+    "watchForChanges": true,
+    "reloadDebounce": 1000
   }
 }
 ```
 
-#### Documentation Not Found
-
-**Problem**: Error message "Failed to load documentation"
-
-**Solution**: 
-1. Verify the path in your configuration is correct
-2. Ensure the file exists and is readable
-3. Check that the file is valid JSON
-
-```bash
-# Test if file is valid JSON
-cat documentation.json | jq .
-```
-
-#### Empty Component List
-
-**Problem**: `list-components` returns empty array
-
-**Solution**:
-1. Check that your `documentation.json` contains components
-2. Try with `includeDeprecated: true` to see if all components are deprecated
-3. Verify the JSON structure matches Compodoc's output format
-
-#### Search Returns No Results
-
-**Problem**: `search-components` returns empty results
-
-**Solution**:
-1. Try a broader search query
-2. Check that components exist with `list-components`
-3. Ensure search query is at least 2 characters (configurable)
-
-#### File Watching Not Working
-
-**Problem**: Changes to `documentation.json` don't trigger reload
-
-**Solution**:
-1. Check that `watchForChanges` is `true` in configuration
-2. Verify file system permissions
-3. Try increasing `reloadDebounce` value
-4. Check server logs for file watcher errors
-
-### Debug Mode
-
-Enable debug logging to troubleshoot issues:
+### Enable Debug Logging
 
 ```json
 {
+  "documentation": {
+    "path": "https://euidev.ecdevops.eu/eui-docs-eui-21.x/json/documentation.json"
+  },
   "logging": {
     "level": "debug"
   }
 }
 ```
 
-Or use environment variable:
+### HTTP Polling for Remote URLs
 
-```bash
-COMPODOC_MCP_LOG_LEVEL=debug npm start
+```json
+{
+  "documentation": {
+    "path": "https://euidev.ecdevops.eu/eui-docs-eui-21.x/json/documentation.json",
+    "pollInterval": 300000
+  }
+}
 ```
 
-### Getting Help
-
-If you encounter issues:
-
-1. Check the [Troubleshooting](#troubleshooting) section
-2. Review server logs for error messages
-3. Verify your `documentation.json` is valid Compodoc output
-4. Check that Node.js version is 18 or higher
-
-## Contributing
-
-Contributions are welcome! Please follow these guidelines:
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/my-feature`)
-3. Write tests for new functionality
-4. Ensure all tests pass (`npm test`)
-5. Follow TypeScript and ESLint conventions
-6. Update documentation as needed
-7. Submit a pull request
-
-### Code Style
-
-- Use TypeScript strict mode
-- Follow existing code formatting
-- Add JSDoc comments to public APIs
-- Write descriptive commit messages
-
-## License
-
-MIT License - see LICENSE file for details
+## Next Steps
 
-## Acknowledgments
+- Read the [full documentation](./README.md) for all features
+- Explore all available tools
+- Customize configuration for your workflow
 
-- Built with [@modelcontextprotocol/sdk](https://github.com/modelcontextprotocol/sdk)
-- Uses [Compodoc](https://compodoc.app/) for Angular documentation generation
-- Property-based testing with [fast-check](https://github.com/dubzzz/fast-check)
+Happy coding! 🚀