# IDS Enterprise Web Components MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to IDS Enterprise Web Components documentation, enabling AI assistants to search and retrieve component information, examples, and development guidelines.

## 🚀 Quick Start

### Prerequisites
- Node.js 18+ installed
- GitLab access to https://oxford.awsdev.infor.com

### 1. Get Your GitLab Token

1. Visit: https://oxford.awsdev.infor.com/-/user_settings/personal_access_tokens
2. Click "Add new token"
3. Configure:
   - **Name**: `ids-enterprise-mcp-server` or anything you want
   - **Scopes**: Select `read_api` and `read_repository`
4. Copy the generated token

### 2. Add to Your AI Assistant

**Amazon Q CLI / Visual Code**:

1. Make a file in the project you work on `.amazonq/mcp.json`
2. Add to it

```json
{
  "mcpServers": {
    "ids-enterprise-wc": {
      "command": "npx",
      "args": ["ids-enterprise-mcp-server", "--token=YOUR_GITLAB_TOKEN_HERE"]
    }
  }
}
```

To target a specific IDS version (tag or branch):

```json
{
  "mcpServers": {
    "ids-enterprise-wc": {
      "command": "npx",
      "args": ["ids-enterprise-mcp-server", "--token=YOUR_GITLAB_TOKEN_HERE", "--version=1.5.0"]
    }
  }
}
```

You can also set the version via environment variable:

```json
{
  "mcpServers": {
    "ids-enterprise-wc": {
      "command": "npx",
      "args": ["ids-enterprise-mcp-server", "--token=YOUR_GITLAB_TOKEN_HERE"],
      "env": {
        "IDS_VERSION": "1.5.0"
      }
    }
  }
}
```

The `--version` value can be any valid Git ref — a release tag (e.g., `1.5.0`), branch name (e.g., `main`), or omitted to use the default `development` branch.

3. Restart visual code
4. Open q chat in the terminal of the project and you should see `✓ ids_enterprise_mcp_server loaded in ...`
5. When you open q chat plugin you should see

### WSL (Windows Subsystem for Linux) Configuration
 
**Important Note for WSL Users:**

When running Amazon Q CLI on WSL, ensure:
1. Node.js is installed in your WSL environment
2. Set the environment variables in your `.amazonq/mcp.json` to ensure proper MCP server operation:
 
```json
{
  "mcpServers": {
    "ids-enterprise-wc": {
      "command": "npx",
      "args": ["ids-enterprise-mcp-server", "--token=YOUR_GITLAB_TOKEN_HERE"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}
```

You can add `"--version=1.5.0"` to the `args` array to target a specific IDS version.

### 3. Temporary Files

When the MCP server starts, it downloads IDS component source files from GitLab into your system's temporary directory (e.g., `/tmp/ids-enterprise-mcp/` on macOS/Linux). This is used to enable enhanced features like AST-based code analysis.

- Files are stored in your OS temp directory, so they never appear in your project folder.
- The directory is automatically created on server startup and cleaned up when the server shuts down.
- No `.gitignore` entry is needed since files are outside your project.
- If the server is not shut down cleanly, leftover files in the temp directory will be cleaned up by your OS or on the next server start.

### 4. Start Using

Once configured, ask your AI assistant questions like:
- "Search for button components with icons"
- "Show me Angular examples for ids-data-grid"
- "List all Form Input Components"
- "How do I implement ids-modal in Angular?"

## 📋 Available Tools

The server provides 11 tools organized by purpose:

### Project Discovery
- **`get_project_overview`** - Get overview of IDS Enterprise Web Components
- **`list_all_categories`** - List component categories with counts
- **`list_frameworks`** - List supported framework integrations

### Component Discovery
- **`search_components`** - Search for components by name/feature
  - Parameters: `query` (required), `category` (optional), `limit` (optional)
- **`list_components_by_category`** - List components in a category
  - Parameters: `category` (required)
- **`get_component_details`** - Get detailed component information
  - Parameters: `component` (required)

### Implementation Examples
- **`get_component_readme_examples`** - Get basic usage examples
  - Parameters: `component` (required)
