@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.
Files changed (44) hide show
  1. package/CHANGELOG.md +242 -0
  2. package/LICENSE +21 -0
  3. package/README.md +1030 -2
  4. package/dist/index.d.ts +11 -0
  5. package/dist/index.js +33 -0
  6. package/dist/prompts/auditSecurityPosture.d.ts +12 -0
  7. package/dist/prompts/auditSecurityPosture.js +52 -0
  8. package/dist/prompts/index.d.ts +12 -0
  9. package/dist/prompts/index.js +16 -0
  10. package/dist/prompts/provisionProjectEnvironment.d.ts +11 -0
  11. package/dist/prompts/provisionProjectEnvironment.js +48 -0
  12. package/dist/tools/audit.d.ts +42 -0
  13. package/dist/tools/audit.js +394 -0
  14. package/dist/tools/database.d.ts +14 -0
  15. package/dist/tools/database.js +179 -0
  16. package/dist/tools/index.d.ts +12 -0
  17. package/dist/tools/index.js +52 -0
  18. package/dist/tools/ldap.d.ts +33 -0
  19. package/dist/tools/ldap.js +252 -0
  20. package/dist/tools/mapping.d.ts +15 -0
  21. package/dist/tools/mapping.js +175 -0
  22. package/dist/tools/namespace.d.ts +14 -0
  23. package/dist/tools/namespace.js +145 -0
  24. package/dist/tools/oauth.d.ts +17 -0
  25. package/dist/tools/oauth.js +269 -0
  26. package/dist/tools/permission.d.ts +13 -0
  27. package/dist/tools/permission.js +70 -0
  28. package/dist/tools/presets.d.ts +20 -0
  29. package/dist/tools/presets.js +84 -0
  30. package/dist/tools/resource.d.ts +81 -0
  31. package/dist/tools/resource.js +402 -0
  32. package/dist/tools/role.d.ts +14 -0
  33. package/dist/tools/role.js +139 -0
  34. package/dist/tools/service.d.ts +19 -0
  35. package/dist/tools/service.js +199 -0
  36. package/dist/tools/ssl.d.ts +14 -0
  37. package/dist/tools/ssl.js +201 -0
  38. package/dist/tools/user.d.ts +20 -0
  39. package/dist/tools/user.js +326 -0
  40. package/dist/tools/webapp.d.ts +20 -0
  41. package/dist/tools/webapp.js +268 -0
  42. package/dist/tools/x509.d.ts +42 -0
  43. package/dist/tools/x509.js +224 -0
  44. package/package.json +58 -3
package/README.md CHANGED
@@ -1,3 +1,1031 @@
1
- # Temporary Holding Version
1
+ # @iris-mcp/admin
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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)