@eui/mcp 1.0.3

package/README.md

@@ -0,0 +1,846 @@
+# EUI Compodoc MCP Server
+
+A Model Context Protocol (MCP) server that exposes Angular component library metadata from Compodoc's `documentation.json` to AI assistants.
+
+## 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
+
+- Node.js 18 or higher
+- npm or yarn package manager
+- A Compodoc-generated `documentation.json` file
+
+### Install Dependencies
+
+```bash
+npm install
+```
+
+### Build the Project
+
+```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
+```
+
+2. **Create a configuration file** (`config.json`):
+
+```json
+{
+  "documentation": {
+    "path": "./docs/documentation.json"
+  }
+}
+```
+
+3. **Start the MCP server**:
+
+```bash
+npm start -- --config ./config.json
+```
+
+4. **Configure your MCP client** (e.g., in Kiro's `mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "eui-compodoc": {
+      "command": "node",
+      "args": ["/path/to/eui-compodoc-mcp/dist/main.js", "--config", "/path/to/config.json"]
+    }
+  }
+}
+```
+
+## Configuration
+
+### Configuration File Format
+
+The server accepts a JSON configuration file with the following structure:
+
+```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"
+  }
+}
+```
+
+### 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 |
+
+#### Documentation Configuration
+
+| 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 |
+
+#### Search Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `search.maxResults` | number | `50` | Maximum search results to return |
+| `search.minQueryLength` | number | `2` | Minimum query length for searches |
+
+#### Logging Configuration
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `logging.level` | string | `"info"` | Log level: `"debug"`, `"info"`, `"warn"`, `"error"` |
+| `logging.format` | string | `"json"` | Log format: `"json"` or `"text"` |
+
+### Environment Variables
+
+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:
+
+```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;
+  }>;
+}
+```
+
+## Usage Examples
+
+### Example 1: List All Components
+
+```typescript
+// Request
+{
+  "tool": "list-components",
+  "params": {
+    "type": "component",
+    "limit": 10
+  }
+}
+
+// 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
+
+```typescript
+// Request
+{
+  "tool": "get-component-docs",
+  "params": {
+    "name": "ButtonComponent"
+  }
+}
+
+// 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
+  }
+}
+
+// Response
+{
+  "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
+    }
+  ],
+  "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
+
+2. **Protected Branches**:
+   - Protect the `main` branch
+   - Protect version tags (`v*` pattern)
+
+3. **Variable Masking**:
+   - All credentials are automatically masked in logs
+   - Uses credential masking utilities to prevent exposure
+
+### Quick Start
+
+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
+
+For detailed setup instructions, security best practices, and troubleshooting, see the [CI/CD Setup Guide](./docs/CI_CD_SETUP.md).
+
+### 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
+
+### Running Tests
+
+```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
+```
+
+### Property-Based Testing
+
+The project includes comprehensive property-based tests that verify correctness properties such as:
+
+- 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
+
+### Common Issues
+
+#### Server Won't Start
+
+**Problem**: Server fails to start with configuration error
+
+**Solution**: Check that your `config.json` is valid JSON and includes required fields:
+
+```json
+{
+  "documentation": {
+    "path": "./documentation.json"
+  }
+}
+```
+
+#### 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:
+
+```json
+{
+  "logging": {
+    "level": "debug"
+  }
+}
+```
+
+Or use environment variable:
+
+```bash
+COMPODOC_MCP_LOG_LEVEL=debug npm start
+```
+
+### 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
+
+## Acknowledgments
+
+- 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)