- **`get_component_framework_examples`** - Get framework-specific examples
  - Parameters: `component` (required), `framework` (required)

### Development Resources
- **`get_framework_guide`** - Get framework setup guides
  - Parameters: `framework` (required)
- **`search_documentation`** - Search general documentation
  - Parameters: `query` (required), `limit` (optional)
- **`get_development_guidelines`** - Get development best practices
  - Parameters: `topic` (optional)
- **`get_ids_version`** - Get the configured IDS version/branch the server is targeting

### Example Usage Patterns
```
"Give me an overview of IDS Enterprise Web Components"
"Search for data grid components"
"Get details for ids-button component"
"Show me React examples for ids-modal"
"How do I set up IDS components in Angular?"
"What are the accessibility guidelines?"
```

## 🛠️ Development

### Local Development Setup

#### Step 1: Clone Repository

```bash
git clone ssh://git@oxfordssh.awsdev.infor.com:7999/infor-design/ids-enterprise-mcp-server.git
cd enterprise-wc-mcp-server
```

#### Step 2: Install & Build
```bash
# Install dependencies
npm install

# Build the project
npm run build
```

#### Step 3: Replace GitLab Token

Replace `YOUR_TOKEN` with your actual GitLab token in:

**package.json commands:**
```json
{
  "scripts": {
    "start": "node build/main.js --token=YOUR_TOKEN",
    "dev": "npm run build && node build/main.js --token=YOUR_TOKEN"
  }
}
```

**mcp-inspector-config.json:**

```json
# Replace YOUR_TOKEN with your actual token
{
  "mcpServers": {
    "ids-enterprise-mcp-server": {
      "command": "node",
      "args": ["build/main.js", "--token=YOUR_TOKEN"],
      "cwd": "."
    }
  }
}
```

#### Step 4: Test the Server (Two Ways)

**Method 1: Web Interface Testing**

```bash
npm run test:inspector
```

This opens a web interface where you can:
- View all available tools
- Test tool calls with parameters
- See formatted responses
- Debug issues

**Method 2: Amazon Q Configuration**

Add this configuration to your Amazon Q MCP settings:

```json
{
  "mcpServers": {
    "enterprise-wc-mcp-server": {
      "command": "node",
      "args": [
        "/path/to/your/enterprise-wc-mcp-server/build/main.js"
      ],
      "env": {
        "GITLAB_TOKEN": "YOUR_TOKEN"
      }
    }
  }
}
```


### Debugging & Logs

The server runs in **silent mode by default** (only errors shown) for MCP compatibility.

**Enable debug logs** by setting `IDS_LOG_LEVEL`:

```json
{
  "mcpServers": {
    "ids-enterprise-wc": {
      "command": "npx",
      "args": ["ids-enterprise-mcp-server", "--token=YOUR_GITLAB_TOKEN_HERE"],
      "env": {
        "IDS_LOG_LEVEL": "debug"
      }
    }
  }
}
```

**Available log levels**: `error` (default), `warn`, `info`, `debug`, `trace`

**Running directly with npx:**

```bash
# Linux/macOS
IDS_LOG_LEVEL=debug npx ids-enterprise-mcp-server --token=YOUR_TOKEN

# Windows Command Prompt
set IDS_LOG_LEVEL=debug && npx ids-enterprise-mcp-server --token=YOUR_TOKEN

# Windows PowerShell
$env:IDS_LOG_LEVEL="debug"; npx ids-enterprise-mcp-server --token=YOUR_TOKEN
```

## Publishing Commands

To publish a new version, first bump the version in package.json.

```bash
npm login
npm run release
```

To test the release without publishing:

```bash
npm run release:dry-run
```


## 🔗 Resources

- **[IDS Enterprise Web Components](https://oxford.awsdev.infor.com/infor-design/enterprise-wc)** - Main repository
- **[IDS Design System](https://design.infor.com/)** - Design guidelines
- **[Model Context Protocol](https://github.com/modelcontextprotocol)** - MCP specification