# ucontrol-mcp

MCP stdio server for the uControl Schema, uAsset, and uMap APIs documented in:

- `DOCC80-API Settings-060526-173133.pdf`
- `DOCC80-Schema API's-060526-173649.pdf`
- `DOCC80-uAsset API's-060526-173407.pdf`
- `DOCC80-uMap API's-060526-173553.pdf`

The server deliberately separates protocols by access type:

- Read-only tools are named `ucontrol_read_*` and are registered with `readOnlyHint: true`.
- Write/mutation tools are named `ucontrol_write_*` and are registered with `readOnlyHint: false`.
- Destructive write tools, such as delete, remove, unlink, and decommission operations, are registered with `destructiveHint: true`.
- `ucontrol_read_protocols` returns the complete local inventory with read/write/destructive classification and whether each tool is currently registered.

## Install

```bash
npm install
npm run build
```

## Configuration

Required:

```bash
UCONTROL_BASE_URL=https://ucontrol.example.com/uControl
```

Optional:

```bash
UCONTROL_API_TOKEN=...
UCONTROL_COOKIE=JSESSIONID=...
UCONTROL_TIMEOUT_MS=30000
UCONTROL_TOOL_MODE=read-only
UCONTROL_ALLOW_WRITES=false
```

Authentication follows the API Settings document: uControl can be configured to require bearer-token authentication, and authenticated users must be in the API-Access team.

`UCONTROL_BASE_URL` should normally include the `/uControl` context path. The server appends documented API paths such as `/api/schema/definitions`.

## Read-only mode

This is the default. Only `ucontrol_read_*` tools are registered.

```json
{
  "mcpServers": {
    "ucontrol": {
      "command": "node",
      "args": ["/Volumes/Hub/Code/GitHub/ucontrol-mcp/dist/index.js"],
      "env": {
        "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
        "UCONTROL_API_TOKEN": "replace-me",
        "UCONTROL_TOOL_MODE": "read-only"
      }
    }
  }
}
```

## Read/write mode

Write tools are registered only when `UCONTROL_TOOL_MODE=read-write`. They still refuse to execute unless `UCONTROL_ALLOW_WRITES=true`.

```json
{
  "mcpServers": {
    "ucontrol": {
      "command": "node",
      "args": ["/Volumes/Hub/Code/GitHub/ucontrol-mcp/dist/index.js"],
      "env": {
        "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
        "UCONTROL_API_TOKEN": "replace-me",
        "UCONTROL_TOOL_MODE": "read-write",
        "UCONTROL_ALLOW_WRITES": "true"
      }
    }
  }
}
```

## LM Studio setup

LM Studio can run local stdio MCP servers from its MCP configuration. Build this project first, then add the server in LM Studio's MCP settings. If LM Studio exposes an **Edit mcp.json** action, use that; otherwise add the same JSON through its MCP server UI.

From this repository:

```bash
cd /Volumes/Hub/Code/GitHub/ucontrol-mcp
npm install
npm run build
```

Recommended starting configuration is read-only:

```json
{
  "mcpServers": {
    "ucontrol": {
      "command": "node",
      "args": ["/Volumes/Hub/Code/GitHub/ucontrol-mcp/dist/index.js"],
      "env": {
        "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
        "UCONTROL_API_TOKEN": "replace-me",
        "UCONTROL_TOOL_MODE": "read-only"
      }
    }
  }
}
```

If LM Studio cannot find `node`, replace `"command": "node"` with the absolute path from:

```bash
which node
```

For write access, change the environment block explicitly:

```json
"env": {
  "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
  "UCONTROL_API_TOKEN": "replace-me",
  "UCONTROL_TOOL_MODE": "read-write",
  "UCONTROL_ALLOW_WRITES": "true"
}
```

Restart or reload LM Studio's MCP servers after saving the configuration. In a chat, verify the connection with:

```text
Use the ucontrol_read_protocols tool and summarize which uControl tools are registered.
```

Expected behavior:

- In read-only mode, only `ucontrol_read_*` tools appear as registered.
- In read/write mode, `ucontrol_write_*` tools also appear, but write calls still fail unless `UCONTROL_ALLOW_WRITES=true`.
- If uControl requires authentication, the API token must belong to a user in the API-Access team.

## VS Code setup

VS Code supports MCP servers through an `mcp.json` file. You can configure this server either for one workspace or for your VS Code user profile.

Options:

- Workspace config: create or edit `.vscode/mcp.json` in the workspace where you want the server available.
- User config: run **MCP: Open User Configuration** from the Command Palette.
- Guided flow: run **MCP: Add Server** from the Command Palette and choose Workspace or Global.

