@cyanheads/openalex-mcp-server 0.2.7

package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts

@@ -0,0 +1,40 @@
+/**
+ * @fileoverview Primary discovery and lookup tool for OpenAlex entities.
+ * @module mcp-server/tools/definitions/search-entities.tool
+ */
+import { z } from '@cyanheads/mcp-ts-core';
+export declare const searchEntitiesTool: 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";
+    }>;
+    id: z.ZodOptional<z.ZodString>;
+    query: z.ZodOptional<z.ZodString>;
+    search_mode: z.ZodDefault<z.ZodEnum<{
+        keyword: "keyword";
+        exact: "exact";
+        semantic: "semantic";
+    }>>;
+    filters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    sort: z.ZodOptional<z.ZodString>;
+    select: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    per_page: z.ZodDefault<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    meta: z.ZodObject<{
+        count: z.ZodNumber;
+        per_page: z.ZodNumber;
+        next_cursor: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>;
+    results: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        display_name: z.ZodString;
+    }, z.core.$loose>>;
+}, z.core.$strip>>;
+//# sourceMappingURL=search-entities.tool.d.ts.map

package/dist/mcp-server/tools/definitions/search-entities.tool.d.ts.map

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

package/dist/mcp-server/tools/definitions/search-entities.tool.js

@@ -0,0 +1,113 @@
+/**
+ * @fileoverview Primary discovery and lookup tool for OpenAlex entities.
+ * @module mcp-server/tools/definitions/search-entities.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 searchEntitiesTool = tool('openalex_search_entities', {
+    description: 'Search, filter, sort, or retrieve by ID. Covers all OpenAlex entity types (works, authors, sources, institutions, topics, keywords, publishers, funders). Pass `id` to retrieve a single entity (free, unlimited API calls). Otherwise, use `query` and/or `filters` for discovery. Supports keyword search with boolean operators, exact phrase matching, and AI semantic search. Use openalex_resolve_name to resolve names to IDs before filtering. Use the `select` parameter to reduce payload size — works (~70KB) and institutions (~20KB) are especially large without it.',
+    annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: true },
+    input: z.object({
+        entity_type: z.enum(ENTITY_TYPES).describe('Type of scholarly entity to search.'),
+        id: z
+            .string()
+            .optional()
+            .describe('Retrieve a single entity by ID. Supports: OpenAlex ID ("W2741809807"), DOI ("10.1038/nature12373"), ORCID ("0000-0002-1825-0097"), ROR ("https://ror.org/00hx57361"), PMID ("12345678"), PMCID ("PMC1234567"), ISSN ("1234-5678"). When provided, other search/filter/sort params are ignored. Use openalex_resolve_name to find the ID if unknown.'),
+        query: z
+            .string()
+            .optional()
+            .describe('Text search query. Supports boolean operators (AND, OR, NOT), quoted phrases ("exact match"), wildcards (machin*), fuzzy matching (machin~1), and proximity ("climate change"~5). Omit for filter-only queries.'),
+        search_mode: z
+            .enum(['keyword', 'exact', 'semantic'])
+            .default('keyword')
+            .describe('Search strategy. "keyword": stemmed full-text (default). "exact": no stemming, matches individual words (use quoted phrases for multi-word exact match). "semantic": AI embedding similarity (max 50 results, 1 req/sec).'),
+        filters: z
+            .record(z.string(), z.string())
+            .optional()
+            .describe('Filter criteria as field:value pairs. AND across fields (multiple keys). OR within field: pipe-separate ("us|gb"). NOT: prefix "!" ("!us"). Range: "2020-2024". Comparison: ">100", "<50". AND within same field: "+"-separate. Use OpenAlex IDs (not names) for entity filters — resolve names first.'),
+        sort: z
+            .string()
+            .optional()
+            .describe('Sort field. Prefix with "-" for descending. Common: "cited_by_count", "-publication_date", "relevance_score" (default when query present).'),
+        select: z
+            .array(z.string())
+            .optional()
+            .describe('Fields to return (reduces payload). Top-level fields only. STRONGLY RECOMMENDED for works and institutions — full records are 20-70KB each. Example: ["id", "doi", "display_name", "publication_year", "cited_by_count", "primary_topic"].'),
+        per_page: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .default(25)
+            .describe('Results per page (1-100). Default 25.'),
+        cursor: z
+            .string()
+            .optional()
+            .describe('Pagination cursor from a previous response. Pass to get the next page.'),
+    }),
+    output: z.object({
+        meta: z
+            .object({
+            count: z.number().describe('Total results matching the query/filters.'),
+            per_page: z.number().describe('Results on this page.'),
+            next_cursor: z
+                .string()
+                .nullable()
+                .describe('Cursor for next page. null if no more results.'),
+        })
+            .describe('Result metadata including pagination.'),
+        results: z
+            .array(z
+            .object({
+            id: z.string().describe('OpenAlex ID (e.g., "W2741809807", "A1234567890").'),
+            display_name: z.string().describe('Entity name or work title.'),
+        })
+            .passthrough())
+            .describe('Entity objects. Additional fields depend on entity_type and select.'),
+    }),
+    async handler(input, ctx) {
+        const service = getOpenAlexService();
+        const result = await service.search({
+            entityType: input.entity_type,
+            id: input.id,
+            query: input.query,
+            searchMode: input.search_mode,
+            filters: input.filters,
+            sort: input.sort,
+            select: input.select,
+            perPage: input.per_page,
+            cursor: input.cursor,
+        }, ctx);
+        ctx.log.info('Search completed', {
+            entityType: input.entity_type,
+            id: input.id,
+            query: input.query,
+            resultCount: result.results.length,
+            totalCount: result.meta.count,
+        });
+        return result;
+    },
+    format: (result) => {
+        const header = `Found ${result.meta.count} result(s).`;
+        if (result.results.length === 0) {
+            return [{ type: 'text', text: header }];
+        }
+        const lines = result.results.map((r) => {
+            const parts = [r.display_name];
+            const rec = r;
+            if (rec.publication_year)
+                parts.push(String(rec.publication_year));
+            if (typeof rec.cited_by_count === 'number')
+                parts.push(`${rec.cited_by_count.toLocaleString()} citations`);
+            if (rec.doi)
+                parts.push(String(rec.doi));
+            return `- ${parts[0]} (${r.id})${parts.length > 1 ? ` — ${parts.slice(1).join(', ')}` : ''}`;
+        });
+        const footer = result.meta.next_cursor
+            ? `\n[More results available — pass cursor to paginate]`
+            : '';
+        return [{ type: 'text', text: `${header}\n\n${lines.join('\n')}${footer}` }];
+    },
+});
+//# sourceMappingURL=search-entities.tool.js.map

package/dist/mcp-server/tools/definitions/search-entities.tool.js.map

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

package/dist/services/openalex/openalex-service.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @fileoverview OpenAlex API client service. Handles all communication with the OpenAlex REST API.
+ * @module services/openalex/openalex-service
+ */
+import type { Context } from '@cyanheads/mcp-ts-core';
+import { type AnalyzeParams, type AnalyzeResult, type AutocompleteParams, type AutocompleteResult, type SearchParams, type SearchResult } from './types.js';
+declare class OpenAlexService {
+    private readonly baseUrl;
+    private readonly apiKey;
+    constructor();
+    /** Execute an HTTP request against the OpenAlex API with retry on transient failures. */
+    private request;
+    /** Search/filter/sort entities, or retrieve a single entity by ID. */
+    search(params: SearchParams, ctx: Context): Promise<SearchResult>;
+    /** Group-by aggregation. */
+    analyze(params: AnalyzeParams, ctx: Context): Promise<AnalyzeResult>;
+    /** Autocomplete name resolution. */
+    autocomplete(params: AutocompleteParams, ctx: Context): Promise<AutocompleteResult>;
+}
+export declare function initOpenAlexService(): void;
+export declare function getOpenAlexService(): OpenAlexService;
+export {};
+//# sourceMappingURL=openalex-service.d.ts.map

