@digital-science-dsl/dimensions-analytics-mcp 1.1.0 → 1.3.0

package/dist/mcp/tools/similar-documents.js

@@ -0,0 +1,166 @@
+import { z } from "zod";
+import { applyFilters, ExtendedWhereFilterSchema, parseEntityResponse, resolveSkipAndLimit, SCHEMA_LIMITS, searchResultKey, validateSearchPaginationPolicy, } from "../../dsl/index.js";
+import { withFieldAliases } from "../middleware/field-aliases.js";
+import { registerTrackedTool } from "../usage-tracking.js";
+import { formatErrorResult, formatToolResult, READ_ONLY_API_ANNOTATIONS, withSearchPagination, } from "../utils.js";
+import { PAGINATION_INPUT_SCHEMA, PAGINATION_OUTPUT_SCHEMA } from "./search-input.js";
+/** Entity types that support the DSL similar_documents() search function. */
+export const SIMILAR_DOCUMENTS_ENTITY_TYPES = ["publications", "grants"];
+/** Year filter field per entity (publications use year; grants use start_year). */
+const YEAR_FIELD = {
+    publications: "year",
+    grants: "start_year",
+};
+/**
+ * Builds DSL for a similar_documents search from tool arguments.
+ * @param client - Dimensions client
+ * @param entityType - publications or grants
+ * @param args - Tool arguments (after field-alias resolution)
+ * @returns DSL query string
+ */
+export function buildSimilarDocumentsDsl(client, entityType, args) {
+    const text = String(args.text ?? "");
+    const builder = client.createQueryBuilder().search(entityType).forSimilar(text);
+    const yearField = YEAR_FIELD[entityType];
+    if (typeof args.yearFrom === "number") {
+        builder.where(yearField, ">=", args.yearFrom);
+    }
+    if (typeof args.yearTo === "number") {
+        builder.where(yearField, "<=", args.yearTo);
+    }
+    const filters = args.filters;
+    if (filters?.length) {
+        applyFilters(builder, filters);
+    }
+    const fields = args.fields;
+    if (fields?.length) {
+        builder.fields(fields);
+    }
+    const sortBy = typeof args.sortBy === "string" ? args.sortBy : "score";
+    builder.sort(sortBy, "desc");
+    // Default to 20 for similarity (top-N relevance), not the search_* default of 100.
+    const { skip, limit } = resolveSkipAndLimit({
+        skip: args.skip,
+        page: args.page,
+        limit: args.limit ?? 20,
+        pageSize: args.pageSize,
+    });
+    builder.limit(limit);
+    if (skip > 0) {
+        builder.skip(skip);
+    }
+    return builder.build();
+}
+/**
+ * Registers the similar_documents tool with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export function registerSimilarDocumentsTool(server, client) {
+    registerTrackedTool(server, "similar_documents", {
+        description: "Find publications or grants with similar research topics based on abstract/description text. " +
+            "Uses Dimensions concept extraction and weighted concepts search (not vector embeddings). " +
+            "Prefer this over execute_dsl for similarity. For a known record: get_by_id / get_by_doi first, " +
+            "then pass its abstract/description as text. Supported entityType: publications, grants only.",
+        inputSchema: z.object({
+            entityType: z
+                .enum(SIMILAR_DOCUMENTS_ENTITY_TYPES)
+                .describe("Entity type to search (publications or grants)"),
+            text: z
+                .string()
+                .min(1)
+                .describe("Abstract, description, or other prose to find similar documents for. " +
+                "Longer topical text works better than short keywords."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(SCHEMA_LIMITS.maxLimit)
+                .default(20)
+                .describe(`Maximum results to return (max ${SCHEMA_LIMITS.maxLimit}, default 20)`),
+            ...PAGINATION_INPUT_SCHEMA,
+            fields: z
+                .array(z.string())
+                .optional()
+                .describe("Fields to return. Accepts aliases or DSL names. Use dimensions://fields/{entity} for the full list."),
+            filters: z
+                .array(ExtendedWhereFilterSchema)
+                .optional()
+                .describe("Additional where-clause filters"),
+            yearFrom: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter from this year inclusive (publications: year; grants: start_year)"),
+            yearTo: z
+                .number()
+                .int()
+                .optional()
+                .describe("Filter up to this year inclusive (publications: year; grants: start_year)"),
+            sortBy: z
+                .string()
+                .optional()
+                .describe("Sort field (default: score for relevance). Examples: score, times_cited, year, start_year."),
+            confirmLargeFetch: z
+                .boolean()
+                .optional()
+                .default(false)
+                .describe("Required when skip≥5000, page≥5, or limit=1000 with skip>0. See dimensions://schema/policy."),
+        }),
+        outputSchema: z.object({
+            entityType: z.enum(SIMILAR_DOCUMENTS_ENTITY_TYPES).describe("Entity type searched"),
+            totalCount: z.number().describe("Total matching records"),
+            returnedCount: z.number().describe("Records returned in this response"),
+            truncated: z.boolean().optional().describe("True when more results exist beyond this page"),
+            truncationWarning: z.string().optional().describe("Warning message when truncated"),
+            ...PAGINATION_OUTPUT_SCHEMA,
+            publications: z
+                .array(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe("Matching publications (when entityType is publications)"),
+            grants: z
+                .array(z.record(z.string(), z.unknown()))
+                .optional()
+                .describe("Matching grants (when entityType is grants)"),
+        }),
+        annotations: READ_ONLY_API_ANNOTATIONS,
+    }, withFieldAliases({
+        entitySource: { kind: "dynamic", argName: "entityType" },
+        fieldArrayArgs: ["fields"],
+        fieldStringArgs: ["sortBy"],
+        filterArrayArgs: ["filters"],
+    }, async (args) => {
+        try {
+            const entityType = args.entityType;
+            const record = args;
+            const { skip, limit } = resolveSkipAndLimit({
+                skip: record.skip,
+                page: record.page,
+                limit: record.limit ?? 20,
+            });
+            validateSearchPaginationPolicy({
+                skip,
+                limit,
+                confirmLargeFetch: record.confirmLargeFetch,
+            });
+            const dsl = buildSimilarDocumentsDsl(client, entityType, {
+                ...record,
+                limit,
+            });
+            const response = (await client.rawQuery(dsl));
+            const parsed = parseEntityResponse(response, entityType);
+            const rows = parsed.data;
+            const resultKey = searchResultKey(entityType);
+            return formatToolResult(withSearchPagination({
+                entityType,
+                totalCount: parsed.totalCount,
+                returnedCount: rows.length,
+                [resultKey]: rows,
+            }, parsed.totalCount, rows.length, skip, limit));
+        }
+        catch (error) {
+            return formatErrorResult(error);
+        }
+    }));
+}
+//# sourceMappingURL=similar-documents.js.map

package/dist/mcp/tools/similar-documents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"similar-documents.js","sourceRoot":"","sources":["../../../src/mcp/tools/similar-documents.ts"],"names":[],"mappings":"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"}

package/dist/mcp/usage-tracking.d.ts

@@ -2,7 +2,7 @@
  * MCP tool usage tracking helpers.
  * @module mcp/usage-tracking
  */
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 import { type McpDeploymentMode } from "../client/usage-context.js";
 export interface McpUsageTrackingOptions {
     readonly deployment: McpDeploymentMode;

package/dist/mcp/usage-tracking.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-tracking.d.ts","sourceRoot":"","sources":["../../src/mcp/usage-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,EACL,KAAK,iBAAiB,EAGvB,MAAM,4BAA4B,CAAC;AAEpC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAO3E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EACjD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GACnD,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAEnC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAE/B,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,GAAG,GAC1B,IAAI,CAMN;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAS5E"}
+{"version":3,"file":"usage-tracking.d.ts","sourceRoot":"","sources":["../../src/mcp/usage-tracking.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAE9D,OAAO,EACL,KAAK,iBAAiB,EAGvB,MAAM,4BAA4B,CAAC;AAEpC,MAAM,WAAW,uBAAuB;IACtC,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,IAAI,CAO3E;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,EACjD,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GACnD,CAAC,IAAI,EAAE,KAAK,KAAK,OAAO,CAAC,OAAO,CAAC,CAEnC;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAE/B,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,GAAG,GAC1B,IAAI,CAMN;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAS5E"}

package/dist/mcp/utils.d.ts

@@ -2,8 +2,7 @@
  * Utility functions for MCP tools.
  * @module mcp/utils
  */
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import type { McpServer, ToolAnnotations } from "@modelcontextprotocol/server";
 import { type PaginationMetadata } from "../dsl/index.js";
 /** Annotations for read-only tools that call external APIs. */
 export declare const READ_ONLY_API_ANNOTATIONS: ToolAnnotations;

package/dist/mcp/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/mcp/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oCAAoC,CAAC;AAC1E,OAAO,EAIL,KAAK,kBAAkB,EAExB,MAAM,iBAAiB,CAAC;AAEzB,+DAA+D;AAC/D,eAAO,MAAM,yBAAyB,EAAE,eAK9B,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEtE;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAU1D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAc1E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAU5D;AAED,uDAAuD;AACvD,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,IAAI,EAAE,CAAC,EACP,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,CAAC,GAAG,sBAAsB,CA2B5B;AAED,sEAAsE;AACtE,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,MAAM,GACN,QAAQ,GACR,SAAS,GACT,OAAO,GACP,UAAU,GACV,OAAO,GACP,WAAW,CAAC;AAEhB;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAMN"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/mcp/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAC/E,OAAO,EAIL,KAAK,kBAAkB,EAExB,MAAM,iBAAiB,CAAC;AAEzB,+DAA+D;AAC/D,eAAO,MAAM,yBAAyB,EAAE,eAK9B,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEtE;AAED;;;GAGG;AACH,MAAM,WAAW,UAAU;IACzB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACvB,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,EAAE,MAAM,CAAC;KACd,CAAC,CAAC;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,OAAO,GAAG,UAAU,CAU1D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAc1E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAU5D;AAED,uDAAuD;AACvD,MAAM,MAAM,sBAAsB,GAAG;IACnC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,kBAAkB,CAAC;IAChC,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EACpE,IAAI,EAAE,CAAC,EACP,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,EACrB,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,GACf,CAAC,GAAG,sBAAsB,CA2B5B;AAED,sEAAsE;AACtE,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,MAAM,GACN,QAAQ,GACR,SAAS,GACT,OAAO,GACP,UAAU,GACV,OAAO,GACP,WAAW,CAAC;AAEhB;;;;;;GAMG;AACH,wBAAgB,MAAM,CACpB,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,WAAW,EAClB,IAAI,EAAE,OAAO,EACb,MAAM,CAAC,EAAE,MAAM,GACd,IAAI,CAMN"}

package/dist/mcp/utils.js

@@ -1,7 +1,3 @@
-/**
- * Utility functions for MCP tools.
- * @module mcp/utils
- */
 import { buildPaginationMetadata, DimensionsError, largeResultWarning, POLICY_NOTICE, } from "../dsl/index.js";
 /** Annotations for read-only tools that call external APIs. */
 export const READ_ONLY_API_ANNOTATIONS = {

package/dist/mcp/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/mcp/utils.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAIH,OAAO,EACL,uBAAuB,EACvB,eAAe,EACf,kBAAkB,EAElB,aAAa,GACd,MAAM,iBAAiB,CAAC;AAEzB,+DAA+D;AAC/D,MAAM,CAAC,MAAM,yBAAyB,GAAoB;IACxD,YAAY,EAAE,IAAI;IAClB,eAAe,EAAE,KAAK;IACtB,cAAc,EAAE,IAAI;IACpB,aAAa,EAAE,IAAI;CACX,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,OAAO,CAAC,KAAc;IACpC,OAAO,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAE,KAAwC,CAAC,CAAC,CAAC,EAAE,CAAC;AAC/E,CAAC;AAgBD;;;;;GAKG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAa;IAC5C,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;aACpC;SACF;QACD,iBAAiB,EAAE,IAA+B;KACnD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,KAAc;IAC/C,IAAI,KAAK,YAAY,eAAe,EAAE,CAAC;QACrC,MAAM,IAAI,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC;QAC5B,OAAO;YACL,GAAG,IAAI;YACP,KAAK,EAAE,IAAI,CAAC,OAAO;YACnB,IAAI,EAAE,IAAI,CAAC,IAAI;SAChB,CAAC;IACJ,CAAC;IAED,OAAO;QACL,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC;QAC7D,IAAI,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO;KACpD,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAc;IAC9C,OAAO;QACL,OAAO,EAAE;YACP;gBACE,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,KAAK,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;aACzD;SACF;QACD,OAAO,EAAE,IAAI;KACd,CAAC;AACJ,CAAC;AAWD;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAO,EACP,UAAkB,EAClB,aAAqB,EACrB,IAAY,EACZ,QAAgB;IAEhB,MAAM,OAAO,GAAG,kBAAkB,CAAC,UAAU,CAAC,CAAC;IAC/C,MAAM,SAAS,GAAG,UAAU,GAAG,IAAI,GAAG,aAAa,CAAC;IACpD,MAAM,eAAe,GAAG,IAAI,GAAG,CAAC,IAAI,SAAS,IAAI,OAAO,KAAK,SAAS,CAAC;IAEvE,IAAI,CAAC,eAAe,EAAE,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,UAAU,GAAG,uBAAuB,CAAC,IAAI,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;IAEvE,MAAM,gBAAgB,GAAG,SAAS,IAAI,OAAO,KAAK,SAAS,CAAC;IAE5D,OAAO;QACL,GAAG,IAAI;QACP,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,kBAAkB,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACnD,GAAG,CAAC,gBAAgB,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,aAAa,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5D,GAAG,CAAC,SAAS;YACX,CAAC,CAAC;gBACE,SAAS,EAAE,IAAI;gBACf,iBAAiB,EACf,QAAQ,aAAa,OAAO,UAAU,+BAA+B,IAAI,KAAK;oBAC9E,kGAAkG;aACrG;YACH,CAAC,CAAC,EAAE,CAAC;QACP,UAAU;KACX,CAAC;AACJ,CAAC;AAaD;;;;;;GAMG;AACH,MAAM,UAAU,MAAM,CACpB,MAAiB,EACjB,KAAkB,EAClB,IAAa,EACb,MAAe;IAEf,MAAM,CAAC,kBAAkB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE;QAC5D,OAAO,CAAC,KAAK,CACX,IAAI,KAAK,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,CACtG,CAAC;IACJ,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/mcp/utils.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digital-science-dsl/dimensions-analytics-mcp",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Dimensions Analytics MCP server for Dimensions DSL querying",
   "type": "module",
   "main": "./dist/index.js",
@@ -16,10 +16,14 @@
     }
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.27.0",
+    "@modelcontextprotocol/express": "^2.0.0",
+    "@modelcontextprotocol/node": "^2.0.0",
+    "@modelcontextprotocol/server": "^2.0.0",
+    "express": "^5.0.0",
     "zod": "4.3.6"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "^2.0.0",
     "@types/express": "^5.0.0",
     "fast-check": "^4.6.0",
     "typescript": "^5.9.3"

package/src/http-main.ts

@@ -5,6 +5,7 @@
  */
 
 import { loadDeploymentConfig } from "./client/deployment-config.js";
+import { maybeWarnStaleHostedVersion } from "./mcp/auto-update.js";
 import { startHostedHttpServer } from "./mcp/http-server.js";
 
 const deployment = loadDeploymentConfig();
@@ -13,6 +14,8 @@ if (deployment.deploymentMode !== "hosted") {
   process.exit(1);
 }
 
+maybeWarnStaleHostedVersion();
+
 const { close, ready } = startHostedHttpServer({
   hosted: deployment,
   port: deployment.httpPort,

package/src/main.ts

@@ -4,10 +4,12 @@
  * Starts the Dimensions Analytics MCP server with stdio transport.
  * @module main
  */
-
-import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { maybeAutoUpdateAndReexec } from "./mcp/auto-update.js";
 import { createMcpServerAsync } from "./mcp/server.js";
 
+maybeAutoUpdateAndReexec();
+
 let close: () => Promise<void>;
 
 try {

package/src/mcp/auto-update.ts

@@ -0,0 +1,379 @@
+/**
+ * Best-effort version check and prefix-only auto-update for stdio installs.
+ * @module mcp/auto-update
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const NPM_PACKAGE = "@digital-science-dsl/dimensions-analytics-mcp";
+export const UPDATING_DOCS_URL =
+  "https://github.com/digital-science/dimensions-analytics-mcp/blob/main/docs/INSTALLATION.md#updating";
+export const DEFAULT_UPDATE_INTERVAL_MS = 86_400_000;
+export const NPM_VIEW_TIMEOUT_MS = 3_000;
+export const NPM_INSTALL_TIMEOUT_MS = 12_000;
+export const PREFIX_DIR_NAME = ".dimensions-analytics-mcp";
+
+const REGISTRY = "https://registry.npmjs.org";
+const INSTALL_SH = `bash -c "$(curl -fsSL https://raw.githubusercontent.com/digital-science/dimensions-analytics-mcp/main/scripts/install.sh)"`;
+const INSTALL_PS1 =
+  "irm https://raw.githubusercontent.com/digital-science/dimensions-analytics-mcp/main/scripts/install.ps1 | iex";
+
+export type InstallLayout = "prefix" | "npx" | "global" | "source" | "hosted";
+export type VersionRelation =
+  | "same"
+  | "older"
+  | "newer-same-major"
+  | "newer-major"
+  | "incomparable";
+export type UpdateCheckResult = "skipped" | "current" | "warned" | "updated";
+
+export interface UpdateStamp {
+  readonly checkedAt: number;
+  readonly from?: string;
+  readonly to?: string;
+  readonly skippedReason?: string;
+}
+
+export interface AutoUpdateIo {
+  readonly now: () => number;
+  readonly env: NodeJS.ProcessEnv;
+  readonly layout: InstallLayout;
+  readonly currentVersion: string;
+  readonly allowInstall: boolean;
+  readonly stampPath: string;
+  readonly readStamp: (path: string) => UpdateStamp | undefined;
+  readonly writeStamp: (path: string, stamp: UpdateStamp) => void;
+  readonly npmView: () => string | undefined;
+  readonly npmInstall: (version: string) => boolean;
+  readonly log: (message: string) => void;
+  readonly reexec: () => void;
+}
+
+export function envFlagOff(value: string | undefined): boolean {
+  if (value == null) return false;
+  return ["0", "false", "off", "no"].includes(value.trim().toLowerCase());
+}
+
+export function resolvePackageRoot(moduleUrl: string = import.meta.url): string {
+  return join(dirname(fileURLToPath(moduleUrl)), "..", "..");
+}
+
+export function readCurrentVersion(packageRoot: string): string {
+  const raw = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8")) as {
+    version?: unknown;
+  };
+  if (typeof raw.version !== "string" || raw.version.length === 0) {
+    throw new Error(`Missing version in ${join(packageRoot, "package.json")}`);
+  }
+  return raw.version;
+}
+
+export function normalizePath(path: string): string {
+  return path.replace(/\\/g, "/");
+}
+
+export function detectInstallLayout(
+  packageRoot: string,
+  homeDir: string,
+): Exclude<InstallLayout, "hosted"> {
+  const root = normalizePath(packageRoot);
+  const prefixRoot = normalizePath(
+    join(
+      homeDir,
+      PREFIX_DIR_NAME,
+      "node_modules",
+      "@digital-science-dsl",
+      "dimensions-analytics-mcp",
+    ),
+  );
+  if (root === prefixRoot || root.startsWith(`${prefixRoot}/`)) return "prefix";
+  if (root.includes("/_npx/") || root.includes("/_npx")) return "npx";
+  if (root.includes("/node_modules/@digital-science-dsl/dimensions-analytics-mcp")) return "global";
+  return "source";
+}
+
+export function parseSemver(
+  version: string,
+): { major: number; minor: number; patch: number } | undefined {
+  const match = version
+    .trim()
+    .replace(/^v/i, "")
+    .match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return undefined;
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+export function versionRelation(current: string, latest: string): VersionRelation {
+  const a = parseSemver(current);
+  const b = parseSemver(latest);
+  if (!a || !b) return "incomparable";
+  if (a.major === b.major && a.minor === b.minor && a.patch === b.patch) return "same";
+  const cmp =
+    a.major !== b.major
+      ? a.major - b.major
+      : a.minor !== b.minor
+        ? a.minor - b.minor
+        : a.patch - b.patch;
+  if (cmp > 0) return "older";
+  if (b.major > a.major) return "newer-major";
+  return "newer-same-major";
+}
+
+export function upgradeGuidance(
+  layout: InstallLayout,
+  current: string,
+  latest: string,
+  options: { major?: boolean; installFailed?: boolean } = {},
+): string {
+  const lines = [`Dimensions Analytics MCP ${current} is behind npm ${latest}.`];
+  if (options.major) {
+    lines.push("This is a new major version; auto-update will not apply it.");
+  }
+  if (options.installFailed) {
+    lines.push("Automatic update failed; install the new version manually.");
+  }
+  lines.push(upgradeRecipe(layout));
+  lines.push(`See ${UPDATING_DOCS_URL}`);
+  return lines.join("\n");
+}
+
+export function upgradeRecipe(layout: InstallLayout): string {
+  switch (layout) {
+    case "prefix":
+      return [
+        "Update with the installer, then restart your AI app:",
+        `  Mac/Linux: ${INSTALL_SH}`,
+        `  Windows PowerShell: ${INSTALL_PS1}`,
+        `  Or: npm install ${NPM_PACKAGE}@latest --prefix ~/${PREFIX_DIR_NAME}`,
+      ].join("\n");
+    case "npx":
+      return [
+        `Set MCP args to ["-y", "${NPM_PACKAGE}@latest"] (or clear the npx cache) and restart.`,
+        "Without @latest, npx keeps the cached tarball.",
+      ].join("\n");
+    case "global":
+      return `Run: npm install -g ${NPM_PACKAGE}@latest\nThen restart your AI app.`;
+    case "source":
+      return "Run: git pull && pnpm install && pnpm run build";
+    case "hosted":
+      return "Bump the deployed image / npm pin and redeploy. Do not run the stdio installer on the host.";
+  }
+}
+
+export function resolveNpmBin(
+  execPath: string = process.execPath,
+  platform: NodeJS.Platform = process.platform,
+  exists: (path: string) => boolean = existsSync,
+): string {
+  const dir = dirname(execPath);
+  const names = platform === "win32" ? ["npm.cmd", "npm.exe", "npm"] : ["npm"];
+  for (const name of names) {
+    const candidate = join(dir, name);
+    if (exists(candidate)) return candidate;
+  }
+  return platform === "win32" ? "npm.cmd" : "npm";
+}
+
+export function stampPathFor(layout: InstallLayout, homeDir: string, tmpDir: string): string {
+  if (layout === "hosted") {
+    return join(tmpDir, "dimensions-analytics-mcp-auto-update.json");
+  }
+  return join(homeDir, PREFIX_DIR_NAME, ".auto-update.json");
+}
+
+export function readStampFile(path: string): UpdateStamp | undefined {
+  try {
+    const raw = JSON.parse(readFileSync(path, "utf8")) as Partial<UpdateStamp>;
+    if (typeof raw.checkedAt !== "number") return undefined;
+    return {
+      checkedAt: raw.checkedAt,
+      ...(typeof raw.from === "string" ? { from: raw.from } : {}),
+      ...(typeof raw.to === "string" ? { to: raw.to } : {}),
+      ...(typeof raw.skippedReason === "string" ? { skippedReason: raw.skippedReason } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+export function writeStampFile(path: string, stamp: UpdateStamp): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(stamp)}\n`, "utf8");
+}
+
+function updateIntervalMs(env: NodeJS.ProcessEnv): number {
+  const raw = env.DIMENSIONS_MCP_AUTO_UPDATE_INTERVAL_MS;
+  if (raw == null || raw.trim() === "") return DEFAULT_UPDATE_INTERVAL_MS;
+  const parsed = Number(raw);
+  return Number.isFinite(parsed) && parsed >= 0 ? parsed : DEFAULT_UPDATE_INTERVAL_MS;
+}
+
+export function runUpdateCheck(io: AutoUpdateIo): UpdateCheckResult {
+  if (io.env.DIMENSIONS_MCP_UPDATED === "1") return "skipped";
+  if (envFlagOff(io.env.DIMENSIONS_MCP_UPDATE_CHECK)) return "skipped";
+
+  const stamp = io.readStamp(io.stampPath);
+  if (stamp && io.now() - stamp.checkedAt < updateIntervalMs(io.env)) {
+    return "skipped";
+  }
+
+  const latest = io.npmView();
+  if (latest == null) {
+    io.writeStamp(io.stampPath, {
+      checkedAt: io.now(),
+      from: io.currentVersion,
+      skippedReason: "view-failed",
+    });
+    return "current";
+  }
+
+  const relation = versionRelation(io.currentVersion, latest);
+  if (relation === "same" || relation === "older" || relation === "incomparable") {
+    io.writeStamp(io.stampPath, { checkedAt: io.now(), from: io.currentVersion, to: latest });
+    return "current";
+  }
+
+  const canInstall =
+    io.allowInstall &&
+    io.layout === "prefix" &&
+    !envFlagOff(io.env.DIMENSIONS_MCP_AUTO_UPDATE) &&
+    relation === "newer-same-major";
+
+  if (canInstall) {
+    const ok = io.npmInstall(latest);
+    if (ok) {
+      io.writeStamp(io.stampPath, { checkedAt: io.now(), from: io.currentVersion, to: latest });
+      io.reexec();
+      return "updated";
+    }
+    io.log(
+      upgradeGuidance(io.layout, io.currentVersion, latest, {
+        installFailed: true,
+        major: false,
+      }),
+    );
+    io.writeStamp(io.stampPath, {
+      checkedAt: io.now(),
+      from: io.currentVersion,
+      to: latest,
+      skippedReason: "install-failed",
+    });
+    return "warned";
+  }
+
+  io.log(
+    upgradeGuidance(io.layout, io.currentVersion, latest, {
+      major: relation === "newer-major",
+    }),
+  );
+  io.writeStamp(io.stampPath, {
+    checkedAt: io.now(),
+    from: io.currentVersion,
+    to: latest,
+    skippedReason: relation === "newer-major" ? "major" : "manual",
+  });
+  return "warned";
+}
+
+function spawnNpm(
+  args: string[],
+  timeout: number,
+): { status: number | null; stdout: string; stderr: string } {
+  const npmBin = resolveNpmBin();
+  const result = spawnSync(npmBin, args, {
+    encoding: "utf8",
+    timeout,
+    windowsHide: true,
+    shell: process.platform === "win32",
+  });
+  return {
+    status: result.status,
+    stdout: result.stdout ?? "",
+    stderr: result.stderr ?? "",
+  };
+}
+
+function npmViewLatest(): string | undefined {
+  const result = spawnNpm(
+    ["view", NPM_PACKAGE, "version", "--registry", REGISTRY],
+    NPM_VIEW_TIMEOUT_MS,
+  );
+  if (result.status !== 0) return undefined;
+  const version = result.stdout.trim().replace(/^"+|"+$/g, "");
+  return parseSemver(version) ? version : undefined;
+}
+
+function npmInstallVersion(version: string, prefix: string): boolean {
+  const result = spawnNpm(
+    [
+      "install",
+      `${NPM_PACKAGE}@${version}`,
+      "--prefix",
+      prefix,
+      "--registry",
+      REGISTRY,
+      "--no-fund",
+      "--no-audit",
+    ],
+    NPM_INSTALL_TIMEOUT_MS,
+  );
+  return result.status === 0;
+}
+
+function reexecCurrentProcess(): void {
+  const result = spawnSync(process.execPath, process.argv.slice(1), {
+    env: { ...process.env, DIMENSIONS_MCP_UPDATED: "1" },
+    stdio: "inherit",
+    windowsHide: true,
+  });
+  process.exit(result.status ?? 1);
+}
+
+function createIo(options: { allowInstall: boolean; layout?: InstallLayout }): AutoUpdateIo {
+  const home = homedir();
+  const packageRoot = resolvePackageRoot();
+  const layout = options.layout ?? detectInstallLayout(packageRoot, home);
+  const prefix = join(home, PREFIX_DIR_NAME);
+  return {
+    now: () => Date.now(),
+    env: process.env,
+    layout,
+    currentVersion: readCurrentVersion(packageRoot),
+    allowInstall: options.allowInstall,
+    stampPath: stampPathFor(layout, home, tmpdir()),
+    readStamp: readStampFile,
+    writeStamp: writeStampFile,
+    npmView: npmViewLatest,
+    npmInstall: (version) => npmInstallVersion(version, prefix),
+    log: (message) => console.error(message),
+    reexec: reexecCurrentProcess,
+  };
+}
+
+/**
+ * Stdio entry: may install + re-exec for prefix layouts.
+ */
+export function maybeAutoUpdateAndReexec(): void {
+  try {
+    runUpdateCheck(createIo({ allowInstall: true }));
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Dimensions Analytics MCP update check failed: ${message}`);
+  }
+}
+
+/**
+ * Hosted HTTP entry: version warning only, never install or re-exec.
+ */
+export function maybeWarnStaleHostedVersion(): void {
+  try {
+    runUpdateCheck(createIo({ allowInstall: false, layout: "hosted" }));
+  } catch (error: unknown) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`Dimensions Analytics MCP update check failed: ${message}`);
+  }
+}