# UILM MCP Server

MCP (Model Context Protocol) server for the SELISE Blocks UILM (UI Language Management) API. Provides translation key management tools for Claude Code, Cursor, and any MCP-compatible client.

## Features

- Automatic Bearer token management (caches + auto-refreshes on 15-min expiry)
- Module name resolution (use `"auth"` instead of UUIDs)
- Batch key creation with automatic fallback
- 13 tools covering modules, languages, and translation keys

## Quick Start

### Option A: Interactive setup (recommended)

```bash
npx uilm-mcp-server --init
```

This walks you through entering credentials and writes the config directly to your Claude Code or Cursor settings.

### Option B: Manual config

Add to your project's `.mcp.json` (Claude Code) or Cursor MCP settings:

```json
{
  "mcpServers": {
    "uilm": {
      "command": "npx",
      "args": ["-y", "uilm-mcp-server"],
      "env": {
        "UILM_API_BASE_URL": "https://api.seliseblocks.com",
        "UILM_PROJECT_KEY": "your-project-key",
        "UILM_CLIENT_ID": "your-client-id",
        "UILM_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

No clone or build step required -- `npx` handles everything.

### Option C: Using a `.env` file

Create a `.env` file in your project root (make sure it's in `.gitignore`):

```
UILM_API_BASE_URL=https://api.seliseblocks.com
UILM_PROJECT_KEY=your-project-key
UILM_CLIENT_ID=your-client-id
UILM_CLIENT_SECRET=your-client-secret
```

Then use a simpler MCP config without the `env` block:

```json
{
  "mcpServers": {
    "uilm": {
      "command": "npx",
      "args": ["-y", "uilm-mcp-server"]
    }
  }
}
```

## Getting Your Credentials

You need four values from the SELISE Blocks platform.

### API Base URL

```
https://api.seliseblocks.com
```

### Project Key

1. Log in to the [SELISE Blocks Console](https://console.seliseblocks.com)
2. Select your project
3. Go to **Settings** (gear icon)
4. Copy the **Project Key** (starts with `P`)

### Client ID and Client Secret

These are OAuth credentials used for machine-to-machine authentication:

1. In the SELISE Blocks Console, navigate to your project
2. Go to **IAM** > **Clients** (or **Settings** > **API Clients**, depending on your console version)
3. Click **Create Client** (or use an existing one)
4. Set the grant type to **Client Credentials**
5. Copy the **Client ID** (UUID format) and **Client Secret**

> **Note:** If you don't see the Clients section, ask your project admin to create a client credential for you or grant you access to IAM settings.

## Environment Variables

| Variable | Description |
|----------|-------------|
| `UILM_API_BASE_URL` | SELISE Blocks API base URL |
| `UILM_PROJECT_KEY` | Project key (starts with `P`, used as `x-blocks-key` header) |
| `UILM_CLIENT_ID` | OAuth client ID (UUID format) |
| `UILM_CLIENT_SECRET` | OAuth client secret |

## Tools

### Auth
| Tool | Description |
|------|-------------|
| `uilm_authenticate` | Force-refresh Bearer token and check auth status |

### Modules
| Tool | Description |
|------|-------------|
| `uilm_list_modules` | List all modules with IDs |
| `uilm_create_module` | Create a new translation module |

### Languages
| Tool | Description |
|------|-------------|
| `uilm_list_languages` | List all configured languages |

### Keys (Read)
| Tool | Description |
|------|-------------|
| `uilm_get_keys` | Get published translations for a module + language |
| `uilm_search_keys` | Search keys with filters and pagination |
| `uilm_get_key` | Get a single key by item ID |
| `uilm_get_keys_by_names` | Look up keys by name (check existence) |

### Keys (Write)
| Tool | Description |
|------|-------------|
| `uilm_create_key` | Create a single translation key |
| `uilm_create_keys` | Batch create multiple keys |
| `uilm_update_key` | Update an existing key's translations |

### Keys (Delete / Rollback)
| Tool | Description |
|------|-------------|
| `uilm_delete_key` | Delete a key by item ID (irreversible) |
| `uilm_rollback_key` | Rollback a key to previous state |

## Usage Examples

Once configured, ask your AI assistant:

- "List all UILM modules"
- "Create a translation key LOGIN_TITLE in the auth module with en-US: 'Login' and de-DE: 'Anmelden'"
- "Create these keys in the dashboard module: WELCOME_MESSAGE (Welcome / Willkommen), LOGOUT (Logout / Abmelden)"
- "Search for keys containing 'LOGIN'"
- "Get all English translations for the common module"
- "Delete the key with ID abc-123"

## CLI

```bash
npx uilm-mcp-server              # Start the MCP server (stdio transport)
npx uilm-mcp-server --init       # Interactive setup wizard
npx uilm-mcp-server --help       # Show help
npx uilm-mcp-server --version    # Show version
```

## Development

```bash
git clone https://github.com/sohanuzzaman/uilm-mcp-server.git
cd uilm-mcp-server
npm install        # Also runs build via prepare script
npm run dev        # Run with tsx (hot TypeScript execution)
npm run build      # Compile TypeScript
npm start          # Run compiled version
```

### Verify with MCP Inspector

```bash
UILM_API_BASE_URL=https://api.seliseblocks.com \
UILM_PROJECT_KEY=your-project-key \
UILM_CLIENT_ID=your-client-id \
UILM_CLIENT_SECRET=your-client-secret \
  npx @modelcontextprotocol/inspector node dist/index.js
```