# Spec-Driven IntelliMatch / iSuite MCP

A single [Model Context Protocol](https://modelcontextprotocol.io) server for both **IntelliMatch** and **iSuite**, where every tool is defined in a YAML or JSON file — no code changes needed to add new capabilities.

## Architecture

```
specs/
├── intellimatch/          ← IntelliMatch tool specs
│   ├── candidates.yaml
│   ├── jobs.yaml
│   └── reports.yaml
└── isuite/                ← iSuite tool specs
    ├── policies.yaml
    ├── claims.yaml
    └── workflows.yaml

config/
└── connections.yaml       ← API/DB/log connection definitions

src/
├── loader/                ← Scans and validates spec files
├── connections/           ← Connection pool manager
├── executor/              ← Action handlers (http, db, log, ui)
├── template.ts            ← {{variable}} interpolation engine
└── server.ts              ← MCP server (list/call tools)
```

**Adding a new tool = adding or editing a YAML file. Zero code changes.**

---

## Quick Start

### 1. Install dependencies

```bash
npm install
```

For UI automation (optional):
```bash
npx playwright install chromium
```

### 2. Configure environment

```bash
cp .env.example .env
# Edit .env with your actual URLs, credentials, and DB connection strings
```

### 3. Configure connections

Edit `config/connections.yaml` to point at your IntelliMatch and iSuite environments. Connection values support `${ENV_VAR}` syntax — keep secrets in `.env`, not the YAML.

### 4. Build and run

```bash
npm run build          # Compile TypeScript → dist/
npm start              # Run the MCP server (stdio transport)
```

Development (no build step):
```bash
npm run dev            # Run directly with tsx
```

Inspect tools interactively:
```bash
npm run inspect        # Opens MCP Inspector in browser
```

---

## VS Code Integration

### Option A — Claude Code (recommended)

Add the server to your Claude Code MCP config. In VS Code, open the Command Palette → **Claude: Open MCP Settings**, or edit the file directly:

**`.claude/settings.json`** (project-level, checked in):
```json
{
  "mcpServers": {
    "intellimatch-isuite": {
      "command": "node",
      "args": ["C:/NewInitiatives/mcp/Spec-Driven Intellimatch MCP/dist/index.js"],
      "env": {
        "INTELLIMATCH_API_URL": "https://intellimatch.internal/api",
        "INTELLIMATCH_API_TOKEN": "your-token",
        "ISUITE_API_URL": "https://isuite.internal/api",
        "ISUITE_USERNAME": "api_user",
        "ISUITE_PASSWORD": "your-password",
        "INTELLIMATCH_DB_HOST": "localhost",
        "INTELLIMATCH_DB_NAME": "intellimatch",
        "INTELLIMATCH_DB_USER": "im_readonly",
        "INTELLIMATCH_DB_PASSWORD": "your-password",
        "ISUITE_DB_HOST": "sqlserver.internal",
        "ISUITE_DB_NAME": "iSuiteDB",
        "ISUITE_DB_USER": "isuite_readonly",
        "ISUITE_DB_PASSWORD": "your-password"
      }
    }
  }
}
```

Or use `tsx` for development (no build step):
```json
{
  "mcpServers": {
    "intellimatch-isuite": {
      "command": "npx",
      "args": [
        "tsx",
        "C:/NewInitiatives/mcp/Spec-Driven Intellimatch MCP/src/index.ts"
      ]
    }
  }
}
```

### Option B — VS Code MCP Extension

If you're using the VS Code MCP extension, add to **`settings.json`**:
```json
{
  "mcp.servers": {
    "intellimatch-isuite": {
      "command": "node",
      "args": ["${workspaceFolder}/dist/index.js"],
      "transport": "stdio"
    }
  }
}
```

---

## Adding New Tools

1. Create or edit a YAML file in `specs/intellimatch/` or `specs/isuite/`
2. Add a tool entry following the spec format below
3. Restart the MCP server — it reloads all specs on startup

### Spec File Format

```yaml
app: intellimatch   # or isuite, or shared
version: "1.0"

tools:
  - name: im_my_tool          # lowercase_with_underscores, prefix im_ or is_
    description: >
      What this tool does — shown to Claude so write it clearly.
    inputSchema:
      type: object
      properties:
        my_param:
          type: string
          description: What this param does
        limit:
          type: integer
          default: 20
      required:
        - my_param
    action:
      type: http | db | log | ui   # pick one
      # ... action-specific config below
```

---

## Action Types

### `http` — REST API call

```yaml
action:
  type: http
  connection: intellimatch_api    # name from config/connections.yaml
  method: GET                     # GET POST PUT PATCH DELETE
  path: /v1/candidates/{{candidate_id}}
  params:                         # URL query params (GET)
    q: "{{query}}"
    limit: "{{limit}}"
  body:                           # Request body (POST/PUT)
    name: "{{name}}"
  headers:                        # Extra headers (optional)
    X-Custom: "{{custom_value}}"
  resultPath: data.items          # dot-path to extract from response (optional)
```

`{{variable}}` patterns are resolved from the tool's input arguments.

### `db` — Parameterized SQL query

```yaml
action:
  type: db
  connection: intellimatch_db     # postgres | mssql | mysql connection
  # Write native SQL for your DB type. NEVER put {{variables}} in the query.
  query: >
    SELECT id, name, status FROM candidates
    WHERE status = $1 AND name ILIKE '%' || $2 || '%'
    LIMIT $3
  params:
    - "{{status}}"               # resolved and passed as $1 (pg) / ? (mysql) / @param1 (mssql)
    - "{{query}}"                # → $2
    - "{{limit}}"                # → $3
  rowLimit: 500                  # hard cap on returned rows
```

**SQL injection safe**: user inputs in `params` are passed as parameterized values, never string-interpolated into the SQL.

**PostgreSQL**: use `$1`, `$2`, ...
**MySQL**: use `?`, `?`, ...
**SQL Server**: use `@param1`, `@param2`, ...

### `log` — Log access

**File-based** (path must be under `LOG_BASE_DIR`):
```yaml
action:
  type: log
  source: file
  path: "/var/log/intellimatch/app.log"
  lines: 200
  filter: "{{search_term}}"      # optional grep-style filter
```

**HTTP log API**:
```yaml
action:
  type: log
  source: http
  connection: intellimatch_logs
  endpoint: /logs/search
  params:
    level: "{{level}}"
    limit: "{{lines}}"
```

### `ui` — Browser automation (Playwright)

```yaml
action:
  type: ui
  connection: intellimatch_ui    # type: ui connection with baseUrl and auth
  browser: chromium              # chromium | firefox | webkit
  headless: true
  steps:
    - action: navigate
      url: "{{connection.baseUrl}}/login"
    - action: fill
      selector: "#username"
      value: "{{connection.auth.username}}"
    - action: fill
      selector: "#password"
      value: "{{connection.auth.password}}"
    - action: click
      selector: "[type=submit]"
    - action: waitFor
      selector: ".dashboard"
      timeout: 10000
    - action: navigate
      url: "{{connection.baseUrl}}/reports"
    - action: screenshot
      fullPage: false
    - action: getText
      selector: ".result-count"
      as: resultCount            # stored in output as results.resultCount
    - action: getTable
      selector: "table.data"
      as: tableData
    - action: selectOption
      selector: "#status-filter"
      value: "{{status}}"
```

`{{connection.baseUrl}}`, `{{connection.auth.username}}`, and `{{connection.auth.password}}` are automatically resolved from the connection config.

---

## Connection Configuration

Edit `config/connections.yaml`. All `${ENV_VAR}` references are resolved from environment variables at startup.

### HTTP Connection
```yaml
my_api:
  type: http
  baseUrl: "${MY_API_URL}"
  timeout: 30000
  headers:
    Accept: application/json
  auth:
    type: bearer          # bearer | basic | api-key | none
    token: "${MY_TOKEN}"
```

### PostgreSQL
```yaml
my_pg_db:
  type: postgres
  host: "${PG_HOST}"
  port: 5432
  database: "${PG_DB}"
  user: "${PG_USER}"
  password: "${PG_PASSWORD}"
  ssl: true
  pool:
    min: 1
    max: 5
```

### SQL Server
```yaml
my_mssql:
  type: mssql
  server: "${MSSQL_HOST}"
  database: "${MSSQL_DB}"
  user: "${MSSQL_USER}"
  password: "${MSSQL_PASSWORD}"
  options:
    encrypt: true
    trustServerCertificate: false
```

### MySQL / MariaDB
```yaml
my_mysql:
  type: mysql
  host: "${MYSQL_HOST}"
  port: 3306
  database: "${MYSQL_DB}"
  user: "${MYSQL_USER}"
  password: "${MYSQL_PASSWORD}"
```

### UI (Playwright)
```yaml
my_app_ui:
  type: ui
  baseUrl: "${APP_UI_URL}"
  auth:
    username: "${UI_USERNAME}"
    password: "${UI_PASSWORD}"
```

---

## Useful Claude Prompts

Once the MCP is connected in Claude Code, try these prompts:

### IntelliMatch — Recruiting

```
Search for active Java developer candidates in London and show the top 10 matches.
```

```
Find the best candidates for job requisition JOB-2025-0042 with a match score above 0.7.
```

```
What is the current pipeline status for candidate C-10023?
```

```
Show me the placement metrics for Q1 2025 broken down by department.
```

```
Get the last 50 error logs from the IntelliMatch matching engine.
```

```
Take a screenshot of the IntelliMatch reports dashboard.
```

```
Which jobs have been open for more than 30 days and are still unfilled?
```

### iSuite — Insurance

```
Search for all active home insurance policies for "John Smith".
```

```
Get the full details for policy POL-2025-001234 including coverage and renewal date.
```

```
Show me all open claims filed this year with their current amounts and status.
```

```
Submit a new auto insurance claim for policy POL-2025-001234 — incident on 2025-06-10, minor collision, estimated $3,500.
```

```
List all underwriting workflows pending my review.
```

```
Approve workflow WF-2025-00891 with the note "All requirements verified, approved for standard rate".
```

```
Show the claims summary for 2025 — total count, average settlement, and days to close by claim type.
```

```
What iSuite workflows have been stalled for more than 5 days?
```

```
Take a screenshot of workflow WF-2025-00891 for the approval documentation.
```

### General

```
List all available IntelliMatch and iSuite tools and what they do.
```

```
What tools are available for working with insurance claims?
```

---

## Environment Variables Reference

| Variable | Required | Description |
|---|---|---|
| `INTELLIMATCH_API_URL` | Yes | IntelliMatch REST API base URL |
| `INTELLIMATCH_API_TOKEN` | Yes | Bearer token for IntelliMatch API |
| `INTELLIMATCH_DB_HOST` | If using DB tools | PostgreSQL host |
| `INTELLIMATCH_DB_NAME` | If using DB tools | Database name |
| `INTELLIMATCH_DB_USER` | If using DB tools | DB username |
| `INTELLIMATCH_DB_PASSWORD` | If using DB tools | DB password |
| `ISUITE_API_URL` | Yes | iSuite REST API base URL |
| `ISUITE_USERNAME` | Yes | iSuite API username |
| `ISUITE_PASSWORD` | Yes | iSuite API password |
| `ISUITE_DB_HOST` | If using DB tools | SQL Server host |
| `ISUITE_DB_NAME` | If using DB tools | Database name |
| `ISUITE_DB_USER` | If using DB tools | DB username |
| `ISUITE_DB_PASSWORD` | If using DB tools | DB password |
| `INTELLIMATCH_LOGS_URL` | If using log tools | Log API base URL |
| `INTELLIMATCH_LOGS_TOKEN` | If using log tools | Log API token |
| `LOG_BASE_DIR` | If using file logs | Root directory for log file access |
| `INTELLIMATCH_UI_URL` | If using UI tools | IntelliMatch web app URL |
| `INTELLIMATCH_UI_USER` | If using UI tools | Automation user |
| `INTELLIMATCH_UI_PASSWORD` | If using UI tools | Automation password |
| `ISUITE_UI_URL` | If using UI tools | iSuite web app URL |
| `ISUITE_UI_USER` | If using UI tools | Automation user |
| `ISUITE_UI_PASSWORD` | If using UI tools | Automation password |
| `SPECS_DIR` | No | Override specs directory (default: `./specs`) |
| `CONNECTIONS_FILE` | No | Override connections config path |

---

## Security Notes

- **SQL injection**: DB tools use parameterized queries exclusively. `{{variable}}` in the `params` array maps to a positional placeholder (`$1`, `?`, `@param1`) — user input is never concatenated into SQL strings.
- **Path traversal**: File-based log tools restrict access to the `LOG_BASE_DIR` directory.
- **Secrets**: Connection passwords and API tokens are read from environment variables, never stored in spec files.
- **Dependency hygiene**: All packages are pinned to actively maintained major versions with no known CVEs at time of writing. Run `npm audit` regularly.

---

## Troubleshooting

**Tools not loading**: Check the server stderr output — each spec file reports success or the Zod validation error that caused it to be skipped.

**DB connection errors**: DB drivers (`pg`, `mssql`, `mysql2`) are loaded on first use. Confirm the correct driver is installed and the connection config matches your DB type.

**UI automation fails**: Run `npx playwright install` to download browser binaries. Use `headless: false` temporarily to watch the browser for debugging.

**Duplicate tool names**: If two spec files define the same `name`, the server warns and the last loaded definition wins. Keep tool names unique across all spec files.