Build the server first:

```bash
cd /Volumes/Hub/Code/GitHub/ucontrol-mcp
npm install
npm run build
```

Recommended read-only `.vscode/mcp.json`:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "ucontrol-api-token",
      "description": "uControl API bearer token",
      "password": true
    }
  ],
  "servers": {
    "ucontrol": {
      "type": "stdio",
      "command": "node",
      "args": ["/Volumes/Hub/Code/GitHub/ucontrol-mcp/dist/index.js"],
      "env": {
        "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
        "UCONTROL_API_TOKEN": "${input:ucontrol-api-token}",
        "UCONTROL_TOOL_MODE": "read-only"
      }
    }
  }
}
```

For write access, change only the environment values intentionally:

```json
"env": {
  "UCONTROL_BASE_URL": "https://ucontrol.example.com/uControl",
  "UCONTROL_API_TOKEN": "${input:ucontrol-api-token}",
  "UCONTROL_TOOL_MODE": "read-write",
  "UCONTROL_ALLOW_WRITES": "true"
}
```

After saving the config, start or restart the server with **MCP: List Servers**, then select `ucontrol` and choose **Start** or **Restart**. VS Code may ask you to trust the local server before exposing its tools in chat.

Verification prompt in VS Code Chat:

```text
Use the ucontrol_read_protocols tool and summarize which uControl tools are registered.
```

Troubleshooting:

- If VS Code cannot find Node.js, replace `"command": "node"` with the absolute path from `which node`.
- If tools do not refresh after a code change, run **MCP: Reset Cached Tools** and restart the server.
- Use **MCP: List Servers** > `ucontrol` > **Show Output** to inspect startup errors.
- For remote SSH/devcontainer workspaces, configure the MCP server in the environment where Node.js and this repo path exist.
- Avoid committing real API tokens. Use VS Code `inputs` as shown above, or an `envFile` outside source control.

## Tool matrix

| Tool | Access | HTTP | Endpoint | Destructive |
| --- | --- | --- | --- | --- |
| `ucontrol_read_protocols` | read | LOCAL | local | no |
| `ucontrol_read_schema_definitions` | read | GET | `/api/schema/definitions` | no |
| `ucontrol_read_schema_data` | read | GET | `/api/schema/data/{definition}` | no |
| `ucontrol_read_schema_ire_rules` | read | GET | `/api/schema/ire/data` | no |
| `ucontrol_read_assets` | read | GET | `/api/asset/data/{definition}` | no |
| `ucontrol_read_asset` | read | GET | `/api/asset/data/{definition}/{record_identifier}` | no |
| `ucontrol_read_asset_tags` | read | GET | `/api/asset/tag/view` | no |
| `ucontrol_write_asset_assign_location` | write | POST | `/api/asset/location/assign` | no |
| `ucontrol_write_asset_remove_location` | write | POST | `/api/asset/location/remove` | yes |
| `ucontrol_write_asset_assign_business_unit` | write | POST | `/api/asset/business-unit/assign` | no |
| `ucontrol_write_asset_remove_business_unit` | write | POST | `/api/asset/business-unit/remove` | yes |
| `ucontrol_write_asset_assign_business_context` | write | POST | `/api/asset/business-context-info/assign` | no |
| `ucontrol_write_asset_remove_business_context` | write | POST | `/api/asset/business-context-info/remove` | yes |
| `ucontrol_write_asset_set_deleted_status` | write | POST | `/api/asset/set/deleted/status` | yes |
| `ucontrol_write_asset_add_relationships` | write | POST | `/api/asset/relationships/add` | no |
| `ucontrol_write_asset_delete_relationships` | write | POST | `/api/asset/relationships/delete` | yes |
| `ucontrol_write_asset_create` | write | POST | `/api/asset/create` | no |
| `ucontrol_write_asset_update` | write | POST | `/api/asset/update` | no |
| `ucontrol_write_asset_tag_create` | write | POST | `/api/asset/tag/create` | no |
| `ucontrol_write_asset_tag_delete` | write | POST | `/api/asset/tag/delete` | yes |
| `ucontrol_write_umap_model_create` | write | POST | `/api/umap/model/create` | no |
| `ucontrol_write_umap_sso_group_create` | write | POST | `/api/umap/sso/group` | no |
| `ucontrol_write_umap_team_create` | write | POST | `/api/umap/team` | no |
| `ucontrol_write_umap_model_decommission` | write | POST | `/api/umap/model/decommission` | yes |
| `ucontrol_read_umap_model_details` | read | GET | `/api/umap/model/details` | no |
| `ucontrol_read_umap_review_data` | read | GET | `/api/umap/review/data` | no |
| `ucontrol_read_umap_sso_group_details` | read | GET | `/api/umap/sso/group/details` | no |
| `ucontrol_read_umap_team_details` | read | GET | `/api/umap/team/details` | no |
| `ucontrol_write_umap_model_recommission` | write | POST | `/api/umap/model/recommission` | no |
| `ucontrol_write_umap_model_rename` | write | POST | `/api/umap/model/rename` | no |
| `ucontrol_write_umap_model_assign` | write | POST | `/api/umap/model/assign` | no |
| `ucontrol_write_umap_component_create` | write | POST | `/api/umap/component/create` | no |
| `ucontrol_write_umap_dependency_create` | write | POST | `/api/umap/dependency/create` | no |
| `ucontrol_write_umap_environment_create` | write | POST | `/api/umap/environment/create` | no |
| `ucontrol_write_umap_service_create` | write | POST | `/api/umap/model/services/create` | no |
| `ucontrol_write_umap_model_delete` | write | POST | `/api/umap/model/delete` | yes |
| `ucontrol_write_umap_service_delete` | write | POST | `/api/umap/model/services/delete` | yes |
| `ucontrol_read_umap_application_types` | read | GET | `/api/umap/model/applicationType/list` | no |
| `ucontrol_read_umap_bmc_appliances` | read | GET | `/api/bmc_appliance/data` | no |
| `ucontrol_read_umap_components` | read | GET | `/api/umap/component/data` | no |
| `ucontrol_read_umap_dependencies` | read | GET | `/api/umap/dependency/data` | no |
| `ucontrol_read_umap_environments` | read | GET | `/api/umap/environment/data` | no |
| `ucontrol_read_umap_ire_rules` | read | GET | `/api/umap/ire/data` | no |
| `ucontrol_read_umap_lead_accounts` | read | GET | `/api/umap/model/leadAccount/list` | no |
| `ucontrol_read_umap_modelling_types` | read | GET | `/api/umap/model/modellingType/list` | no |
| `ucontrol_read_umap_models` | read | GET | `/api/umap/model/list` | no |
| `ucontrol_read_umap_service_types` | read | GET | `/api/umap/model/services/serviceType/list` | no |
| `ucontrol_read_umap_services` | read | GET | `/api/umap/model/services/list` | no |
| `ucontrol_write_umap_service_link` | write | POST | `/api/umap/model/services/link` | no |
| `ucontrol_read_umap_model_cis` | read | GET | `/api/umap/model/ci/list` | no |
| `ucontrol_read_umap_model_patterns` | read | GET | `/api/umap/model/dp/pattern/list` | no |
| `ucontrol_write_umap_component_modify` | write | POST | `/api/umap/component/modify` | no |
| `ucontrol_write_umap_dependency_modify` | write | POST | `/api/umap/dependency/modify` | no |
| `ucontrol_write_umap_environment_modify` | write | POST | `/api/umap/environment/modify` | no |
| `ucontrol_write_umap_model_modify` | write | POST | `/api/umap/model/modify` | no |
| `ucontrol_write_umap_service_modify` | write | POST | `/api/umap/model/services/modify` | no |
| `ucontrol_write_umap_model_publish` | write | POST | `/api/umap/model/publish` | no |
| `ucontrol_write_umap_service_pull` | write | POST | `/api/umap/model/services/pull` | no |
| `ucontrol_write_umap_service_push` | write | POST | `/api/umap/model/services/push` | no |
| `ucontrol_write_umap_model_ci_unlink` | write | POST | `/api/umap/model/ci/unlink` | yes |
| `ucontrol_write_umap_model_patterns_unlink` | write | POST | `/api/umap/model/dp/patterns/unlink` | yes |
| `ucontrol_write_umap_populate` | write | POST | `/api/umap/populate/umap` | no |

## Notes on documented edge cases

- `ucontrol_read_asset_tags` preserves the vendor-documented `GET` request with a JSON body. Native `fetch` disallows GET bodies, so the client uses Node's HTTP client for that path.
- `ucontrol_write_umap_populate` sends `Content-Type: text/plain` with a JSON string body shaped as `{ "data": [...] }`, matching the uMap document.
- Query values that accept multiple IDs can be passed either as a comma-separated string or as an array; arrays are serialized as comma-separated values.
- `ucontrol_write_umap_model_modify` keeps the vendor warning in the tool description: omitted optional values may wipe existing values.

## Development

```bash
npm run build
npm test
```

The test suite starts a local loopback HTTP server. In restricted sandboxes, that may require approval.