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

package/src/mcp/tools/schema.ts

@@ -2,8 +2,7 @@
  * Schema introspection and validation tools for the MCP server.
  * @module mcp/tools/schema
  */
-
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import type { DimensionsClient } from "../../dsl/index.js";
 import { buildReverseAliasMap } from "../middleware/field-aliases.js";
@@ -32,7 +31,7 @@ export function registerSchemaTools(
         "Default: compact summary with source/entity counts and resource URIs. " +
         "Use full=true or dimensions://schema for the complete describe payload. " +
         "Optionally fetch live describe for a single source or entity.",
-      inputSchema: {
+      inputSchema: z.object({
         source: z.string().optional().describe("Source name (e.g. publications)"),
         entity: z.string().optional().describe("Auxiliary entity name (e.g. journals)"),
         full: z
@@ -43,8 +42,8 @@ export function registerSchemaTools(
           .boolean()
           .optional()
           .describe("When true, fetch fresh describe for source/entity from the API"),
-      },
-      outputSchema: {
+      }),
+      outputSchema: z.object({
         summary: z
           .record(z.string(), z.unknown())
           .optional()
@@ -55,7 +54,7 @@ export function registerSchemaTools(
           .describe("Full or sliced schema when full=true or source/entity is set"),
         version: z.string().optional().describe("DSL version"),
         stats: z.record(z.string(), z.unknown()).optional().describe("Load stats and provenance"),
-      },
+      }),
       annotations: READ_ONLY_API_ANNOTATIONS,
     },
     async (args) => {
@@ -106,11 +105,11 @@ export function registerSchemaTools(
     {
       description:
         "Re-fetch describe schema from the Dimensions API, rebuild in-memory schema, and re-register MCP resources.",
-      inputSchema: {},
-      outputSchema: {
+      inputSchema: z.object({}),
+      outputSchema: z.object({
         refreshed: z.boolean(),
         stats: z.record(z.string(), z.unknown()),
-      },
+      }),
       annotations: READ_ONLY_API_ANNOTATIONS,
     },
     async () => {

package/src/mcp/tools/search.ts

@@ -3,8 +3,7 @@
  * Registers `search_{source}` tools from describe schema and shared QueryBuilder handlers.
  * @module mcp/tools/search
  */
-
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 import { z } from "zod";
 import type { DimensionsClient } from "../../dsl/index.js";
 import {
@@ -105,11 +104,11 @@ export function registerSearchTools(
       toolName,
       {
         description: meta.description,
-        inputSchema: {
+        inputSchema: z.object({
           ...SHARED_SEARCH_INPUT,
           ...meta.extraInputSchema,
-        },
-        outputSchema: {
+        }),
+        outputSchema: z.object({
           totalCount: z.number().describe("Total matching records"),
           returnedCount: z.number().describe("Records returned in this response"),
           truncated: z
@@ -119,7 +118,7 @@ export function registerSearchTools(
           truncationWarning: z.string().optional().describe("Warning message when truncated"),
           ...PAGINATION_OUTPUT_SCHEMA,
           [resultKey]: z.array(z.record(z.string(), z.unknown())).describe("Result records"),
-        },
+        }),
         annotations: READ_ONLY_API_ANNOTATIONS,
       },
       withFieldAliases(

package/src/mcp/tools/similar-documents.ts

@@ -0,0 +1,231 @@
+/**
+ * similar_documents MCP tool — find publications/grants with similar topics via DSL.
+ * Uses concept extraction + weighted concepts search (not vector embeddings).
+ * @module mcp/tools/similar-documents
+ */
+import type { McpServer } from "@modelcontextprotocol/server";
+import { z } from "zod";
+import type { DimensionsClient } from "../../dsl/index.js";
+import {
+  applyFilters,
+  type ExtendedWhereFilterInput,
+  ExtendedWhereFilterSchema,
+  parseEntityResponse,
+  resolveSkipAndLimit,
+  SCHEMA_LIMITS,
+  type StructuredEntityType,
+  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"] as const;
+
+/** Entity type supported by similar_documents. */
+export type SimilarDocumentsEntityType = (typeof SIMILAR_DOCUMENTS_ENTITY_TYPES)[number];
+
+/** Year filter field per entity (publications use year; grants use start_year). */
+const YEAR_FIELD: Record<SimilarDocumentsEntityType, string> = {
+  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: DimensionsClient,
+  entityType: SimilarDocumentsEntityType,
+  args: Record<string, unknown>,
+): string {
+  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 as ExtendedWhereFilterInput[] | undefined;
+  if (filters?.length) {
+    applyFilters(builder, filters);
+  }
+
+  const fields = args.fields as string[] | undefined;
+  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 as number | undefined,
+    page: args.page as number | undefined,
+    limit: (args.limit as number | undefined) ?? 20,
+    pageSize: args.pageSize as number | undefined,
+  });
+  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: McpServer, client: DimensionsClient): void {
+  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 as SimilarDocumentsEntityType;
+          const record = args as Record<string, unknown>;
+          const { skip, limit } = resolveSkipAndLimit({
+            skip: record.skip as number | undefined,
+            page: record.page as number | undefined,
+            limit: (record.limit as number | undefined) ?? 20,
+          });
+
+          validateSearchPaginationPolicy({
+            skip,
+            limit,
+            confirmLargeFetch: record.confirmLargeFetch as boolean | undefined,
+          });
+
+          const dsl = buildSimilarDocumentsDsl(client, entityType, {
+            ...record,
+            limit,
+          });
+          const response = (await client.rawQuery(dsl)) as Record<string, unknown>;
+          const parsed = parseEntityResponse(response, entityType as StructuredEntityType);
+          const rows = parsed.data as Record<string, unknown>[];
+          const resultKey = searchResultKey(entityType as StructuredEntityType);
+
+          return formatToolResult(
+            withSearchPagination(
+              {
+                entityType,
+                totalCount: parsed.totalCount,
+                returnedCount: rows.length,
+                [resultKey]: rows,
+              },
+              parsed.totalCount,
+              rows.length,
+              skip,
+              limit,
+            ),
+          );
+        } catch (error) {
+          return formatErrorResult(error);
+        }
+      },
+    ),
+  );
+}

package/src/mcp/usage-tracking.ts

@@ -4,7 +4,7 @@
  */
 
 import { randomUUID } from "node:crypto";
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { McpServer } from "@modelcontextprotocol/server";
 import pkg from "../../package.json" with { type: "json" };
 import {
   type McpDeploymentMode,

package/src/mcp/utils.ts

@@ -2,9 +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 {
   buildPaginationMetadata,
   DimensionsError,

package/test/examples/dsl-examples.test.ts

@@ -20,6 +20,14 @@ describe("dsl-examples", () => {
     expect(getDslExamplesForSource("unknown")).toBeUndefined();
   });
 
+  it("includes similar_documents examples for publications and grants", () => {
+    const pubs = getDslExamplesForSource("publications") ?? [];
+    const grants = getDslExamplesForSource("grants") ?? [];
+    expect(pubs.some((q) => q.includes("similar_documents("))).toBe(true);
+    expect(grants.some((q) => q.includes("similar_documents("))).toBe(true);
+    expect(DSL_GENERAL_EXAMPLES.some((q) => q.includes("similar_documents("))).toBe(true);
+  });
+
   it("uses sort by (not bare sort) and places sort before limit", () => {
     for (const dsl of ALL_EXAMPLES) {
       expect(dsl).not.toMatch(/\blimit \d+ sort\b/);

package/test/examples/usage-scenarios.test.ts

@@ -8,6 +8,7 @@ import { registerAnalyticsTools } from "../../src/mcp/tools/analytics.js";
 import { registerLookupTools } from "../../src/mcp/tools/lookup.js";
 import { registerQueryTools } from "../../src/mcp/tools/query.js";
 import { registerSearchTools } from "../../src/mcp/tools/search.js";
+import { registerSimilarDocumentsTool } from "../../src/mcp/tools/similar-documents.js";
 import { testSchemaStore } from "../helpers/schema-fixture.js";
 import {
   callTool,
@@ -34,11 +35,12 @@ describe("usage-scenarios", () => {
     registerLookupTools(server as never, client as never);
     registerAnalyticsTools(server as never, client as never, schemaStore);
     registerQueryTools(server as never, client as never, schemaStore);
+    registerSimilarDocumentsTool(server as never, client as never);
   });
 
-  it("documents eleven natural-language workflows", () => {
-    expect(USAGE_SCENARIOS).toHaveLength(11);
-    expect(new Set(USAGE_SCENARIOS.map((s) => s.id)).size).toBe(11);
+  it("documents thirteen natural-language workflows", () => {
+    expect(USAGE_SCENARIOS).toHaveLength(13);
+    expect(new Set(USAGE_SCENARIOS.map((s) => s.id)).size).toBe(13);
   });
 
   for (const scenario of USAGE_SCENARIOS) {

package/test/integration/harness.ts

@@ -5,9 +5,7 @@
  * via in-memory transport, and executes eval suites against it.
  * @module test/integration/harness
  */
-
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
 import { createMcpServerAsync, type McpServerConfig } from "../../src/mcp/server.js";
 import { missingEnvVars } from "./env.js";
 import type {

package/test/integration/hosted-client.ts

@@ -2,9 +2,7 @@
  * MCP client helpers for hosted Streamable HTTP transport.
  * @module test/integration/hosted-client
  */
-
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 import { hostedMcpEndpoint } from "./env.js";
 
 export interface HostedMcpSession {

package/test/integration/hosted.e2e.test.ts

@@ -31,7 +31,7 @@ const MOCK_HOSTED: HostedEnvConfig = {
 
 const TEST_API_KEY = "test-hosted-api-key";
 
-describe("Hosted MCP e2e (mocked backends)", () => {
+describe("Hosted MCP e2e (mocked backends)", { timeout: 30_000 }, () => {
   let restoreFetch: (() => void) | undefined;
   let server: HostedHttpServerHandle | undefined;
   let baseUrl: string;

package/test/integration/suites/index.ts

@@ -10,6 +10,7 @@ import { lookupSuite } from "./lookup.integration.js";
 import { querySuite } from "./query.integration.js";
 import { resourcesSuite } from "./resources.integration.js";
 import { searchSuite } from "./search.integration.js";
+import { similarDocumentsSuite } from "./similar-documents.integration.js";
 
 /** All integration test suites, in execution order. */
 export const allSuites: readonly EvalSuite[] = [
@@ -17,6 +18,7 @@ export const allSuites: readonly EvalSuite[] = [
   lookupSuite,
   querySuite,
   functionsSuite,
+  similarDocumentsSuite,
   analyticsSuite,
   resourcesSuite,
 ];

package/test/integration/suites/similar-documents.integration.ts

@@ -0,0 +1,51 @@
+/**
+ * Eval suite for similar_documents tool.
+ * @module test/integration/suites/similar-documents
+ */
+
+import { arrayMinLength, fieldAtLeast, hasField, isSuccess } from "../assertions.js";
+import type { EvalSuite } from "../types.js";
+
+const SAMPLE_ABSTRACT =
+  "After spinal cord injury, macrophages infiltrate the lesion site and contribute to both tissue damage and repair processes. Understanding macrophage polarization could lead to novel therapeutic strategies.";
+
+const SAMPLE_GRANT_TEXT =
+  "Development of novel cancer immunotherapy approaches using checkpoint inhibitors and CAR-T cell engineering for solid tumors.";
+
+export const similarDocumentsSuite: EvalSuite = {
+  name: "similar_documents",
+  description: "Concept-based similar document search for publications and grants",
+  cases: [
+    {
+      name: "similar publications from abstract text",
+      tool: "similar_documents",
+      args: {
+        entityType: "publications",
+        text: SAMPLE_ABSTRACT,
+        yearFrom: 2016,
+        limit: 5,
+        fields: ["id", "title", "year"],
+      },
+      assertions: [
+        isSuccess(),
+        hasField("totalCount"),
+        fieldAtLeast("totalCount", 1),
+        arrayMinLength("publications", 1),
+      ],
+      timeout: 60_000,
+    },
+    {
+      name: "similar grants from description text",
+      tool: "similar_documents",
+      args: {
+        entityType: "grants",
+        text: SAMPLE_GRANT_TEXT,
+        yearFrom: 2020,
+        limit: 5,
+        fields: ["id", "title"],
+      },
+      assertions: [isSuccess(), hasField("totalCount"), arrayMinLength("grants", 1)],
+      timeout: 60_000,
+    },
+  ],
+};

package/test/integration/verify-usage-scenarios.ts

@@ -3,9 +3,7 @@
  * Live verification of docs/USAGE.md natural-language scenarios.
  * Run: node --import tsx apps/mcp/test/integration/verify-usage-scenarios.ts
  */
-
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
+import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
 import { USAGE_SCENARIOS } from "../../src/mcp/examples/usage-scenarios.js";
 import { buildServerInstructions, createMcpServerAsync } from "../../src/mcp/server.js";