@iris-mcp/data 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/README.md CHANGED
@@ -1,3 +1,613 @@
1
- # Temporary Holding Version
1
+ # @iris-mcp/data
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 Data & Analytics MCP Server** -- DocDB document database, DeepSee analytics (MDX queries and cube management), and REST API 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/data
13
+ ```
14
+
15
+ Or run directly without installing:
16
+
17
+ ```bash
18
+ npx -y @iris-mcp/data@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
+ This server's 7 tools are already inside the researched 5-15-tool sweet spot, so `IRIS_TOOLS_PRESET=core` and `=developer` both keep all **8 runtime tools** (7 + `iris_server_profiles`) visible — `iris-data-mcp` is unaffected by any preset. `IRIS_TOOLS_DISABLE`/`IRIS_TOOLS_ENABLE` still work here to hide/force-show individual tools independent of the preset. Full model and the payload-size measurements: [Tool Visibility Presets](../../README.md#tool-visibility-presets).
46
+
47
+ ---
48
+
49
+ ### Audit Logging (`IRIS_AUDIT_LOG`)
50
+
51
+ 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 security-audit tools: [Compliance & Auditability](../../README.md#compliance--auditability).
52
+
53
+ ### Server Manager connections (`IRIS_SERVER_MANAGER`)
54
+
55
+ 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).
56
+
57
+ ## MCP Client Configuration
58
+
59
+ ### Claude Code (`.mcp.json`)
60
+
61
+ ```json
62
+ {
63
+ "mcpServers": {
64
+ "iris-data-mcp": {
65
+ "command": "npx",
66
+ "args": ["-y", "@iris-mcp/data@1"],
67
+ "env": {
68
+ "IRIS_HOST": "localhost",
69
+ "IRIS_PORT": "52773",
70
+ "IRIS_USERNAME": "_SYSTEM",
71
+ "IRIS_PASSWORD": "SYS",
72
+ "IRIS_NAMESPACE": "USER"
73
+ }
74
+ }
75
+ }
76
+ }
77
+ ```
78
+
79
+ ### Claude Desktop (`claude_desktop_config.json`)
80
+
81
+ ```json
82
+ {
83
+ "mcpServers": {
84
+ "iris-data-mcp": {
85
+ "command": "npx",
86
+ "args": ["-y", "@iris-mcp/data@1"],
87
+ "env": {
88
+ "IRIS_HOST": "localhost",
89
+ "IRIS_PORT": "52773",
90
+ "IRIS_USERNAME": "_SYSTEM",
91
+ "IRIS_PASSWORD": "SYS",
92
+ "IRIS_NAMESPACE": "USER"
93
+ }
94
+ }
95
+ }
96
+ }
97
+ ```
98
+
99
+ ### Cursor
100
+
101
+ ```json
102
+ {
103
+ "iris-data-mcp": {
104
+ "command": "npx",
105
+ "args": ["-y", "@iris-mcp/data@1"],
106
+ "env": {
107
+ "IRIS_HOST": "localhost",
108
+ "IRIS_PORT": "52773",
109
+ "IRIS_USERNAME": "_SYSTEM",
110
+ "IRIS_PASSWORD": "SYS",
111
+ "IRIS_NAMESPACE": "USER"
112
+ }
113
+ }
114
+ }
115
+ ```
116
+
117
+ > **Note:** Replace `"SYS"` with your actual IRIS password. Avoid committing real credentials to version control.
118
+
119
+ ---
120
+
121
+ ## Prerequisites
122
+
123
+ In addition to the standard prerequisites, the four DocDB tools require the `%Service_DocDB` service to be enabled on the IRIS instance. **`%Service_DocDB` is disabled by default on IRIS.** Enable it through the Management Portal under *System Administration > Security > Services > %Service_DocDB*, or via the `iris_service_manage` tool (`action="enable"`, `name="%Service_DocDB"` — that tool is provided by the `@iris-mcp/admin` server) — note that action is itself governance-default-disabled and needs an `IRIS_GOVERNANCE` override such as `{"global": {"iris_service_manage:enable": true}}`. While the service is disabled, every DocDB call fails with `ERROR #822: Access Denied`; the tools detect this case and return an actionable error naming both remedy routes. The detection performs one follow-up check of the live service state via the suite's custom ExecuteMCPv2 REST endpoint — on an instance without that endpoint deployed, the raw `ERROR #822` passes through unchanged.
124
+
125
+ ---
126
+
127
+ ## Tool Reference
128
+
129
+ ### Framework Tools
130
+
131
+ Provided by the shared framework and available on **every** suite server (Epic 19).
132
+
133
+ | Tool | Description | Key Parameters | Annotations |
134
+ |------|-------------|----------------|-------------|
135
+ | `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 |
136
+
137
+ `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.
138
+
139
+ ### Document Database (DocDB) Tools
140
+
141
+ | Tool | Description | Key Parameters | Annotations |
142
+ |------|-------------|----------------|-------------|
143
+ | `iris_docdb_manage` | Create, drop, or list document databases | `action`, `database?`, `namespace?` | destructive |
144
+ | `iris_docdb_document` | Insert, get, update, or delete documents | `action`, `database`, `id?`, `document?`, `namespace?` | destructive |
145
+ | `iris_docdb_find` | Query documents with filter criteria | `database`, `filter`, `namespace?` | readOnly, idempotent |
146
+ | `iris_docdb_property` | Create, drop, or index properties | `action`, `database`, `property`, `type?`, `namespace?` | destructive |
147
+
148
+ > All four DocDB tools require `%Service_DocDB` to be enabled on the instance (disabled by default on IRIS) — see [Prerequisites](#prerequisites). With the service disabled they return an actionable `ERROR #822: Access Denied` error naming both remedy routes.
149
+
150
+ ### Analytics Tools
151
+
152
+ | Tool | Description | Key Parameters | Annotations |
153
+ |------|-------------|----------------|-------------|
154
+ | `iris_analytics_mdx` | Execute MDX queries against DeepSee | `query`, `namespace?` | readOnly, idempotent |
155
+ | `iris_analytics_cubes` | List, build, or synchronize DeepSee cubes | `action`, `cube?`, `namespace?` | -- |
156
+
157
+ ### REST API Management Tools
158
+
159
+ | Tool | Description | Key Parameters | Annotations |
160
+ |------|-------------|----------------|-------------|
161
+ | `iris_rest_manage` | List, get details, or delete REST applications | `action`, `scope?`, `application?`, `fullSpec?`, `namespace?` | destructive |
162
+
163
+ **`iris_rest_manage` scope values:**
164
+
165
+ | `scope` | Returns |
166
+ |---------|---------|
167
+ | `"spec-first"` *(default)* | OpenAPI/spec-first apps only (via IRIS Management API) |
168
+ | `"legacy"` | Hand-written `%CSP.REST` subclasses only |
169
+ | `"all"` | Union of spec-first + legacy (deduplicated by name) |
170
+
171
+ > **Breaking change (pre-release):** The former `scope:"all"` (legacy-only) has been renamed `scope:"legacy"`. The new `scope:"all"` returns the full union of both types.
172
+
173
+ **`iris_rest_manage` get action — `fullSpec` parameter:**
174
+
175
+ When `action:"get"`, the OpenAPI spec can be a large JSON document (50 KB+). By default (`fullSpec:false`) the tool returns a compact envelope in which the full spec is replaced by a `swaggerSpec` summary (and `name`/`namespace` fall back to the requested application path and resolved namespace when the spec body carries none):
176
+
177
+ ```json
178
+ {
179
+ "name": "/api/myapp",
180
+ "dispatchClass": null,
181
+ "namespace": "USER",
182
+ "swaggerSpec": {
183
+ "basePath": "/api/myapp",
184
+ "pathCount": 12,
185
+ "definitionCount": 5,
186
+ "description": "...",
187
+ "title": "My REST API",
188
+ "version": "1.0"
189
+ }
190
+ }
191
+ ```
192
+
193
+ Pass `fullSpec:true` to receive the complete OpenAPI spec object (returned as-is). When the application has no resolvable spec, `swaggerSpec` is `null`.
194
+
195
+ **`iris_rest_manage` get action — legacy names (Story 35.6):**
196
+
197
+ `get` resolves every name `list` returns. For a legacy `%CSP.REST` name (which the IRIS Management API does not know — it covers spec-first apps only), `get` falls back to the legacy webapp list and returns the legacy detail with an `explanation` field; `swaggerSpec` stays `null` (a legacy app has no OpenAPI spec by design) and `fullSpec` has no effect:
198
+
199
+ ```json
200
+ {
201
+ "name": "/api/executemcp/v2",
202
+ "dispatchClass": "ExecuteMCPv2.REST.Dispatch",
203
+ "namespace": "HSCUSTOM",
204
+ "swaggerSpec": null,
205
+ "explanation": "Legacy hand-written %CSP.REST application — resolved via the ExecuteMCPv2 webapp list ..."
206
+ }
207
+ ```
208
+
209
+ A name found in neither scope fails with an accurate not-found naming BOTH scopes checked — never the CSP gateway's misleading "Check the IRIS web server configuration" 404 text. If the legacy webapp list itself cannot be queried, the error says the legacy scope could not be checked (with the reason) rather than claiming the name is absent from it.
210
+
211
+ **`iris_rest_manage` delete action:** removes **spec-first** REST applications only. Deleting a legacy `%CSP.REST` name fails with an explanation pointing at `iris_webapp_manage:delete` (the correct tool for removing a legacy web application — there are no spec classes to remove).
212
+
213
+ ---
214
+
215
+ ## Prompts
216
+
217
+ No prompts in v1 (Epic 25). See the [Workflow Prompts & Agent Skills](../../README.md#workflow-prompts--agent-skills) section of the suite README for the prompts shipped by the other four servers.
218
+
219
+ ---
220
+
221
+ ## Tool Examples
222
+
223
+ <details>
224
+ <summary><strong>iris_docdb_manage</strong> -- List document databases</summary>
225
+
226
+ **Input:**
227
+ ```json
228
+ {
229
+ "action": "list"
230
+ }
231
+ ```
232
+
233
+ **Output:**
234
+ ```json
235
+ {
236
+ "items": [
237
+ { "name": "People", "count": 150 },
238
+ { "name": "Products", "count": 42 }
239
+ ],
240
+ "count": 2
241
+ }
242
+ ```
243
+ </details>
244
+
245
+ <details>
246
+ <summary><strong>iris_docdb_manage</strong> -- Create a document database</summary>
247
+
248
+ **Input:**
249
+ ```json
250
+ {
251
+ "action": "create",
252
+ "database": "Customers"
253
+ }
254
+ ```
255
+
256
+ **Output:**
257
+ ```json
258
+ {
259
+ "database": "Customers",
260
+ "status": "created"
261
+ }
262
+ ```
263
+ </details>
264
+
265
+ <details>
266
+ <summary><strong>iris_docdb_document</strong> -- Insert a document</summary>
267
+
268
+ **Input:**
269
+ ```json
270
+ {
271
+ "action": "insert",
272
+ "database": "Customers",
273
+ "document": {
274
+ "name": "John Smith",
275
+ "email": "john@example.com",
276
+ "age": 35
277
+ }
278
+ }
279
+ ```
280
+
281
+ **Output:**
282
+ ```json
283
+ {
284
+ "id": "1",
285
+ "status": "inserted"
286
+ }
287
+ ```
288
+ </details>
289
+
290
+ <details>
291
+ <summary><strong>iris_docdb_document</strong> -- Get a document by ID</summary>
292
+
293
+ **Input:**
294
+ ```json
295
+ {
296
+ "action": "get",
297
+ "database": "Customers",
298
+ "id": "1"
299
+ }
300
+ ```
301
+
302
+ **Output:**
303
+ ```json
304
+ {
305
+ "%DocumentId": "1",
306
+ "name": "John Smith",
307
+ "email": "john@example.com",
308
+ "age": 35
309
+ }
310
+ ```
311
+ </details>
312
+
313
+ <details>
314
+ <summary><strong>iris_docdb_find</strong> -- Query documents</summary>
315
+
316
+ **Input:**
317
+ ```json
318
+ {
319
+ "database": "Customers",
320
+ "filter": {
321
+ "age": { "$gt": 30 }
322
+ }
323
+ }
324
+ ```
325
+
326
+ **Output:**
327
+ ```json
328
+ {
329
+ "items": [
330
+ { "%DocumentId": "1", "name": "John Smith", "email": "john@example.com", "age": 35 }
331
+ ],
332
+ "count": 1
333
+ }
334
+ ```
335
+
336
+ **Filter translation:** MongoDB-style operators are translated to IRIS DocDB restriction predicates.
337
+ Supported: `$eq` (=), `$ne` (!=), `$lt` (<), `$lte` (<=), `$gt` (>), `$gte` (>=).
338
+ Multiple fields are combined with AND. Example: `{"age": {"$gt": 26}, "active": true}` translates to
339
+ `[["age", 26, ">"], ["active", true, "="]]` and is sent as `{restriction: [...]}` in the request body.
340
+ Properties must be defined on the database (via `iris_docdb_property`) and the property type must match the
341
+ comparison operator for filtering to work correctly (e.g., use `%Integer` for numeric `$gt`/`$lt` comparisons).
342
+ </details>
343
+
344
+ <details>
345
+ <summary><strong>iris_docdb_property</strong> -- Create a property</summary>
346
+
347
+ **Input:**
348
+ ```json
349
+ {
350
+ "action": "create",
351
+ "database": "Customers",
352
+ "property": "age",
353
+ "type": "%Integer"
354
+ }
355
+ ```
356
+
357
+ **Output:**
358
+ ```json
359
+ {
360
+ "Name": "age",
361
+ "Type": "%Library.Integer"
362
+ }
363
+ ```
364
+
365
+ **Type encoding note:** The IRIS DocDB API reads `type` from a URL query parameter, not the JSON body.
366
+ IRIS type names begin with `%` (e.g. `%Integer`, `%String`). The tool encodes these correctly using
367
+ split/join encoding that preserves the `%` prefix as a literal `%` in the URL — standard `encodeURIComponent`
368
+ would convert `%Integer` to `%25Integer`, causing IRIS to look for class `%Library.25Integer`.
369
+ </details>
370
+
371
+ <details>
372
+ <summary><strong>iris_docdb_property</strong> -- Index a property</summary>
373
+
374
+ **Input:**
375
+ ```json
376
+ {
377
+ "action": "index",
378
+ "database": "Customers",
379
+ "property": "email"
380
+ }
381
+ ```
382
+
383
+ **Output:**
384
+ ```json
385
+ {
386
+ "property": "email",
387
+ "indexed": true
388
+ }
389
+ ```
390
+ </details>
391
+
392
+ <details>
393
+ <summary><strong>iris_analytics_mdx</strong> -- Execute MDX query</summary>
394
+
395
+ **Input:**
396
+ ```json
397
+ {
398
+ "query": "SELECT [Measures].[Count] ON 0, [Product].[Product Category].Members ON 1 FROM [Sales]"
399
+ }
400
+ ```
401
+
402
+ **Output:**
403
+ ```json
404
+ {
405
+ "columns": ["Count"],
406
+ "rows": [
407
+ { "label": "Electronics", "values": [1200] },
408
+ { "label": "Clothing", "values": [850] },
409
+ { "label": "Books", "values": [2100] }
410
+ ],
411
+ "rowCount": 3,
412
+ "columnCount": 1
413
+ }
414
+ ```
415
+ </details>
416
+
417
+ <details>
418
+ <summary><strong>iris_analytics_cubes</strong> -- List cubes</summary>
419
+
420
+ **Input:**
421
+ ```json
422
+ {
423
+ "action": "list"
424
+ }
425
+ ```
426
+
427
+ **Output:**
428
+ ```json
429
+ {
430
+ "cubes": [
431
+ {
432
+ "name": "Sales",
433
+ "sourceClass": "MyApp.Fact.Sales",
434
+ "factCount": 50000,
435
+ "lastBuildTime": "2026-04-06T22:00:00.000Z",
436
+ "lastBuildTimeRaw": "67300,79200.000"
437
+ }
438
+ ],
439
+ "count": 1
440
+ }
441
+ ```
442
+
443
+ Each cube entry carries both a human-readable ISO 8601 `lastBuildTime` and
444
+ the original `$HOROLOG` string under `lastBuildTimeRaw`, so clients can
445
+ cross-check against `$ZDATETIME` or round-trip the raw value when needed.
446
+ Malformed or missing horolog values yield `lastBuildTime: ""` without
447
+ throwing; the raw value is still preserved when it is a string.
448
+ </details>
449
+
450
+ <details>
451
+ <summary><strong>iris_analytics_cubes</strong> -- Build a cube</summary>
452
+
453
+ **Input:**
454
+ ```json
455
+ {
456
+ "action": "build",
457
+ "cube": "Sales"
458
+ }
459
+ ```
460
+
461
+ **Output:**
462
+ ```json
463
+ {
464
+ "cube": "Sales",
465
+ "action": "build",
466
+ "status": "completed",
467
+ "recordCount": 50000
468
+ }
469
+ ```
470
+ </details>
471
+
472
+ <details>
473
+ <summary><strong>iris_rest_manage</strong> -- List REST applications (spec-first by default)</summary>
474
+
475
+ **Input (default — spec-first apps only):**
476
+ ```json
477
+ {
478
+ "action": "list"
479
+ }
480
+ ```
481
+
482
+ **Output (spec-first):**
483
+ ```json
484
+ {
485
+ "items": [
486
+ {
487
+ "name": "HS.FHIRServer.Management.REST.v1",
488
+ "dispatchClass": "HS.FHIRServer.Management.REST.v1.disp",
489
+ "swaggerSpec": "/api/mgmnt/v2/HSCUSTOM/HS.FHIRServer.Management.REST.v1"
490
+ }
491
+ ],
492
+ "count": 1
493
+ }
494
+ ```
495
+
496
+ The default `scope: "spec-first"` matches the SMP REST listing and routes
497
+ to IRIS's built-in Management API (`/api/mgmnt/v2/{ns}/`), which returns only
498
+ OpenAPI-spec-first dispatch classes (the ones with a `.spec` companion).
499
+ Hand-written `%CSP.REST` subclasses (for example, `ExecuteMCPv2.REST.Dispatch`)
500
+ are excluded by design of the IRIS Management API.
501
+
502
+ **Input (hand-written `%CSP.REST` subclasses only):**
503
+ ```json
504
+ {
505
+ "action": "list",
506
+ "scope": "legacy",
507
+ "namespace": "HSCUSTOM"
508
+ }
509
+ ```
510
+
511
+ **Output (`scope: "legacy"`):**
512
+ ```json
513
+ {
514
+ "items": [
515
+ {
516
+ "name": "/api/executemcp/v2",
517
+ "dispatchClass": "ExecuteMCPv2.REST.Dispatch",
518
+ "namespace": "HSCUSTOM",
519
+ "swaggerSpec": null
520
+ }
521
+ ],
522
+ "count": 1
523
+ }
524
+ ```
525
+
526
+ `scope: "legacy"` uses the ExecuteMCPv2 webapp endpoint and filters entries
527
+ with a non-empty `dispatchClass`. Hand-written dispatch classes have no
528
+ companion spec class, so `swaggerSpec` is `null` for them.
529
+
530
+ **Input (all REST applications — spec-first + hand-written):**
531
+ ```json
532
+ {
533
+ "action": "list",
534
+ "scope": "all",
535
+ "namespace": "HSCUSTOM"
536
+ }
537
+ ```
538
+
539
+ `scope: "all"` fetches both spec-first (via IRIS Management API) and legacy
540
+ (via ExecuteMCPv2 webapp endpoint) in parallel and returns the deduplicated union.
541
+
542
+ > **Note:** The former `scope:"all"` (pre-release, before the Story 12.5 rename) only returned hand-written classes. That behavior is now `scope:"legacy"`. Update any existing calls accordingly.
543
+ </details>
544
+
545
+ <details>
546
+ <summary><strong>iris_rest_manage</strong> -- Get REST application details</summary>
547
+
548
+ **Input:**
549
+ ```json
550
+ {
551
+ "action": "get",
552
+ "application": "/api/myapp"
553
+ }
554
+ ```
555
+
556
+ **Output:**
557
+ ```json
558
+ {
559
+ "name": "/api/myapp",
560
+ "dispatchClass": "MyApp.REST.Dispatch",
561
+ "routes": [
562
+ { "method": "GET", "url": "/items", "call": "GetItems" },
563
+ { "method": "POST", "url": "/items", "call": "CreateItem" }
564
+ ]
565
+ }
566
+ ```
567
+
568
+ For a legacy `%CSP.REST` name (e.g. `/api/executemcp/v2`, which `list` with `scope:"legacy"` or `"all"` returns), `get` falls back to the legacy webapp list and returns `{name, dispatchClass, namespace, swaggerSpec: null, explanation}` — see **get action — legacy names** above. A name in neither scope returns an accurate not-found naming both scopes checked.
569
+ </details>
570
+
571
+ ---
572
+
573
+ ## Namespace Scoping
574
+
575
+ All 7 tools in this package accept the optional `namespace` parameter to target a specific IRIS namespace. If omitted, the configured default namespace (`IRIS_NAMESPACE` environment variable) is used.
576
+
577
+ DocDB tools use the IRIS built-in DocDB REST API at `/api/docdb/v1/{namespace}/...`. The namespace is included directly in the API URL path.
578
+
579
+ Analytics tools use the custom REST endpoint and pass namespace as a request parameter.
580
+
581
+ REST management tools use the IRIS built-in Management API at `/api/mgmnt/v2/{namespace}/...`.
582
+
583
+ **Important:** DocDB tools require the `%Service_DocDB` service to be enabled in the target IRIS instance (it is disabled by default on IRIS). Without this service, DocDB operations fail with `ERROR #822: Access Denied` — the tools detect this case and return an actionable error naming the cause and both remedy routes (Management Portal, or `iris_service_manage` `action="enable"` under an `IRIS_GOVERNANCE` override).
584
+
585
+ ---
586
+
587
+ ## Error Handling
588
+
589
+ ### Common Errors
590
+
591
+ | Error | Cause | Resolution |
592
+ |-------|-------|------------|
593
+ | `IRIS connection refused` | IRIS web server not running or wrong host/port | Verify `IRIS_HOST` and `IRIS_PORT` settings |
594
+ | `401 Unauthorized` | Invalid credentials | Check `IRIS_USERNAME` and `IRIS_PASSWORD` |
595
+ | `ERROR #822: Access Denied` (from `/api/docdb/v1/...`) | `%Service_DocDB` not enabled (disabled by default on IRIS) — the DocDB tools translate this into an actionable error naming both remedies | Enable the service via the Management Portal (*System Administration > Security > Services > %Service_DocDB*), or `iris_service_manage` `action="enable"` (itself governance-default-disabled; needs an `IRIS_GOVERNANCE` override) |
596
+ | `Database not found` | DocDB database does not exist | Use `iris_docdb_manage` with action `list` to check available databases |
597
+ | `Document not found` | Invalid document ID | Verify the document ID with `iris_docdb_find` |
598
+ | `Cube not found` | DeepSee cube does not exist | Use `iris_analytics_cubes` with action `list` to see available cubes |
599
+ | `MDX syntax error` | Invalid MDX query | Check MDX syntax; ensure the cube and dimension names are correct |
600
+ | `REST application not found` | Invalid application path | Use `iris_rest_manage` with action `list` to see available applications |
601
+
602
+ ### Error Response Format
603
+
604
+ ```json
605
+ {
606
+ "content": [{ "type": "text", "text": "Error querying documents: <details>" }],
607
+ "isError": true
608
+ }
609
+ ```
610
+
611
+ ---
612
+
613
+ [Back to IRIS MCP Server Suite](../../README.md)
@@ -0,0 +1,11 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * @iris-mcp/data -- IRIS Data & Analytics MCP Server
4
+ *
5
+ * Entry point that creates an {@link McpServerBase} instance with
6
+ * the registered data tool definitions and connects the
7
+ * stdio transport, the only supported transport; any other configured
8
+ * transport is a fatal configuration error.
9
+ */
10
+ export {};
11
+ //# sourceMappingURL=index.d.ts.map
package/dist/index.js ADDED
@@ -0,0 +1,31 @@
1
+ #!/usr/bin/env node
2
+ /**
3
+ * @iris-mcp/data -- IRIS Data & Analytics MCP Server
4
+ *
5
+ * Entry point that creates an {@link McpServerBase} instance with
6
+ * the registered data tool definitions and connects the
7
+ * stdio transport, the only supported transport; any other configured
8
+ * transport is a fatal configuration error.
9
+ */
10
+ import { createRequire } from "node:module";
11
+ import { McpServerBase, resolveTransport } from "@iris-mcp/shared";
12
+ import { tools } from "./tools/index.js";
13
+ import { toolPresets } from "./tools/presets.js";
14
+ // Read version from package.json using createRequire (ESM-safe)
15
+ const require = createRequire(import.meta.url);
16
+ const pkg = require("../package.json");
17
+ const server = new McpServerBase({
18
+ name: "@iris-mcp/data",
19
+ version: pkg.version,
20
+ tools,
21
+ toolPresets,
22
+ needsCustomRest: true,
23
+ });
24
+ try {
25
+ await server.start(resolveTransport());
26
+ }
27
+ catch (err) {
28
+ console.error("Fatal:", err);
29
+ process.exit(1);
30
+ }
31
+ //# sourceMappingURL=index.js.map