openalex-mcp-server 1.0.1

package/src/json-optimizer.js

@@ -0,0 +1,153 @@
+/**
+ * JSON 格式优化器模块
+ * 将 OpenAlex API 返回的原始数据转换为简洁格式，提升 LLM 上下文利用效率
+ */
+
+import { rebuildAbstract, simplifyOpenAlexId } from './utils.js';
+
+/**
+ * 优化单篇论文数据
+ * 将 OpenAlex 原始响应转换为简化格式
+ * @param {Object} rawWork - OpenAlex API 返回的原始论文数据
+ * @returns {Object} 优化后的论文数据
+ * @example
+ * const optimized = optimizeWork(rawApiResponse);
+ */
+export function optimizeWork(rawWork) {
+  if (!rawWork || typeof rawWork !== 'object') {
+    return null;
+  }
+
+  // 提取和简化基础字段
+  const optimized = {
+    id: simplifyOpenAlexId(rawWork.id),
+    title: rawWork.title || '',
+    doi: rawWork.doi || null,
+    pmid: rawWork.pmid || null,
+    publication_year: rawWork.publication_year || null,
+    type: rawWork.type || null,
+    cited_by_count: rawWork.cited_by_count || 0,
+    concepts: (rawWork.concepts || []).slice(0, 5).map(c => ({
+      id: simplifyOpenAlexId(c.id),
+      display_name: c.display_name,
+      score: c.score
+    }))
+  };
+
+  // 提取发表期刊/会议信息
+  if (rawWork.primary_location) {
+    const source = rawWork.primary_location.source;
+    if (source) {
+      optimized.venue = {
+        id: simplifyOpenAlexId(source.id),
+        display_name: source.display_name,
+        type: source.type,
+        issn: source.issn || null,
+        is_oa: source.is_oa || false
+      };
+    }
+
+    // 提取卷期页码
+    if (rawWork.primary_location.volume) {
+      optimized.volume = rawWork.primary_location.volume;
+    }
+    if (rawWork.primary_location.issue) {
+      optimized.issue = rawWork.primary_location.issue;
+    }
+    if (rawWork.primary_location.pages) {
+      optimized.pages = rawWork.primary_location.pages;
+    }
+  }
+
+  // 扁平化作者信息
+  if (rawWork.authorships && rawWork.authorships.length > 0) {
+    optimized.authors = rawWork.authorships.map(authorship => ({
+      id: authorship.author ? simplifyOpenAlexId(authorship.author.id) : null,
+      display_name: authorship.author?.display_name || authorship.raw_author_name || '',
+      institution: authorship.institutions?.[0]?.display_name || null,
+      country: authorship.institutions?.[0]?.country_code || null,
+      is_corresponding: authorship.is_corresponding || null
+    }));
+  }
+
+  // 提取开放访问信息
+  if (rawWork.open_access) {
+    optimized.open_access = {
+      is_oa: rawWork.open_access.is_oa || false,
+      oa_status: rawWork.open_access.oa_status || null,
+      oa_url: rawWork.open_access.oa_url || null
+    };
+  }
+
+  // 重建摘要文本
+  if (rawWork.abstract_inverted_index) {
+    optimized.abstract = rebuildAbstract(rawWork.abstract_inverted_index);
+  }
+
+  // 提取主题/领域信息
+  if (rawWork.topics && rawWork.topics.length > 0) {
+    optimized.topics = rawWork.topics.slice(0, 3).map(topic => ({
+      id: simplifyOpenAlexId(topic.id),
+      display_name: topic.display_name,
+      subfield: topic.subfield?.display_name || null,
+      field: topic.field?.display_name || null,
+      domain: topic.domain?.display_name || null
+    }));
+  }
+
+  // 提取参考文献和被引信息
+  if (rawWork.referenced_works && rawWork.referenced_works.length > 0) {
+    optimized.referenced_works_count = rawWork.referenced_works.length;
+  }
+
+  // 提取最佳位置（OA URL）
+  if (rawWork.best_oa_location) {
+    optimized.best_pdf_url = rawWork.best_oa_location.pdf_url || null;
+  }
+
+  return optimized;
+}
+
+/**
+ * 优化搜索结果列表
+ * @param {Object} rawResults - OpenAlex API 返回的原始搜索结果
+ * @returns {Object} 优化后的搜索结果
+ * @example
+ * const optimized = optimizeSearchResults(rawSearchResponse);
+ */
+export function optimizeSearchResults(rawResults) {
+  if (!rawResults || typeof rawResults !== 'object') {
+    return {
+      meta: {
+        total_count: 0,
+        page: 1,
+        per_page: 20
+      },
+      papers: []
+    };
+  }
+
+  // 提取元数据
+  const meta = {
+    total_count: rawResults.meta?.count || 0,
+    page: rawResults.meta?.page || 1,
+    per_page: rawResults.meta?.per_page || 20
+  };
+
+  // 优化每篇论文
+  const papers = (rawResults.results || rawResults.results || []).map(work => optimizeWork(work));
+
+  return {
+    meta,
+    papers: papers.filter(p => p !== null)
+  };
+}
+
+/**
+ * 优化批量查询结果
+ * @param {Object} rawResults - OpenAlex API 返回的批量查询结果
+ * @returns {Object} 优化后的批量查询结果
+ */
+export function optimizeBatchResults(rawResults) {
+  return optimizeSearchResults(rawResults);
+}