package/dist/services/openalex/openalex-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openalex-service.d.ts","sourceRoot":"","sources":["../../../src/services/openalex/openalex-service.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,wBAAwB,CAAC;AAKtD,OAAO,EACL,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EAGvB,KAAK,YAAY,EACjB,KAAK,YAAY,EAClB,MAAM,YAAY,CAAC;AA8GpB,cAAM,eAAe;IACnB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;;IAQhC,yFAAyF;YAC3E,OAAO;IAwDrB,sEAAsE;IAChE,MAAM,CAAC,MAAM,EAAE,YAAY,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC;IAqEvE,4BAA4B;IACtB,OAAO,CAAC,MAAM,EAAE,aAAa,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC;IAgC1E,oCAAoC;IAC9B,YAAY,CAAC,MAAM,EAAE,kBAAkB,EAAE,GAAG,EAAE,OAAO,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAwB1F;AAID,wBAAgB,mBAAmB,IAAI,IAAI,CAE1C;AAED,wBAAgB,kBAAkB,IAAI,eAAe,CAIpD"}

package/dist/services/openalex/openalex-service.js

@@ -0,0 +1,254 @@
+/**
+ * @fileoverview OpenAlex API client service. Handles all communication with the OpenAlex REST API.
+ * @module services/openalex/openalex-service
+ */
+import { notFound, serviceUnavailable } from '@cyanheads/mcp-ts-core/errors';
+import { getServerConfig } from '../../config/server-config.js';
+import { ENTITY_TYPES, } from './types.js';
+/**
+ * Build an OpenAlex filter string from a key-value record.
+ * Input: { "cited_by_count": ">100", "is_oa": "true" }
+ * Output: "cited_by_count:>100,is_oa:true"
+ */
+function buildFilterString(filters) {
+    return Object.entries(filters)
+        .map(([key, value]) => `${key}:${value}`)
+        .join(',');
+}
+/**
+ * Detect ID format and return the API path segment.
+ * "10.1038/nature12373" → "doi:10.1038/nature12373"
+ * "https://doi.org/10.1038/nature12373" → "doi:10.1038/nature12373"
+ * "0000-0002-1825-0097" → "orcid:0000-0002-1825-0097"
+ * "https://ror.org/00hx57361" → "ror:https://ror.org/00hx57361"
+ * "PMC1234567" → "pmcid:PMC1234567"
+ * "W2741809807" → "W2741809807"
+ */
+function normalizeId(id) {
+    const trimmed = id.trim();
+    // Full OpenAlex URL
+    if (trimmed.startsWith('https://openalex.org/')) {
+        return trimmed.replace('https://openalex.org/', '');
+    }
+    // DOI URL
+    if (trimmed.startsWith('https://doi.org/')) {
+        return `doi:${trimmed.replace('https://doi.org/', '')}`;
+    }
+    // DOI pattern (10.xxxx/...)
+    if (/^10\.\d{4,}\//.test(trimmed)) {
+        return `doi:${trimmed}`;
+    }
+    // ROR URL
+    if (trimmed.startsWith('https://ror.org/')) {
+        return `ror:${trimmed}`;
+    }
+    // ORCID pattern (0000-0000-0000-0000)
+    if (/^\d{4}-\d{4}-\d{4}-\d{3}[\dX]$/i.test(trimmed)) {
+        return `orcid:${trimmed}`;
+    }
+    // ISSN pattern (0000-0000)
+    if (/^\d{4}-\d{3}[\dX]$/i.test(trimmed)) {
+        return `issn:${trimmed}`;
+    }
+    // PMCID
+    if (/^PMC\d+$/i.test(trimmed)) {
+        return `pmcid:${trimmed}`;
+    }
+    // Pure numeric → PMID
+    if (/^\d{5,}$/.test(trimmed)) {
+        return `pmid:${trimmed}`;
+    }
+    // OpenAlex ID or already prefixed — pass through
+    return trimmed;
+}
+/**
+ * Reconstruct abstract text from OpenAlex's inverted index format.
+ * The API stores abstracts as { word: [position, ...] } — we reverse this to plaintext.
+ */
+function reconstructAbstract(invertedIndex) {
+    const words = [];
+    for (const [word, positions] of Object.entries(invertedIndex)) {
+        for (const pos of positions) {
+            words.push([pos, word]);
+        }
+    }
+    words.sort((a, b) => a[0] - b[0]);
+    return words.map(([, word]) => word).join(' ');
+}
+/**
+ * Post-process entity records: reconstruct abstracts from inverted indices.
+ */
+function processResults(results) {
+    for (const record of results) {
+        if (record.abstract_inverted_index &&
+            typeof record.abstract_inverted_index === 'object' &&
+            !Array.isArray(record.abstract_inverted_index)) {
+            record.abstract = reconstructAbstract(record.abstract_inverted_index);
+            delete record.abstract_inverted_index;
+        }
+    }
+    return results;
+}
+const MAX_RETRIES = 3;
+const BASE_BACKOFF_MS = 1000;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+class OpenAlexService {
+    baseUrl;
+    apiKey;
+    constructor() {
+        const config = getServerConfig();
+        this.baseUrl = config.baseUrl.replace(/\/+$/, '');
+        this.apiKey = config.apiKey;
+    }
+    /** Execute an HTTP request against the OpenAlex API with retry on transient failures. */
+    async request(path, params, ctx) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        url.searchParams.set('mailto', this.apiKey);
+        for (const [key, value] of Object.entries(params)) {
+            if (value)
+                url.searchParams.set(key, value);
+        }
+        ctx.log.debug('OpenAlex request', { path, params: Object.keys(params) });
+        for (let attempt = 0; attempt < MAX_RETRIES; attempt++) {
+            const response = await fetch(url.toString(), {
+                headers: { Accept: 'application/json' },
+                signal: ctx.signal,
+            });
+            if (response.ok)
+                return response.json();
+            if (response.status === 404) {
+                throw notFound(`Entity not found at ${path}`, { path, status: 404 });
+            }
+            const retryable = response.status === 429 ||
+                response.status === 500 ||
+                response.status === 502 ||
+                response.status === 503 ||
+                response.status === 504;
+            if (retryable && attempt < MAX_RETRIES - 1) {
+                await sleep(BASE_BACKOFF_MS * 2 ** attempt);
+                continue;
+            }
+            const body = await response.text().catch(() => '');
+            let detail = '';
+            try {
+                const parsed = JSON.parse(body);
+                detail = parsed.message ?? '';
+            }
+            catch {
+                detail = body
+                    .replace(/<[^>]*>/g, '')
+                    .trim()
+                    .slice(0, 200);
+            }
+            const message = detail
+                ? `OpenAlex API error (${response.status}): ${detail}`
+                : `OpenAlex API error: ${response.status} ${response.statusText}`;
+            throw serviceUnavailable(message, { path, status: response.status });
+        }
+        throw serviceUnavailable(`OpenAlex API request failed after ${MAX_RETRIES} attempts`, { path });
+    }
+    /** Search/filter/sort entities, or retrieve a single entity by ID. */
+    async search(params, ctx) {
+        // Singleton lookup by ID
+        if (params.id) {
+            const normalizedId = normalizeId(params.id);
+            const queryParams = {};
+            if (params.select?.length) {
+                queryParams.select = params.select.join(',');
+            }
+            const data = (await this.request(`/${params.entityType}/${normalizedId}`, queryParams, ctx));
+            const results = processResults([data]);
+            return {
+                meta: { count: 1, per_page: 1, next_cursor: null },
+                results,
+            };
+        }
+        // Search/filter/list
+        const queryParams = {};
+        if (params.query) {
+            const searchKey = params.searchMode === 'exact'
+                ? 'search.exact'
+                : params.searchMode === 'semantic'
+                    ? 'search.semantic'
+                    : 'search';
+            queryParams[searchKey] = params.query;
+        }
+        if (params.filters && Object.keys(params.filters).length > 0) {
+            queryParams.filter = buildFilterString(params.filters);
+        }
+        if (params.sort) {
+            // Translate "-field" prefix to "field:desc" (OpenAlex API syntax)
+            queryParams.sort = params.sort.startsWith('-') ? `${params.sort.slice(1)}:desc` : params.sort;
+        }
+        if (params.select?.length) {
+            queryParams.select = params.select.join(',');
+        }
+        queryParams.per_page = String(params.perPage ?? 25);
+        // Semantic search doesn't support cursor pagination — use page/per_page only
+        if (params.searchMode !== 'semantic') {
+            queryParams.cursor = params.cursor ?? '*';
+        }
+        const data = (await this.request(`/${params.entityType}`, queryParams, ctx));
+        return {
+            meta: {
+                ...data.meta,
+                next_cursor: data.meta.next_cursor ?? null,
+            },
+            results: processResults(data.results),
+        };
+    }
+    /** Group-by aggregation. */
+    async analyze(params, ctx) {
+        const queryParams = {};
+        queryParams.group_by = params.includeUnknown
+            ? `${params.groupBy}:include_unknown`
+            : params.groupBy;
+        if (params.filters && Object.keys(params.filters).length > 0) {
+            queryParams.filter = buildFilterString(params.filters);
+        }
+        // Only send cursor when explicitly provided — boolean group_by fields
+        // (is_retracted, has_orcid, etc.) reject cursor pagination entirely.
+        if (params.cursor) {
+            queryParams.cursor = params.cursor;
+        }
+        const data = (await this.request(`/${params.entityType}`, queryParams, ctx));
+        return {
+            meta: {
+                count: data.meta.count,
+                groups_count: data.meta.groups_count ?? data.group_by?.length ?? null,
+                next_cursor: data.meta.next_cursor ?? null,
+            },
+            groups: data.group_by ?? [],
+        };
+    }
+    /** Autocomplete name resolution. */
+    async autocomplete(params, ctx) {
+        const path = params.entityType ? `/autocomplete/${params.entityType}` : '/autocomplete';
+        const queryParams = {
+            q: params.query,
+        };
+        if (params.filters && Object.keys(params.filters).length > 0) {
+            queryParams.filter = buildFilterString(params.filters);
+        }
+        const data = (await this.request(path, queryParams, ctx));
+        // Cross-entity autocomplete can return types not in our enum (country, license, etc.).
+        // Filter to known entity types so callers can use results in other tools directly.
+        const knownTypes = new Set(ENTITY_TYPES.map((t) => t.replace(/s$/, '')));
+        const results = params.entityType
+            ? data.results
+            : data.results.filter((r) => knownTypes.has(r.entity_type));
+        return { results };
+    }
+}
+let _service;
+export function initOpenAlexService() {
+    _service = new OpenAlexService();
+}
+export function getOpenAlexService() {
+    if (!_service)
+        throw new Error('OpenAlexService not initialized — call initOpenAlexService() in setup()');
+    return _service;
+}
+//# sourceMappingURL=openalex-service.js.map

