Spec-Driven IntelliMatch / iSuite MCP

A single Model Context Protocol 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

npm install

For UI automation (optional):

npx playwright install chromium

2. Configure environment

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

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

Development (no build step):

npm run dev            # Run directly with tsx

Inspect tools interactively:

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):

{
  "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):

{
  "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:

{
  "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

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

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

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):

action:
  type: log
  source: file
  path: "/var/log/intellimatch/app.log"
  lines: 200
  filter: "{{search_term}}"      # optional grep-style filter

HTTP log API:

action:
  type: log
  source: http
  connection: intellimatch_logs
  endpoint: /logs/search
  params:
    level: "{{level}}"
    limit: "{{lines}}"

ui — Browser automation (Playwright)

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

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

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

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

MySQL / MariaDB

my_mysql:
  type: mysql
  host: "${MYSQL_HOST}"
  port: 3306
  database: "${MYSQL_DB}"
  user: "${MYSQL_USER}"
  password: "${MYSQL_PASSWORD}"

UI (Playwright)

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.