package/src/openalex-client.js

@@ -0,0 +1,305 @@
+/**
+ * OpenAlex API 客户端模块
+ * 提供与 OpenAlex API 交互的基础功能
+ */
+
+import fetch from 'node-fetch';
+import { sleep } from './utils.js';
+
+/**
+ * OpenAlex API 客户端类
+ * 用于与 OpenAlex API 进行交互，支持可选的 API 密钥认证
+ */
+export class OpenAlexClient {
+  /**
+   * 创建 OpenAlex API 客户端实例
+   * @param {string} [apiKey] - 可选的 OpenAlex API 密钥
+   */
+  constructor(apiKey) {
+    this.baseUrl = 'https://api.openalex.org';
+    this.apiKey = apiKey;
+    this.userAgent = 'openalex-mcp-server/1.0.0 (mailto:your-email@example.com)';
+
+    // 速率限制：最多 10 请求/秒
+    this.rateLimitDelay = 100;
+    this.lastRequestTime = 0;
+  }
+
+  /**
+   * 发送 GET 请求到 OpenAlex API
+   * @private
+   * @param {string} endpoint - API 端点路径（相对于 baseUrl）
+   * @param {Object.<string, any>} [params={}] - 查询参数对象
+   * @returns {Promise<any>} API 响应的 JSON 数据
+   * @throws {Error} 当 HTTP 请求失败时抛出错误
+   * @example
+   * const data = await client._request('/works/W123456789');
+   * const results = await client._request('/works', { filter: 'title.search:quantum' });
+   */
+  async _request(endpoint, params = {}) {
+    // 速率限制：确保不超过 10 请求/秒
+    const now = Date.now();
+    const timeSinceLastRequest = now - this.lastRequestTime;
+    if (timeSinceLastRequest < this.rateLimitDelay) {
+      await sleep(this.rateLimitDelay - timeSinceLastRequest);
+    }
+    this.lastRequestTime = Date.now();
+
+    // 指数退避重试
+    const maxRetries = 5;
+    const retryDelays = [1000, 2000, 4000, 8000, 16000];
+    let lastError;
+
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
+      try {
+        return await this._executeRequest(endpoint, params);
+      } catch (error) {
+        lastError = error;
+
+        // 检查是否需要重试
+        if (error instanceof Error) {
+          const statusCode = this._extractStatusCode(error.message);
+
+          // 429 (Rate Limit)、500、502、503、504 可以重试
+          if (statusCode && (statusCode === 429 || statusCode >= 500)) {
+            if (attempt < maxRetries - 1) {
+              const delay = retryDelays[attempt];
+              console.error(`OpenAlex API 请求失败 (尝试 ${attempt + 1}/${maxRetries}): ${error.message}. ${delay}ms 后重试...`);
+              await sleep(delay);
+              continue;
+            }
+          }
+        }
+
+        // 不需要重试的错误直接抛出
+        throw error;
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * 执行单次 HTTP 请求
+   * @private
+   * @param {string} endpoint - API 端点路径
+   * @param {Object.<string, any>} params - 查询参数对象
+   * @returns {Promise<any>} API 响应的 JSON 数据
+   */
+  async _executeRequest(endpoint, params = {}) {
+    // 构建 URL
+    const url = new URL(endpoint, this.baseUrl);
+
+    // 添加查询参数
+    for (const [key, value] of Object.entries(params)) {
+      if (value !== undefined && value !== null) {
+        url.searchParams.append(key, String(value));
+      }
+    }
+
+    // 如果提供了 API 密钥，添加到查询参数
+    if (this.apiKey) {
+      url.searchParams.append('api_key', this.apiKey);
+    }
+
+    // 设置请求头
+    const headers = {
+      'User-Agent': this.userAgent,
+      'Accept': 'application/json'
+    };
+
+    try {
+      // 发送 GET 请求
+      const response = await fetch(url.toString(), {
+        method: 'GET',
+        headers
+      });
+
+      // 检查 HTTP 状态码
+      if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(
+          `OpenAlex API 请求失败: HTTP ${response.status} ${response.statusText}. ` +
+          `详情: ${errorText}`
+        );
+      }
+
+      // 解析并返回 JSON 响应
+      const data = await response.json();
+      return data;
+
+    } catch (error) {
+      // 如果是网络错误或其他异常，包装并重新抛出
+      if (error instanceof Error && error.message.includes('OpenAlex API 请求失败')) {
+        throw error;
+      }
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      throw new Error(`OpenAlex API 网络请求错误: ${errorMessage}`);
+    }
+  }
+
+  /**
+   * 从错误消息中提取 HTTP 状态码
+   * @private
+   * @param {string} errorMessage - 错误消息
+   * @returns {number|null} HTTP 状态码
+   */
+  _extractStatusCode(errorMessage) {
+    const match = errorMessage.match(/HTTP (\d{3})/);
+    return match ? parseInt(match[1], 10) : null;
+  }
+
+  /**
+   * 搜索论文
+   * @param {string} query - 搜索关键词（必需）
+   * @param {Object} [options={}] - 可选参数
+   * @param {number} [options.max_results=20] - 每页结果数（最大200）
+   * @param {number} [options.page=1] - 页码
+   * @param {string} [options.sort_by] - 排序字段，例如 'cited_by_count:desc'
+   * @param {Object} [options.filters] - 过滤器对象
+   * @param {number} [options.filters.publication_year] - 发表年份
+   * @param {boolean} [options.filters.is_oa] - 是否为开放获取
+   * @param {string} [options.filters.type] - 文献类型
+   * @returns {Promise<Object>} 搜索结果
+   * @example
+   * const results = await client.search('machine learning', { max_results: 10, sort_by: 'cited_by_count:desc' });
+   */
+  async search(query, options = {}) {
+    const {
+      max_results = 20,
+      page = 1,
+      sort_by,
+      filters = {}
+    } = options;
+
+    // 构建查询参数
+    const params = {};
+
+    // 添加分页参数
+    if (max_results > 0 && max_results <= 200) {
+      params['per-page'] = max_results;
+    }
+    if (page > 1) {
+      params.page = page;
+    }
+
+    // 添加排序
+    if (sort_by) {
+      params.sort = sort_by;
+    }
+
+    // 添加过滤器
+    const filterParts = [`title.search:${query}`];
+    if (filters.publication_year) {
+      filterParts.push(`publication_year:${filters.publication_year}`);
+    }
+    if (filters.is_oa !== undefined) {
+      filterParts.push(`is_oa:${filters.is_oa}`);
+    }
+    if (filters.type) {
+      filterParts.push(`type:${filters.type}`);
+    }
+
+    params.filter = filterParts.join(',');
+
+    // 使用 select 参数只获取必要字段
+    params.select = 'id,title,authorships,publication_year,primary_location,cited_by_count,open_access,doi,concepts';
+
+    return await this._request('/works', params);
+  }
+
+  /**
+   * 获取单篇论文详情
+   * @param {string} workId - 论文 ID（支持 OpenAlex ID、DOI、PMID）
+   * @param {Object} [options={}] - 可选参数
+   * @param {boolean} [options.include_abstract=true] - 是否包含摘要
+   * @param {boolean} [options.include_authors=true] - 是否包含作者信息
+   * @param {boolean} [options.include_topics=true] - 是否包含主题信息
+   * @returns {Promise<Object>} 论文详情
+   * @example
+   * const work = await client.getWork('W3128609807');
+   * const work2 = await client.getWork('10.1038/nature12373', { include_abstract: true });
+   */
+  async getWork(workId, options = {}) {
+    const {
+      include_abstract = true,
+      include_authors = true,
+      include_topics = true
+    } = options;
+
+    // 构建 select 参数
+    const selectParts = ['id', 'title', 'publication_year', 'type', 'cited_by_count', 'doi', 'pmid', 'primary_location', 'open_access', 'best_oa_location', 'referenced_works', 'concepts'];
+
+    if (include_abstract) {
+      selectParts.push('abstract_inverted_index');
+    }
+    if (include_authors) {
+      selectParts.push('authorships');
+    }
+    if (include_topics) {
+      selectParts.push('topics');
+    }
+
+    const params = {
+      select: selectParts.join(',')
+    };
+
+    // 判断 ID 类型并构建相应的请求
+    let endpoint;
+    if (workId.startsWith('10.')) {
+      // DOI 格式
+      endpoint = `/works/https://doi.org/${workId}`;
+    } else if (workId.match(/^\d+$/) && workId.length <= 8) {
+      // PMID 格式（纯数字且不超过8位）
+      endpoint = `/works/https://pubmed.ncbi.nlm.nih.gov/${workId}`;
+    } else {
+      // OpenAlex ID 格式（W123 或完整 URL）
+      endpoint = `/works/${workId}`;
+    }
+
+    return await this._request(endpoint, params);
+  }
+
+  /**
+   * 批量获取多篇论文信息
+   * @param {string[]} workIds - 论文 ID 数组（最多 50 个）
+   * @param {Object} [options={}] - 可选参数
+   * @param {boolean} [options.include_abstract=false] - 是否包含摘要
+   * @param {boolean} [options.include_authors=true] - 是否包含作者信息
+   * @returns {Promise<Object>} 批量查询结果
+   * @example
+   * const results = await client.batchGetWorks(['W3128609807', 'W2741809807']);
+   */
+  async batchGetWorks(workIds, options = {}) {
+    if (!Array.isArray(workIds) || workIds.length === 0) {
+      throw new Error('workIds 必须是非空数组');
+    }
+
+    if (workIds.length > 50) {
+      throw new Error('批量查询最多支持 50 个论文 ID');
+    }
+
+    const {
+      include_abstract = false,
+      include_authors = true
+    } = options;
+
+    // 构建 select 参数
+    const selectParts = ['id', 'title', 'publication_year', 'type', 'cited_by_count', 'doi', 'pmid', 'primary_location', 'open_access', 'concepts'];
+
+    if (include_abstract) {
+      selectParts.push('abstract_inverted_index');
+    }
+    if (include_authors) {
+      selectParts.push('authorships');
+    }
+
+    const params = {
+      select: selectParts.join(','),
+      'per-page': Math.min(workIds.length, 200),
+      filter: `openalex:${workIds.join('|')}`
+    };
+
+    return await this._request('/works', params);
+  }
+}

package/src/types/pdf-parse.d.ts

@@ -0,0 +1,13 @@
+declare module 'pdf-parse' {
+  interface PDFParseData {
+    text: string;
+    numpages: number;
+    numrender: number;
+    info: any;
+    metadata: any;
+    version: string;
+  }
+
+  function pdfParse(buffer: Buffer): Promise<PDFParseData>;
+  export = pdfParse;
+}

package/src/utils.js

@@ -0,0 +1,90 @@
+/**
+ * 工具函数模块
+ * 提供 OpenAlex MCP 服务器所需的通用工具函数
+ */
+
+/**
+ * 从 OpenAlex 的 abstract_inverted_index 重建完整摘要文本
+ * @param {Object.<string, number[]>} invertedIndex - 倒排索引对象，键为单词，值为位置数组
+ * @returns {string} 重建的完整摘要文本
+ * @example
+ * const invertedIndex = {
+ *   "This": [0],
+ *   "is": [1],
+ *   "a": [2],
+ *   "test": [3]
+ * };
+ * rebuildAbstract(invertedIndex); // "This is a test"
+ */
+export function rebuildAbstract(invertedIndex) {
+  if (!invertedIndex || typeof invertedIndex !== 'object') {
+    return '';
+  }
+
+  // 创建一个数组来存储按位置排列的单词
+  const words = [];
+
+  // 遍历倒排索引，将每个单词放到对应的位置
+  for (const [word, positions] of Object.entries(invertedIndex)) {
+    for (const position of positions) {
+      words[position] = word;
+    }
+  }
+
+  // 过滤掉空位置并用空格连接
+  return words.filter(word => word !== undefined).join(' ');
+}
+
+/**
+ * 将 OpenAlex 的完整 URL 简化为 ID
+ * @param {string} url - OpenAlex URL，例如 "https://openalex.org/W123456"
+ * @returns {string} 简化后的 ID，例如 "W123456"
+ * @example
+ * simplifyOpenAlexId("https://openalex.org/W123456"); // "W123456"
+ * simplifyOpenAlexId("W123456"); // "W123456"
+ */
+export function simplifyOpenAlexId(url) {
+  if (!url || typeof url !== 'string') {
+    return '';
+  }
+
+  // 如果已经是简化格式，直接返回
+  if (!url.includes('/')) {
+    return url;
+  }
+
+  // 提取 URL 最后一部分作为 ID
+  const parts = url.split('/');
+  return parts[parts.length - 1];
+}
+
+/**
+ * 异步延迟函数
+ * @param {number} ms - 延迟的毫秒数
+ * @returns {Promise<void>} 延迟后解决的 Promise
+ * @example
+ * await sleep(1000); // 延迟 1 秒
+ */
+export function sleep(ms) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+/**
+ * 验证 OpenAlex Work ID 格式
+ * @param {string} id - 要验证的 Work ID
+ * @returns {boolean} ID 格式是否有效
+ * @example
+ * validateWorkId("W123456789"); // true
+ * validateWorkId("W123"); // true
+ * validateWorkId("A123"); // false
+ * validateWorkId("123"); // false
+ */
+export function validateWorkId(id) {
+  if (!id || typeof id !== 'string') {
+    return false;
+  }
+
+  // OpenAlex Work ID 格式：以 'W' 开头，后跟数字
+  const workIdPattern = /^W\d+$/;
+  return workIdPattern.test(id);
+}

package/tests/cli.test.js

@@ -0,0 +1,31 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const rootDir = path.resolve(__dirname, '..');
+const require = createRequire(import.meta.url);
+const pkg = require(path.join(rootDir, 'package.json'));
+
+function runCli(args) {
+  const cliPath = path.join(rootDir, 'src', 'cli.js');
+  return spawnSync(process.execPath, [cliPath, ...args], {
+    encoding: 'utf-8'
+  });
+}
+
+test('cli --help exits 0', () => {
+  const result = runCli(['--help']);
+  assert.equal(result.status, 0);
+  assert.match(result.stdout, /OpenAlex MCP Server/i);
+});
+
+test('cli --version prints package version', () => {
+  const result = runCli(['--version']);
+  assert.equal(result.status, 0);
+  assert.equal(result.stdout.trim(), pkg.version);
+});

package/tsconfig.json

@@ -0,0 +1,22 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ES2022",
+    "moduleResolution": "node",
+    "lib": ["ES2022"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": false,
+    "resolveJsonModule": true,
+    "allowSyntheticDefaultImports": true,
+    "noEmit": true,
+    "checkJs": false,
+    "allowJs": true,
+    "noImplicitAny": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}