package/dist/services/openalex/openalex-service.js.map

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

package/dist/services/openalex/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @fileoverview Domain types for OpenAlex API interactions.
+ * @module services/openalex/types
+ */
+export declare const ENTITY_TYPES: readonly ["works", "authors", "sources", "institutions", "topics", "keywords", "publishers", "funders"];
+export type EntityType = (typeof ENTITY_TYPES)[number];
+export interface SearchParams {
+    cursor?: string | undefined;
+    entityType: EntityType;
+    filters?: Record<string, string> | undefined;
+    id?: string | undefined;
+    perPage?: number | undefined;
+    query?: string | undefined;
+    searchMode?: 'keyword' | 'exact' | 'semantic' | undefined;
+    select?: string[] | undefined;
+    sort?: string | undefined;
+}
+export interface SearchResult {
+    meta: {
+        count: number;
+        per_page: number;
+        next_cursor: string | null;
+    };
+    results: EntityRecord[];
+}
+export interface AnalyzeParams {
+    cursor?: string | undefined;
+    entityType: EntityType;
+    filters?: Record<string, string> | undefined;
+    groupBy: string;
+    includeUnknown?: boolean | undefined;
+}
+export interface AnalyzeResult {
+    groups: GroupRecord[];
+    meta: {
+        count: number;
+        groups_count: number | null;
+        next_cursor: string | null;
+    };
+}
+export interface AutocompleteParams {
+    entityType?: EntityType | undefined;
+    filters?: Record<string, string> | undefined;
+    query: string;
+}
+export interface AutocompleteResult {
+    results: AutocompleteRecord[];
+}
+export interface EntityRecord {
+    display_name: string;
+    id: string;
+    [key: string]: unknown;
+}
+export interface GroupRecord {
+    count: number;
+    key: string;
+    key_display_name: string;
+}
+export interface AutocompleteRecord {
+    cited_by_count: number;
+    display_name: string;
+    entity_type: string;
+    external_id: string | null;
+    hint: string | null;
+    id: string;
+    works_count: number | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/services/openalex/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/services/openalex/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,eAAO,MAAM,YAAY,yGASf,CAAC;AAEX,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC7C,EAAE,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,KAAK,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,UAAU,CAAC,EAAE,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,CAAC;IAC1D,MAAM,CAAC,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC9B,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC3B;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,CAAC;IACF,OAAO,EAAE,YAAY,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,UAAU,EAAE,UAAU,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,OAAO,GAAG,SAAS,CAAC;CACtC;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,WAAW,EAAE,CAAC;IACtB,IAAI,EAAE;QACJ,KAAK,EAAE,MAAM,CAAC;QACd,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;KAC5B,CAAC;CACH;AAED,MAAM,WAAW,kBAAkB;IACjC,UAAU,CAAC,EAAE,UAAU,GAAG,SAAS,CAAC;IACpC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,kBAAkB,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,YAAY,EAAE,MAAM,CAAC;IACrB,EAAE,EAAE,MAAM,CAAC;IACX,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;CAC5B"}

package/dist/services/openalex/types.js

@@ -0,0 +1,15 @@
+/**
+ * @fileoverview Domain types for OpenAlex API interactions.
+ * @module services/openalex/types
+ */
+export const ENTITY_TYPES = [
+    'works',
+    'authors',
+    'sources',
+    'institutions',
+    'topics',
+    'keywords',
+    'publishers',
+    'funders',
+];
+//# sourceMappingURL=types.js.map

package/dist/services/openalex/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/services/openalex/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,OAAO;IACP,SAAS;IACT,SAAS;IACT,cAAc;IACd,QAAQ;IACR,UAAU;IACV,YAAY;IACZ,SAAS;CACD,CAAC"}

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "@cyanheads/openalex-mcp-server",
+  "version": "0.2.7",
+  "description": "Access the OpenAlex academic research catalog - 270M+ publications through MCP. STDIO & Streamable HTTP.",
+  "mcpName": "io.github.cyanheads/openalex-mcp-server",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "openalex-mcp-server": "dist/index.js"
+  },
+  "files": ["dist/", "README.md", "LICENSE", "CLAUDE.md", "Dockerfile", "server.json"],
+  "scripts": {
+    "build": "bun scripts/build.ts",
+    "rebuild": "bun scripts/clean.ts && bun scripts/build.ts",
+    "clean": "bun scripts/clean.ts",
+    "devcheck": "bun scripts/devcheck.ts",
+    "tree": "bun scripts/tree.ts",
+    "format": "biome check --write --unsafe .",
+    "lint:mcp": "bun scripts/lint-mcp.ts",
+    "test": "vitest run",
+    "dev:stdio": "MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts",
+    "dev:http": "MCP_TRANSPORT_TYPE=http bun --watch src/index.ts",
+    "start:stdio": "MCP_TRANSPORT_TYPE=stdio node dist/index.js",
+    "start:http": "MCP_TRANSPORT_TYPE=http node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "openalex",
+    "academic-research",
+    "academic-search",
+    "bibliometrics",
+    "citation-analysis",
+    "literature-search",
+    "scholarly-data",
+    "scholarly-research",
+    "typescript"
+  ],
+  "author": "cyanheads (https://github.com/cyanheads)",
+  "homepage": "https://github.com/cyanheads/openalex-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/cyanheads/openalex-mcp-server/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cyanheads/openalex-mcp-server.git"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.0.0",
+    "bun": ">=1.3.0"
+  },
+  "packageManager": "bun@1.3.11",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@cyanheads/mcp-ts-core": "^0.1.28",
+    "pino-pretty": "^13.1.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.8",
+    "@types/node": "^25.5.0",
+    "depcheck": "^1.4.7",
+    "ignore": "^7.0.5",
+    "tsc-alias": "^1.8.16",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.1"
+  }
+}