@iris-mcp/data 0.0.0-stage → 1.1.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.
@@ -0,0 +1,40 @@
1
+ /**
2
+ * Tool visibility preset rosters for iris-data-mcp (Epic 30, architecture
3
+ * decision I2; Story 30.1). Transcribed EXACTLY from the product-owner-
4
+ * approved spec §2.5 note (approved 2026-07-12 — "implement as written").
5
+ *
6
+ * iris-data-mcp's 7 tools are already inside the researched 5-15 sweet spot,
7
+ * so both `core` and `developer` include all 7 (`exclude: []`) — the coverage
8
+ * assert (`assertPresetCoverage`, see `index.ts`) still applies uniformly, so
9
+ * the roster is declared explicitly rather than omitted.
10
+ *
11
+ * [Source: research/feature-specs/11-tool-visibility-presets.md#2.5 "iris-data-mcp"]
12
+ */
13
+ /** data-mcp's `core`/`developer` visibility rosters (§2.5) — full inclusion for both. */
14
+ export const toolPresets = {
15
+ core: {
16
+ include: [
17
+ "iris_docdb_manage",
18
+ "iris_docdb_document",
19
+ "iris_docdb_find",
20
+ "iris_docdb_property",
21
+ "iris_analytics_mdx",
22
+ "iris_analytics_cubes",
23
+ "iris_rest_manage",
24
+ ],
25
+ exclude: [],
26
+ },
27
+ developer: {
28
+ include: [
29
+ "iris_docdb_manage",
30
+ "iris_docdb_document",
31
+ "iris_docdb_find",
32
+ "iris_docdb_property",
33
+ "iris_analytics_mdx",
34
+ "iris_analytics_cubes",
35
+ "iris_rest_manage",
36
+ ],
37
+ exclude: [],
38
+ },
39
+ };
40
+ //# sourceMappingURL=presets.js.map
@@ -0,0 +1,20 @@
1
+ /**
2
+ * REST API management tools for the IRIS Data & Analytics MCP server.
3
+ *
4
+ * Provides one tool for managing IRIS REST API dispatch classes:
5
+ * - {@link restManageTool} — List, get details, or delete REST applications
6
+ *
7
+ * Most operations call the IRIS built-in Management API at
8
+ * `/api/mgmnt/v2/{namespace}/...`.
9
+ *
10
+ * FEAT-2 (BREAKING, pre-release): `scope` values renamed:
11
+ * - `"spec-first"` (default) — Mgmnt v2 API, spec-first apps only
12
+ * - `"legacy"` (was `"all"`) — hand-written %CSP.REST subclasses only
13
+ * - `"all"` (new) — union of spec-first + legacy
14
+ *
15
+ * FEAT-6: `action:"get"` gains `fullSpec: boolean` (default false).
16
+ * Summary mode returns condensed swaggerSpec metadata; full mode returns raw blob.
17
+ */
18
+ import { type ToolDefinition } from "@iris-mcp/shared";
19
+ export declare const restManageTool: ToolDefinition;
20
+ //# sourceMappingURL=rest.d.ts.map
@@ -0,0 +1,407 @@
1
+ /**
2
+ * REST API management tools for the IRIS Data & Analytics MCP server.
3
+ *
4
+ * Provides one tool for managing IRIS REST API dispatch classes:
5
+ * - {@link restManageTool} — List, get details, or delete REST applications
6
+ *
7
+ * Most operations call the IRIS built-in Management API at
8
+ * `/api/mgmnt/v2/{namespace}/...`.
9
+ *
10
+ * FEAT-2 (BREAKING, pre-release): `scope` values renamed:
11
+ * - `"spec-first"` (default) — Mgmnt v2 API, spec-first apps only
12
+ * - `"legacy"` (was `"all"`) — hand-written %CSP.REST subclasses only
13
+ * - `"all"` (new) — union of spec-first + legacy
14
+ *
15
+ * FEAT-6: `action:"get"` gains `fullSpec: boolean` (default false).
16
+ * Summary mode returns condensed swaggerSpec metadata; full mode returns raw blob.
17
+ */
18
+ import { IrisApiError } from "@iris-mcp/shared";
19
+ import { z } from "zod";
20
+ import { extractResult, toStructured } from "./docdb.js";
21
+ /** Base URL for the IRIS Management REST API (spec-first apps only). */
22
+ const BASE_MGMNT_URL = "/api/mgmnt/v2";
23
+ /** Base URL for the custom ExecuteMCPv2 REST service (covers all %CSP.REST apps). */
24
+ const BASE_EXECUTEMCP_URL = "/api/executemcp/v2";
25
+ /**
26
+ * Fetch legacy (hand-written %CSP.REST) apps from ExecuteMCPv2 webapp endpoint.
27
+ *
28
+ * Filters for entries with a non-empty `dispatchClass` and normalizes
29
+ * to the Mgmnt API response shape {name, dispatchClass, namespace, swaggerSpec: null}.
30
+ *
31
+ * Used by scope:"legacy" and scope:"all" (FEAT-2).
32
+ */
33
+ async function fetchLegacyApps(ctx, ns) {
34
+ const webappPath = `${BASE_EXECUTEMCP_URL}/security/webapp?namespace=${encodeURIComponent(ns)}`;
35
+ const webappResponse = await ctx.http.get(webappPath);
36
+ const rawWebapps = webappResponse.result;
37
+ const webapps = Array.isArray(rawWebapps)
38
+ ? rawWebapps
39
+ : [];
40
+ return webapps
41
+ .filter((w) => {
42
+ const dc = w.dispatchClass;
43
+ return typeof dc === "string" && dc.length > 0;
44
+ })
45
+ .map((w) => ({
46
+ name: w.name,
47
+ dispatchClass: w.dispatchClass,
48
+ namespace: w.namespace,
49
+ swaggerSpec: null,
50
+ }));
51
+ }
52
+ async function findLegacyApp(ctx, ns, application) {
53
+ try {
54
+ const legacyApps = await fetchLegacyApps(ctx, ns);
55
+ return { ok: true, match: legacyApps.find((a) => a.name === application) ?? null };
56
+ }
57
+ catch (lookupError) {
58
+ // Status-driven reason, never the embedded message text (Rule #8/#13): a
59
+ // failing endpoint's prose can itself carry the misleading gateway 404
60
+ // wording this story exists to remove.
61
+ const reason = lookupError instanceof IrisApiError
62
+ ? `HTTP ${lookupError.statusCode}`
63
+ : lookupError instanceof Error
64
+ ? lookupError.message
65
+ : String(lookupError);
66
+ return { ok: false, reason };
67
+ }
68
+ }
69
+ /**
70
+ * Story 35.6: accurate not-found text naming BOTH scopes checked — replaces
71
+ * the Mgmnt API's misleading "Check the IRIS web server configuration" text
72
+ * (an HTTP-status-driven branch, never message-text matching: Rule #8/#13).
73
+ */
74
+ function notFoundBothScopes(application, ns) {
75
+ return (`Error managing REST application: '${application}' was not found in namespace '${ns}' ` +
76
+ `as a spec-first REST application (IRIS Mgmnt API, /api/mgmnt/v2) or as a legacy ` +
77
+ `%CSP.REST application (ExecuteMCPv2 webapp list — the names 'list' with scope ` +
78
+ `'legacy' or 'all' returns).`);
79
+ }
80
+ /**
81
+ * Story 35.6 (code review): the Mgmnt 404 fired but the legacy lookup itself
82
+ * FAILED — the legacy scope was never actually consulted, so say that instead
83
+ * of asserting absence in it.
84
+ */
85
+ function notFoundLegacyUnchecked(application, ns, reason) {
86
+ return (`Error managing REST application: '${application}' was not found in namespace '${ns}' ` +
87
+ `as a spec-first REST application (IRIS Mgmnt API, /api/mgmnt/v2), and the legacy ` +
88
+ `%CSP.REST scope could not be checked — the ExecuteMCPv2 webapp list query failed ` +
89
+ `(${reason}).`);
90
+ }
91
+ // ── iris_rest_manage ──────────────────────────────────────────
92
+ export const restManageTool = {
93
+ name: "iris_rest_manage",
94
+ title: "Manage REST API",
95
+ description: "List, get details, or delete REST API dispatch classes on IRIS. " +
96
+ "\n\n'list' returns REST application dispatch classes in the namespace. " +
97
+ "scope values:\n" +
98
+ " - 'spec-first' (default): OpenAPI-spec-first apps only, via IRIS Mgmnt API " +
99
+ "(/api/mgmnt/v2/{ns}/). These have a .spec companion class.\n" +
100
+ " - 'legacy': hand-written %CSP.REST subclasses only (no .spec class), " +
101
+ "via ExecuteMCPv2 webapp endpoint. swaggerSpec is null for these.\n" +
102
+ " - 'all': union of both — spec-first + legacy combined into one response.\n\n" +
103
+ "BREAKING (pre-release): old scope:'all' behavior is now scope:'legacy'.\n\n" +
104
+ "'get' returns REST application details (dispatch class, URL map, swagger spec) for a named application. " +
105
+ "Use fullSpec:false (default) for a compact summary; fullSpec:true for the full 50KB+ swagger blob. " +
106
+ "'get' resolves EVERY name 'list' returns: for a legacy %CSP.REST name (a Mgmnt API 404) it falls back " +
107
+ "to the legacy webapp list and returns {name, dispatchClass, namespace, swaggerSpec: null} plus an " +
108
+ "'explanation' field — legacy apps have no OpenAPI spec by design, so swaggerSpec stays null and " +
109
+ "fullSpec has no effect. A name in neither scope fails with an accurate not-found naming BOTH scopes " +
110
+ "checked (never a 'web server configuration' misdirection).\n\n" +
111
+ "'delete' removes a SPEC-FIRST REST application only (Mgmnt API scope). A legacy %CSP.REST name " +
112
+ "fails with an explanation pointing at iris_webapp_manage:delete, which is the correct tool for " +
113
+ "removing a legacy web application.",
114
+ inputSchema: z.object({
115
+ action: z
116
+ .enum(["list", "get", "delete"])
117
+ .describe("Action to perform: 'list', 'get', or 'delete'"),
118
+ scope: z
119
+ .enum(["spec-first", "legacy", "all"])
120
+ .optional()
121
+ .default("spec-first")
122
+ .describe("For 'list' action only. " +
123
+ "'spec-first' (default): OpenAPI-spec-first apps via IRIS Mgmnt API. " +
124
+ "'legacy': hand-written %CSP.REST dispatch classes (was 'all' before Story 12.5 — BREAKING). " +
125
+ "'all': union of spec-first + legacy."),
126
+ application: z
127
+ .string()
128
+ .min(1)
129
+ .optional()
130
+ .describe("REST application path (required for 'get' and 'delete', e.g., '/api/myapp')"),
131
+ namespace: z
132
+ .string()
133
+ .optional()
134
+ .describe("Target namespace (default: configured namespace)"),
135
+ fullSpec: z
136
+ .boolean()
137
+ .optional()
138
+ .default(false)
139
+ .describe("For 'get' action only. When false (default) returns a compact summary " +
140
+ "{name, dispatchClass, namespace, swaggerSpec:{basePath,pathCount,definitionCount,description,title,version}} " +
141
+ "to avoid 50KB+ responses. When true, returns the full swagger spec blob. " +
142
+ "Has no effect for legacy %CSP.REST apps — no spec exists, swaggerSpec stays null."),
143
+ }),
144
+ annotations: {
145
+ destructiveHint: true,
146
+ readOnlyHint: false,
147
+ idempotentHint: false,
148
+ openWorldHint: false,
149
+ },
150
+ scope: "NS",
151
+ handler: async (args, ctx) => {
152
+ const { action, scope, application, namespace, fullSpec } = args;
153
+ const ns = ctx.resolveNamespace(namespace);
154
+ // Zod `.default("spec-first")` only fires when inputs are parsed through
155
+ // Zod. The tool registry typically passes raw args, so the `scope` may be
156
+ // `undefined` at runtime — fall back here to preserve the contract.
157
+ const effectiveScope = scope ?? "spec-first";
158
+ // FEAT-6: default fullSpec to false (summary mode)
159
+ const useFullSpec = fullSpec ?? false;
160
+ try {
161
+ let response;
162
+ if (action === "list") {
163
+ if (effectiveScope === "legacy") {
164
+ // FEAT-2: "legacy" (was "all" before Story 12.5) — hand-written %CSP.REST
165
+ // dispatch classes only. %REST.API.GetAllRESTApps filters these out by design.
166
+ // Use ExecuteMCPv2 webapp endpoint, filter for non-empty dispatchClass.
167
+ const legacyApps = await fetchLegacyApps(ctx, ns);
168
+ const structured = { items: legacyApps, count: legacyApps.length };
169
+ return {
170
+ content: [
171
+ {
172
+ type: "text",
173
+ text: JSON.stringify(structured, null, 2),
174
+ },
175
+ ],
176
+ structuredContent: structured,
177
+ };
178
+ }
179
+ else if (effectiveScope === "all") {
180
+ // FEAT-2: "all" = union of spec-first + legacy
181
+ const [specFirstResponse, legacyApps] = await Promise.all([
182
+ ctx.http.get(`${BASE_MGMNT_URL}/${encodeURIComponent(ns)}/`),
183
+ fetchLegacyApps(ctx, ns),
184
+ ]);
185
+ const rawSpecFirst = extractResult(specFirstResponse);
186
+ const specFirstItems = Array.isArray(rawSpecFirst)
187
+ ? rawSpecFirst
188
+ : [];
189
+ // Merge: spec-first items first, then legacy. Deduplicate by name.
190
+ const seen = new Set();
191
+ const merged = [];
192
+ for (const item of specFirstItems) {
193
+ const key = String(item.name ?? "");
194
+ if (!seen.has(key)) {
195
+ seen.add(key);
196
+ merged.push(item);
197
+ }
198
+ }
199
+ for (const item of legacyApps) {
200
+ const key = String(item.name ?? "");
201
+ if (!seen.has(key)) {
202
+ seen.add(key);
203
+ merged.push(item);
204
+ }
205
+ }
206
+ const structured = { items: merged, count: merged.length };
207
+ return {
208
+ content: [
209
+ {
210
+ type: "text",
211
+ text: JSON.stringify(structured, null, 2),
212
+ },
213
+ ],
214
+ structuredContent: structured,
215
+ };
216
+ }
217
+ // effectiveScope === "spec-first" (default)
218
+ response = await ctx.http.get(`${BASE_MGMNT_URL}/${encodeURIComponent(ns)}/`);
219
+ }
220
+ else if (action === "get") {
221
+ if (!application) {
222
+ return {
223
+ content: [
224
+ {
225
+ type: "text",
226
+ text: "Error: 'application' is required for 'get' action",
227
+ },
228
+ ],
229
+ isError: true,
230
+ };
231
+ }
232
+ try {
233
+ response = await ctx.http.get(`${BASE_MGMNT_URL}/${encodeURIComponent(ns)}/${encodeURIComponent(application)}`);
234
+ }
235
+ catch (error) {
236
+ // Story 35.6 (AC 35.6.4): the Mgmnt API covers SPEC-FIRST apps only
237
+ // (Rule #12), so a 404 here may simply be a legacy hand-written
238
+ // %CSP.REST app that 'list' scope 'legacy'/'all' returns. Resolve it
239
+ // via the legacy webapp list instead of surfacing the CSP gateway's
240
+ // misleading "Check the IRIS web server configuration" 404 text.
241
+ // Branch on the HTTP STATUS, never the message text (Rule #8/#13).
242
+ if (error instanceof IrisApiError && error.statusCode === 404) {
243
+ const legacyLookup = await findLegacyApp(ctx, ns, application);
244
+ if (legacyLookup.ok && legacyLookup.match) {
245
+ const legacyMatch = legacyLookup.match;
246
+ const detail = {
247
+ name: legacyMatch.name,
248
+ dispatchClass: legacyMatch.dispatchClass,
249
+ namespace: legacyMatch.namespace ?? ns,
250
+ swaggerSpec: null,
251
+ explanation: "Legacy hand-written %CSP.REST application — resolved via the ExecuteMCPv2 " +
252
+ "webapp list because the IRIS Mgmnt API (/api/mgmnt/v2) covers spec-first " +
253
+ "apps only. No OpenAPI spec exists for a legacy app by design, so " +
254
+ "swaggerSpec is null and fullSpec has no effect.",
255
+ };
256
+ return {
257
+ content: [
258
+ { type: "text", text: JSON.stringify(detail, null, 2) },
259
+ ],
260
+ structuredContent: detail,
261
+ };
262
+ }
263
+ return {
264
+ content: [
265
+ {
266
+ type: "text",
267
+ text: legacyLookup.ok
268
+ ? notFoundBothScopes(application, ns)
269
+ : notFoundLegacyUnchecked(application, ns, legacyLookup.reason),
270
+ },
271
+ ],
272
+ isError: true,
273
+ };
274
+ }
275
+ throw error;
276
+ }
277
+ }
278
+ else {
279
+ // delete
280
+ if (!application) {
281
+ return {
282
+ content: [
283
+ {
284
+ type: "text",
285
+ text: "Error: 'application' is required for 'delete' action",
286
+ },
287
+ ],
288
+ isError: true,
289
+ };
290
+ }
291
+ try {
292
+ response = await ctx.http.delete(`${BASE_MGMNT_URL}/${encodeURIComponent(ns)}/${encodeURIComponent(application)}`);
293
+ }
294
+ catch (error) {
295
+ // Story 35.6: same by-design scope boundary as 'get'. Deleting a
296
+ // legacy app is deliberately NOT routed anywhere here — that is
297
+ // iris_webapp_manage:delete's job (it deletes the web application;
298
+ // there are no spec classes to remove).
299
+ if (error instanceof IrisApiError && error.statusCode === 404) {
300
+ const legacyLookup = await findLegacyApp(ctx, ns, application);
301
+ if (legacyLookup.ok && legacyLookup.match) {
302
+ const legacyMatch = legacyLookup.match;
303
+ // fetchLegacyApps filters to non-empty dispatchClass, so a match
304
+ // always carries a real class name — no empty-parenthetical guard.
305
+ return {
306
+ content: [
307
+ {
308
+ type: "text",
309
+ text: `Error managing REST application: '${application}' is a legacy ` +
310
+ `hand-written %CSP.REST application (dispatch class ${String(legacyMatch.dispatchClass)}). ` +
311
+ `iris_rest_manage:delete removes spec-first REST applications only ` +
312
+ `(IRIS Mgmnt API scope). To remove a legacy web application, use ` +
313
+ `iris_webapp_manage:delete.`,
314
+ },
315
+ ],
316
+ isError: true,
317
+ };
318
+ }
319
+ return {
320
+ content: [
321
+ {
322
+ type: "text",
323
+ text: legacyLookup.ok
324
+ ? notFoundBothScopes(application, ns)
325
+ : notFoundLegacyUnchecked(application, ns, legacyLookup.reason),
326
+ },
327
+ ],
328
+ isError: true,
329
+ };
330
+ }
331
+ throw error;
332
+ }
333
+ }
334
+ const result = extractResult(response);
335
+ // FEAT-6: summary mode for get action (default)
336
+ if (action === "get" && !useFullSpec && result && typeof result === "object") {
337
+ const raw = result;
338
+ // The Mgmnt API `get` returns the swagger spec at the TOP LEVEL of the
339
+ // result (keys like `swagger`/`info`/`paths`/`basePath`), NOT nested under
340
+ // a `swaggerSpec` field the way the `list` rows are. Accept either shape:
341
+ // prefer a nested `swaggerSpec` object if present, otherwise treat the
342
+ // result itself as the spec when it carries swagger/openapi markers.
343
+ // (Previously this only read `raw.swaggerSpec`, so the summary was always
344
+ // null for spec-first apps even though the full spec was clearly present.)
345
+ let swaggerRaw = raw.swaggerSpec;
346
+ if ((!swaggerRaw || typeof swaggerRaw !== "object") &&
347
+ (raw.swagger !== undefined ||
348
+ raw.openapi !== undefined ||
349
+ raw.info !== undefined ||
350
+ raw.paths !== undefined)) {
351
+ swaggerRaw = raw;
352
+ }
353
+ let swaggerSummary = null;
354
+ if (swaggerRaw && typeof swaggerRaw === "object") {
355
+ // Count paths and definitions to avoid sending the full blob
356
+ const paths = swaggerRaw.paths;
357
+ const definitions = swaggerRaw.definitions;
358
+ const info = swaggerRaw.info;
359
+ swaggerSummary = {
360
+ basePath: swaggerRaw.basePath ?? null,
361
+ pathCount: paths ? Object.keys(paths).length : 0,
362
+ definitionCount: definitions ? Object.keys(definitions).length : 0,
363
+ description: info?.description ?? null,
364
+ title: info?.title ?? null,
365
+ version: info?.version ?? null,
366
+ };
367
+ }
368
+ // The `get` spec body carries no name/dispatchClass/namespace of its own,
369
+ // so fall back to the requested application path and resolved namespace.
370
+ const summarized = {
371
+ name: raw.name ?? application,
372
+ dispatchClass: raw.dispatchClass ?? null,
373
+ namespace: raw.namespace ?? ns,
374
+ swaggerSpec: swaggerSummary,
375
+ };
376
+ return {
377
+ content: [
378
+ { type: "text", text: JSON.stringify(summarized, null, 2) },
379
+ ],
380
+ structuredContent: summarized,
381
+ };
382
+ }
383
+ const structured = toStructured(result);
384
+ return {
385
+ content: [
386
+ { type: "text", text: JSON.stringify(structured, null, 2) },
387
+ ],
388
+ structuredContent: structured,
389
+ };
390
+ }
391
+ catch (error) {
392
+ if (error instanceof IrisApiError) {
393
+ return {
394
+ content: [
395
+ {
396
+ type: "text",
397
+ text: `Error managing REST application: ${error.message}`,
398
+ },
399
+ ],
400
+ isError: true,
401
+ };
402
+ }
403
+ throw error;
404
+ }
405
+ },
406
+ };
407
+ //# sourceMappingURL=rest.js.map
package/package.json CHANGED
@@ -1,6 +1,61 @@
1
1
  {
2
2
  "name": "@iris-mcp/data",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.1.0",
4
+ "description": "IRIS Data & Analytics MCP Server",
5
+ "keywords": [
6
+ "iris",
7
+ "mcp",
8
+ "model-context-protocol",
9
+ "mcp-server",
10
+ "analytics",
11
+ "document-database",
12
+ "ai-agents"
13
+ ],
14
+ "homepage": "https://github.com/jbrandtmse/iris-execute-mcp-v2/tree/main/packages/iris-data-mcp#readme",
15
+ "bugs": {
16
+ "url": "https://github.com/jbrandtmse/iris-execute-mcp-v2/issues"
17
+ },
18
+ "license": "MIT",
19
+ "author": "jbrandtmse (https://github.com/jbrandtmse)",
20
+ "repository": {
21
+ "type": "git",
22
+ "url": "git+https://github.com/jbrandtmse/iris-execute-mcp-v2.git",
23
+ "directory": "packages/iris-data-mcp"
24
+ },
25
+ "type": "module",
26
+ "main": "./dist/index.js",
27
+ "types": "./dist/index.d.ts",
28
+ "bin": {
29
+ "iris-data-mcp": "./dist/index.js"
30
+ },
31
+ "mcpName": "io.github.jbrandtmse/iris-data-mcp",
32
+ "exports": {
33
+ ".": {
34
+ "types": "./dist/index.d.ts",
35
+ "import": "./dist/index.js"
36
+ }
37
+ },
38
+ "files": [
39
+ "dist",
40
+ "CHANGELOG.md",
41
+ "!dist/**/__tests__",
42
+ "!dist/**/*.map"
43
+ ],
44
+ "engines": {
45
+ "node": ">=22.17.0"
46
+ },
47
+ "dependencies": {
48
+ "zod": "^4.3.6",
49
+ "@iris-mcp/shared": "1.1.0"
50
+ },
51
+ "devDependencies": {
52
+ "@types/node": "^22.17.0"
53
+ },
54
+ "scripts": {
55
+ "build": "tsc --project tsconfig.json",
56
+ "test": "vitest run",
57
+ "test:integration": "vitest run --config vitest.integration.config.ts",
58
+ "lint": "eslint src/ --max-warnings 0",
59
+ "type-check": "tsc --noEmit"
60
+ }
6
61
  }