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

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 1.2.0
+
+### Minor Changes
+
+- Add `similar_documents` MCP tool for concept-based similar publication/grant lookup from abstract text (replacing the need to hand-write `similar_documents()` via `execute_dsl`).
+
 ## 1.1.0
 
 ### Minor Changes

package/dist/mcp/examples/dsl-examples.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dsl-examples.d.ts","sourceRoot":"","sources":["../../../src/mcp/examples/dsl-examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qDAAqD;AACrD,eAAO,MAAM,0BAA0B,mCAAmC,CAAC;AAE3E,4CAA4C;AAC5C,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CA4CpE,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,oBAAoB,6OAMvB,CAAC;AAEX,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,oCAAoC,CAAC;AAEvE,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,UAA6C,CAAC;AAEnF;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAErF"}
+{"version":3,"file":"dsl-examples.d.ts","sourceRoot":"","sources":["../../../src/mcp/examples/dsl-examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qDAAqD;AACrD,eAAO,MAAM,0BAA0B,mCAAmC,CAAC;AAE3E,4CAA4C;AAC5C,eAAO,MAAM,sBAAsB,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CA8CpE,CAAC;AAEF,8DAA8D;AAC9D,eAAO,MAAM,oBAAoB,6OAMvB,CAAC;AAEX,0CAA0C;AAC1C,eAAO,MAAM,qBAAqB,oCAAoC,CAAC;AAEvE,mEAAmE;AACnE,eAAO,MAAM,wBAAwB,UAA6C,CAAC;AAEnF;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,SAAS,CAErF"}

package/dist/mcp/examples/dsl-examples.js

@@ -10,11 +10,13 @@ export const DSL_EXAMPLES_BY_ENTITY = {
         'search publications for "machine learning" return publications[id+title+doi] limit 10',
         'search publications for "CRISPR" where year >= 2020 return publications[id+title+times_cited+year] sort by times_cited desc limit 25',
         'search publications in title_only for "gene therapy" return publications[basics] limit 10',
+        'search publications for similar_documents("After spinal cord injury, macrophages infiltrate the lesion site") where year > 2015 return publications[id+title+year] sort by score desc limit 5',
         "search publications return publications facet journal limit 20",
     ],
     grants: [
         'search grants for "cancer immunotherapy" return grants limit 10',
         'search grants where funder_org_name = "National Institutes of Health" return grants[basics] limit 10',
+        'search grants for similar_documents("Cancer immunotherapy with checkpoint inhibitors and CAR-T") where start_year >= 2020 return grants[id+title] sort by score desc limit 5',
         "search grants return grants aggregate funding_usd",
     ],
     patents: [

package/dist/mcp/examples/dsl-examples.js.map

@@ -1 +1 @@
-{"version":3,"file":"dsl-examples.js","sourceRoot":"","sources":["../../../src/mcp/examples/dsl-examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;AAE3E,4CAA4C;AAC5C,MAAM,CAAC,MAAM,sBAAsB,GAAsC;IACvE,YAAY,EAAE;QACZ,uFAAuF;QACvF,sIAAsI;QACtI,2FAA2F;QAC3F,gEAAgE;KACjE;IACD,MAAM,EAAE;QACN,iEAAiE;QACjE,sGAAsG;QACtG,mDAAmD;KACpD;IACD,OAAO,EAAE;QACP,8DAA8D;QAC9D,qEAAqE;KACtE;IACD,eAAe,EAAE;QACf,uEAAuE;QACvE,gFAAgF;KACjF;IACD,QAAQ,EAAE,CAAC,8DAA8D,CAAC;IAC1E,gBAAgB,EAAE;QAChB,iFAAiF;KAClF;IACD,WAAW,EAAE;QACX,0EAA0E;QAC1E,+EAA+E;KAChF;IACD,aAAa,EAAE;QACb,mEAAmE;QACnE,oFAAoF;KACrF;IACD,OAAO,EAAE;QACP,qEAAqE;QACrE,0EAA0E;KAC3E;IACD,aAAa,EAAE;QACb,yEAAyE;QACzE,8FAA8F;KAC/F;IACD,aAAa,EAAE,CAAC,sEAAsE,CAAC;IACvF,mBAAmB,EAAE;QACnB,yFAAyF;KAC1F;CACF,CAAC;AAEF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,kBAAkB;IAClB,iBAAiB;IACjB,8BAA8B;IAC9B,gFAAgF;IAChF,iEAAiE;CACzD,CAAC;AAEX,0CAA0C;AAC1C,MAAM,CAAC,MAAM,qBAAqB,GAAG,iCAAiC,CAAC;AAEvE,mEAAmE;AACnE,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,IAAI,EAAE,CAAC;AAEnF;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC"}
+{"version":3,"file":"dsl-examples.js","sourceRoot":"","sources":["../../../src/mcp/examples/dsl-examples.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,qDAAqD;AACrD,MAAM,CAAC,MAAM,0BAA0B,GAAG,gCAAgC,CAAC;AAE3E,4CAA4C;AAC5C,MAAM,CAAC,MAAM,sBAAsB,GAAsC;IACvE,YAAY,EAAE;QACZ,uFAAuF;QACvF,sIAAsI;QACtI,2FAA2F;QAC3F,+LAA+L;QAC/L,gEAAgE;KACjE;IACD,MAAM,EAAE;QACN,iEAAiE;QACjE,sGAAsG;QACtG,8KAA8K;QAC9K,mDAAmD;KACpD;IACD,OAAO,EAAE;QACP,8DAA8D;QAC9D,qEAAqE;KACtE;IACD,eAAe,EAAE;QACf,uEAAuE;QACvE,gFAAgF;KACjF;IACD,QAAQ,EAAE,CAAC,8DAA8D,CAAC;IAC1E,gBAAgB,EAAE;QAChB,iFAAiF;KAClF;IACD,WAAW,EAAE;QACX,0EAA0E;QAC1E,+EAA+E;KAChF;IACD,aAAa,EAAE;QACb,mEAAmE;QACnE,oFAAoF;KACrF;IACD,OAAO,EAAE;QACP,qEAAqE;QACrE,0EAA0E;KAC3E;IACD,aAAa,EAAE;QACb,yEAAyE;QACzE,8FAA8F;KAC/F;IACD,aAAa,EAAE,CAAC,sEAAsE,CAAC;IACvF,mBAAmB,EAAE;QACnB,yFAAyF;KAC1F;CACF,CAAC;AAEF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,kBAAkB;IAClB,iBAAiB;IACjB,8BAA8B;IAC9B,gFAAgF;IAChF,iEAAiE;CACzD,CAAC;AAEX,0CAA0C;AAC1C,MAAM,CAAC,MAAM,qBAAqB,GAAG,iCAAiC,CAAC;AAEvE,mEAAmE;AACnE,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC,IAAI,CAAC,sBAAsB,CAAC,CAAC,IAAI,EAAE,CAAC;AAEnF;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,OAAO,sBAAsB,CAAC,MAAM,CAAC,CAAC;AACxC,CAAC"}

package/dist/mcp/examples/usage-scenarios.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"usage-scenarios.d.ts","sourceRoot":"","sources":["../../../src/mcp/examples/usage-scenarios.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAoK1C,CAAC"}
+{"version":3,"file":"usage-scenarios.d.ts","sourceRoot":"","sources":["../../../src/mcp/examples/usage-scenarios.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,aAAa;IAC5B,0BAA0B;IAC1B,EAAE,EAAE,MAAM,CAAC;IACX,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,4DAA4D;IAC5D,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;CACxB;AAED,eAAO,MAAM,eAAe,EAAE,SAAS,aAAa,EAuL1C,CAAC"}

package/dist/mcp/examples/usage-scenarios.js

@@ -148,6 +148,25 @@ export const USAGE_SCENARIOS = [
         },
         dslContains: ["large language model", "citations_per_year(2018, 2024)"],
     },
+    {
+        id: "similar-documents",
+        goal: "Similar papers from an abstract",
+        prompt: "Find publications similar to this abstract about spinal cord injury macrophages.",
+        tool: "similar_documents",
+        args: {
+            entityType: "publications",
+            text: "After spinal cord injury, macrophages infiltrate the lesion site and contribute to both tissue damage and repair processes.",
+            yearFrom: 2016,
+            limit: 10,
+            fields: ["id", "title", "year"],
+        },
+        dslContains: [
+            "search publications for similar_documents(",
+            "year >= 2016",
+            "sort by score desc",
+            "limit 10",
+        ],
+    },
     {
         id: "build-complex-query",
         goal: "Build a complex query",

package/dist/mcp/examples/usage-scenarios.js.map

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

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAE/E,OAAO,EAAE,KAAK,eAAe,EAAwB,MAAM,oBAAoB,CAAC;AAEhF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,gBAAgB,EAEhB,UAAU,EACV,KAAK,WAAW,EACjB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAWzD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,+BAA+B;IAC/B,cAAc,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACpC,qEAAqE;IACrE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA4BD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAuCxE;AAmCD;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAIzF;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,GAAE,eAAoB,GAAG,OAAO,CAAC;IAChF,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,WAAW,CAAC;CAC1B,CAAC,CAoDD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,iBAAiB,CAAC,EAAE,SAAS,EAC7B,MAAM,GAAE,eAAoB,GAC3B,OAAO,CAAC,eAAe,CAAC,CAmB1B;AAED,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAE/E,OAAO,EAAE,KAAK,eAAe,EAAwB,MAAM,oBAAoB,CAAC;AAEhF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAC;AACxD,OAAO,EACL,gBAAgB,EAEhB,UAAU,EACV,KAAK,WAAW,EACjB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAYzD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qEAAqE;IACrE,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,+BAA+B;IAC/B,cAAc,CAAC,EAAE,OAAO,GAAG,QAAQ,CAAC;IACpC,qEAAqE;IACrE,MAAM,CAAC,EAAE,eAAe,CAAC;IACzB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,qDAAqD;IACrD,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA4BD;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,CAyCxE;AAoCD;;GAEG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,WAAW,CAAC,CAIzF;AAED;;GAEG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,GAAE,eAAoB,GAAG,OAAO,CAAC;IAChF,MAAM,EAAE,SAAS,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,aAAa,EAAE,aAAa,CAAC;IAC7B,WAAW,EAAE,WAAW,CAAC;CAC1B,CAAC,CAoDD;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CACrC;AAED;;GAEG;AACH,wBAAsB,cAAc,CAClC,iBAAiB,CAAC,EAAE,SAAS,EAC7B,MAAM,GAAE,eAAoB,GAC3B,OAAO,CAAC,eAAe,CAAC,CAmB1B;AAED,OAAO,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC"}

package/dist/mcp/server.js

@@ -18,6 +18,7 @@ import { registerLookupTools } from "./tools/lookup.js";
 import { registerQueryTools } from "./tools/query.js";
 import { registerSchemaTools, validateFieldAliases } from "./tools/schema.js";
 import { registerSearchTools } from "./tools/search.js";
+import { registerSimilarDocumentsTool } from "./tools/similar-documents.js";
 import { initMcpUsageTracking } from "./usage-tracking.js";
 /**
  * Reads a positive integer from an environment variable with a default fallback.
@@ -54,7 +55,7 @@ export function buildServerInstructions(schemaStore) {
         [
             "Workflow:",
             "(1) Discover schema — read dimensions://schema/summary, dimensions://fields/{entity}, dimensions://examples/{source}, or describe_schema;",
-            "(2) Search — search_* for keyword discovery with filters; get_by_doi, get_by_pmid, get_by_id for known identifiers;",
+            "(2) Search — search_* for keyword discovery with filters; similar_documents for topic-similar pubs/grants from abstract text; get_by_doi, get_by_pmid, get_by_id for known identifiers;",
             "(3) Analyze — facet_query, aggregate_query, citation_trend, funding_trend;",
             "(4) Drill down — get_by_id, search_* with filters (e.g. researchers.id, research_orgs.id), facet_query for top researchers at an org.",
         ].join(" "),
@@ -65,12 +66,14 @@ export function buildServerInstructions(schemaStore) {
             "search_organizations for institution lookup — prefer GRID id in filters when the name is ambiguous;",
             "search_source_titles for journals / ISSN lookup (not articles); search_reports for technical reports;",
             "search_funder_groups / search_research_org_groups for curated group name → member GRID ids;",
+            "similar_documents finds concept-similar publications/grants from prose (not embeddings); for a known ID, get_by_id then pass abstract/description as text;",
             "facet_query supports yearFrom/yearTo for year-scoped facets.",
         ].join(" "),
         [
             "Query construction:",
             "for ranked publication search (e.g. most-cited since 2020), use search_publications with query, yearFrom, sortBy (times_cited or total_citations), limit — do not hand-write execute_dsl;",
-            "use execute_dsl for boolean concept groups and DSL special functions;",
+            "for similar-document lookup, use similar_documents — do not hand-write similar_documents() in execute_dsl;",
+            "use execute_dsl for boolean concept groups and remaining DSL special functions (classify, extract_concepts);",
             "use execute_dsl only when structured tools are insufficient; DSL order is return ... sort by FIELD order limit N (never limit before sort).",
         ].join(" "),
         [
@@ -91,6 +94,7 @@ function registerAllTools(server, client, schemaStore, schemaContext, deployment
     registerLookupTools(server, client);
     registerQueryTools(server, client, schemaStore);
     registerFunctionTools(server, client);
+    registerSimilarDocumentsTool(server, client);
     registerAnalyticsTools(server, client, schemaStore);
     registerSchemaTools(server, client, schemaContext);
 }

package/dist/mcp/server.js.map

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

package/dist/mcp/tools/similar-documents.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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/sdk/server/mcp.js";
+import type { DimensionsClient } from "../../dsl/index.js";
+/** Entity types that support the DSL similar_documents() search function. */
+export declare const SIMILAR_DOCUMENTS_ENTITY_TYPES: readonly ["publications", "grants"];
+/** Entity type supported by similar_documents. */
+export type SimilarDocumentsEntityType = (typeof SIMILAR_DOCUMENTS_ENTITY_TYPES)[number];
+/**
+ * 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 declare function buildSimilarDocumentsDsl(client: DimensionsClient, entityType: SimilarDocumentsEntityType, args: Record<string, unknown>): string;
+/**
+ * Registers the similar_documents tool with the MCP server.
+ * @param server - MCP server instance
+ * @param client - Dimensions client instance
+ */
+export declare function registerSimilarDocumentsTool(server: McpServer, client: DimensionsClient): void;
+//# sourceMappingURL=similar-documents.d.ts.map

package/dist/mcp/tools/similar-documents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similar-documents.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/similar-documents.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAsB3D,6EAA6E;AAC7E,eAAO,MAAM,8BAA8B,qCAAsC,CAAC;AAElF,kDAAkD;AAClD,MAAM,MAAM,0BAA0B,GAAG,CAAC,OAAO,8BAA8B,CAAC,CAAC,MAAM,CAAC,CAAC;AAQzF;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,gBAAgB,EACxB,UAAU,EAAE,0BAA0B,EACtC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC5B,MAAM,CAsCR;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAqI9F"}

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

@@ -0,0 +1,171 @@
+/**
+ * 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 { 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: {
+            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: {
+            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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@digital-science-dsl/dimensions-analytics-mcp",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Dimensions Analytics MCP server for Dimensions DSL querying",
   "type": "module",
   "main": "./dist/index.js",

package/src/mcp/examples/dsl-examples.ts

@@ -12,11 +12,13 @@ export const DSL_EXAMPLES_BY_ENTITY: Record<string, readonly string[]> = {
     'search publications for "machine learning" return publications[id+title+doi] limit 10',
     'search publications for "CRISPR" where year >= 2020 return publications[id+title+times_cited+year] sort by times_cited desc limit 25',
     'search publications in title_only for "gene therapy" return publications[basics] limit 10',
+    'search publications for similar_documents("After spinal cord injury, macrophages infiltrate the lesion site") where year > 2015 return publications[id+title+year] sort by score desc limit 5',
     "search publications return publications facet journal limit 20",
   ],
   grants: [
     'search grants for "cancer immunotherapy" return grants limit 10',
     'search grants where funder_org_name = "National Institutes of Health" return grants[basics] limit 10',
+    'search grants for similar_documents("Cancer immunotherapy with checkpoint inhibitors and CAR-T") where start_year >= 2020 return grants[id+title] sort by score desc limit 5',
     "search grants return grants aggregate funding_usd",
   ],
   patents: [

package/src/mcp/examples/usage-scenarios.ts

@@ -164,6 +164,25 @@ export const USAGE_SCENARIOS: readonly UsageScenario[] = [
     },
     dslContains: ["large language model", "citations_per_year(2018, 2024)"],
   },
+  {
+    id: "similar-documents",
+    goal: "Similar papers from an abstract",
+    prompt: "Find publications similar to this abstract about spinal cord injury macrophages.",
+    tool: "similar_documents",
+    args: {
+      entityType: "publications",
+      text: "After spinal cord injury, macrophages infiltrate the lesion site and contribute to both tissue damage and repair processes.",
+      yearFrom: 2016,
+      limit: 10,
+      fields: ["id", "title", "year"],
+    },
+    dslContains: [
+      "search publications for similar_documents(",
+      "year >= 2016",
+      "sort by score desc",
+      "limit 10",
+    ],
+  },
   {
     id: "build-complex-query",
     goal: "Build a complex query",

package/src/mcp/server.ts

@@ -27,6 +27,7 @@ import { registerLookupTools } from "./tools/lookup.js";
 import { registerQueryTools } from "./tools/query.js";
 import { registerSchemaTools, validateFieldAliases } from "./tools/schema.js";
 import { registerSearchTools } from "./tools/search.js";
+import { registerSimilarDocumentsTool } from "./tools/similar-documents.js";
 import { initMcpUsageTracking } from "./usage-tracking.js";
 
 /**
@@ -94,7 +95,7 @@ export function buildServerInstructions(schemaStore: SchemaStore): string {
     [
       "Workflow:",
       "(1) Discover schema — read dimensions://schema/summary, dimensions://fields/{entity}, dimensions://examples/{source}, or describe_schema;",
-      "(2) Search — search_* for keyword discovery with filters; get_by_doi, get_by_pmid, get_by_id for known identifiers;",
+      "(2) Search — search_* for keyword discovery with filters; similar_documents for topic-similar pubs/grants from abstract text; get_by_doi, get_by_pmid, get_by_id for known identifiers;",
       "(3) Analyze — facet_query, aggregate_query, citation_trend, funding_trend;",
       "(4) Drill down — get_by_id, search_* with filters (e.g. researchers.id, research_orgs.id), facet_query for top researchers at an org.",
     ].join(" "),
@@ -105,12 +106,14 @@ export function buildServerInstructions(schemaStore: SchemaStore): string {
       "search_organizations for institution lookup — prefer GRID id in filters when the name is ambiguous;",
       "search_source_titles for journals / ISSN lookup (not articles); search_reports for technical reports;",
       "search_funder_groups / search_research_org_groups for curated group name → member GRID ids;",
+      "similar_documents finds concept-similar publications/grants from prose (not embeddings); for a known ID, get_by_id then pass abstract/description as text;",
       "facet_query supports yearFrom/yearTo for year-scoped facets.",
     ].join(" "),
     [
       "Query construction:",
       "for ranked publication search (e.g. most-cited since 2020), use search_publications with query, yearFrom, sortBy (times_cited or total_citations), limit — do not hand-write execute_dsl;",
-      "use execute_dsl for boolean concept groups and DSL special functions;",
+      "for similar-document lookup, use similar_documents — do not hand-write similar_documents() in execute_dsl;",
+      "use execute_dsl for boolean concept groups and remaining DSL special functions (classify, extract_concepts);",
       "use execute_dsl only when structured tools are insufficient; DSL order is return ... sort by FIELD order limit N (never limit before sort).",
     ].join(" "),
     [
@@ -138,6 +141,7 @@ function registerAllTools(
   registerLookupTools(server, client);
   registerQueryTools(server, client, schemaStore);
   registerFunctionTools(server, client);
+  registerSimilarDocumentsTool(server, client);
   registerAnalyticsTools(server, client, schemaStore);
   registerSchemaTools(server, client, schemaContext);
 }

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

@@ -0,0 +1,232 @@
+/**
+ * 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/sdk/server/mcp.js";
+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: {
+        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: {
+        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/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 twelve natural-language workflows", () => {
+    expect(USAGE_SCENARIOS).toHaveLength(12);
+    expect(new Set(USAGE_SCENARIOS.map((s) => s.id)).size).toBe(12);
   });
 
   for (const scenario of USAGE_SCENARIOS) {

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/server.test.ts

@@ -63,6 +63,7 @@ describe("createMcpServerAsync", () => {
     expect(instructions).toContain("search_organizations for institution lookup");
     expect(instructions).toContain("search_source_titles");
     expect(instructions).toContain("search_reports");
+    expect(instructions).toContain("similar_documents");
     expect(instructions).toContain("fetch_search_pages");
     expect(instructions).toContain("dimensions://schema/policy");
   });
@@ -137,6 +138,7 @@ describe("MCP protocol", () => {
     const toolNames = tools.tools.map((t) => t.name);
     expect(toolNames).toContain("search_publications");
     expect(toolNames).toContain("fetch_search_pages");
+    expect(toolNames).toContain("similar_documents");
     expect(toolNames).toContain("execute_dsl");
     expect(toolNames).not.toContain("validate_dsl");
 

package/test/tools/similar-documents.test.ts

@@ -0,0 +1,173 @@
+/**
+ * Tests for the similar_documents MCP tool.
+ * @module test/tools/similar-documents
+ */
+
+import { beforeEach, describe, expect, it } from "vitest";
+import { registerSimilarDocumentsTool } from "../../src/mcp/tools/similar-documents.js";
+import {
+  callTool,
+  createMockClient,
+  createMockServer,
+  parseToolResult,
+} from "../helpers/tool-test-harness.js";
+
+/** API-shaped mock response for parseEntityResponse. */
+function apiRows(
+  entity: string,
+  rows: Record<string, unknown>[],
+  totalCount?: number,
+): Record<string, unknown> {
+  return {
+    [entity]: rows,
+    _stats: { total_count: totalCount ?? rows.length },
+  };
+}
+
+const SAMPLE_ABSTRACT =
+  "After spinal cord injury, macrophages infiltrate the lesion site and contribute to both tissue damage and repair.";
+
+describe("similar_documents tool", () => {
+  let handlers: ReturnType<typeof createMockServer>["handlers"];
+  let client: ReturnType<typeof createMockClient>;
+
+  beforeEach(() => {
+    const { server, handlers: h } = createMockServer();
+    client = createMockClient();
+    handlers = h;
+    registerSimilarDocumentsTool(server as never, client as never);
+  });
+
+  it("registers similar_documents", () => {
+    expect(handlers.has("similar_documents")).toBe(true);
+  });
+
+  it("builds similar_documents DSL with default score sort and limit 20", async () => {
+    client.rawQuery.mockResolvedValue(apiRows("publications", [{ id: "pub.1", title: "A" }], 1));
+
+    await callTool(handlers, "similar_documents", {
+      entityType: "publications",
+      text: SAMPLE_ABSTRACT,
+    });
+
+    expect(client.rawQuery).toHaveBeenCalledTimes(1);
+    const dsl = client.rawQuery.mock.calls[0][0] as string;
+    expect(dsl).toContain("search publications for similar_documents(");
+    expect(dsl).toContain(SAMPLE_ABSTRACT);
+    expect(dsl).toContain("sort by score desc");
+    expect(dsl).toContain("limit 20");
+  });
+
+  it("applies year filters on publications and custom limit/fields", async () => {
+    client.rawQuery.mockResolvedValue(apiRows("publications", [], 0));
+
+    await callTool(handlers, "similar_documents", {
+      entityType: "publications",
+      text: SAMPLE_ABSTRACT,
+      yearFrom: 2018,
+      yearTo: 2024,
+      limit: 5,
+      fields: ["id", "title", "year"],
+    });
+
+    const dsl = client.rawQuery.mock.calls[0][0] as string;
+    expect(dsl).toContain("year >= 2018");
+    expect(dsl).toContain("year <= 2024");
+    expect(dsl).toContain("limit 5");
+    expect(dsl).toContain("return publications[id+title+year]");
+  });
+
+  it("uses start_year for grants year filters", async () => {
+    client.rawQuery.mockResolvedValue(apiRows("grants", [{ id: "grant.1" }], 1));
+
+    await callTool(handlers, "similar_documents", {
+      entityType: "grants",
+      text: "Cancer immunotherapy CAR-T solid tumors",
+      yearFrom: 2020,
+      limit: 5,
+      fields: ["id", "title"],
+    });
+
+    const dsl = client.rawQuery.mock.calls[0][0] as string;
+    expect(dsl).toContain("search grants for similar_documents(");
+    expect(dsl).toContain("start_year >= 2020");
+    expect(dsl).toContain("return grants[id+title]");
+  });
+
+  it("formats publication results", async () => {
+    const pubs = [
+      { id: "pub.1", title: "Paper A" },
+      { id: "pub.2", title: "Paper B" },
+    ];
+    client.rawQuery.mockResolvedValue(apiRows("publications", pubs, 2));
+
+    const result = await callTool(handlers, "similar_documents", {
+      entityType: "publications",
+      text: SAMPLE_ABSTRACT,
+      limit: 5,
+    });
+    const data = parseToolResult(result);
+
+    expect(result.isError).toBeUndefined();
+    expect(data.entityType).toBe("publications");
+    expect(data.totalCount).toBe(2);
+    expect(data.returnedCount).toBe(2);
+    expect(data.publications).toEqual(pubs);
+  });
+
+  it("formats grant results", async () => {
+    const grants = [{ id: "grant.1", title: "Grant A" }];
+    client.rawQuery.mockResolvedValue(apiRows("grants", grants, 1));
+
+    const result = await callTool(handlers, "similar_documents", {
+      entityType: "grants",
+      text: "Climate adaptation funding",
+      limit: 5,
+    });
+    const data = parseToolResult(result);
+
+    expect(data.entityType).toBe("grants");
+    expect(data.grants).toEqual(grants);
+    expect(data.publications).toBeUndefined();
+  });
+
+  it("applies extra filters", async () => {
+    client.rawQuery.mockResolvedValue(apiRows("publications", [], 0));
+
+    await callTool(handlers, "similar_documents", {
+      entityType: "publications",
+      text: SAMPLE_ABSTRACT,
+      filters: [{ field: "type", operator: "=", value: "article" }],
+      limit: 5,
+    });
+
+    const dsl = client.rawQuery.mock.calls[0][0] as string;
+    expect(dsl).toContain('type = "article"');
+  });
+
+  it("escapes quotes in text", async () => {
+    client.rawQuery.mockResolvedValue(apiRows("publications", [], 0));
+
+    await callTool(handlers, "similar_documents", {
+      entityType: "publications",
+      text: 'Text with "quotes" inside',
+      limit: 5,
+    });
+
+    const dsl = client.rawQuery.mock.calls[0][0] as string;
+    expect(dsl).toContain('similar_documents("Text with \\"quotes\\" inside")');
+  });
+
+  it("handles API errors gracefully", async () => {
+    client.rawQuery.mockRejectedValueOnce(new Error("Similarity search failed"));
+
+    const result = await callTool(handlers, "similar_documents", {
+      entityType: "publications",
+      text: SAMPLE_ABSTRACT,
+    });
+    const data = parseToolResult(result);
+
+    expect(result.isError).toBe(true);
+    expect(data.error).toBe("Similarity search failed");
+  });
+});

package/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["./src/http-main.ts","./src/index.ts","./src/main.ts","./src/client/command.ts","./src/client/config.ts","./src/client/deployment-config.ts","./src/client/errors.ts","./src/client/http-client.ts","./src/client/index.ts","./src/client/internal-dsl-client.ts","./src/client/rate-limiter.ts","./src/client/request-retry.ts","./src/client/resolve-api-key-user.ts","./src/client/types.ts","./src/client/usage-context.ts","./src/client/usage-headers.ts","./src/client/auth/config-loaders.ts","./src/client/auth/factory.ts","./src/client/auth/index.ts","./src/client/auth/jwt-utils.ts","./src/client/auth/node.ts","./src/client/auth/schemas.ts","./src/client/auth/types.ts","./src/client/auth/decorators/index.ts","./src/client/auth/decorators/with-caching.ts","./src/client/auth/providers/index.ts","./src/client/auth/providers/jwt-auth-provider.ts","./src/client/config/index.ts","./src/client/config/loader.ts","./src/client/config/node.ts","./src/client/config/schemas.ts","./src/client/config/types.ts","./src/client/config/unified-loader.ts","./src/dsl/client.ts","./src/dsl/create-client.ts","./src/dsl/fluent-query-builder.ts","./src/dsl/index.ts","./src/dsl/pagination.ts","./src/dsl/query-builder.ts","./src/dsl/response-parser.ts","./src/dsl/usage-policy.ts","./src/dsl/commands/apply-filters.ts","./src/dsl/commands/index.ts","./src/dsl/commands/validate-input.ts","./src/dsl/commands/facet/index.ts","./src/dsl/commands/facet/schemas.ts","./src/dsl/commands/functions/ClassifyCommand.ts","./src/dsl/commands/functions/ExtractAffiliationsCommand.ts","./src/dsl/commands/functions/ExtractConceptsCommand.ts","./src/dsl/commands/functions/ExtractGrantsCommand.ts","./src/dsl/commands/functions/index.ts","./src/dsl/schema/cache.ts","./src/dsl/schema/extract.ts","./src/dsl/schema/index.ts","./src/dsl/schema/load.ts","./src/dsl/schema/store.ts","./src/dsl/schema/structured-entities.ts","./src/dsl/schema/summary.ts","./src/dsl/schema/types.ts","./src/dsl/schema/validation.ts","./src/dsl/types/buckets.ts","./src/dsl/types/common.ts","./src/dsl/types/entities.ts","./src/dsl/types/index.ts","./src/dsl/types/return-clauses.ts","./src/dsl/types/special-functions.ts","./src/dsl/types/vocabulary.ts","./src/dsl/utils/escape.ts","./src/dsl/utils/sanitize.ts","./src/dsl/utils/string-utils.ts","./src/dsl/utils/validate-field-name.ts","./src/mcp/batch-fetch.ts","./src/mcp/export-format.ts","./src/mcp/funder-org-names.ts","./src/mcp/http-server.ts","./src/mcp/server.ts","./src/mcp/shared-schema.ts","./src/mcp/usage-tracking.ts","./src/mcp/utils.ts","./src/mcp/examples/dsl-examples.ts","./src/mcp/examples/usage-scenarios.ts","./src/mcp/middleware/field-aliases.ts","./src/mcp/resources/schema.ts","./src/mcp/schema/context.ts","./src/mcp/schema/index.ts","./src/mcp/tools/analytics-filters.ts","./src/mcp/tools/analytics.ts","./src/mcp/tools/fetch-search-pages.ts","./src/mcp/tools/functions.ts","./src/mcp/tools/lookup.ts","./src/mcp/tools/query.ts","./src/mcp/tools/schema.ts","./src/mcp/tools/search-entity-metadata.ts","./src/mcp/tools/search-input.ts","./src/mcp/tools/search.ts"],"version":"5.9.3"}
+{"root":["./src/http-main.ts","./src/index.ts","./src/main.ts","./src/client/command.ts","./src/client/config.ts","./src/client/deployment-config.ts","./src/client/errors.ts","./src/client/http-client.ts","./src/client/index.ts","./src/client/internal-dsl-client.ts","./src/client/rate-limiter.ts","./src/client/request-retry.ts","./src/client/resolve-api-key-user.ts","./src/client/types.ts","./src/client/usage-context.ts","./src/client/usage-headers.ts","./src/client/auth/config-loaders.ts","./src/client/auth/factory.ts","./src/client/auth/index.ts","./src/client/auth/jwt-utils.ts","./src/client/auth/node.ts","./src/client/auth/schemas.ts","./src/client/auth/types.ts","./src/client/auth/decorators/index.ts","./src/client/auth/decorators/with-caching.ts","./src/client/auth/providers/index.ts","./src/client/auth/providers/jwt-auth-provider.ts","./src/client/config/index.ts","./src/client/config/loader.ts","./src/client/config/node.ts","./src/client/config/schemas.ts","./src/client/config/types.ts","./src/client/config/unified-loader.ts","./src/dsl/client.ts","./src/dsl/create-client.ts","./src/dsl/fluent-query-builder.ts","./src/dsl/index.ts","./src/dsl/pagination.ts","./src/dsl/query-builder.ts","./src/dsl/response-parser.ts","./src/dsl/usage-policy.ts","./src/dsl/commands/apply-filters.ts","./src/dsl/commands/index.ts","./src/dsl/commands/validate-input.ts","./src/dsl/commands/facet/index.ts","./src/dsl/commands/facet/schemas.ts","./src/dsl/commands/functions/ClassifyCommand.ts","./src/dsl/commands/functions/ExtractAffiliationsCommand.ts","./src/dsl/commands/functions/ExtractConceptsCommand.ts","./src/dsl/commands/functions/ExtractGrantsCommand.ts","./src/dsl/commands/functions/index.ts","./src/dsl/schema/cache.ts","./src/dsl/schema/extract.ts","./src/dsl/schema/index.ts","./src/dsl/schema/load.ts","./src/dsl/schema/store.ts","./src/dsl/schema/structured-entities.ts","./src/dsl/schema/summary.ts","./src/dsl/schema/types.ts","./src/dsl/schema/validation.ts","./src/dsl/types/buckets.ts","./src/dsl/types/common.ts","./src/dsl/types/entities.ts","./src/dsl/types/index.ts","./src/dsl/types/return-clauses.ts","./src/dsl/types/special-functions.ts","./src/dsl/types/vocabulary.ts","./src/dsl/utils/escape.ts","./src/dsl/utils/sanitize.ts","./src/dsl/utils/string-utils.ts","./src/dsl/utils/validate-field-name.ts","./src/mcp/batch-fetch.ts","./src/mcp/export-format.ts","./src/mcp/funder-org-names.ts","./src/mcp/http-server.ts","./src/mcp/server.ts","./src/mcp/shared-schema.ts","./src/mcp/usage-tracking.ts","./src/mcp/utils.ts","./src/mcp/examples/dsl-examples.ts","./src/mcp/examples/usage-scenarios.ts","./src/mcp/middleware/field-aliases.ts","./src/mcp/resources/schema.ts","./src/mcp/schema/context.ts","./src/mcp/schema/index.ts","./src/mcp/tools/analytics-filters.ts","./src/mcp/tools/analytics.ts","./src/mcp/tools/fetch-search-pages.ts","./src/mcp/tools/functions.ts","./src/mcp/tools/lookup.ts","./src/mcp/tools/query.ts","./src/mcp/tools/schema.ts","./src/mcp/tools/search-entity-metadata.ts","./src/mcp/tools/search-input.ts","./src/mcp/tools/search.ts","./src/mcp/tools/similar-documents.ts"],"version":"5.9.3"}