@cyanheads/openalex-mcp-server 0.2.7

package/README.md

@@ -0,0 +1,188 @@
+<div align="center">
+  <h1>@cyanheads/openalex-mcp-server</h1>
+  <p><b>Access the OpenAlex academic research catalog - 270M+ publications through MCP. STDIO & Streamable HTTP.</b></p>
+  <p><b>3 Tools &middot; 2 Prompts</b></p>
+</div>
+
+<div align="center">
+
+[![Version](https://img.shields.io/badge/Version-0.2.6-blue.svg?style=flat-square)](./CHANGELOG.md) [![Framework](https://img.shields.io/badge/Built%20on-@cyanheads/mcp--ts--core-259?style=flat-square)](https://www.npmjs.com/package/@cyanheads/mcp-ts-core) [![MCP SDK](https://img.shields.io/badge/MCP%20SDK-^1.27.1-green.svg?style=flat-square)](https://modelcontextprotocol.io/) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg?style=flat-square)](./LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-^6.0.2-3178C6.svg?style=flat-square)](https://www.typescriptlang.org/)
+
+</div>
+
+---
+
+## Tools
+
+Three tools for querying the [OpenAlex](https://openalex.org) academic research catalog:
+
+| Tool Name | Description |
+|:----------|:------------|
+| `openalex_search_entities` | Search, filter, sort, or retrieve by ID across all 8 entity types. |
+| `openalex_analyze_trends` | Group-by aggregation for trend and distribution analysis. |
+| `openalex_resolve_name` | Resolve a name or partial name to an OpenAlex ID via autocomplete. |
+
+### `openalex_search_entities`
+
+Primary discovery and lookup tool. Covers all OpenAlex entity types (works, authors, sources, institutions, topics, keywords, publishers, funders).
+
+- Retrieve a single entity by ID (OpenAlex ID, DOI, ORCID, ROR, PMID, PMCID, ISSN)
+- Keyword search with boolean operators, quoted phrases, wildcards, and fuzzy matching
+- Exact and AI semantic search modes
+- Rich filter syntax: AND across fields, OR within fields (`us|gb`), NOT (`!us`), ranges (`2020-2024`), comparisons (`>100`)
+- Field selection via `select` to control payload size (full work records are ~70KB each)
+- Cursor pagination, sorting, up to 100 results per page
+
+---
+
+### `openalex_analyze_trends`
+
+Aggregate entities into groups and count them for trend, distribution, and comparative analysis.
+
+- Group by any supported field (publication year, OA status, institution, country, topic, etc.)
+- Combine with filters to scope the population before aggregation
+- Up to 200 groups per page with cursor pagination
+- Supports `include_unknown` to show entities with no value for the grouped field
+
+---
+
+### `openalex_resolve_name`
+
+Name-to-ID resolution via autocomplete. **Always use this before filtering by entity** — names are ambiguous, IDs are not.
+
+- Returns up to 10 matches with disambiguation hints
+- Accepts partial names and DOIs for direct lookup
+- Optional entity type filter and field-level filters
+- ~200ms response time
+
+## Prompts
+
+| Prompt | Description |
+|:-------|:------------|
+| `openalex_literature_review` | Guides a systematic literature search: formulate query, search, filter, analyze citation network, synthesize findings. |
+| `openalex_research_landscape` | Analyzes the research landscape for a topic: volume trends, top authors/institutions, open access rates, funding sources. |
+
+## Features
+
+Built on [`@cyanheads/mcp-ts-core`](https://github.com/cyanheads/mcp-ts-core):
+
+- Declarative tool definitions — single file per tool, framework handles registration and validation
+- Unified error handling across all tools
+- Pluggable auth (`none`, `jwt`, `oauth`)
+- Swappable storage backends via the framework (not currently used by this server)
+- Structured logging with optional OpenTelemetry tracing
+- Runs locally (stdio/HTTP) or in Docker from the same codebase
+
+OpenAlex-specific:
+
+- Typed API client with automatic ID normalization (DOI, ORCID, ROR, PMID, PMCID, ISSN, OpenAlex URLs)
+- Abstract reconstruction from inverted indices
+- Cancellation support via `AbortSignal`
+
+## Getting Started
+
+Add to your MCP client config (e.g., `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "openalex": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@cyanheads/openalex-mcp-server"],
+      "env": {
+        "OPENALEX_API_KEY": "your-email@example.com"
+      }
+    }
+  }
+}
+```
+
+No API key needed — just provide your email to access the [polite pool](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#the-polite-pool) (10x faster rate limits).
+
+### Prerequisites
+
+- [Bun v1.3.0](https://bun.sh/) or higher (for development)
+
+### Installation
+
+1. **Clone the repository:**
+```sh
+git clone https://github.com/cyanheads/openalex-mcp-server.git
+```
+
+2. **Navigate into the directory:**
+```sh
+cd openalex-mcp-server
+```
+
+3. **Install dependencies:**
+```sh
+bun install
+```
+
+## Configuration
+
+| Variable | Description | Default |
+|:---------|:------------|:--------|
+| `OPENALEX_API_KEY` | **Required.** Email address for the OpenAlex [polite pool](https://docs.openalex.org/how-to-use-the-api/rate-limits-and-authentication#the-polite-pool) (faster rate limits). | — |
+| `OPENALEX_BASE_URL` | OpenAlex API base URL. | `https://api.openalex.org` |
+| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
+| `MCP_HTTP_PORT` | Port for HTTP server. | `3010` |
+| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
+| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `debug` |
+| `OTEL_ENABLED` | Enable OpenTelemetry. | `false` |
+
+## Running the Server
+
+### Local Development
+
+- **Build and run the production version:**
+  ```sh
+  bun run build
+  bun run start:http   # or start:stdio
+  ```
+
+- **Run checks and tests:**
+  ```sh
+  bun run devcheck     # Lints, formats, type-checks
+  bun run test         # Runs test suite
+  ```
+
+### Docker
+
+```sh
+docker build -t openalex-mcp-server .
+docker run -e OPENALEX_API_KEY=your-key -p 3010:3010 openalex-mcp-server
+```
+
+## Project Structure
+
+| Directory | Purpose |
+|:----------|:--------|
+| `src/mcp-server/tools/definitions/` | Tool definitions (`*.tool.ts`). |
+| `src/mcp-server/prompts/definitions/` | Prompt definitions (`*.prompt.ts`). |
+| `src/services/openalex/` | OpenAlex API client service and domain types. |
+| `src/config/` | Environment variable parsing and validation with Zod. |
+| `tests/` | Unit and integration tests, mirroring the `src/` structure. |
+
+## Development Guide
+
+See [`CLAUDE.md`](./CLAUDE.md) for development guidelines and architectural rules. The short version:
+
+- Handlers throw, framework catches — no `try/catch` in tool logic
+- Use `ctx.log` for logging, `ctx.state` for storage
+- Always resolve names to IDs via `openalex_resolve_name` before using them in filters
+
+## Contributing
+
+Issues and pull requests are welcome. Run checks before submitting:
+
+```sh
+bun run devcheck
+bun run test
+```
+
+## License
+
+Apache-2.0 — see [LICENSE](LICENSE) for details.

package/dist/config/server-config.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Server-specific configuration for OpenAlex API access.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+declare const ServerConfigSchema: z.ZodObject<{
+    apiKey: z.ZodString;
+    baseUrl: z.ZodDefault<z.ZodString>;
+}, z.core.$strip>;
+export type ServerConfig = z.infer<typeof ServerConfigSchema>;
+export declare function getServerConfig(): ServerConfig;
+export {};
+//# sourceMappingURL=server-config.d.ts.map

package/dist/config/server-config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.d.ts","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,QAAA,MAAM,kBAAkB;;;iBAGtB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAI9D,wBAAgB,eAAe,IAAI,YAAY,CAM9C"}

package/dist/config/server-config.js

@@ -0,0 +1,18 @@
+/**
+ * @fileoverview Server-specific configuration for OpenAlex API access.
+ * @module config/server-config
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+const ServerConfigSchema = z.object({
+    apiKey: z.string().min(1).describe('OpenAlex API key'),
+    baseUrl: z.string().url().default('https://api.openalex.org').describe('OpenAlex API base URL'),
+});
+let _config;
+export function getServerConfig() {
+    _config ??= ServerConfigSchema.parse({
+        apiKey: process.env.OPENALEX_API_KEY,
+        baseUrl: process.env.OPENALEX_BASE_URL,
+    });
+    return _config;
+}
+//# sourceMappingURL=server-config.js.map

package/dist/config/server-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-config.js","sourceRoot":"","sources":["../../src/config/server-config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAE3C,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,kBAAkB,CAAC;IACtD,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,0BAA0B,CAAC,CAAC,QAAQ,CAAC,uBAAuB,CAAC;CAChG,CAAC,CAAC;AAIH,IAAI,OAAiC,CAAC;AAEtC,MAAM,UAAU,eAAe;IAC7B,OAAO,KAAK,kBAAkB,CAAC,KAAK,CAAC;QACnC,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,gBAAgB;QACpC,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB;KACvC,CAAC,CAAC;IACH,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview openalex-mcp-server MCP server entry point.
+ * @module index
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG"}

package/dist/index.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+/**
+ * @fileoverview openalex-mcp-server MCP server entry point.
+ * @module index
+ */
+import { createApp } from '@cyanheads/mcp-ts-core';
+import { literatureReviewPrompt } from './mcp-server/prompts/definitions/literature-review.prompt.js';
+import { researchLandscapePrompt } from './mcp-server/prompts/definitions/research-landscape.prompt.js';
+import { analyzeTrendsTool } from './mcp-server/tools/definitions/analyze-trends.tool.js';
+import { resolveNameTool } from './mcp-server/tools/definitions/resolve-name.tool.js';
+import { searchEntitiesTool } from './mcp-server/tools/definitions/search-entities.tool.js';
+import { initOpenAlexService } from './services/openalex/openalex-service.js';
+await createApp({
+    tools: [resolveNameTool, searchEntitiesTool, analyzeTrendsTool],
+    prompts: [literatureReviewPrompt, researchLandscapePrompt],
+    setup() {
+        initOpenAlexService();
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;GAGG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AACnD,OAAO,EAAE,sBAAsB,EAAE,MAAM,8DAA8D,CAAC;AACtG,OAAO,EAAE,uBAAuB,EAAE,MAAM,+DAA+D,CAAC;AACxG,OAAO,EAAE,iBAAiB,EAAE,MAAM,uDAAuD,CAAC;AAC1F,OAAO,EAAE,eAAe,EAAE,MAAM,qDAAqD,CAAC;AACtF,OAAO,EAAE,kBAAkB,EAAE,MAAM,wDAAwD,CAAC;AAC5F,OAAO,EAAE,mBAAmB,EAAE,MAAM,yCAAyC,CAAC;AAE9E,MAAM,SAAS,CAAC;IACd,KAAK,EAAE,CAAC,eAAe,EAAE,kBAAkB,EAAE,iBAAiB,CAAC;IAC/D,OAAO,EAAE,CAAC,sBAAsB,EAAE,uBAAuB,CAAC;IAC1D,KAAK;QACH,mBAAmB,EAAE,CAAC;IACxB,CAAC;CACF,CAAC,CAAC"}

package/dist/mcp-server/prompts/definitions/literature-review.prompt.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Prompt template for guided systematic literature review using OpenAlex tools.
+ * @module mcp-server/prompts/definitions/literature-review.prompt
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const literatureReviewPrompt: import("@cyanheads/mcp-ts-core").PromptDefinition<z.ZodObject<{
+    topic: z.ZodString;
+    scope: z.ZodDefault<z.ZodEnum<{
+        narrow: "narrow";
+        broad: "broad";
+    }>>;
+}, z.core.$strip>>;
+//# sourceMappingURL=literature-review.prompt.d.ts.map

package/dist/mcp-server/prompts/definitions/literature-review.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"literature-review.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/literature-review.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,eAAO,MAAM,sBAAsB;;;;;;kBAiDjC,CAAC"}

package/dist/mcp-server/prompts/definitions/literature-review.prompt.js

@@ -0,0 +1,53 @@
+/**
+ * @fileoverview Prompt template for guided systematic literature review using OpenAlex tools.
+ * @module mcp-server/prompts/definitions/literature-review.prompt
+ */
+import { prompt, z } from '@cyanheads/mcp-ts-core';
+export const literatureReviewPrompt = prompt('openalex_literature_review', {
+    description: 'Guides a systematic literature search: formulate query, search, filter, analyze citation network, synthesize findings.',
+    args: z.object({
+        topic: z.string().describe('Research topic or question to review.'),
+        scope: z
+            .enum(['narrow', 'broad'])
+            .default('narrow')
+            .describe('"narrow": focused on specific question. "broad": survey of the field.'),
+    }),
+    generate: (args) => [
+        {
+            role: 'user',
+            content: {
+                type: 'text',
+                text: `Conduct a systematic literature review on: "${args.topic}"
+
+Scope: ${args.scope}
+
+Follow this workflow using the OpenAlex tools:
+
+1. **Resolve entities** — Use openalex_resolve_name to identify key authors, institutions, or topics related to "${args.topic}". Collect their OpenAlex IDs.
+
+2. **Search literature** — Use openalex_search_entities to find relevant works.${args.scope === 'narrow'
+                    ? `
+   - Use exact search mode with specific phrases
+   - Filter tightly by resolved topic IDs
+   - Focus on a single topic cluster`
+                    : `
+   - Try keyword search for the topic
+   - Use semantic search for conceptually related work across subfields
+   - Search with multiple related topic IDs to capture adjacent areas`}
+   Use select to keep payloads manageable.
+
+3. **Identify key papers** — Sort by cited_by_count to find landmark works. Use openalex_search_entities with id to get full details on the most important ones.
+
+4. **Trace citations** — For key papers, search with the cited_by filter to find subsequent work, and the cites filter to find foundational work.
+
+5. **Analyze the landscape** — Use openalex_analyze_trends to understand:
+   - Publication volume over time (group_by: publication_year)
+   - Top contributing institutions (group_by: authorships.institutions.id)
+   - Open access availability (group_by: oa_status)
+
+6. **Synthesize** — Summarize findings: key themes, seminal papers, active research fronts, gaps in the literature, and methodological trends.`,
+            },
+        },
+    ],
+});
+//# sourceMappingURL=literature-review.prompt.js.map

package/dist/mcp-server/prompts/definitions/literature-review.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"literature-review.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/literature-review.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC,4BAA4B,EAAE;IACzE,WAAW,EACT,wHAAwH;IAC1H,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;QACnE,KAAK,EAAE,CAAC;aACL,IAAI,CAAC,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;aACzB,OAAO,CAAC,QAAQ,CAAC;aACjB,QAAQ,CAAC,uEAAuE,CAAC;KACrF,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB;YACE,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE;gBACP,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,+CAA+C,IAAI,CAAC,KAAK;;SAE9D,IAAI,CAAC,KAAK;;;;mHAIgG,IAAI,CAAC,KAAK;;iFAGnH,IAAI,CAAC,KAAK,KAAK,QAAQ;oBACrB,CAAC,CAAC;;;qCAGuB;oBACzB,CAAC,CAAC;;;sEAIN;;;;;;;;;;;;+IAYuI;aACxI;SACF;KACF;CACF,CAAC,CAAC"}

package/dist/mcp-server/prompts/definitions/research-landscape.prompt.d.ts

@@ -0,0 +1,9 @@
+/**
+ * @fileoverview Prompt template for quantitative research landscape analysis using OpenAlex tools.
+ * @module mcp-server/prompts/definitions/research-landscape.prompt
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const researchLandscapePrompt: import("@cyanheads/mcp-ts-core").PromptDefinition<z.ZodObject<{
+    topic: z.ZodString;
+}, z.core.$strip>>;
+//# sourceMappingURL=research-landscape.prompt.d.ts.map

package/dist/mcp-server/prompts/definitions/research-landscape.prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-landscape.prompt.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/research-landscape.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAU,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,eAAO,MAAM,uBAAuB;;kBAoClC,CAAC"}

package/dist/mcp-server/prompts/definitions/research-landscape.prompt.js

@@ -0,0 +1,42 @@
+/**
+ * @fileoverview Prompt template for quantitative research landscape analysis using OpenAlex tools.
+ * @module mcp-server/prompts/definitions/research-landscape.prompt
+ */
+import { prompt, z } from '@cyanheads/mcp-ts-core';
+export const researchLandscapePrompt = prompt('openalex_research_landscape', {
+    description: 'Analyzes the research landscape for a topic: volume trends, top authors/institutions, open access rates, funding sources.',
+    args: z.object({
+        topic: z.string().describe('Research area to analyze.'),
+    }),
+    generate: (args) => [
+        {
+            role: 'user',
+            content: {
+                type: 'text',
+                text: `Analyze the research landscape for: "${args.topic}"
+
+Use the OpenAlex tools to build a quantitative profile:
+
+1. **Resolve** — Use openalex_resolve_name to find the OpenAlex topic ID for "${args.topic}".
+
+2. **Volume & trends** — Use openalex_analyze_trends to group works by publication_year, filtered to the resolved topic. Is the field growing, stable, or declining?
+
+3. **Top contributors** — Analyze by:
+   - authorships.institutions.id (which institutions lead?)
+   - authorships.institutions.country_code (geographic distribution)
+   - primary_location.source.id (which journals publish most?)
+
+4. **Open access** — Group by oa_status. What fraction is freely available?
+
+5. **Funding** — Group by awards.funder_id to identify major funders. The group keys are OpenAlex IDs — resolve the top funder IDs with openalex_resolve_name to get human-readable names.
+
+6. **Impact** — Search for the most-cited works (sort by -cited_by_count). Get details on the top 5.
+
+7. **Emerging fronts** — Filter to the last 2 years, sort by -cited_by_count to find rising papers. Compare topics to the broader field.
+
+Present findings as a structured report with data tables and key takeaways.`,
+            },
+        },
+    ],
+});
+//# sourceMappingURL=research-landscape.prompt.js.map

package/dist/mcp-server/prompts/definitions/research-landscape.prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"research-landscape.prompt.js","sourceRoot":"","sources":["../../../../src/mcp-server/prompts/definitions/research-landscape.prompt.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAEnD,MAAM,CAAC,MAAM,uBAAuB,GAAG,MAAM,CAAC,6BAA6B,EAAE;IAC3E,WAAW,EACT,2HAA2H;IAC7H,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC;QACb,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,2BAA2B,CAAC;KACxD,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC;QAClB;YACE,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE;gBACP,IAAI,EAAE,MAAM;gBACZ,IAAI,EAAE,wCAAwC,IAAI,CAAC,KAAK;;;;gFAIgB,IAAI,CAAC,KAAK;;;;;;;;;;;;;;;;;4EAiBd;aACrE;SACF;KACF;CACF,CAAC,CAAC"}

package/dist/mcp-server/tools/definitions/analyze-trends.tool.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @fileoverview Aggregation tool for trend and distribution analysis via OpenAlex group_by.
+ * @module mcp-server/tools/definitions/analyze-trends.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const analyzeTrendsTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    entity_type: z.ZodEnum<{
+        works: "works";
+        authors: "authors";
+        sources: "sources";
+        institutions: "institutions";
+        topics: "topics";
+        keywords: "keywords";
+        publishers: "publishers";
+        funders: "funders";
+    }>;
+    group_by: z.ZodString;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    include_unknown: z.ZodDefault<z.ZodBoolean>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    meta: z.ZodObject<{
+        count: z.ZodNumber;
+        groups_count: z.ZodNullable<z.ZodNumber>;
+        next_cursor: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    groups: z.ZodArray<z.ZodObject<{
+        key: z.ZodString;
+        key_display_name: z.ZodString;
+        count: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+//# sourceMappingURL=analyze-trends.tool.d.ts.map

package/dist/mcp-server/tools/definitions/analyze-trends.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"analyze-trends.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/analyze-trends.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAIjD,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;kBA4F5B,CAAC"}

package/dist/mcp-server/tools/definitions/analyze-trends.tool.js

@@ -0,0 +1,82 @@
+/**
+ * @fileoverview Aggregation tool for trend and distribution analysis via OpenAlex group_by.
+ * @module mcp-server/tools/definitions/analyze-trends.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getOpenAlexService } from '../../../services/openalex/openalex-service.js';
+import { ENTITY_TYPES } from '../../../services/openalex/types.js';
+export const analyzeTrendsTool = tool('openalex_analyze_trends', {
+    description: 'Aggregate OpenAlex entities into groups and count them. Use for trend analysis (group works by publication_year), distribution analysis (group by oa_status, type, country), and comparative analysis (group by institution or topic). Combine with filters to scope the analysis. Returns up to 200 groups per page — use cursor pagination for fields with many distinct values.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        entity_type: z.enum(ENTITY_TYPES).describe('Entity type to aggregate.'),
+        group_by: z
+            .string()
+            .describe('Field to group by. Works examples: "publication_year", "type", "oa_status", "primary_topic.field.id", "authorships.institutions.country_code", "is_retracted". Authors: "last_known_institutions.country_code", "has_orcid". Sources: "type", "is_oa", "country_code". Not all fields support group_by — check entity docs if unsure.'),
+        filters: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe('Filter criteria (same syntax as openalex_search_entities filters). Narrows the population before aggregation. Example: group works by year, filtered to a specific topic.'),
+        include_unknown: z
+            .boolean()
+            .default(false)
+            .describe('Include a group for entities with no value for the grouped field. Hidden by default.'),
+        cursor: z
+            .string()
+            .optional()
+            .describe('Pagination cursor from a previous response. Group-by returns max 200 groups per page. Pass cursor to get the next page. Note: paginated groups are sorted by key, not by count.'),
+    }),
+    output: z.object({
+        meta: z
+            .object({
+            count: z.number().describe('Total entities matching the filters (before grouping).'),
+            groups_count: z.number().nullable().describe('Number of groups on this page (max 200).'),
+            next_cursor: z
+                .string()
+                .nullable()
+                .describe('Cursor for next page of groups. null if no more groups.'),
+        })
+            .describe('Aggregation metadata.'),
+        groups: z
+            .array(z.object({
+            key: z.string().describe('Group key (OpenAlex ID or raw value).'),
+            key_display_name: z.string().describe('Human-readable group label.'),
+            count: z.number().describe('Number of entities in this group.'),
+        }))
+            .describe('Aggregation groups with counts.'),
+    }),
+    async handler(input, ctx) {
+        const service = getOpenAlexService();
+        const result = await service.analyze({
+            entityType: input.entity_type,
+            groupBy: input.group_by,
+            filters: input.filters,
+            includeUnknown: input.include_unknown,
+            cursor: input.cursor,
+        }, ctx);
+        ctx.log.info('Trend analysis completed', {
+            entityType: input.entity_type,
+            groupBy: input.group_by,
+            totalCount: result.meta.count,
+            groupCount: result.groups.length,
+        });
+        return result;
+    },
+    format: (result) => {
+        if (result.groups.length === 0) {
+            return [{ type: 'text', text: 'No groups found.' }];
+        }
+        const sorted = [...result.groups].sort((a, b) => b.count - a.count);
+        const MAX_DISPLAY = 50;
+        const display = sorted.slice(0, MAX_DISPLAY);
+        const lines = display.map((g) => `${g.key_display_name}: ${g.count.toLocaleString()}`);
+        const truncated = sorted.length > MAX_DISPLAY ? `\n\n...and ${sorted.length - MAX_DISPLAY} more groups` : '';
+        return [
+            {
+                type: 'text',
+                text: `${result.meta.count.toLocaleString()} total entities across ${result.groups.length} groups:\n\n${lines.join('\n')}${truncated}`,
+            },
+        ];
+    },
+});
+//# sourceMappingURL=analyze-trends.tool.js.map

package/dist/mcp-server/tools/definitions/analyze-trends.tool.js.map

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

package/dist/mcp-server/tools/definitions/resolve-name.tool.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @fileoverview Tool for resolving names to OpenAlex IDs via autocomplete.
+ * @module mcp-server/tools/definitions/resolve-name.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const resolveNameTool: import("@cyanheads/mcp-ts-core").ToolDefinition<z.ZodObject<{
+    entity_type: z.ZodOptional<z.ZodEnum<{
+        works: "works";
+        authors: "authors";
+        sources: "sources";
+        institutions: "institutions";
+        topics: "topics";
+        keywords: "keywords";
+        publishers: "publishers";
+        funders: "funders";
+    }>>;
+    query: z.ZodString;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    results: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        external_id: z.ZodNullable<z.ZodString>;
+        display_name: z.ZodString;
+        entity_type: z.ZodString;
+        cited_by_count: z.ZodNumber;
+        works_count: z.ZodNullable<z.ZodNumber>;
+        hint: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>>;
+//# sourceMappingURL=resolve-name.tool.d.ts.map

package/dist/mcp-server/tools/definitions/resolve-name.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-name.tool.d.ts","sourceRoot":"","sources":["../../../../src/mcp-server/tools/definitions/resolve-name.tool.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAQ,CAAC,EAAE,MAAM,wBAAwB,CAAC;AAIjD,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;kBAkF1B,CAAC"}

package/dist/mcp-server/tools/definitions/resolve-name.tool.js

@@ -0,0 +1,73 @@
+/**
+ * @fileoverview Tool for resolving names to OpenAlex IDs via autocomplete.
+ * @module mcp-server/tools/definitions/resolve-name.tool
+ */
+import { tool, z } from '@cyanheads/mcp-ts-core';
+import { getOpenAlexService } from '../../../services/openalex/openalex-service.js';
+import { ENTITY_TYPES } from '../../../services/openalex/types.js';
+export const resolveNameTool = tool('openalex_resolve_name', {
+    description: 'Resolve a name or partial name to an OpenAlex ID. Returns up to 10 matches with disambiguation hints. ALWAYS use this before filtering by entity — names are ambiguous, IDs are not. Also accepts DOIs directly for quick lookup. Response time ~200ms.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        entity_type: z
+            .enum(ENTITY_TYPES)
+            .optional()
+            .describe('Entity type to search. Omit for cross-entity search (useful when entity type is unknown).'),
+        query: z
+            .string()
+            .min(1)
+            .describe('Name or partial name to resolve. Also accepts DOIs for quick lookup.'),
+        filters: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe('Narrow autocomplete results with filters. Example: restrict to a specific country or publication year range.'),
+    }),
+    output: z.object({
+        results: z
+            .array(z.object({
+            id: z.string().describe('OpenAlex ID.'),
+            external_id: z
+                .string()
+                .nullable()
+                .describe('Canonical external ID (DOI, ORCID, ROR, ISSN).'),
+            display_name: z.string().describe('Human-readable name.'),
+            entity_type: z
+                .string()
+                .describe('Entity type (work, author, source, institution, etc.).'),
+            cited_by_count: z
+                .number()
+                .describe('Citation count (direct for works, aggregate for others).'),
+            works_count: z
+                .number()
+                .nullable()
+                .describe('Associated works. null for works themselves.'),
+            hint: z
+                .string()
+                .nullable()
+                .describe('Disambiguation context: author names (works), last institution (authors), host org (sources), location (institutions).'),
+        }))
+            .describe('Autocomplete matches, up to 10.'),
+    }),
+    async handler(input, ctx) {
+        const service = getOpenAlexService();
+        const result = await service.autocomplete({
+            entityType: input.entity_type,
+            query: input.query,
+            filters: input.filters,
+        }, ctx);
+        ctx.log.info('Name resolved', {
+            query: input.query,
+            entityType: input.entity_type ?? 'all',
+            matchCount: result.results.length,
+        });
+        return result;
+    },
+    format: (result) => {
+        if (result.results.length === 0) {
+            return [{ type: 'text', text: 'No matches found.' }];
+        }
+        const lines = result.results.map((r) => `${r.display_name} (${r.entity_type}) — ${r.id}${r.hint ? ` [${r.hint}]` : ''}`);
+        return [{ type: 'text', text: lines.join('\n') }];
+    },
+});
+//# sourceMappingURL=resolve-name.tool.js.map

package/dist/mcp-server/tools/definitions/resolve-name.tool.js.map

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