# iSuite Operations MCP Server

A Model Context Protocol (MCP) server that exposes **48 tools** covering the full spectrum of iSuite enterprise administration — user management, role verification, job monitoring, scheduler control, batch execution, audit trail lookup, and configuration validation.

---

## Table of Contents

- [Overview](#overview)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Build](#build)
- [VS Code Integration — Cline](#vs-code-integration--cline)
- [VS Code Integration — Roo](#vs-code-integration--roo)
- [Claude Desktop Integration](#claude-desktop-integration)
- [Available Tools](#available-tools)
- [Example Prompts](#example-prompts)
- [Troubleshooting](#troubleshooting)

---

## Overview

```
src/
  index.ts             MCP server entry point (stdio transport)
  server-config.ts     Environment-based connection configuration
  tools/
    users.ts           8 tools  — user CRUD, disable/enable, password reset
    roles.ts           7 tools  — role listing, permission checks, assign/revoke
    jobs.ts            7 tools  — job status, running/failed lists, cancel, retry
    scheduler.ts       7 tools  — schedule management, upcoming jobs, history
    batch.ts           6 tools  — batch status, rerun, cancel, history
    audit.ts           6 tools  — log search, user activity, export, login history
    config.ts          7 tools  — config validation, health check, compare envs
```

**Runtime:** Node.js 18+  
**Transport:** stdio (works with any MCP-compatible client)  
**Authentication:** API Key, Bearer token, or Basic auth

---

## Prerequisites

| Requirement | Version |
|-------------|---------|
| Node.js | 18 or later |
| npm | 9 or later |
| iSuite instance | With REST API access enabled |

---

## Installation

```bash
# Clone or download the project
cd c:\NewInitiatives\mcp\mcp-isuite

# Install dependencies (zero vulnerabilities)
npm install
```

---

## Configuration

Copy the example environment file and fill in your iSuite connection details:

```bash
copy .env.example .env
```

Edit `.env`:

```env
# Required
ISUITE_BASE_URL=https://isuite.yourcompany.com/api/v1
ISUITE_API_KEY=your-api-key-here

# Auth type: apikey | bearer | basic
ISUITE_AUTH_TYPE=apikey

# For basic auth only
ISUITE_USERNAME=
ISUITE_PASSWORD=

# Optional
ISUITE_ENVIRONMENT=production
ISUITE_TIMEOUT_MS=30000
ISUITE_VERIFY_TLS=true
```

> **Note:** The server reads environment variables at startup. When integrating with Cline or Roo, set these in the plugin's MCP server `env` block (see below) rather than relying on a `.env` file.

---

## Build

```bash
npm run build
```

Compiled output lands in `dist/`. The entry point is `dist/index.js`.

To verify the build:

```bash
node dist/index.js
# Expected output on stderr: iSuite Operations MCP server running on stdio
```

Press `Ctrl+C` to stop.

---

## VS Code Integration — Cline

[Cline](https://marketplace.visualstudio.com/items?itemName=saoudrizwan.claude-dev) is a VS Code extension that supports MCP servers natively.

### Step 1 — Install Cline

Open VS Code → Extensions (`Ctrl+Shift+X`) → search **Cline** → Install.

### Step 2 — Open MCP Settings

1. Click the **Cline** icon in the Activity Bar.
2. Click the **MCP Servers** button (plug icon) in the Cline panel header.
3. Click **Edit MCP Settings** — this opens `cline_mcp_settings.json`.

### Step 3 — Add the iSuite Server

```json
{
  "mcpServers": {
    "isuite": {
      "command": "node",
      "args": ["c:/NewInitiatives/mcp/mcp-isuite/dist/index.js"],
      "env": {
        "ISUITE_BASE_URL": "https://isuite.yourcompany.com/api/v1",
        "ISUITE_API_KEY": "your-api-key-here",
        "ISUITE_AUTH_TYPE": "apikey",
        "ISUITE_ENVIRONMENT": "production",
        "ISUITE_TIMEOUT_MS": "30000"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}
```

> **Windows path note:** Use forward slashes (`/`) or escaped backslashes (`\\`) in JSON paths.

### Step 4 — Verify Connection

1. Save `cline_mcp_settings.json`.
2. In the Cline panel, the **isuite** server should appear with a green dot.
3. Click the server name to see all 48 registered tools listed.

### Step 5 — Use in Chat

Open a Cline chat and type any of the [example prompts](#example-prompts) below.

---

## VS Code Integration — Roo

[Roo Code](https://marketplace.visualstudio.com/items?itemName=RooVeterinaryInc.roo-cline) (formerly Roo Cline) is a Cline fork with additional features and its own MCP configuration.

### Step 1 — Install Roo Code

Open VS Code → Extensions (`Ctrl+Shift+X`) → search **Roo Code** → Install.

### Step 2 — Open Roo MCP Settings

**Option A — Via Command Palette:**

```
Ctrl+Shift+P → Roo Code: Open MCP Settings
```

**Option B — Via UI:**

1. Click the **Roo Code** icon in the Activity Bar.
2. Click the gear icon → **MCP Servers**.
3. Click **Edit Global MCP Settings**.

This opens `%APPDATA%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json` on Windows.

### Step 3 — Add the iSuite Server

```json
{
  "mcpServers": {
    "isuite": {
      "command": "node",
      "args": ["c:/NewInitiatives/mcp/mcp-isuite/dist/index.js"],
      "env": {
        "ISUITE_BASE_URL": "https://isuite.yourcompany.com/api/v1",
        "ISUITE_API_KEY": "your-api-key-here",
        "ISUITE_AUTH_TYPE": "apikey",
        "ISUITE_ENVIRONMENT": "production",
        "ISUITE_TIMEOUT_MS": "30000"
      },
      "disabled": false,
      "alwaysAllow": [
        "list_users",
        "get_user",
        "list_roles",
        "get_user_roles",
        "list_running_jobs",
        "list_failed_jobs",
        "get_job_status",
        "list_schedules",
        "get_scheduler_status",
        "list_running_batches",
        "search_audit_logs",
        "check_system_health",
        "get_config_value",
        "list_config_keys"
      ]
    }
  }
}
```

> **`alwaysAllow`** lists read-only tools that Roo will call without prompting for permission. Write/mutating tools (create, delete, cancel, rerun) are intentionally omitted so Roo asks before executing them.

### Step 4 — Workspace-Scoped Config (Optional)

To scope the MCP server to a single workspace, create `.roo/mcp.json` in your project root instead:

```json
{
  "mcpServers": {
    "isuite": {
      "command": "node",
      "args": ["c:/NewInitiatives/mcp/mcp-isuite/dist/index.js"],
      "env": {
        "ISUITE_BASE_URL": "https://isuite.yourcompany.com/api/v1",
        "ISUITE_API_KEY": "your-api-key-here",
        "ISUITE_ENVIRONMENT": "staging"
      }
    }
  }
}
```

This is useful for pointing different workspaces at different iSuite environments (prod vs. staging).

### Step 5 — Verify Connection

1. Open the Roo Code panel.
2. Click the **MCP** tab — the **isuite** server should show as connected.
3. Expand it to confirm all 48 tools are listed.

---

## Claude Desktop Integration

For use with the Claude Desktop app, edit `claude_desktop_config.json`:

**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`  
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "isuite": {
      "command": "node",
      "args": ["c:/NewInitiatives/mcp/mcp-isuite/dist/index.js"],
      "env": {
        "ISUITE_BASE_URL": "https://isuite.yourcompany.com/api/v1",
        "ISUITE_API_KEY": "your-api-key-here",
        "ISUITE_AUTH_TYPE": "apikey",
        "ISUITE_ENVIRONMENT": "production"
      }
    }
  }
}
```

Restart Claude Desktop after saving.

---

## Available Tools

### User Management

| Tool | Description |
|------|-------------|
| `list_users` | List users with status/role filters and pagination |
| `get_user` | Full profile for a user by ID or username |
| `create_user` | Create a new user account with role assignments |
| `update_user` | Update email, name, department, or manager |
| `disable_user` | Disable account (preserves data, blocks login) |
| `enable_user` | Re-enable a disabled account |
| `delete_user` | Permanently delete a user, with ownership transfer |
| `reset_user_password` | Send reset email or return temporary password |

### Role Verification

| Tool | Description |
|------|-------------|
| `list_roles` | All roles, optionally with full permission lists |
| `get_role` | Full details and permissions for one role |
| `get_user_roles` | All roles assigned to a specific user |
| `verify_user_permission` | Check if a user has a specific permission |
| `assign_role` | Assign a role (supports temporary/expiring assignments) |
| `revoke_role` | Remove a role from a user |
| `list_role_members` | All users who hold a given role |

### Job Status Monitoring

| Tool | Description |
|------|-------------|
| `get_job_status` | Status, progress, and details for a job execution |
| `list_running_jobs` | All currently running jobs |
| `list_failed_jobs` | Failed jobs filtered by time range and type |
| `list_completed_jobs` | Completed jobs filtered by time range |
| `get_job_history` | Full run history for a job definition |
| `cancel_job` | Gracefully or forcefully cancel a running job |
| `retry_job` | Retry a failed job, optionally from a specific step |

### Scheduler Monitoring

| Tool | Description |
|------|-------------|
| `list_schedules` | All schedules with status filter |
| `get_schedule` | Full details including cron expression and next run |
| `get_scheduler_status` | Scheduler engine status (running/paused/standby) |
| `enable_schedule` | Resume a disabled schedule |
| `disable_schedule` | Pause a schedule without deleting it |
| `list_upcoming_jobs` | Jobs scheduled to run within N hours |
| `get_schedule_history` | Past execution history for a schedule |

### Batch Execution Status

| Tool | Description |
|------|-------------|
| `get_batch_status` | Status, progress, and step details for a batch |
| `list_batch_jobs` | Batch jobs filtered by status and time range |
| `list_running_batches` | All currently executing batch jobs |
| `get_batch_history` | Execution history for a batch definition |
| `rerun_batch` | Re-execute from failure point or beginning |
| `cancel_batch` | Cancel a running or pending batch job |

### Audit Trail Lookup

| Tool | Description |
|------|-------------|
| `search_audit_logs` | Full-text + field search across audit logs |
| `get_audit_log` | Complete details for a single log entry |
| `list_user_activity` | All actions performed by a specific user |
| `list_recent_changes` | System changes (config, roles, schedules) within N hours |
| `export_audit_trail` | Export logs to CSV, JSON, or XLSX |
| `get_login_history` | Login, logout, and failed login events |

### Configuration Validation

| Tool | Description |
|------|-------------|
| `validate_config` | Validate all or a specific config section |
| `get_config_value` | Get a config value by dot-notation key |
| `list_config_keys` | All config keys, filterable by section |
| `compare_configs` | Diff configuration between two environments |
| `check_system_health` | Health check all subsystems (DB, cache, queue, etc.) |
| `validate_connection` | Test a named connection (DB, SMTP, SFTP, S3, etc.) |
| `update_config_value` | Update a config value (requires admin permission) |

---

## Example Prompts

Copy and paste any of these into Cline, Roo, or Claude to get started.

---

### User Management

```
List all active iSuite users in the Finance department and show me
which roles each one has assigned.
```

```
Create a new iSuite user account for Jane Smith (jsmith@company.com)
in the Operations department. Assign her the OPERATOR and BATCH_RUNNER
roles, and send a welcome email.
```

```
User john.doe hasn't logged in for 90 days. Check his account status,
list his current roles, then disable the account with the reason
"Inactive account — 90 day policy".
```

```
I need to audit who has the ADMIN role in iSuite. List all members
of that role and verify whether any of them also have the SCHEDULER_ADMIN
role at the same time.
```

---

### Job Monitoring & Control

```
Show me all currently running iSuite jobs. For any job that has been
running longer than 2 hours, get its full status and step details.
```

```
List all failed jobs from the last 24 hours. Group them by job type
and tell me which type has the highest failure rate.
```

```
Job execution JOB-20240612-0042 is stuck. Check its current status,
then cancel it gracefully with the reason "Manual intervention — stuck job".
After cancellation, retry it from the failed step.
```

```
Get the full execution history for job definition ETL-DAILY-SALES
for the past 30 runs. Summarize average duration, success rate,
and identify any patterns in failures.
```

---

### Scheduler

```
Show me all scheduled jobs that are set to run in the next 6 hours.
Highlight any that overlap in timing and might cause resource contention.
```

```
The end-of-month batch window starts tomorrow. Disable all non-critical
schedules (type: report) for the next 24 hours to free up resources.
List which ones you disabled.
```

```
Get the scheduler engine status and list all currently disabled schedules.
Tell me which ones have been disabled longest.
```

---

### Batch Execution

```
Show me all batch jobs that are currently running. For each one,
show progress percentage and estimated completion time.
```

```
Batch job BATCH-RECON-2024-0610 failed overnight. Get its full status
including step details, then rerun it from the failed step with
normal priority.
```

```
Get the last 20 executions of the MONTH-END-CLOSE batch. Summarize
average runtime, any failures, and whether performance has degraded
over the last 5 runs compared to the previous 15.
```

---

### Audit Trail

```
Search the audit logs for all CONFIG_UPDATE actions performed in the
last 7 days. Show me who made changes, what was changed, and when.
```

```
Pull all activity for user admin.user from the past 30 days.
Summarize the types of actions they performed and flag anything
that looks unusual (e.g. bulk deletes, after-hours logins, role changes).
```

```
Export the full audit trail for June 2024 to CSV format.
Include only events related to job cancellations and batch reruns.
```

```
Show me all failed login attempts in the last 48 hours.
Group by username and highlight any accounts with more than
3 failed attempts — these may need to be locked.
```

---

### Configuration & Health

```
Run a full iSuite system health check across all subsystems.
Summarize which are healthy, which have warnings, and which are failing.
```

```
Validate the entire iSuite configuration in strict mode.
List all errors and warnings and suggest remediation steps.
```

```
Compare the iSuite configuration between production and staging environments.
Highlight every difference and flag any production settings that look
risky if accidentally used in staging.
```

```
Check the database connection health and validate the SMTP connection.
If either fails, show the full error details from the config.
```

```
What is the current value of scheduler.maxConcurrentJobs?
Also list all configuration keys under the scheduler section
so I can review the full scheduler configuration.
```

---

### Combined / Multi-Domain

```
Do a daily operations check:
1. Show all currently running jobs and batches
2. List any failed jobs or batches from the last 12 hours
3. Show upcoming scheduled jobs in the next 4 hours
4. Run a system health check
Give me a summary with any action items.
```

```
User sarah.jones is leaving the company today. 
1. Get her current profile and role assignments
2. Revoke all her roles with reason "Employee offboarding"
3. Disable her account
4. Show her audit activity from the last 30 days for compliance records
```

```
Before the production deployment tonight:
1. Validate the full iSuite configuration
2. Check system health
3. List any jobs currently running that might be affected
4. Show upcoming scheduled jobs in the next 8 hours that could conflict
Summarize the go/no-go status.
```

---

## Troubleshooting

### Server not appearing in Cline/Roo

- Verify the path in `args` is correct and `dist/index.js` exists after `npm run build`.
- Check that Node.js 18+ is on your system `PATH`: `node --version`.
- Use forward slashes in JSON paths on Windows.

### Authentication errors (401/403)

- Confirm `ISUITE_API_KEY` is correct and not expired.
- Check `ISUITE_AUTH_TYPE` matches what your iSuite instance expects.
- For basic auth, ensure `ISUITE_USERNAME` and `ISUITE_PASSWORD` are both set.

### Connection timeout

- Increase `ISUITE_TIMEOUT_MS` (default 30000 ms).
- Verify `ISUITE_BASE_URL` is reachable from your machine.
- Check firewall/VPN if iSuite is on a private network.

### TLS certificate errors

- If using a self-signed certificate in a dev environment, set `ISUITE_VERIFY_TLS=false`.
- Never set this to `false` in production.

### Tool returns HTTP 404

- The API path may differ from the defaults. Check your iSuite API documentation and update the path in the relevant `src/tools/*.ts` file, then rebuild.

### Rebuild after changes

```bash
npm run build
```

Cline and Roo will pick up changes the next time they start the server process (usually on the next chat session or after clicking Reconnect in the MCP panel).