@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.
- package/CHANGELOG.md +205 -0
- package/LICENSE +21 -0
- package/README.md +612 -2
- package/dist/index.d.ts +11 -0
- package/dist/index.js +31 -0
- package/dist/tools/analytics.d.ts +43 -0
- package/dist/tools/analytics.js +227 -0
- package/dist/tools/debug.d.ts +14 -0
- package/dist/tools/debug.js +15 -0
- package/dist/tools/docdb.d.ts +118 -0
- package/dist/tools/docdb.js +637 -0
- package/dist/tools/index.d.ts +11 -0
- package/dist/tools/index.js +21 -0
- package/dist/tools/presets.d.ts +16 -0
- package/dist/tools/presets.js +40 -0
- package/dist/tools/rest.d.ts +20 -0
- package/dist/tools/rest.js +407 -0
- package/package.json +58 -3
|
@@ -0,0 +1,637 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Document Database (DocDB) tools for the IRIS Data & Analytics MCP server.
|
|
3
|
+
*
|
|
4
|
+
* Provides four tools for managing IRIS document databases:
|
|
5
|
+
* - {@link docdbManageTool} — Create, drop, or list document databases
|
|
6
|
+
* - {@link docdbDocumentTool} — Insert, get, update, or delete documents
|
|
7
|
+
* - {@link docdbFindTool} — Query documents with filter criteria
|
|
8
|
+
* - {@link docdbPropertyTool} — Create, drop, or index properties
|
|
9
|
+
*
|
|
10
|
+
* All tools call the IRIS built-in DocDB REST API at
|
|
11
|
+
* `/api/docdb/v1/{namespace}/...`. No custom ObjectScript handler
|
|
12
|
+
* is required.
|
|
13
|
+
*
|
|
14
|
+
* ## DocDB API contract notes (from reading %Api.DocDB.v1.cls and %DocDB.Database.cls)
|
|
15
|
+
*
|
|
16
|
+
* ### Property create (BUG-5 fix)
|
|
17
|
+
* `POST /api/docdb/v1/{ns}/prop/{db}/{prop}` reads `type` from
|
|
18
|
+
* `%request.Data("type",1)` — i.e., a **URL query parameter**, not the
|
|
19
|
+
* JSON body. Sending `{type: "..."}` in the body is silently ignored and
|
|
20
|
+
* the server defaults to `%String`. Fix: append `?type=<encoded>` to the
|
|
21
|
+
* URL and send an empty body `{}`.
|
|
22
|
+
*
|
|
23
|
+
* ENCODING: IRIS type names start with `%` (e.g. `%Integer`).
|
|
24
|
+
* `encodeURIComponent` turns `%` into `%25`, but the IRIS CSP layer does
|
|
25
|
+
* NOT URL-decode `%XX` sequences in `%request.Data` — it reads `%25Integer`
|
|
26
|
+
* literally, causing lookup failure for class `%Library.25Integer`.
|
|
27
|
+
* Fix: split on `%`, encode each segment, rejoin with `%`.
|
|
28
|
+
* This keeps the type `%` prefix as a literal `%` while encoding any other
|
|
29
|
+
* special characters in the type name. Verified via direct HTTP probe.
|
|
30
|
+
*
|
|
31
|
+
* ### Find / filter (BUG-6 fix)
|
|
32
|
+
* `POST /api/docdb/v1/{ns}/find/{db}` reads `requestBody.restriction`,
|
|
33
|
+
* `.projection`, and `.options` from the JSON body. `restriction` is
|
|
34
|
+
* either a single DocDB predicate array `[field, value, operator]` or an
|
|
35
|
+
* array of such arrays (combined with AND). The MongoDB-style filter
|
|
36
|
+
* `{field: {$gt: value}}` must be translated to `["field", value, ">"]`.
|
|
37
|
+
* Supported operators: $eq → =, $ne → !=, $lt → <, $lte → <=, $gt → >,
|
|
38
|
+
* $gte → >=. Multiple field/op pairs are combined as an array of predicates.
|
|
39
|
+
*/
|
|
40
|
+
import { IrisApiError } from "@iris-mcp/shared";
|
|
41
|
+
import { z } from "zod";
|
|
42
|
+
/** Base URL for the IRIS DocDB REST API. */
|
|
43
|
+
const BASE_DOCDB_URL = "/api/docdb/v1";
|
|
44
|
+
/** Base URL for the custom ExecuteMCPv2 REST service (service-state probes). */
|
|
45
|
+
const BASE_EXECUTEMCP_URL = "/api/executemcp/v2";
|
|
46
|
+
/**
|
|
47
|
+
* Map from MongoDB-style comparison operator to IRIS DocDB SQL operator.
|
|
48
|
+
* Source: %DocDB.Database.generatePredicate() — the supported set is
|
|
49
|
+
* =, !=, <, >, <=, >=, <>, %STARTSWITH, NULL, NOT NULL, IN.
|
|
50
|
+
*/
|
|
51
|
+
const MONGO_OP_MAP = {
|
|
52
|
+
$eq: "=",
|
|
53
|
+
$ne: "!=",
|
|
54
|
+
$lt: "<",
|
|
55
|
+
$lte: "<=",
|
|
56
|
+
$gt: ">",
|
|
57
|
+
$gte: ">=",
|
|
58
|
+
};
|
|
59
|
+
/**
|
|
60
|
+
* Translate a MongoDB-style filter object to a DocDB restriction value.
|
|
61
|
+
*
|
|
62
|
+
* The DocDB `%FindDocuments()` method accepts a `restriction` argument that
|
|
63
|
+
* is either:
|
|
64
|
+
* - A single predicate array: `[field, value, operator]`
|
|
65
|
+
* - An array of predicate arrays for AND-combination: `[[f1,v1,op1],[f2,v2,op2]]`
|
|
66
|
+
*
|
|
67
|
+
* This function converts:
|
|
68
|
+
* ```json
|
|
69
|
+
* { "age": { "$gt": 26 }, "name": { "$eq": "Alice" } }
|
|
70
|
+
* ```
|
|
71
|
+
* to:
|
|
72
|
+
* ```json
|
|
73
|
+
* [["age", 26, ">"], ["name", "Alice", "="]]
|
|
74
|
+
* ```
|
|
75
|
+
* A single predicate is returned as a flat `[field, value, operator]` array
|
|
76
|
+
* (not nested) per the DocDB API contract.
|
|
77
|
+
*
|
|
78
|
+
* Unsupported operators are silently skipped.
|
|
79
|
+
*
|
|
80
|
+
* @param filter - The MongoDB-style filter object.
|
|
81
|
+
* @returns The DocDB restriction value, or `null` if no predicates could be built.
|
|
82
|
+
*/
|
|
83
|
+
export function buildDocDbRestriction(filter) {
|
|
84
|
+
const predicates = [];
|
|
85
|
+
for (const [field, condition] of Object.entries(filter)) {
|
|
86
|
+
if (condition !== null &&
|
|
87
|
+
typeof condition === "object" &&
|
|
88
|
+
!Array.isArray(condition)) {
|
|
89
|
+
const condObj = condition;
|
|
90
|
+
for (const [mongoOp, value] of Object.entries(condObj)) {
|
|
91
|
+
const docdbOp = MONGO_OP_MAP[mongoOp];
|
|
92
|
+
if (docdbOp !== undefined) {
|
|
93
|
+
predicates.push([field, value, docdbOp]);
|
|
94
|
+
}
|
|
95
|
+
// Unknown operators are silently skipped — the caller will get all docs
|
|
96
|
+
}
|
|
97
|
+
}
|
|
98
|
+
else {
|
|
99
|
+
// Plain equality: { field: value }
|
|
100
|
+
predicates.push([field, condition, "="]);
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
if (predicates.length === 0)
|
|
104
|
+
return null;
|
|
105
|
+
if (predicates.length === 1)
|
|
106
|
+
return predicates[0];
|
|
107
|
+
return predicates;
|
|
108
|
+
}
|
|
109
|
+
/**
|
|
110
|
+
* Extract the usable result from a DocDB API response.
|
|
111
|
+
*
|
|
112
|
+
* The {@link IrisHttpClient} casts every JSON response to
|
|
113
|
+
* `AtelierEnvelope<T>`, but the DocDB API returns plain JSON
|
|
114
|
+
* (no `{status, console, result}` wrapper). When the response
|
|
115
|
+
* lacks the Atelier envelope, `.result` is `undefined` and the
|
|
116
|
+
* actual data sits at the top level of the parsed object.
|
|
117
|
+
*
|
|
118
|
+
* @param response - The parsed response from `ctx.http.*`.
|
|
119
|
+
* @returns The actual data payload.
|
|
120
|
+
*/
|
|
121
|
+
export function extractResult(response) {
|
|
122
|
+
if (response !== null &&
|
|
123
|
+
typeof response === "object" &&
|
|
124
|
+
"result" in response &&
|
|
125
|
+
response.result !== undefined) {
|
|
126
|
+
return response.result;
|
|
127
|
+
}
|
|
128
|
+
return response;
|
|
129
|
+
}
|
|
130
|
+
/**
|
|
131
|
+
* Ensure a value is a record suitable for MCP `structuredContent`.
|
|
132
|
+
* MCP requires structuredContent to be a JSON object (record), not an array.
|
|
133
|
+
* Arrays are wrapped in `{ items, count }`.
|
|
134
|
+
*/
|
|
135
|
+
export function toStructured(value) {
|
|
136
|
+
if (Array.isArray(value)) {
|
|
137
|
+
return { items: value, count: value.length };
|
|
138
|
+
}
|
|
139
|
+
if (value !== null && typeof value === "object") {
|
|
140
|
+
return value;
|
|
141
|
+
}
|
|
142
|
+
return { value };
|
|
143
|
+
}
|
|
144
|
+
// ── %Service_DocDB gate translation (Story 35.7) ───────────────
|
|
145
|
+
/**
|
|
146
|
+
* IRIS error code for "Access Denied" (ERROR #822). The numeric code is
|
|
147
|
+
* locale-stable — the message text is NOT (Rules #8/#13: IRIS localizes
|
|
148
|
+
* error prefixes/text), so detection keys on `code` only.
|
|
149
|
+
*
|
|
150
|
+
* Code 822 is SHARED between a disabled `%Service_DocDB` and a genuine
|
|
151
|
+
* privilege failure (lead live probe, 2026-08-19: `_SYSTEM` holding `%All`
|
|
152
|
+
* still receives 822 when the service is off), so the code alone is never
|
|
153
|
+
* a sufficient discriminator (Rule #54) — the live service state is.
|
|
154
|
+
*/
|
|
155
|
+
const IRIS_ERROR_CODE_ACCESS_DENIED = 822;
|
|
156
|
+
/** The DocDB gateway service — disabled by default on IRIS. */
|
|
157
|
+
const DOCDB_SERVICE_NAME = "%Service_DocDB";
|
|
158
|
+
/**
|
|
159
|
+
* Translate a DocDB access-denied failure into an actionable error message
|
|
160
|
+
* when the root cause is a disabled `%Service_DocDB` (Story 35.7,
|
|
161
|
+
* AC 35.7.1/35.7.3/35.7.4).
|
|
162
|
+
*
|
|
163
|
+
* Returns the enriched message when (and only when) ALL of the following
|
|
164
|
+
* hold; returns `null` (caller passes the original error through unchanged)
|
|
165
|
+
* otherwise:
|
|
166
|
+
*
|
|
167
|
+
* - the error carries an `errors[]` entry with numeric `code === 822`
|
|
168
|
+
* (the real disabled-service shape is HTTP 200 with a code-822 object in
|
|
169
|
+
* `status.errors[]` — never match message text, never branch on the HTTP
|
|
170
|
+
* status); AND
|
|
171
|
+
* - a follow-up `GET /api/executemcp/v2/security/service?name=...` reports
|
|
172
|
+
* `%Service_DocDB` as `enabled: false`.
|
|
173
|
+
*
|
|
174
|
+
* Pass-through is total: service enabled (genuine privilege failure),
|
|
175
|
+
* service-state check itself failing, unexpected response shape, or a
|
|
176
|
+
* non-822 error all return `null` — a secondary failure must never mask
|
|
177
|
+
* the real error.
|
|
178
|
+
*
|
|
179
|
+
* This is a catch-path translation, not a pre-check: the extra round-trip
|
|
180
|
+
* happens only when a call has already failed with 822.
|
|
181
|
+
*
|
|
182
|
+
* @param ctx - Tool context (used for the single service-state follow-up).
|
|
183
|
+
* @param error - The `IrisApiError` thrown by the DocDB call.
|
|
184
|
+
* @returns The actionable message, or `null` for pass-through.
|
|
185
|
+
*/
|
|
186
|
+
export async function translateDocDbAccessDenied(ctx, error) {
|
|
187
|
+
// The runtime cast in http-client.ts passes envelope.status.errors through
|
|
188
|
+
// whenever it has a length — a non-empty STRING satisfies that check, so
|
|
189
|
+
// `errors` can be a non-array here despite the unknown[] type (the shared
|
|
190
|
+
// formatIrisErrors guards the same shape). Guard before .some so a
|
|
191
|
+
// malformed error can never throw out of the caller's catch path.
|
|
192
|
+
const hasAccessDenied = Array.isArray(error.errors) &&
|
|
193
|
+
error.errors.some((entry) => entry !== null &&
|
|
194
|
+
typeof entry === "object" &&
|
|
195
|
+
entry.code ===
|
|
196
|
+
IRIS_ERROR_CODE_ACCESS_DENIED);
|
|
197
|
+
if (!hasAccessDenied)
|
|
198
|
+
return null;
|
|
199
|
+
let enabled;
|
|
200
|
+
try {
|
|
201
|
+
const response = await ctx.http.get(`${BASE_EXECUTEMCP_URL}/security/service?name=${encodeURIComponent(DOCDB_SERVICE_NAME)}`);
|
|
202
|
+
const result = response.result;
|
|
203
|
+
enabled =
|
|
204
|
+
result !== null && typeof result === "object"
|
|
205
|
+
? result.enabled
|
|
206
|
+
: undefined;
|
|
207
|
+
}
|
|
208
|
+
catch {
|
|
209
|
+
// The service-state check itself failed — never mask the original error.
|
|
210
|
+
return null;
|
|
211
|
+
}
|
|
212
|
+
if (enabled !== false) {
|
|
213
|
+
// Service enabled (genuine privilege/other failure) or an unexpected
|
|
214
|
+
// response shape — pass the original error through unchanged.
|
|
215
|
+
return null;
|
|
216
|
+
}
|
|
217
|
+
return (`ERROR #822: Access Denied — this usually means the ${DOCDB_SERVICE_NAME} ` +
|
|
218
|
+
`service is disabled (it is disabled by default on IRIS). Checked live: ` +
|
|
219
|
+
`${DOCDB_SERVICE_NAME} is currently DISABLED on this instance. ` +
|
|
220
|
+
`To fix: enable it in the Management Portal (System Administration > ` +
|
|
221
|
+
`Security > Services > ${DOCDB_SERVICE_NAME}), or via the ` +
|
|
222
|
+
`iris_service_manage tool (in the @iris-mcp/admin server) with ` +
|
|
223
|
+
`action="enable" and ` +
|
|
224
|
+
`name="${DOCDB_SERVICE_NAME}" — note that action is itself ` +
|
|
225
|
+
`governance-default-disabled and needs an IRIS_GOVERNANCE override such ` +
|
|
226
|
+
`as {"global": {"iris_service_manage:enable": true}}. ` +
|
|
227
|
+
`Original error: ${error.message}`);
|
|
228
|
+
}
|
|
229
|
+
// ── iris_docdb_manage ──────────────────────────────────────────
|
|
230
|
+
export const docdbManageTool = {
|
|
231
|
+
name: "iris_docdb_manage",
|
|
232
|
+
title: "Manage Document Database",
|
|
233
|
+
description: "Create, drop, or list IRIS document databases. " +
|
|
234
|
+
"'list' returns all DocDB databases in the namespace. " +
|
|
235
|
+
"'create' creates a new document database with optional property definitions. " +
|
|
236
|
+
"'drop' permanently removes a document database and all its data. " +
|
|
237
|
+
"Prerequisite: the %Service_DocDB service must be enabled on the instance " +
|
|
238
|
+
"(it is disabled by default on IRIS) — a disabled service fails these calls " +
|
|
239
|
+
"with ERROR #822: Access Denied.",
|
|
240
|
+
inputSchema: z.object({
|
|
241
|
+
action: z
|
|
242
|
+
.enum(["list", "create", "drop"])
|
|
243
|
+
.describe("Action to perform: 'list', 'create', or 'drop'"),
|
|
244
|
+
database: z
|
|
245
|
+
.string()
|
|
246
|
+
.min(1)
|
|
247
|
+
.optional()
|
|
248
|
+
.describe("Database name (required for 'create' and 'drop')"),
|
|
249
|
+
namespace: z
|
|
250
|
+
.string()
|
|
251
|
+
.optional()
|
|
252
|
+
.describe("Target namespace (default: configured namespace)"),
|
|
253
|
+
}),
|
|
254
|
+
annotations: {
|
|
255
|
+
destructiveHint: true,
|
|
256
|
+
readOnlyHint: false,
|
|
257
|
+
idempotentHint: false,
|
|
258
|
+
openWorldHint: false,
|
|
259
|
+
},
|
|
260
|
+
scope: "NS",
|
|
261
|
+
handler: async (args, ctx) => {
|
|
262
|
+
const { action, database, namespace } = args;
|
|
263
|
+
const ns = ctx.resolveNamespace(namespace);
|
|
264
|
+
try {
|
|
265
|
+
let response;
|
|
266
|
+
if (action === "list") {
|
|
267
|
+
response = await ctx.http.get(`${BASE_DOCDB_URL}/${encodeURIComponent(ns)}`);
|
|
268
|
+
}
|
|
269
|
+
else if (action === "create") {
|
|
270
|
+
if (!database) {
|
|
271
|
+
return {
|
|
272
|
+
content: [
|
|
273
|
+
{
|
|
274
|
+
type: "text",
|
|
275
|
+
text: "Error: 'database' is required for 'create' action",
|
|
276
|
+
},
|
|
277
|
+
],
|
|
278
|
+
isError: true,
|
|
279
|
+
};
|
|
280
|
+
}
|
|
281
|
+
response = await ctx.http.post(`${BASE_DOCDB_URL}/${encodeURIComponent(ns)}/db/${encodeURIComponent(database)}`, {});
|
|
282
|
+
}
|
|
283
|
+
else {
|
|
284
|
+
// drop
|
|
285
|
+
if (!database) {
|
|
286
|
+
return {
|
|
287
|
+
content: [
|
|
288
|
+
{
|
|
289
|
+
type: "text",
|
|
290
|
+
text: "Error: 'database' is required for 'drop' action",
|
|
291
|
+
},
|
|
292
|
+
],
|
|
293
|
+
isError: true,
|
|
294
|
+
};
|
|
295
|
+
}
|
|
296
|
+
response = await ctx.http.delete(`${BASE_DOCDB_URL}/${encodeURIComponent(ns)}/db/${encodeURIComponent(database)}`);
|
|
297
|
+
}
|
|
298
|
+
const result = extractResult(response);
|
|
299
|
+
return {
|
|
300
|
+
content: [
|
|
301
|
+
{ type: "text", text: JSON.stringify(result, null, 2) },
|
|
302
|
+
],
|
|
303
|
+
structuredContent: toStructured(result),
|
|
304
|
+
};
|
|
305
|
+
}
|
|
306
|
+
catch (error) {
|
|
307
|
+
if (error instanceof IrisApiError) {
|
|
308
|
+
// Story 35.7: a disabled %Service_DocDB surfaces as ERROR #822 —
|
|
309
|
+
// translate it into an actionable message (pass-through otherwise).
|
|
310
|
+
const gateMessage = await translateDocDbAccessDenied(ctx, error);
|
|
311
|
+
return {
|
|
312
|
+
content: [
|
|
313
|
+
{
|
|
314
|
+
type: "text",
|
|
315
|
+
text: gateMessage ?? `Error managing DocDB database: ${error.message}`,
|
|
316
|
+
},
|
|
317
|
+
],
|
|
318
|
+
isError: true,
|
|
319
|
+
};
|
|
320
|
+
}
|
|
321
|
+
throw error;
|
|
322
|
+
}
|
|
323
|
+
},
|
|
324
|
+
};
|
|
325
|
+
// ── iris_docdb_document ────────────────────────────────────────
|
|
326
|
+
export const docdbDocumentTool = {
|
|
327
|
+
name: "iris_docdb_document",
|
|
328
|
+
title: "Manage Document",
|
|
329
|
+
description: "Insert, get, update, or delete a document in an IRIS document database. " +
|
|
330
|
+
"'insert' adds a new document and returns its generated ID. " +
|
|
331
|
+
"'get' retrieves a document by ID. " +
|
|
332
|
+
"'update' replaces a document by ID. " +
|
|
333
|
+
"'delete' removes a document by ID. " +
|
|
334
|
+
"Prerequisite: the %Service_DocDB service must be enabled on the instance " +
|
|
335
|
+
"(it is disabled by default on IRIS) — a disabled service fails these calls " +
|
|
336
|
+
"with ERROR #822: Access Denied.",
|
|
337
|
+
inputSchema: z.object({
|
|
338
|
+
action: z
|
|
339
|
+
.enum(["insert", "get", "update", "delete"])
|
|
340
|
+
.describe("Action to perform: 'insert', 'get', 'update', or 'delete'"),
|
|
341
|
+
database: z.string().min(1).describe("Document database name"),
|
|
342
|
+
id: z
|
|
343
|
+
.string()
|
|
344
|
+
.min(1)
|
|
345
|
+
.optional()
|
|
346
|
+
.describe("Document ID (required for 'get', 'update', 'delete')"),
|
|
347
|
+
document: z
|
|
348
|
+
.record(z.string(), z.unknown())
|
|
349
|
+
.optional()
|
|
350
|
+
.describe("Document content as JSON (required for 'insert' and 'update')"),
|
|
351
|
+
namespace: z
|
|
352
|
+
.string()
|
|
353
|
+
.optional()
|
|
354
|
+
.describe("Target namespace (default: configured namespace)"),
|
|
355
|
+
}),
|
|
356
|
+
annotations: {
|
|
357
|
+
destructiveHint: true,
|
|
358
|
+
readOnlyHint: false,
|
|
359
|
+
idempotentHint: false,
|
|
360
|
+
openWorldHint: false,
|
|
361
|
+
},
|
|
362
|
+
scope: "NS",
|
|
363
|
+
handler: async (args, ctx) => {
|
|
364
|
+
const { action, database, id, document, namespace } = args;
|
|
365
|
+
const ns = ctx.resolveNamespace(namespace);
|
|
366
|
+
const dbPath = `${BASE_DOCDB_URL}/${encodeURIComponent(ns)}/doc/${encodeURIComponent(database)}`;
|
|
367
|
+
try {
|
|
368
|
+
let response;
|
|
369
|
+
if (action === "insert") {
|
|
370
|
+
if (!document) {
|
|
371
|
+
return {
|
|
372
|
+
content: [
|
|
373
|
+
{
|
|
374
|
+
type: "text",
|
|
375
|
+
text: "Error: 'document' is required for 'insert' action",
|
|
376
|
+
},
|
|
377
|
+
],
|
|
378
|
+
isError: true,
|
|
379
|
+
};
|
|
380
|
+
}
|
|
381
|
+
response = await ctx.http.post(`${dbPath}/`, document);
|
|
382
|
+
}
|
|
383
|
+
else if (action === "get") {
|
|
384
|
+
if (!id) {
|
|
385
|
+
return {
|
|
386
|
+
content: [
|
|
387
|
+
{
|
|
388
|
+
type: "text",
|
|
389
|
+
text: "Error: 'id' is required for 'get' action",
|
|
390
|
+
},
|
|
391
|
+
],
|
|
392
|
+
isError: true,
|
|
393
|
+
};
|
|
394
|
+
}
|
|
395
|
+
response = await ctx.http.get(`${dbPath}/${encodeURIComponent(id)}`);
|
|
396
|
+
}
|
|
397
|
+
else if (action === "update") {
|
|
398
|
+
if (!id) {
|
|
399
|
+
return {
|
|
400
|
+
content: [
|
|
401
|
+
{
|
|
402
|
+
type: "text",
|
|
403
|
+
text: "Error: 'id' is required for 'update' action",
|
|
404
|
+
},
|
|
405
|
+
],
|
|
406
|
+
isError: true,
|
|
407
|
+
};
|
|
408
|
+
}
|
|
409
|
+
if (!document) {
|
|
410
|
+
return {
|
|
411
|
+
content: [
|
|
412
|
+
{
|
|
413
|
+
type: "text",
|
|
414
|
+
text: "Error: 'document' is required for 'update' action",
|
|
415
|
+
},
|
|
416
|
+
],
|
|
417
|
+
isError: true,
|
|
418
|
+
};
|
|
419
|
+
}
|
|
420
|
+
response = await ctx.http.put(`${dbPath}/${encodeURIComponent(id)}`, document);
|
|
421
|
+
}
|
|
422
|
+
else {
|
|
423
|
+
// delete
|
|
424
|
+
if (!id) {
|
|
425
|
+
return {
|
|
426
|
+
content: [
|
|
427
|
+
{
|
|
428
|
+
type: "text",
|
|
429
|
+
text: "Error: 'id' is required for 'delete' action",
|
|
430
|
+
},
|
|
431
|
+
],
|
|
432
|
+
isError: true,
|
|
433
|
+
};
|
|
434
|
+
}
|
|
435
|
+
response = await ctx.http.delete(`${dbPath}/${encodeURIComponent(id)}`);
|
|
436
|
+
}
|
|
437
|
+
const result = extractResult(response);
|
|
438
|
+
return {
|
|
439
|
+
content: [
|
|
440
|
+
{ type: "text", text: JSON.stringify(result, null, 2) },
|
|
441
|
+
],
|
|
442
|
+
structuredContent: toStructured(result),
|
|
443
|
+
};
|
|
444
|
+
}
|
|
445
|
+
catch (error) {
|
|
446
|
+
if (error instanceof IrisApiError) {
|
|
447
|
+
// Story 35.7: a disabled %Service_DocDB surfaces as ERROR #822 —
|
|
448
|
+
// translate it into an actionable message (pass-through otherwise).
|
|
449
|
+
const gateMessage = await translateDocDbAccessDenied(ctx, error);
|
|
450
|
+
return {
|
|
451
|
+
content: [
|
|
452
|
+
{
|
|
453
|
+
type: "text",
|
|
454
|
+
text: gateMessage ?? `Error managing document: ${error.message}`,
|
|
455
|
+
},
|
|
456
|
+
],
|
|
457
|
+
isError: true,
|
|
458
|
+
};
|
|
459
|
+
}
|
|
460
|
+
throw error;
|
|
461
|
+
}
|
|
462
|
+
},
|
|
463
|
+
};
|
|
464
|
+
// ── iris_docdb_find ────────────────────────────────────────────
|
|
465
|
+
export const docdbFindTool = {
|
|
466
|
+
name: "iris_docdb_find",
|
|
467
|
+
title: "Find Documents",
|
|
468
|
+
description: "Query documents in an IRIS document database using filter criteria. " +
|
|
469
|
+
"Supports comparison operators ($eq, $lt, $gt, $ne, $lte, $gte) " +
|
|
470
|
+
"and returns matching documents. " +
|
|
471
|
+
"Prerequisite: the %Service_DocDB service must be enabled on the instance " +
|
|
472
|
+
"(it is disabled by default on IRIS) — a disabled service fails these calls " +
|
|
473
|
+
"with ERROR #822: Access Denied.",
|
|
474
|
+
inputSchema: z.object({
|
|
475
|
+
database: z.string().min(1).describe("Document database name"),
|
|
476
|
+
filter: z
|
|
477
|
+
.record(z.string(), z.unknown())
|
|
478
|
+
.describe("Filter criteria as JSON with comparison operators (e.g., { \"age\": { \"$gt\": 21 } })"),
|
|
479
|
+
namespace: z
|
|
480
|
+
.string()
|
|
481
|
+
.optional()
|
|
482
|
+
.describe("Target namespace (default: configured namespace)"),
|
|
483
|
+
}),
|
|
484
|
+
annotations: {
|
|
485
|
+
readOnlyHint: true,
|
|
486
|
+
destructiveHint: false,
|
|
487
|
+
idempotentHint: true,
|
|
488
|
+
openWorldHint: false,
|
|
489
|
+
},
|
|
490
|
+
scope: "NS",
|
|
491
|
+
handler: async (args, ctx) => {
|
|
492
|
+
const { database, filter, namespace } = args;
|
|
493
|
+
const ns = ctx.resolveNamespace(namespace);
|
|
494
|
+
try {
|
|
495
|
+
// Translate MongoDB-style filter to DocDB restriction format.
|
|
496
|
+
// The DocDB /find/ endpoint reads requestBody.restriction (not a flat filter).
|
|
497
|
+
// restriction is a predicate array [field, value, operator] or an array of
|
|
498
|
+
// such arrays for AND-combination (from %DocDB.Database.%FindDocuments docs).
|
|
499
|
+
const restriction = buildDocDbRestriction(filter);
|
|
500
|
+
const findBody = {};
|
|
501
|
+
if (restriction !== null) {
|
|
502
|
+
findBody.restriction = restriction;
|
|
503
|
+
}
|
|
504
|
+
const response = await ctx.http.post(`${BASE_DOCDB_URL}/${encodeURIComponent(ns)}/find/${encodeURIComponent(database)}`, findBody);
|
|
505
|
+
const result = extractResult(response);
|
|
506
|
+
return {
|
|
507
|
+
content: [
|
|
508
|
+
{ type: "text", text: JSON.stringify(result, null, 2) },
|
|
509
|
+
],
|
|
510
|
+
structuredContent: toStructured(result),
|
|
511
|
+
};
|
|
512
|
+
}
|
|
513
|
+
catch (error) {
|
|
514
|
+
if (error instanceof IrisApiError) {
|
|
515
|
+
// Story 35.7: a disabled %Service_DocDB surfaces as ERROR #822 —
|
|
516
|
+
// translate it into an actionable message (pass-through otherwise).
|
|
517
|
+
const gateMessage = await translateDocDbAccessDenied(ctx, error);
|
|
518
|
+
return {
|
|
519
|
+
content: [
|
|
520
|
+
{
|
|
521
|
+
type: "text",
|
|
522
|
+
text: gateMessage ?? `Error querying documents: ${error.message}`,
|
|
523
|
+
},
|
|
524
|
+
],
|
|
525
|
+
isError: true,
|
|
526
|
+
};
|
|
527
|
+
}
|
|
528
|
+
throw error;
|
|
529
|
+
}
|
|
530
|
+
},
|
|
531
|
+
};
|
|
532
|
+
// ── iris_docdb_property ────────────────────────────────────────
|
|
533
|
+
export const docdbPropertyTool = {
|
|
534
|
+
name: "iris_docdb_property",
|
|
535
|
+
title: "Manage Document Property",
|
|
536
|
+
description: "Create, drop, or index a property on an IRIS document database. " +
|
|
537
|
+
"'create' defines a new property with a specified type. " +
|
|
538
|
+
"'drop' removes a property definition. " +
|
|
539
|
+
"'index' creates an index on a property for faster queries. " +
|
|
540
|
+
"Prerequisite: the %Service_DocDB service must be enabled on the instance " +
|
|
541
|
+
"(it is disabled by default on IRIS) — a disabled service fails these calls " +
|
|
542
|
+
"with ERROR #822: Access Denied.",
|
|
543
|
+
inputSchema: z.object({
|
|
544
|
+
action: z
|
|
545
|
+
.enum(["create", "drop", "index"])
|
|
546
|
+
.describe("Action to perform: 'create', 'drop', or 'index'"),
|
|
547
|
+
database: z.string().min(1).describe("Document database name"),
|
|
548
|
+
property: z.string().min(1).describe("Property name"),
|
|
549
|
+
type: z
|
|
550
|
+
.string()
|
|
551
|
+
.optional()
|
|
552
|
+
.describe("Property type (required for 'create', e.g., '%String', '%Integer')"),
|
|
553
|
+
namespace: z
|
|
554
|
+
.string()
|
|
555
|
+
.optional()
|
|
556
|
+
.describe("Target namespace (default: configured namespace)"),
|
|
557
|
+
}),
|
|
558
|
+
annotations: {
|
|
559
|
+
destructiveHint: true,
|
|
560
|
+
readOnlyHint: false,
|
|
561
|
+
idempotentHint: false,
|
|
562
|
+
openWorldHint: false,
|
|
563
|
+
},
|
|
564
|
+
scope: "NS",
|
|
565
|
+
handler: async (args, ctx) => {
|
|
566
|
+
const { action, database, property, type, namespace } = args;
|
|
567
|
+
const ns = ctx.resolveNamespace(namespace);
|
|
568
|
+
const propPath = `${BASE_DOCDB_URL}/${encodeURIComponent(ns)}/prop/${encodeURIComponent(database)}/${encodeURIComponent(property)}`;
|
|
569
|
+
try {
|
|
570
|
+
let response;
|
|
571
|
+
if (action === "create") {
|
|
572
|
+
if (!type) {
|
|
573
|
+
return {
|
|
574
|
+
content: [
|
|
575
|
+
{
|
|
576
|
+
type: "text",
|
|
577
|
+
text: "Error: 'type' is required for 'create' action",
|
|
578
|
+
},
|
|
579
|
+
],
|
|
580
|
+
isError: true,
|
|
581
|
+
};
|
|
582
|
+
}
|
|
583
|
+
// The DocDB httpPostProperty handler reads `type` from %request.Data("type",1),
|
|
584
|
+
// which is a URL query parameter — NOT from the JSON body. Sending the type
|
|
585
|
+
// in the body is silently ignored and the server defaults to %String. Fix:
|
|
586
|
+
// append ?type=<encoded> to the URL and send an empty body (BUG-5).
|
|
587
|
+
//
|
|
588
|
+
// ENCODING NOTE: IRIS type names begin with "%" (e.g. "%Integer", "%Library.String").
|
|
589
|
+
// encodeURIComponent("%Integer") → "%25Integer", but the IRIS CSP layer does NOT
|
|
590
|
+
// URL-decode %XX sequences in %request.Data query param values — it reads "%25Integer"
|
|
591
|
+
// literally, causing class lookup for "%Library.25Integer" to fail.
|
|
592
|
+
// Fix: split on "%" and encode each segment individually, then rejoin with bare "%".
|
|
593
|
+
// This keeps IRIS type % prefixes as literal "%" while still encoding any other
|
|
594
|
+
// special characters that might appear in a type name.
|
|
595
|
+
// Verified via %Net.HttpRequest probe: "?type=%Integer" → StoredType: %Library.Integer.
|
|
596
|
+
const encodedType = type
|
|
597
|
+
.split("%")
|
|
598
|
+
.map((part) => encodeURIComponent(part))
|
|
599
|
+
.join("%");
|
|
600
|
+
response = await ctx.http.post(`${propPath}?type=${encodedType}`, {});
|
|
601
|
+
}
|
|
602
|
+
else if (action === "drop") {
|
|
603
|
+
response = await ctx.http.delete(propPath);
|
|
604
|
+
}
|
|
605
|
+
else {
|
|
606
|
+
// index
|
|
607
|
+
response = await ctx.http.post(propPath, { index: true });
|
|
608
|
+
}
|
|
609
|
+
const result = extractResult(response);
|
|
610
|
+
return {
|
|
611
|
+
content: [
|
|
612
|
+
{ type: "text", text: JSON.stringify(result, null, 2) },
|
|
613
|
+
],
|
|
614
|
+
structuredContent: toStructured(result),
|
|
615
|
+
};
|
|
616
|
+
}
|
|
617
|
+
catch (error) {
|
|
618
|
+
if (error instanceof IrisApiError) {
|
|
619
|
+
// Story 35.7: a disabled %Service_DocDB surfaces as ERROR #822 —
|
|
620
|
+
// translate it into an actionable message (pass-through otherwise).
|
|
621
|
+
const gateMessage = await translateDocDbAccessDenied(ctx, error);
|
|
622
|
+
return {
|
|
623
|
+
content: [
|
|
624
|
+
{
|
|
625
|
+
type: "text",
|
|
626
|
+
text: gateMessage ??
|
|
627
|
+
`Error managing property '${property}': ${error.message}`,
|
|
628
|
+
},
|
|
629
|
+
],
|
|
630
|
+
isError: true,
|
|
631
|
+
};
|
|
632
|
+
}
|
|
633
|
+
throw error;
|
|
634
|
+
}
|
|
635
|
+
},
|
|
636
|
+
};
|
|
637
|
+
//# sourceMappingURL=docdb.js.map
|
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tool definitions for the IRIS Data & Analytics MCP server.
|
|
3
|
+
*
|
|
4
|
+
* Exports all tool definitions to be registered with
|
|
5
|
+
* {@link McpServerBase}. Stories 7.2-7.4 populate this array
|
|
6
|
+
* with data, analytics, and REST management tools.
|
|
7
|
+
*/
|
|
8
|
+
import type { ToolDefinition } from "@iris-mcp/shared";
|
|
9
|
+
/** All tool definitions registered by the iris-data-mcp server. */
|
|
10
|
+
export declare const tools: ToolDefinition[];
|
|
11
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Tool definitions for the IRIS Data & Analytics MCP server.
|
|
3
|
+
*
|
|
4
|
+
* Exports all tool definitions to be registered with
|
|
5
|
+
* {@link McpServerBase}. Stories 7.2-7.4 populate this array
|
|
6
|
+
* with data, analytics, and REST management tools.
|
|
7
|
+
*/
|
|
8
|
+
import { docdbManageTool, docdbDocumentTool, docdbFindTool, docdbPropertyTool, } from "./docdb.js";
|
|
9
|
+
import { analyticsMdxTool, analyticsCubesTool } from "./analytics.js";
|
|
10
|
+
import { restManageTool } from "./rest.js";
|
|
11
|
+
/** All tool definitions registered by the iris-data-mcp server. */
|
|
12
|
+
export const tools = [
|
|
13
|
+
docdbManageTool,
|
|
14
|
+
docdbDocumentTool,
|
|
15
|
+
docdbFindTool,
|
|
16
|
+
docdbPropertyTool,
|
|
17
|
+
analyticsMdxTool,
|
|
18
|
+
analyticsCubesTool,
|
|
19
|
+
restManageTool,
|
|
20
|
+
];
|
|
21
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1,16 @@
|
|
|
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
|
+
import type { ToolPresetRosters } from "@iris-mcp/shared";
|
|
14
|
+
/** data-mcp's `core`/`developer` visibility rosters (§2.5) — full inclusion for both. */
|
|
15
|
+
export declare const toolPresets: ToolPresetRosters;
|
|
16
|
+
//# sourceMappingURL=presets.d.ts.map
|