@iris-mcp/admin 0.0.0-stage → 1.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +242 -0
- package/LICENSE +21 -0
- package/README.md +1030 -2
- package/dist/index.d.ts +11 -0
- package/dist/index.js +33 -0
- package/dist/prompts/auditSecurityPosture.d.ts +12 -0
- package/dist/prompts/auditSecurityPosture.js +52 -0
- package/dist/prompts/index.d.ts +12 -0
- package/dist/prompts/index.js +16 -0
- package/dist/prompts/provisionProjectEnvironment.d.ts +11 -0
- package/dist/prompts/provisionProjectEnvironment.js +48 -0
- package/dist/tools/audit.d.ts +42 -0
- package/dist/tools/audit.js +394 -0
- package/dist/tools/database.d.ts +14 -0
- package/dist/tools/database.js +179 -0
- package/dist/tools/index.d.ts +12 -0
- package/dist/tools/index.js +52 -0
- package/dist/tools/ldap.d.ts +33 -0
- package/dist/tools/ldap.js +252 -0
- package/dist/tools/mapping.d.ts +15 -0
- package/dist/tools/mapping.js +175 -0
- package/dist/tools/namespace.d.ts +14 -0
- package/dist/tools/namespace.js +145 -0
- package/dist/tools/oauth.d.ts +17 -0
- package/dist/tools/oauth.js +269 -0
- package/dist/tools/permission.d.ts +13 -0
- package/dist/tools/permission.js +70 -0
- package/dist/tools/presets.d.ts +20 -0
- package/dist/tools/presets.js +84 -0
- package/dist/tools/resource.d.ts +81 -0
- package/dist/tools/resource.js +402 -0
- package/dist/tools/role.d.ts +14 -0
- package/dist/tools/role.js +139 -0
- package/dist/tools/service.d.ts +19 -0
- package/dist/tools/service.js +199 -0
- package/dist/tools/ssl.d.ts +14 -0
- package/dist/tools/ssl.js +201 -0
- package/dist/tools/user.d.ts +20 -0
- package/dist/tools/user.js +326 -0
- package/dist/tools/webapp.d.ts +20 -0
- package/dist/tools/webapp.js +268 -0
- package/dist/tools/x509.d.ts +42 -0
- package/dist/tools/x509.js +224 -0
- package/package.json +58 -3
package/README.md
CHANGED
|
@@ -1,3 +1,1031 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @iris-mcp/admin
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
**IRIS Administration MCP Server** -- Namespace, database, user, role, resource (incl. SQL privileges), web application, SSL/TLS, OAuth2, service, LDAP, X.509, and audit management via the Model Context Protocol.
|
|
4
|
+
|
|
5
|
+
Part of the [IRIS MCP Server Suite](../../README.md).
|
|
6
|
+
|
|
7
|
+
---
|
|
8
|
+
|
|
9
|
+
## Installation
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
npm install -g @iris-mcp/admin
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Or run directly without installing:
|
|
16
|
+
|
|
17
|
+
```bash
|
|
18
|
+
npx -y @iris-mcp/admin@1
|
|
19
|
+
```
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## Configuration
|
|
24
|
+
|
|
25
|
+
All servers use the same environment variables:
|
|
26
|
+
|
|
27
|
+
| Variable | Default | Description |
|
|
28
|
+
|----------|---------|-------------|
|
|
29
|
+
| `IRIS_HOST` | `localhost` | IRIS hostname or IP |
|
|
30
|
+
| `IRIS_PORT` | `52773` | IRIS web server port |
|
|
31
|
+
| `IRIS_USERNAME` | `_SYSTEM` | IRIS username |
|
|
32
|
+
| `IRIS_PASSWORD` | *(required)* | IRIS password |
|
|
33
|
+
| `IRIS_NAMESPACE` | `USER` | Default IRIS namespace |
|
|
34
|
+
| `IRIS_HTTPS` | `false` | Use HTTPS instead of HTTP |
|
|
35
|
+
| `IRIS_ACCEPT_LANGUAGE` | `en-US,en;q=0.9` | **Optional.** `Accept-Language` header sent on every request, pinning `%Status` error text to a predictable language instead of whatever locale an unspecified header resolves to. IRIS also selects a message table per worker process independently of this header, so localized prefixes can still appear — existing prefix-stripping is unaffected. Details: [suite README](../../README.md#2-set-environment-variables). |
|
|
36
|
+
|
|
37
|
+
### Multiple servers & the `server` parameter
|
|
38
|
+
|
|
39
|
+
Optionally, set `IRIS_PROFILES` (a JSON map of named IRIS instances) and `IRIS_GOVERNANCE` (a JSON tool-action policy) to target several instances from one server and restrict which actions are allowed. Every tool accepts an optional `server` parameter (a profile name from `IRIS_PROFILES`) that selects which instance the call targets; omit it to use the `default` profile. It composes with the existing per-call `namespace` override. Both variables are **optional and additive** — omit them and this server behaves exactly as a single-instance, fully-enabled install. Full model, escaping, and worked examples: [Multiple Servers & Governance](../../README.md#multiple-servers--governance).
|
|
40
|
+
|
|
41
|
+
Optionally, set `IRIS_GOVERNANCE_FILE` to the path of a JSON file of the same shape as `IRIS_GOVERNANCE` to load policy from a file shared across several MCP clients instead of inline JSON. **Optional and additive** — unset (the default) means inert: no file is ever read and behavior is byte-for-byte unchanged. An `IRIS_GOVERNANCE` env value always wins over the file. Details: [Governance file](../../README.md#governance-file-iris_governance_file).
|
|
42
|
+
|
|
43
|
+
### Tool Visibility (`IRIS_TOOLS_PRESET`)
|
|
44
|
+
|
|
45
|
+
Set `IRIS_TOOLS_PRESET=core` to trim this server's `tools/list` to a **13-tool runtime roster** (12 package tools + `iris_server_profiles`) — the everyday admin loop (namespaces, databases, users, webapps, permission checks); no mapping/role-security/SSL/OAuth/service/LDAP/X509/audit management. `IRIS_TOOLS_PRESET=developer` trims to **11 runtime tools** (10 + `iris_server_profiles`) — only what a developer self-serves (namespace/database/mapping/webapp config plus permission checks), hiding ALL user/security administration. Omit (or set `"full"`) for today's behavior — every tool visible, byte-for-byte. `IRIS_TOOLS_DISABLE`/`IRIS_TOOLS_ENABLE` hide/force-show individual tools independent of the preset. This is orthogonal to `IRIS_GOVERNANCE` above (visibility = does the agent know a tool exists; governance = is an already-visible call allowed). Full model, exact per-tool roster, and the payload-size measurements: [Tool Visibility Presets](../../README.md#tool-visibility-presets).
|
|
46
|
+
|
|
47
|
+
> **Prompt-pack limitation.** The `audit-security-posture` prompt calls `iris_user_get`, `iris_role_list`, `iris_service_manage`, `iris_ssl_list`, and `iris_audit_manage` — under `core`, `iris_service_manage`/`iris_ssl_list`/`iris_audit_manage` are hidden (the prompt cannot complete steps 4-6); under `developer`, ALL FIVE tools it calls are hidden (the prompt cannot run at all). The `provision-project-environment` prompt calls `iris_user_manage`, which is hidden under `developer` (step 4 fails). Both prompts need `full`, or `IRIS_TOOLS_ENABLE` naming the specific tool(s) they use.
|
|
48
|
+
|
|
49
|
+
---
|
|
50
|
+
|
|
51
|
+
### Audit Logging (`IRIS_AUDIT_LOG`)
|
|
52
|
+
|
|
53
|
+
For regulated deployments, set `IRIS_AUDIT_LOG=/path/to/audit.jsonl` to record **every MCP tool call this server handles** — success, error, or governance denial — as one secrets-free JSON line (session, sequence, tool, action, outcome, redacted parameter keys). It is **off by default** (unset ⇒ a mechanical no-op, zero filesystem writes) and framework-wide — the same interceptor covers every tool on this server. `IRIS_AUDIT_LOG_MAX_MB` (default `50`) sets the single-generation rotation size; `IRIS_AUDIT_LOG_PARAMS=true` additionally records (redacted) parameter *values*. Because it is server-side **configuration** — not a governed tool action — an AI client cannot disable its own audit trail; only an operator with server-environment access can. Full record shape, redaction rules, and how it differs from IRIS's own `iris_audit_manage` security-audit tool: [Compliance & Auditability](../../README.md#compliance--auditability).
|
|
54
|
+
|
|
55
|
+
### Server Manager connections (`IRIS_SERVER_MANAGER`)
|
|
56
|
+
|
|
57
|
+
Set `IRIS_SERVER_MANAGER=auto` to import IRIS connection definitions straight from the InterSystems Server Manager VS Code extension's `intersystems.servers` settings — one curated roster instead of re-typing host/port/username into every MCP client's config. `IRIS_SERVER_MANAGER` is **framework configuration, not a tool** — it applies identically across all five servers in the suite. Omit (or set `"off"`, the default) for today's behavior: no settings file is ever read. A password-less imported definition is completed via an OS-keychain / `IRIS_CREDENTIAL_HELPER` credential chain (see the [`iris-mcp-credentials` CLI](../../README.md#iris-mcp-credentials-cli) — Server Manager passwords themselves are never readable outside VS Code, by design); `iris_server_profiles` reports where each profile's connection fields came from via `source` (`"env"`/`"server-manager"`) and `sourceFile`. The companion variables are all optional, each with its own default: `IRIS_SM_SERVERS` (unset — import all), `IRIS_SM_SETTINGS_PATHS` (unset — normal discovery), `IRIS_SM_WORKSPACE` (unset — the process CWD) and `IRIS_CREDENTIAL_HELPER` (unset). Full model, discovery precedence, and the SecretStorage boundary explained plainly: [Server Manager connections](../../README.md#server-manager-connections-optional).
|
|
58
|
+
|
|
59
|
+
## MCP Client Configuration
|
|
60
|
+
|
|
61
|
+
### Claude Code (`.mcp.json`)
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"mcpServers": {
|
|
66
|
+
"iris-admin-mcp": {
|
|
67
|
+
"command": "npx",
|
|
68
|
+
"args": ["-y", "@iris-mcp/admin@1"],
|
|
69
|
+
"env": {
|
|
70
|
+
"IRIS_HOST": "localhost",
|
|
71
|
+
"IRIS_PORT": "52773",
|
|
72
|
+
"IRIS_USERNAME": "_SYSTEM",
|
|
73
|
+
"IRIS_PASSWORD": "SYS",
|
|
74
|
+
"IRIS_NAMESPACE": "USER"
|
|
75
|
+
}
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### Claude Desktop (`claude_desktop_config.json`)
|
|
82
|
+
|
|
83
|
+
```json
|
|
84
|
+
{
|
|
85
|
+
"mcpServers": {
|
|
86
|
+
"iris-admin-mcp": {
|
|
87
|
+
"command": "npx",
|
|
88
|
+
"args": ["-y", "@iris-mcp/admin@1"],
|
|
89
|
+
"env": {
|
|
90
|
+
"IRIS_HOST": "localhost",
|
|
91
|
+
"IRIS_PORT": "52773",
|
|
92
|
+
"IRIS_USERNAME": "_SYSTEM",
|
|
93
|
+
"IRIS_PASSWORD": "SYS",
|
|
94
|
+
"IRIS_NAMESPACE": "USER"
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
### Cursor
|
|
102
|
+
|
|
103
|
+
```json
|
|
104
|
+
{
|
|
105
|
+
"iris-admin-mcp": {
|
|
106
|
+
"command": "npx",
|
|
107
|
+
"args": ["-y", "@iris-mcp/admin@1"],
|
|
108
|
+
"env": {
|
|
109
|
+
"IRIS_HOST": "localhost",
|
|
110
|
+
"IRIS_PORT": "52773",
|
|
111
|
+
"IRIS_USERNAME": "_SYSTEM",
|
|
112
|
+
"IRIS_PASSWORD": "SYS",
|
|
113
|
+
"IRIS_NAMESPACE": "USER"
|
|
114
|
+
}
|
|
115
|
+
}
|
|
116
|
+
}
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
> **Note:** Replace `"SYS"` with your actual IRIS password. Avoid committing real credentials to version control.
|
|
120
|
+
|
|
121
|
+
---
|
|
122
|
+
|
|
123
|
+
## Tool Reference
|
|
124
|
+
|
|
125
|
+
### Framework Tools
|
|
126
|
+
|
|
127
|
+
Provided by the shared framework and available on **every** suite server (Epic 19).
|
|
128
|
+
|
|
129
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
130
|
+
|------|-------------|----------------|-------------|
|
|
131
|
+
| `iris_server_profiles` | **Call this first.** Reports the configured server-profile roster (non-secret connection metadata — `password` is never included) and the effective governance policy (which actions are enabled/disabled). | `profile?`, `allProfiles?` | readOnly, idempotent |
|
|
132
|
+
|
|
133
|
+
`iris_server_profiles` is a **read tool, enabled by default**. It reports in-memory config and does not connect to IRIS. Use it to choose the right `server` profile and avoid governance-disabled actions before invoking other tools.
|
|
134
|
+
|
|
135
|
+
### Namespace & Database Tools
|
|
136
|
+
|
|
137
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
138
|
+
|------|-------------|----------------|-------------|
|
|
139
|
+
| `iris_namespace_manage` | Create, modify, or delete a namespace | `action`, `name`, `codeDatabase?`, `dataDatabase?`, `library?`, `tempGlobals?` | destructive |
|
|
140
|
+
| `iris_namespace_list` | List all namespaces with DB associations | `cursor?` | readOnly, idempotent |
|
|
141
|
+
| `iris_database_manage` | Create, modify, or delete a database | `action`, `name`, `directory?`, `size?`, `maxSize?`, `expansionSize?`, `readOnly?`, `resource?` | destructive |
|
|
142
|
+
| `iris_database_list` | List all databases with size and mount status | `cursor?` | readOnly, idempotent |
|
|
143
|
+
|
|
144
|
+
### Namespace Mapping Tools
|
|
145
|
+
|
|
146
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
147
|
+
|------|-------------|----------------|-------------|
|
|
148
|
+
| `iris_mapping_manage` | Create or delete global/routine/package mappings | `action`, `type`, `namespace`, `name`, `database?`, `collation?`, `lockDatabase?`, `subscript?`, `force?` | destructive |
|
|
149
|
+
| `iris_mapping_list` | List mappings for a namespace by type | `namespace`, `type`, `cursor?` | readOnly, idempotent |
|
|
150
|
+
|
|
151
|
+
### User & Security Tools
|
|
152
|
+
|
|
153
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
154
|
+
|------|-------------|----------------|-------------|
|
|
155
|
+
| `iris_user_manage` | Create, modify, or delete a user account | `action`, `name`, `password?`, `fullName?`, `roles?`, `enabled?`, `namespace?` | destructive |
|
|
156
|
+
| `iris_user_get` | Get a user or list all users | `name?`, `cursor?` | readOnly, idempotent |
|
|
157
|
+
| `iris_user_roles` | Add or remove a role from a user | `action`, `username`, `role` | destructive |
|
|
158
|
+
| `iris_user_password` | Change or validate a password | `action`, `username?`, `password`, `changePasswordOnNextLogin?` | destructive |
|
|
159
|
+
| `iris_permission_check` | Check user/role permissions on a resource | `target`, `resource`, `permission` | readOnly, idempotent |
|
|
160
|
+
|
|
161
|
+
### Role & Resource Tools
|
|
162
|
+
|
|
163
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
164
|
+
|------|-------------|----------------|-------------|
|
|
165
|
+
| `iris_role_manage` | Create, modify, or delete a security role | `action`, `name`, `description?`, `resources?`, `grantedRoles?` | destructive |
|
|
166
|
+
| `iris_role_list` | List all security roles | `cursor?` | readOnly, idempotent |
|
|
167
|
+
| `iris_resource_manage` | Create/modify/delete a security resource, **or grant/revoke/list SQL object privileges** | `action` (`create`, `modify`, `delete`, `grant`, `revoke`, `listPrivileges`), `name?`, `description?`, `publicPermission?`, `target?`, `privilege?`, `grantee?`, `namespace?`, `maxRows?`, `cursor?` (both `listPrivileges`-only) | destructive |
|
|
168
|
+
| `iris_resource_list` | List all security resources | `cursor?` | readOnly, idempotent |
|
|
169
|
+
|
|
170
|
+
### Web Application Tools
|
|
171
|
+
|
|
172
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
173
|
+
|------|-------------|----------------|-------------|
|
|
174
|
+
| `iris_webapp_manage` | Create, modify, or delete a web application | `action`, `name`, `namespace?`, `dispatchClass?`, `enabled?`, `authEnabled?` | destructive |
|
|
175
|
+
| `iris_webapp_get` | Get a web application by path | `name` | readOnly, idempotent |
|
|
176
|
+
| `iris_webapp_list` | List all web applications | `namespace?`, `cursor?` | readOnly, idempotent |
|
|
177
|
+
|
|
178
|
+
### SSL/TLS Tools
|
|
179
|
+
|
|
180
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
181
|
+
|------|-------------|----------------|-------------|
|
|
182
|
+
| `iris_ssl_manage` | Create, modify, or delete SSL/TLS config | `action`, `name`, `certFile?`, `keyFile?`, `caFile?`, `tlsMinVersion?`, `tlsMaxVersion?`, `verifyPeer?`, `type?` | destructive |
|
|
183
|
+
| `iris_ssl_list` | List all SSL/TLS configurations | `cursor?` | readOnly, idempotent |
|
|
184
|
+
|
|
185
|
+
### OAuth2 Tools
|
|
186
|
+
|
|
187
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
188
|
+
|------|-------------|----------------|-------------|
|
|
189
|
+
| `iris_oauth_manage` | Create/delete OAuth2 servers/clients, OIDC discovery | `action`, `entity?`, `issuerURL?`, `sslConfiguration?`, `name?`, `serverName?`, `clientName?`, `supportedScopes?`, `customizationNamespace?`, `customizationRoles?` | destructive |
|
|
190
|
+
| `iris_oauth_list` | List all OAuth2 server definitions and clients | `cursor?` | readOnly, idempotent |
|
|
191
|
+
|
|
192
|
+
**OAuth2 server creation notes:**
|
|
193
|
+
|
|
194
|
+
- `supportedScopes` — accepts a space- or comma-separated string (e.g., `"openid profile email"` or `"openid,profile,email"`). The tool splits the string into an array before sending to IRIS.
|
|
195
|
+
- `customizationNamespace` — IRIS namespace containing OAuth2 customization classes (required by IRIS; defaults to `""` when omitted).
|
|
196
|
+
- `customizationRoles` — roles granted to the customization code (required by IRIS; defaults to `""` when omitted).
|
|
197
|
+
|
|
198
|
+
**OAuth2 discovery and client registration notes:**
|
|
199
|
+
|
|
200
|
+
- `sslConfiguration` — name of an IRIS SSL/TLS client configuration used for the discovery connection. **Required for `https` issuer URLs** (IRIS rejects the connection with ERROR #6159 otherwise). Inspect existing configurations with `iris_ssl_list`; create one with `iris_ssl_manage` (`action: "create"`).
|
|
201
|
+
- `discover` **saves** an `OAuth2.ServerDefinition` keyed by the exact issuer URL — it is a write, not a read.
|
|
202
|
+
- Client registration (`create` + `entity: "client"`) requires a **prior successful discover** for the issuer: `serverName` is the exact issuer URL string that was discovered (the match is exact; there is no user-chosen server name). The client record inherits the server definition's SSL configuration. If the issuer publishes no dynamic registration endpoint (Google, for example), the local client record is still created and saved, and the response carries the clean "no registration endpoint" error — matching the Management Portal's configure-then-register semantics.
|
|
203
|
+
|
|
204
|
+
### SQL Privilege Tools
|
|
205
|
+
|
|
206
|
+
`iris_resource_manage` also manages **SQL object privileges** (schema/table/column GRANT/REVOKE) via three additional actions. Unlike the security-resource actions (which run in `%SYS`), these execute in the **target namespace** (the `namespace?` parameter, defaulting to the configured default).
|
|
207
|
+
|
|
208
|
+
| Action | Description | Key Parameters | Mutates |
|
|
209
|
+
|--------|-------------|----------------|---------|
|
|
210
|
+
| `grant` | Grant one or more SQL privileges on a schema/table/column to a user or role | `target` (schema, `schema.table`, or `schema.table(col1,col2)`), `privilege` (e.g. `SELECT`, `INSERT,UPDATE`, `%ALTER`), `grantee`, `namespace?` | write (default-disabled under governance) |
|
|
211
|
+
| `revoke` | Revoke SQL privileges from a user or role | `target`, `privilege`, `grantee`, `namespace?` | write (default-disabled under governance) |
|
|
212
|
+
| `listPrivileges` | List the current SQL grants held by a user or role | `grantee`, `target?` (omit for object-level listing; pass `schema.table` for a column-level listing; a bare schema or a `schema.` / `.table` fragment is rejected with a validation message), `namespace?`, `system?` (default `false`; `true` includes system tables), `maxRows?` (default 100, max 1000), `cursor?` | read (enabled by default) |
|
|
213
|
+
|
|
214
|
+
> **Governance:** `grant` and `revoke` are classified `write` (denied by default under an `IRIS_GOVERNANCE` policy until explicitly allowed); `listPrivileges` is a `read` (enabled by default). SQL privileges are namespace-scoped.
|
|
215
|
+
|
|
216
|
+
> **`listPrivileges` bounding (Story 35.4):** a grantee holding `%All` (e.g. `_SYSTEM`) is granted every SQL privilege on every object via a derived `SuperUser` cross-product — live-measured at 15,341 rows / 2,900,478 characters for `_SYSTEM`, which overruns the client transport limit. `listPrivileges` now omits those derived (`GRANTED_VIA=SuperUser`) rows automatically, adding a `reason` string and a `superUserPrivilegesOmitted` count to the response; any REAL non-derived grant is still listed, and the omitted count stays exact even when `maxRows` truncates the real rows. The omission is decided per **row**, from the `GRANTED_VIA` value the query itself reports — the handler never resolves the grantee's roles — so it holds however the grantee acquired `%All`, including through a deeply nested role chain. (An instance-wide sweep of all 46 users and roles found `SuperUser` rows emitted if and only if the principal effectively holds `%All`; powerful non-`%All` accounts such as `Admin` return 0 derived rows and are therefore untouched.)
|
|
217
|
+
>
|
|
218
|
+
> `maxRows` bounds the response further (default 100; values above 1000 are clamped) — it is an OUTPUT-only bound on the server's fetch loop, not a bound on the underlying privilege scan, and therefore **not** timeout protection; a capped response carries `rowsCapped: true`. **Pagination is opt-in:** pass `maxRows` or `cursor` and the response is paged **50 rows at a time** (the suite-wide default page size) within the `maxRows` ceiling; pass neither and every row the server returned comes back unpaged, exactly as before Story 35.4. Resend the same `maxRows` alongside each `cursor` — every page re-runs the server query and the cursor offset is positional. The cursor never crosses the `maxRows` ceiling and `maxRows` is itself capped at 1000, so a grantee with more than 1000 *real* grants cannot be fully enumerated through this action. All three new fields (`rowsCapped`, `reason`, `superUserPrivilegesOmitted`) are present ONLY when actually triggered, so a caller who passes no new parameters, fits under the cap, and does not hold `%All` sees the exact pre-35.4 response shape.
|
|
219
|
+
|
|
220
|
+
### Service Tools
|
|
221
|
+
|
|
222
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
223
|
+
|------|-------------|----------------|-------------|
|
|
224
|
+
| `iris_service_manage` | List/inspect/toggle IRIS services and their authentication settings (`Security.Services` in `%SYS`) | `action` (`list`, `get`, `enable`, `disable`, `set`), `name?`, `settings?`, `namespace?`, `cursor?` | destructive |
|
|
225
|
+
|
|
226
|
+
### LDAP Tools
|
|
227
|
+
|
|
228
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
229
|
+
|------|-------------|----------------|-------------|
|
|
230
|
+
| `iris_ldap_manage` | List/inspect/create/modify/delete/validity-test IRIS LDAP configurations for delegated authentication (`Security.LDAPConfigs` in `%SYS`) | `action` (`list`, `get`, `create`, `modify`, `delete`, `test`), `name?`, `settings?`, `cursor?` | destructive |
|
|
231
|
+
|
|
232
|
+
### X.509 Certificate Tools
|
|
233
|
+
|
|
234
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
235
|
+
|------|-------------|----------------|-------------|
|
|
236
|
+
| `iris_x509_manage` | List/inspect/import/delete IRIS X.509 certificate credentials (`%SYS.X509Credentials` in `%SYS`) | `action` (`list`, `get`, `import`, `delete`), `alias?`, `certificate?`, `privateKey?`, `privateKeyPassword?`, `namespace?`, `cursor?` | destructive |
|
|
237
|
+
|
|
238
|
+
### Auditing Tools
|
|
239
|
+
|
|
240
|
+
| Tool | Description | Key Parameters | Annotations |
|
|
241
|
+
|------|-------------|----------------|-------------|
|
|
242
|
+
| `iris_audit_manage` | Manage auditing configuration and the audit log: status, enable/disable, per-event configuration, view/export/purge the log (`%SYS.Audit*` in `%SYS`) | `action` (`status`, `enable`, `disable`, `configureEvent`, `view`, `purge`, `export`), `source?`, `type?`, `event?`, filter/confirm params | destructive |
|
|
243
|
+
|
|
244
|
+
> **Note:** `iris_audit_manage` configures auditing and manages the audit *log*. It is distinct from `@iris-mcp/ops`'s read-only `iris_audit_events`, which only queries audit events.
|
|
245
|
+
|
|
246
|
+
> **Governance defaults (service / LDAP / X.509 / audit):** the **write** actions of these tools are classified `write` and are **disabled by default** under an `IRIS_GOVERNANCE` policy until explicitly allowed — `iris_service_manage:enable`/`:disable`/`:set`, `iris_ldap_manage:create`/`:modify`/`:delete`, `iris_x509_manage:import`/`:delete`, and `iris_audit_manage:enable`/`:disable`/`:configureEvent`/`:purge`/`:export`. Their **read** actions are **enabled by default** — `:list`/`:get`/`:test`/`:status`/`:view`. (`iris_resource_manage:grant`/`:revoke` follow the same rule; see the SQL-privilege governance note above.)
|
|
247
|
+
|
|
248
|
+
> **Human confirmation (Story 43.3):** `iris_audit_manage` action `purge` (a write, default-disabled) also asks the person before it deletes audit-log records, when the MCP client declares form elicitation; any other client keeps today's `confirm: true` contract, and declining ends the call with `CONFIRMATION_DECLINED` and changes nothing. A Claude Code `Elicitation` hook can answer the dialog for the person, which is the user's choice and removes the person from the loop. See [Human confirmation (elicitation)](../../README.md#human-confirmation-elicitation).
|
|
249
|
+
|
|
250
|
+
---
|
|
251
|
+
|
|
252
|
+
## Prompts
|
|
253
|
+
|
|
254
|
+
Workflow-shaped [MCP prompts](../../README.md#workflow-prompts--agent-skills) (Epic 25) served via `prompts/list`/`prompts/get`. Prompts are a separate protocol capability from tools — they carry no governance key and do not change this server's tool count.
|
|
255
|
+
|
|
256
|
+
| Prompt | Description |
|
|
257
|
+
|---|---|
|
|
258
|
+
| `provision-project-environment` | Provisions a new project environment (two databases, a namespace, a user, a web application), verifying each step before the next, with rollback notes. |
|
|
259
|
+
| `audit-security-posture` | Audits users, roles, service authentication settings, SSL/TLS configs, and instance auditing status; reports default passwords, `%All` holders, and insecure services. |
|
|
260
|
+
|
|
261
|
+
Also installable as [Agent Skills](../../README.md#the-skills-pack).
|
|
262
|
+
|
|
263
|
+
---
|
|
264
|
+
|
|
265
|
+
## Tool Examples
|
|
266
|
+
|
|
267
|
+
<details>
|
|
268
|
+
<summary><strong>iris_namespace_manage</strong> -- Create a namespace</summary>
|
|
269
|
+
|
|
270
|
+
**Input:**
|
|
271
|
+
```json
|
|
272
|
+
{
|
|
273
|
+
"action": "create",
|
|
274
|
+
"name": "MYAPP",
|
|
275
|
+
"codeDatabase": "MYAPP-CODE",
|
|
276
|
+
"dataDatabase": "MYAPP-DATA"
|
|
277
|
+
}
|
|
278
|
+
```
|
|
279
|
+
|
|
280
|
+
**Output:**
|
|
281
|
+
```json
|
|
282
|
+
{
|
|
283
|
+
"action": "create",
|
|
284
|
+
"name": "MYAPP",
|
|
285
|
+
"status": "created"
|
|
286
|
+
}
|
|
287
|
+
```
|
|
288
|
+
</details>
|
|
289
|
+
|
|
290
|
+
<details>
|
|
291
|
+
<summary><strong>iris_namespace_list</strong> -- List namespaces</summary>
|
|
292
|
+
|
|
293
|
+
**Input:**
|
|
294
|
+
```json
|
|
295
|
+
{}
|
|
296
|
+
```
|
|
297
|
+
|
|
298
|
+
**Output:**
|
|
299
|
+
```json
|
|
300
|
+
{
|
|
301
|
+
"namespaces": [
|
|
302
|
+
{ "name": "USER", "globals": "USER", "routines": "USER", "library": "IRISLIB", "tempGlobals": "IRISTEMP" },
|
|
303
|
+
{ "name": "%SYS", "globals": "IRISSYS", "routines": "IRISSYS", "library": "IRISLIB", "tempGlobals": "IRISTEMP" }
|
|
304
|
+
],
|
|
305
|
+
"count": 2
|
|
306
|
+
}
|
|
307
|
+
```
|
|
308
|
+
</details>
|
|
309
|
+
|
|
310
|
+
<details>
|
|
311
|
+
<summary><strong>iris_database_manage</strong> -- Create, modify, or delete a database</summary>
|
|
312
|
+
|
|
313
|
+
**Input (create):**
|
|
314
|
+
```json
|
|
315
|
+
{
|
|
316
|
+
"action": "create",
|
|
317
|
+
"name": "MYAPP-DATA",
|
|
318
|
+
"directory": "C:\\InterSystems\\IRIS\\mgr\\myapp-data",
|
|
319
|
+
"size": 100,
|
|
320
|
+
"maxSize": 1000,
|
|
321
|
+
"expansionSize": 50
|
|
322
|
+
}
|
|
323
|
+
```
|
|
324
|
+
|
|
325
|
+
**Input (modify):**
|
|
326
|
+
```json
|
|
327
|
+
{
|
|
328
|
+
"action": "modify",
|
|
329
|
+
"name": "MYAPP-DATA",
|
|
330
|
+
"maxSize": 2000,
|
|
331
|
+
"expansionSize": 100
|
|
332
|
+
}
|
|
333
|
+
```
|
|
334
|
+
|
|
335
|
+
**Output:**
|
|
336
|
+
```json
|
|
337
|
+
{
|
|
338
|
+
"action": "created",
|
|
339
|
+
"name": "MYAPP-DATA"
|
|
340
|
+
}
|
|
341
|
+
```
|
|
342
|
+
|
|
343
|
+
**Config/SYS routing:** Database properties split across two IRIS classes.
|
|
344
|
+
- **Configuration props** (route to `Config.Databases`): `directory`, `resource`, `mountRequired`, `mountAtStartup`, `readOnly`, `globalJournalState`.
|
|
345
|
+
- **Runtime props** (route to `SYS.Database`): `size`, `maxSize`, `expansionSize`. These control the physical database file and are not accessible via `Config.Databases`. `create` uses `SYS.Database.CreateDatabase()` to create the physical file, then `Config.Databases.Create()` for CPF registration. `modify` routes runtime props through `SYS.Database.%OpenId(directory).%Save()`.
|
|
346
|
+
|
|
347
|
+
**Delete caveat:** `action:"delete"` removes the database from the IRIS configuration (CPF) but does NOT cancel pending background work (e.g., extent-index rebuilds) that may have been scheduled against the deleted directory. The IRIS console may log alerts for such operations post-delete; these are informational and do not indicate tool failure.
|
|
348
|
+
</details>
|
|
349
|
+
|
|
350
|
+
<details>
|
|
351
|
+
<summary><strong>iris_database_list</strong> -- List databases</summary>
|
|
352
|
+
|
|
353
|
+
**Input:**
|
|
354
|
+
```json
|
|
355
|
+
{}
|
|
356
|
+
```
|
|
357
|
+
|
|
358
|
+
**Output:**
|
|
359
|
+
```json
|
|
360
|
+
{
|
|
361
|
+
"databases": [
|
|
362
|
+
{ "name": "USER", "directory": "C:\\InterSystems\\IRIS\\mgr\\user", "size": 11, "maxSize": 0, "expansionSize": 0, "mountAtStartup": true }
|
|
363
|
+
],
|
|
364
|
+
"count": 1
|
|
365
|
+
}
|
|
366
|
+
```
|
|
367
|
+
|
|
368
|
+
The `size`, `maxSize`, and `expansionSize` fields (all in MB) are populated
|
|
369
|
+
from `SYS.Database` (runtime state) rather than `Config.Databases` (static
|
|
370
|
+
configuration), since the latter does not carry those properties. Unmounted
|
|
371
|
+
or inaccessible databases fall back to `0` without raising an error.
|
|
372
|
+
</details>
|
|
373
|
+
|
|
374
|
+
<details>
|
|
375
|
+
<summary><strong>iris_mapping_manage</strong> -- Create a global mapping</summary>
|
|
376
|
+
|
|
377
|
+
**Input:**
|
|
378
|
+
```json
|
|
379
|
+
{
|
|
380
|
+
"action": "create",
|
|
381
|
+
"type": "global",
|
|
382
|
+
"namespace": "USER",
|
|
383
|
+
"name": "MyGlobal",
|
|
384
|
+
"database": "MYAPP-DATA"
|
|
385
|
+
}
|
|
386
|
+
```
|
|
387
|
+
|
|
388
|
+
**Output:**
|
|
389
|
+
```json
|
|
390
|
+
{
|
|
391
|
+
"action": "created",
|
|
392
|
+
"type": "global",
|
|
393
|
+
"namespace": "USER",
|
|
394
|
+
"name": "MyGlobal"
|
|
395
|
+
}
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
**Subscript-level (SLM) mappings.** Supply `subscript` to map a single
|
|
399
|
+
subscript node or range, leaving the base global mapping untouched. The
|
|
400
|
+
subscript is appended to `name` to form the mapped global, and the returned
|
|
401
|
+
`name` echoes that full node:
|
|
402
|
+
|
|
403
|
+
```json
|
|
404
|
+
{
|
|
405
|
+
"action": "create", "type": "global", "namespace": "FHIRBRIDGE",
|
|
406
|
+
"name": "%SYS", "subscript": "(\"HealthShare\")", "database": "HSSYS"
|
|
407
|
+
}
|
|
408
|
+
```
|
|
409
|
+
→ creates `%SYS("HealthShare") -> HSSYS` and returns `"name": "%SYS(\"HealthShare\")"`;
|
|
410
|
+
the base `%SYS` mapping keeps its default. `subscript` accepts a single node
|
|
411
|
+
(`("HealthShare")`) or a range (`(1):(100)`) and is validated server-side.
|
|
412
|
+
Delete a subscript node the same way — pass the same `subscript` so only that
|
|
413
|
+
node is removed.
|
|
414
|
+
|
|
415
|
+
> **⚠️ `%`-prefixed system globals.** Creating a **base** mapping (no
|
|
416
|
+
> `subscript`) for a `%`-prefixed global such as `%SYS` is **refused** unless
|
|
417
|
+
> `force: true` is passed, because remapping a base `%`-global silently shadows
|
|
418
|
+
> its system default and can corrupt system-config access. To map a node under
|
|
419
|
+
> a system global, pass a `subscript` (no `force` needed). Pass `force: true`
|
|
420
|
+
> only to deliberately remap the base global itself.
|
|
421
|
+
</details>
|
|
422
|
+
|
|
423
|
+
<details>
|
|
424
|
+
<summary><strong>iris_mapping_list</strong> -- List mappings</summary>
|
|
425
|
+
|
|
426
|
+
**Input:**
|
|
427
|
+
```json
|
|
428
|
+
{
|
|
429
|
+
"namespace": "USER",
|
|
430
|
+
"type": "global"
|
|
431
|
+
}
|
|
432
|
+
```
|
|
433
|
+
|
|
434
|
+
**Output:**
|
|
435
|
+
```json
|
|
436
|
+
{
|
|
437
|
+
"mappings": [
|
|
438
|
+
{ "name": "MyGlobal", "type": "global", "namespace": "USER", "database": "MYAPP-DATA" }
|
|
439
|
+
],
|
|
440
|
+
"count": 1
|
|
441
|
+
}
|
|
442
|
+
```
|
|
443
|
+
</details>
|
|
444
|
+
|
|
445
|
+
<details>
|
|
446
|
+
<summary><strong>iris_user_manage</strong> -- Create a user</summary>
|
|
447
|
+
|
|
448
|
+
**Input:**
|
|
449
|
+
```json
|
|
450
|
+
{
|
|
451
|
+
"action": "create",
|
|
452
|
+
"name": "AppUser",
|
|
453
|
+
"password": "SecureP@ss123",
|
|
454
|
+
"fullName": "Application User",
|
|
455
|
+
"roles": "%Developer"
|
|
456
|
+
}
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
**Output:**
|
|
460
|
+
```json
|
|
461
|
+
{
|
|
462
|
+
"action": "create",
|
|
463
|
+
"name": "AppUser",
|
|
464
|
+
"status": "created"
|
|
465
|
+
}
|
|
466
|
+
```
|
|
467
|
+
</details>
|
|
468
|
+
|
|
469
|
+
<details>
|
|
470
|
+
<summary><strong>iris_user_get</strong> -- Get user details</summary>
|
|
471
|
+
|
|
472
|
+
**Input (single user):**
|
|
473
|
+
```json
|
|
474
|
+
{
|
|
475
|
+
"name": "_SYSTEM"
|
|
476
|
+
}
|
|
477
|
+
```
|
|
478
|
+
|
|
479
|
+
**Output (single user):**
|
|
480
|
+
```json
|
|
481
|
+
{
|
|
482
|
+
"name": "_SYSTEM",
|
|
483
|
+
"fullName": "SQL System Manager",
|
|
484
|
+
"enabled": true,
|
|
485
|
+
"namespace": "",
|
|
486
|
+
"roles": "%All",
|
|
487
|
+
"comment": "",
|
|
488
|
+
"expirationDate": "",
|
|
489
|
+
"changePasswordOnNextLogin": false
|
|
490
|
+
}
|
|
491
|
+
```
|
|
492
|
+
|
|
493
|
+
> **Note:** Single-user lookups echo the `name` argument back in the
|
|
494
|
+
> response (`Security.Users.Get` in IRIS uses `name` as a lookup key
|
|
495
|
+
> and does not populate it in the returned property array).
|
|
496
|
+
|
|
497
|
+
**Input (list mode):** omit `name`:
|
|
498
|
+
```json
|
|
499
|
+
{}
|
|
500
|
+
```
|
|
501
|
+
|
|
502
|
+
**Output (list mode):**
|
|
503
|
+
```json
|
|
504
|
+
{
|
|
505
|
+
"users": [
|
|
506
|
+
{
|
|
507
|
+
"name": "Admin",
|
|
508
|
+
"enabled": true,
|
|
509
|
+
"fullName": "Administrator",
|
|
510
|
+
"namespace": "",
|
|
511
|
+
"roles": "%Developer,%Manager",
|
|
512
|
+
"comment": "Built-in admin",
|
|
513
|
+
"expirationDate": "",
|
|
514
|
+
"changePasswordOnNextLogin": false
|
|
515
|
+
}
|
|
516
|
+
],
|
|
517
|
+
"count": 1
|
|
518
|
+
}
|
|
519
|
+
```
|
|
520
|
+
|
|
521
|
+
> **Note:** The IRIS `Security.Users:List` ROWSPEC only exposes
|
|
522
|
+
> `Name, Enabled, Roles, LastLoginTime, Flags`. List mode backfills
|
|
523
|
+
> `fullName`, `namespace`, `comment`, `expirationDate`, and
|
|
524
|
+
> `changePasswordOnNextLogin` via per-row `Security.Users.Get()` so
|
|
525
|
+
> responses carry the full set the schema advertises.
|
|
526
|
+
</details>
|
|
527
|
+
|
|
528
|
+
<details>
|
|
529
|
+
<summary><strong>iris_user_roles</strong> -- Add role to user</summary>
|
|
530
|
+
|
|
531
|
+
**Input:**
|
|
532
|
+
```json
|
|
533
|
+
{
|
|
534
|
+
"action": "add",
|
|
535
|
+
"username": "AppUser",
|
|
536
|
+
"role": "%Operator"
|
|
537
|
+
}
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
**Output:**
|
|
541
|
+
```json
|
|
542
|
+
{
|
|
543
|
+
"username": "AppUser",
|
|
544
|
+
"roles": "%Developer,%Operator"
|
|
545
|
+
}
|
|
546
|
+
```
|
|
547
|
+
</details>
|
|
548
|
+
|
|
549
|
+
<details>
|
|
550
|
+
<summary><strong>iris_user_password</strong> -- Change or validate password</summary>
|
|
551
|
+
|
|
552
|
+
**Change password (basic):**
|
|
553
|
+
```json
|
|
554
|
+
{
|
|
555
|
+
"action": "change",
|
|
556
|
+
"username": "AppUser",
|
|
557
|
+
"password": "NewSecureP@ss456"
|
|
558
|
+
}
|
|
559
|
+
```
|
|
560
|
+
|
|
561
|
+
**Change password with force-change-on-next-login flag:**
|
|
562
|
+
```json
|
|
563
|
+
{
|
|
564
|
+
"action": "change",
|
|
565
|
+
"username": "AppUser",
|
|
566
|
+
"password": "NewSecureP@ss456",
|
|
567
|
+
"changePasswordOnNextLogin": true
|
|
568
|
+
}
|
|
569
|
+
```
|
|
570
|
+
|
|
571
|
+
The optional `changePasswordOnNextLogin` boolean (default: leave existing flag unchanged) sets the `Security.Users.ChangePassword` flag in the same `Security.Users.Modify()` call as the password change. When `true`, IRIS will require the user to set a new password on their next login.
|
|
572
|
+
|
|
573
|
+
**Change password output:**
|
|
574
|
+
```json
|
|
575
|
+
{
|
|
576
|
+
"action": "changed",
|
|
577
|
+
"username": "AppUser",
|
|
578
|
+
"success": true
|
|
579
|
+
}
|
|
580
|
+
```
|
|
581
|
+
|
|
582
|
+
**Validate password:**
|
|
583
|
+
```json
|
|
584
|
+
{
|
|
585
|
+
"action": "validate",
|
|
586
|
+
"password": "candidate123"
|
|
587
|
+
}
|
|
588
|
+
```
|
|
589
|
+
|
|
590
|
+
**Validate output (includes active password policy):**
|
|
591
|
+
```json
|
|
592
|
+
{
|
|
593
|
+
"action": "validate",
|
|
594
|
+
"valid": false,
|
|
595
|
+
"message": "Password does not match length or pattern requirements",
|
|
596
|
+
"policy": {
|
|
597
|
+
"minLength": 3,
|
|
598
|
+
"pattern": "3.128ANP"
|
|
599
|
+
}
|
|
600
|
+
}
|
|
601
|
+
```
|
|
602
|
+
|
|
603
|
+
The `policy` block reflects the active IRIS system password policy (`Security.System.PasswordPattern`). `minLength` is extracted from the leading quantifier of the pattern string. When no policy is configured, `pattern` is `null` and a `comment` field explains the absence.
|
|
604
|
+
|
|
605
|
+
> **Note:** When `Security.Users.Modify()` fails (policy violation,
|
|
606
|
+
> missing user, permission error, etc.), the underlying IRIS error
|
|
607
|
+
> text is propagated via the `Details:` suffix of the tool's error
|
|
608
|
+
> response. Examples: `User NonExistent does not exist`,
|
|
609
|
+
> `Password does not meet complexity requirements`. The password
|
|
610
|
+
> value itself is never embedded in IRIS error text for this path.
|
|
611
|
+
</details>
|
|
612
|
+
|
|
613
|
+
<details>
|
|
614
|
+
<summary><strong>iris_permission_check</strong> -- Check permission</summary>
|
|
615
|
+
|
|
616
|
+
**Input:**
|
|
617
|
+
```json
|
|
618
|
+
{
|
|
619
|
+
"target": "_SYSTEM",
|
|
620
|
+
"resource": "%DB_USER",
|
|
621
|
+
"permission": "RW"
|
|
622
|
+
}
|
|
623
|
+
```
|
|
624
|
+
|
|
625
|
+
**Output (target holds %All super-role — short-circuit path):**
|
|
626
|
+
```json
|
|
627
|
+
{
|
|
628
|
+
"target": "_SYSTEM",
|
|
629
|
+
"targetType": "user",
|
|
630
|
+
"resource": "%DB_USER",
|
|
631
|
+
"permission": "RW",
|
|
632
|
+
"granted": true,
|
|
633
|
+
"grantedPermission": "RWU",
|
|
634
|
+
"reason": "target holds %All super-role"
|
|
635
|
+
}
|
|
636
|
+
```
|
|
637
|
+
|
|
638
|
+
**Output (regular path — explicit resource:permission pair match):**
|
|
639
|
+
```json
|
|
640
|
+
{
|
|
641
|
+
"target": "Admin",
|
|
642
|
+
"targetType": "user",
|
|
643
|
+
"resource": "%DB_USER",
|
|
644
|
+
"permission": "RW",
|
|
645
|
+
"granted": true,
|
|
646
|
+
"grantedPermission": "RW"
|
|
647
|
+
}
|
|
648
|
+
```
|
|
649
|
+
|
|
650
|
+
> **Note:** The `%All` role is special-cased by the IRIS security
|
|
651
|
+
> subsystem — `Security.Roles.Get("%All", .tProps)` returns empty
|
|
652
|
+
> `Resources` even though the role grants everything. The handler
|
|
653
|
+
> short-circuits to `granted: true` with `grantedPermission: "RWU"`
|
|
654
|
+
> and emits an extra `reason` field when the target IS the `%All`
|
|
655
|
+
> role OR when a user target's role list contains `%All`. The
|
|
656
|
+
> `reason` field is omitted on the regular path.
|
|
657
|
+
</details>
|
|
658
|
+
|
|
659
|
+
<details>
|
|
660
|
+
<summary><strong>iris_role_manage</strong> -- Create a role</summary>
|
|
661
|
+
|
|
662
|
+
**Input:**
|
|
663
|
+
```json
|
|
664
|
+
{
|
|
665
|
+
"action": "create",
|
|
666
|
+
"name": "MyAppRole",
|
|
667
|
+
"description": "Custom role for MyApp",
|
|
668
|
+
"resources": "%DB_USER:RW,%Development:U"
|
|
669
|
+
}
|
|
670
|
+
```
|
|
671
|
+
|
|
672
|
+
**Output:**
|
|
673
|
+
```json
|
|
674
|
+
{
|
|
675
|
+
"action": "create",
|
|
676
|
+
"name": "MyAppRole",
|
|
677
|
+
"status": "created"
|
|
678
|
+
}
|
|
679
|
+
```
|
|
680
|
+
</details>
|
|
681
|
+
|
|
682
|
+
<details>
|
|
683
|
+
<summary><strong>iris_role_list</strong> -- List roles</summary>
|
|
684
|
+
|
|
685
|
+
**Input:**
|
|
686
|
+
```json
|
|
687
|
+
{}
|
|
688
|
+
```
|
|
689
|
+
|
|
690
|
+
**Output:**
|
|
691
|
+
```json
|
|
692
|
+
{
|
|
693
|
+
"roles": [
|
|
694
|
+
{ "name": "%All", "description": "The Super-User Role", "resources": "", "grantedRoles": "" },
|
|
695
|
+
{ "name": "%Developer", "description": "A Role owned by all Developers", "resources": "%DB_USER:RW,%Development:U,%Service_SQL:U", "grantedRoles": "" },
|
|
696
|
+
{ "name": "%EnsRole_Administrator", "description": "Interoperability Administrator", "resources": "%Ens_Code:R,%Ens_Jobs:W,%Ens_ProductionConfig:W", "grantedRoles": "%DB_ENSLIB,%EnsRole_Operator" }
|
|
697
|
+
],
|
|
698
|
+
"count": 3
|
|
699
|
+
}
|
|
700
|
+
```
|
|
701
|
+
|
|
702
|
+
> **Note:** `resources` is a comma-separated list of
|
|
703
|
+
> `resource:permission` pairs (e.g., `%DB_USER:RW,%Ens_Code:R`).
|
|
704
|
+
> The `%All` super-role always returns `resources: ""` because
|
|
705
|
+
> IRIS special-cases it — its grant coverage is not stored as
|
|
706
|
+
> explicit pairs. Use `iris_permission_check` to test effective
|
|
707
|
+
> permissions for a `%All`-holder.
|
|
708
|
+
</details>
|
|
709
|
+
|
|
710
|
+
<details>
|
|
711
|
+
<summary><strong>iris_resource_manage</strong> -- Create a resource</summary>
|
|
712
|
+
|
|
713
|
+
**Input:**
|
|
714
|
+
```json
|
|
715
|
+
{
|
|
716
|
+
"action": "create",
|
|
717
|
+
"name": "MyAppResource",
|
|
718
|
+
"description": "Access control for MyApp",
|
|
719
|
+
"publicPermission": ""
|
|
720
|
+
}
|
|
721
|
+
```
|
|
722
|
+
|
|
723
|
+
**Output:**
|
|
724
|
+
```json
|
|
725
|
+
{
|
|
726
|
+
"action": "create",
|
|
727
|
+
"name": "MyAppResource",
|
|
728
|
+
"status": "created"
|
|
729
|
+
}
|
|
730
|
+
```
|
|
731
|
+
</details>
|
|
732
|
+
|
|
733
|
+
<details>
|
|
734
|
+
<summary><strong>iris_resource_list</strong> -- List resources</summary>
|
|
735
|
+
|
|
736
|
+
**Input:**
|
|
737
|
+
```json
|
|
738
|
+
{}
|
|
739
|
+
```
|
|
740
|
+
|
|
741
|
+
**Output:**
|
|
742
|
+
```json
|
|
743
|
+
{
|
|
744
|
+
"resources": [
|
|
745
|
+
{ "name": "%DB_USER", "description": "USER database resource", "publicPermission": "RW", "type": "database" }
|
|
746
|
+
],
|
|
747
|
+
"count": 1
|
|
748
|
+
}
|
|
749
|
+
```
|
|
750
|
+
</details>
|
|
751
|
+
|
|
752
|
+
<details>
|
|
753
|
+
<summary><strong>iris_webapp_manage</strong> -- Create a web application</summary>
|
|
754
|
+
|
|
755
|
+
**Input:**
|
|
756
|
+
```json
|
|
757
|
+
{
|
|
758
|
+
"action": "create",
|
|
759
|
+
"name": "/api/myapp",
|
|
760
|
+
"namespace": "USER",
|
|
761
|
+
"dispatchClass": "MyApp.REST.Dispatch",
|
|
762
|
+
"enabled": true
|
|
763
|
+
}
|
|
764
|
+
```
|
|
765
|
+
|
|
766
|
+
**Output:**
|
|
767
|
+
```json
|
|
768
|
+
{
|
|
769
|
+
"action": "create",
|
|
770
|
+
"name": "/api/myapp",
|
|
771
|
+
"status": "created"
|
|
772
|
+
}
|
|
773
|
+
```
|
|
774
|
+
</details>
|
|
775
|
+
|
|
776
|
+
<details>
|
|
777
|
+
<summary><strong>iris_webapp_get</strong> -- Get web application</summary>
|
|
778
|
+
|
|
779
|
+
**Input:**
|
|
780
|
+
```json
|
|
781
|
+
{
|
|
782
|
+
"name": "/csp/user"
|
|
783
|
+
}
|
|
784
|
+
```
|
|
785
|
+
|
|
786
|
+
**Output:**
|
|
787
|
+
```json
|
|
788
|
+
{
|
|
789
|
+
"name": "/csp/user",
|
|
790
|
+
"namespace": "USER",
|
|
791
|
+
"enabled": 1,
|
|
792
|
+
"dispatchClass": "",
|
|
793
|
+
"authEnabled": 32
|
|
794
|
+
}
|
|
795
|
+
```
|
|
796
|
+
</details>
|
|
797
|
+
|
|
798
|
+
<details>
|
|
799
|
+
<summary><strong>iris_webapp_list</strong> -- List web applications</summary>
|
|
800
|
+
|
|
801
|
+
**Input:**
|
|
802
|
+
```json
|
|
803
|
+
{
|
|
804
|
+
"namespace": "USER"
|
|
805
|
+
}
|
|
806
|
+
```
|
|
807
|
+
|
|
808
|
+
**Output:**
|
|
809
|
+
```json
|
|
810
|
+
{
|
|
811
|
+
"webapps": [
|
|
812
|
+
{ "name": "/csp/user", "namespace": "USER", "enabled": 1 },
|
|
813
|
+
{ "name": "/api/executemcp/v2", "namespace": "USER", "enabled": 1 }
|
|
814
|
+
],
|
|
815
|
+
"count": 2
|
|
816
|
+
}
|
|
817
|
+
```
|
|
818
|
+
</details>
|
|
819
|
+
|
|
820
|
+
<details>
|
|
821
|
+
<summary><strong>iris_ssl_manage</strong> -- Create SSL config</summary>
|
|
822
|
+
|
|
823
|
+
> **⚠️ Breaking (pre-release):** the `protocols` bitmask was removed
|
|
824
|
+
> in favor of separate `tlsMinVersion` and `tlsMaxVersion` integer
|
|
825
|
+
> fields, which reflect the real IRIS properties
|
|
826
|
+
> (`Security.SSLConfigs.TLSMinVersion` / `TLSMaxVersion`). The
|
|
827
|
+
> deprecated `Protocols` property it replaced was never actually
|
|
828
|
+
> wired up through the handler, so removing it is a clean break
|
|
829
|
+
> with no data-loss risk. Clients that wrote `protocols: 24` now
|
|
830
|
+
> write `tlsMinVersion: 8, tlsMaxVersion: 16` (or
|
|
831
|
+
> `tlsMinVersion: 16, tlsMaxVersion: 32` for TLS 1.2 through TLS 1.3
|
|
832
|
+
> explicitly). See Story 11.2 in `_bmad-output`. The TypeScript Zod
|
|
833
|
+
> schema now uses these same field names (`tlsMinVersion` /
|
|
834
|
+
> `tlsMaxVersion`) per Story 11.4 — writes are validated client-side
|
|
835
|
+
> and passed through verbatim on the wire.
|
|
836
|
+
>
|
|
837
|
+
> **TLS version value mapping** (IRIS
|
|
838
|
+
> `Security.Datatype.TLSVersion` VALUELIST):
|
|
839
|
+
> `2 = SSLv3`, `4 = TLS 1.0`, `8 = TLS 1.1`, `16 = TLS 1.2`,
|
|
840
|
+
> `32 = TLS 1.3`.
|
|
841
|
+
|
|
842
|
+
**Input:**
|
|
843
|
+
```json
|
|
844
|
+
{
|
|
845
|
+
"action": "create",
|
|
846
|
+
"name": "MyTLS",
|
|
847
|
+
"tlsMinVersion": 16,
|
|
848
|
+
"tlsMaxVersion": 32,
|
|
849
|
+
"type": 0,
|
|
850
|
+
"verifyPeer": 1
|
|
851
|
+
}
|
|
852
|
+
```
|
|
853
|
+
|
|
854
|
+
**Output:**
|
|
855
|
+
```json
|
|
856
|
+
{
|
|
857
|
+
"action": "created",
|
|
858
|
+
"name": "MyTLS"
|
|
859
|
+
}
|
|
860
|
+
```
|
|
861
|
+
</details>
|
|
862
|
+
|
|
863
|
+
<details>
|
|
864
|
+
<summary><strong>iris_ssl_list</strong> -- List SSL configurations</summary>
|
|
865
|
+
|
|
866
|
+
**Input:**
|
|
867
|
+
```json
|
|
868
|
+
{}
|
|
869
|
+
```
|
|
870
|
+
|
|
871
|
+
**Output:**
|
|
872
|
+
```json
|
|
873
|
+
{
|
|
874
|
+
"sslConfigs": [
|
|
875
|
+
{
|
|
876
|
+
"name": "BFC_SSL",
|
|
877
|
+
"description": "",
|
|
878
|
+
"certFile": "",
|
|
879
|
+
"keyFile": "",
|
|
880
|
+
"caFile": "",
|
|
881
|
+
"caPath": "",
|
|
882
|
+
"cipherList": "ALL:!aNULL:!eNULL:!EXP:!SSLv2",
|
|
883
|
+
"tlsMinVersion": 16,
|
|
884
|
+
"tlsMaxVersion": 32,
|
|
885
|
+
"verifyPeer": 0,
|
|
886
|
+
"verifyDepth": 9,
|
|
887
|
+
"type": 0,
|
|
888
|
+
"enabled": true
|
|
889
|
+
}
|
|
890
|
+
],
|
|
891
|
+
"count": 1
|
|
892
|
+
}
|
|
893
|
+
```
|
|
894
|
+
|
|
895
|
+
> **⚠️ Breaking (pre-release):** `protocols` was replaced by
|
|
896
|
+
> `tlsMinVersion` + `tlsMaxVersion` — see the `iris_ssl_manage`
|
|
897
|
+
> note above for the TLS version value mapping.
|
|
898
|
+
</details>
|
|
899
|
+
|
|
900
|
+
<details>
|
|
901
|
+
<summary><strong>iris_oauth_manage</strong> -- Create an OAuth2 server definition</summary>
|
|
902
|
+
|
|
903
|
+
**Input:**
|
|
904
|
+
```json
|
|
905
|
+
{
|
|
906
|
+
"action": "create",
|
|
907
|
+
"entity": "server",
|
|
908
|
+
"issuerURL": "https://auth.example.com/oauth2",
|
|
909
|
+
"supportedScopes": "openid profile email",
|
|
910
|
+
"customizationRoles": "%DB_IRISSYS"
|
|
911
|
+
}
|
|
912
|
+
```
|
|
913
|
+
|
|
914
|
+
`supportedScopes` and `customizationRoles` are **required** by IRIS for a server definition; `customizationNamespace` defaults to the request namespace when omitted. The issuer URL is parsed into the server's endpoint (host/port/prefix/SSL).
|
|
915
|
+
|
|
916
|
+
**Output:**
|
|
917
|
+
```json
|
|
918
|
+
{
|
|
919
|
+
"action": "created",
|
|
920
|
+
"entity": "server",
|
|
921
|
+
"issuerEndpoint": "https://auth.example.com/oauth2"
|
|
922
|
+
}
|
|
923
|
+
```
|
|
924
|
+
</details>
|
|
925
|
+
|
|
926
|
+
<details>
|
|
927
|
+
<summary><strong>iris_oauth_manage</strong> -- OIDC discovery</summary>
|
|
928
|
+
|
|
929
|
+
**Input:**
|
|
930
|
+
```json
|
|
931
|
+
{
|
|
932
|
+
"action": "discover",
|
|
933
|
+
"issuerURL": "https://accounts.google.com",
|
|
934
|
+
"sslConfiguration": "ISC.FeatureTracker.SSL.Config"
|
|
935
|
+
}
|
|
936
|
+
```
|
|
937
|
+
|
|
938
|
+
**Output** (captured live against IRIS 2026.1):
|
|
939
|
+
```json
|
|
940
|
+
{
|
|
941
|
+
"action": "discovered",
|
|
942
|
+
"issuerURL": "https://accounts.google.com",
|
|
943
|
+
"configuration": {
|
|
944
|
+
"issuerEndpoint": "https://accounts.google.com",
|
|
945
|
+
"authorizationEndpoint": "https://accounts.google.com/o/oauth2/v2/auth",
|
|
946
|
+
"tokenEndpoint": "https://oauth2.googleapis.com/token",
|
|
947
|
+
"userinfoEndpoint": "https://openidconnect.googleapis.com/v1/userinfo",
|
|
948
|
+
"revocationEndpoint": "https://oauth2.googleapis.com/revoke",
|
|
949
|
+
"jwksEndpoint": "https://www.googleapis.com/oauth2/v3/certs"
|
|
950
|
+
}
|
|
951
|
+
}
|
|
952
|
+
```
|
|
953
|
+
|
|
954
|
+
> Discovery requires an outbound TLS connection to the issuer, which needs a configured SSL/TLS client configuration on the IRIS instance — pass its name as `sslConfiguration` for `https` issuers (inspect with `iris_ssl_list`, create with `iris_ssl_manage`). Omitting it on an `https` issuer returns a validation error naming this prerequisite. A successful discover **saves** a server definition keyed by the exact issuer URL; that URL is the `serverName` a later client registration references.
|
|
955
|
+
</details>
|
|
956
|
+
|
|
957
|
+
<details>
|
|
958
|
+
<summary><strong>iris_oauth_list</strong> -- List OAuth2 configurations</summary>
|
|
959
|
+
|
|
960
|
+
**Input:**
|
|
961
|
+
```json
|
|
962
|
+
{}
|
|
963
|
+
```
|
|
964
|
+
|
|
965
|
+
**Output:** (a configured server; empty arrays when none exist)
|
|
966
|
+
```json
|
|
967
|
+
{
|
|
968
|
+
"servers": [
|
|
969
|
+
{
|
|
970
|
+
"id": "singleton",
|
|
971
|
+
"issuerEndpoint": "https://auth.example.com/oauth2",
|
|
972
|
+
"description": "Example authorization server",
|
|
973
|
+
"supportedScopes": ["email", "openid", "profile"],
|
|
974
|
+
"accessTokenInterval": 3600,
|
|
975
|
+
"authorizationCodeInterval": 60,
|
|
976
|
+
"refreshTokenInterval": 86400,
|
|
977
|
+
"signingAlgorithm": "RS256"
|
|
978
|
+
}
|
|
979
|
+
],
|
|
980
|
+
"clients": [],
|
|
981
|
+
"serverCount": 1,
|
|
982
|
+
"clientCount": 0
|
|
983
|
+
}
|
|
984
|
+
```
|
|
985
|
+
</details>
|
|
986
|
+
|
|
987
|
+
---
|
|
988
|
+
|
|
989
|
+
## Namespace Scoping
|
|
990
|
+
|
|
991
|
+
**Security note:** Most admin tools operate in the `%SYS` namespace on the IRIS server, regardless of the configured default namespace. This is because IRIS security and configuration classes (`Config.*`, `Security.*`) only exist in `%SYS`.
|
|
992
|
+
|
|
993
|
+
The following tools **do not** accept a user-specified `namespace` parameter (they always execute in `%SYS`):
|
|
994
|
+
- All namespace, database, mapping, user, role, resource (security-resource actions), permission, SSL, OAuth, service, LDAP, X.509, and audit tools
|
|
995
|
+
|
|
996
|
+
**Exception — SQL privileges:** `iris_resource_manage`'s `grant` / `revoke` / `listPrivileges` actions execute in the **target namespace** (the optional `namespace?` parameter, defaulting to the configured default), because SQL object privileges are namespace-scoped.
|
|
997
|
+
|
|
998
|
+
The `iris_webapp_list` tool optionally accepts a `namespace` parameter to filter web applications by namespace.
|
|
999
|
+
|
|
1000
|
+
The `iris_webapp_manage` tool accepts a `namespace` parameter to set the target namespace for the web application being created/modified.
|
|
1001
|
+
|
|
1002
|
+
---
|
|
1003
|
+
|
|
1004
|
+
## Error Handling
|
|
1005
|
+
|
|
1006
|
+
### Common Errors
|
|
1007
|
+
|
|
1008
|
+
| Error | Cause | Resolution |
|
|
1009
|
+
|-------|-------|------------|
|
|
1010
|
+
| `IRIS connection refused` | IRIS web server not running or wrong host/port | Verify `IRIS_HOST` and `IRIS_PORT` settings |
|
|
1011
|
+
| `401 Unauthorized` | Invalid credentials or insufficient privileges | Check credentials; admin operations require `%Admin_Manage`, `%Admin_Security`, or `%Admin_Operate` resources |
|
|
1012
|
+
| `Namespace already exists` | Attempting to create a namespace that exists | Use `iris_namespace_list` to check existing namespaces |
|
|
1013
|
+
| `Database directory not found` | Invalid directory path for database creation | Ensure the directory path is valid and accessible to the IRIS instance |
|
|
1014
|
+
| `User does not exist` | Referencing a non-existent user | Use `iris_user_get` without parameters to list all users |
|
|
1015
|
+
| `Role does not exist` | Adding a non-existent role | Use `iris_role_list` to see available roles |
|
|
1016
|
+
| `Custom REST endpoint not found` | Bootstrap has not completed | The server auto-bootstraps on first connection; save the web app via SMP if 404 persists |
|
|
1017
|
+
|
|
1018
|
+
### Error Response Format
|
|
1019
|
+
|
|
1020
|
+
```json
|
|
1021
|
+
{
|
|
1022
|
+
"content": [{ "type": "text", "text": "Error managing namespace 'MYAPP': <details>" }],
|
|
1023
|
+
"isError": true
|
|
1024
|
+
}
|
|
1025
|
+
```
|
|
1026
|
+
|
|
1027
|
+
Passwords are **never** included in error messages or responses (NFR6 security requirement).
|
|
1028
|
+
|
|
1029
|
+
---
|
|
1030
|
+
|
|
1031
|
+
[Back to IRIS MCP Server Suite](../../README.md)
|