openalex-research-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,6 +1,13 @@
 # OpenAlex MCP Server
 
-A Model Context Protocol (MCP) server that provides access to OpenAlex, a comprehensive open catalog of scholarly papers, authors, institutions, and more. This server is specifically designed to empower AI assistants to conduct literature reviews, analyze research trends, and map the scholarly landscape.
+A Model Context Protocol (MCP) server that provides access to OpenAlex, a comprehensive open catalog of scholarly papers, authors, institutions, and more. Designed to empower AI assistants to conduct literature reviews, analyze research trends, and map the scholarly landscape.
+
+**Features:**
+- ⚡️ **In-memory caching** with TTL for fast repeated requests
+- 🔄 **Retry logic** with exponential backoff for resilient API calls
+- ✅ **Input validation** with Zod schemas
+- 🏥 **Health check** tool for monitoring
+- 📊 **18+ specialized tools** for research
 
 ## Features
 
@@ -114,6 +121,12 @@ Add to your Claude Desktop config file:
 }
 ```
 
+### TypingMind and Other MCP Clients
+
+The same configuration format works for TypingMind and other MCP-compatible clients.
+
+> **⚠️ TypingMind Users**: If you encounter "tool_use_id" errors, see [TYPINGMIND.md](TYPINGMIND.md) for troubleshooting steps and best practices. **TL;DR**: Start a new chat, request fewer results (5-10), and use specific queries with filters.
+
 ## Usage Examples
 
 ### Example 1: Literature Review for AI Safety
@@ -122,7 +135,7 @@ Add to your Claude Desktop config file:
 Find the most influential papers on AI safety published since 2020
 ```
 
-The assistant will use `get_top_cited_works` with appropriate filters to find highly-cited papers in AI safety research.
+The assistant will use `get_top_cited_works` with appropriate filters to find highly-cited papers in AI safety research. The tool automatically filters for papers with at least 50 citations by default, ensuring results focus on influential work. For the most impactful papers, you can specify a higher threshold like `min_citations: 200`.
 
 ### Example 2: Citation Network Analysis
 
@@ -164,6 +177,60 @@ Which countries are leading research in climate change mitigation?
 
 The assistant will use `analyze_geographic_distribution` to map research activity by country.
 
+## Response Format
+
+The MCP server uses a **two-tier response system** to balance performance and completeness:
+
+### Summarized Responses (Search Results)
+
+For list operations (`search_works`, `get_citations`, `get_author_works`, etc.), responses include only essential information:
+
+**Included:**
+- Core identifiers (ID, DOI, title)
+- Publication metadata (year, date, type)
+- Citation metrics (cited_by_count)
+- First 5 authors (with `authors_truncated` flag if more exist)
+- Primary topic classification
+- Open access status and URLs
+- Source/journal name
+- Abstract preview (first 500 chars)
+
+**Excluded to reduce size:**
+- Full author lists beyond 5 authors
+- All secondary topics/concepts
+- Complete affiliation details
+- Full reference lists
+- Detailed bibliographic data
+
+This optimization reduces response sizes by ~80-90% (from ~10 KB to ~1.7 KB per work), making the server compatible with all MCP clients including TypingMind and Claude Desktop.
+
+### Full Details (`get_work` tool)
+
+When you need **complete information** about a specific paper, use the `get_work` tool with a work ID or DOI. This returns:
+
+**Complete Author Information:**
+- ALL authors (not just first 5)
+- Position indicators (first, middle, last author)
+- Institutions and affiliations
+- ORCID IDs
+- Corresponding author flags
+- Country information
+
+**Complete Content:**
+- Full abstract (reconstructed from OpenAlex index)
+- All topics (not just primary)
+- Complete bibliographic data
+- Funding and grant information
+- Keywords
+- Complete reference and citation lists
+
+**Use Cases:**
+- Identifying PIs (often last author in biomedical fields)
+- Finding corresponding authors
+- Getting complete author affiliations
+- Accessing full abstracts
+- Comprehensive paper analysis
+
 ## Tool Reference
 
 ### Search Parameters

package/build/config.d.ts

@@ -0,0 +1,31 @@
+export declare const CONFIG: {
+    API: {
+        BASE_URL: string;
+        TIMEOUT: number;
+        RATE_LIMIT: {
+            REQUESTS_PER_SECOND: number;
+            REQUESTS_PER_DAY: number;
+        };
+        RETRY: {
+            MAX_RETRIES: number;
+            INITIAL_DELAY_MS: number;
+            MAX_DELAY_MS: number;
+            BACKOFF_FACTOR: number;
+        };
+    };
+    CACHE: {
+        TTL_MS: number;
+        MAX_SIZE: number;
+    };
+    MCP: {
+        DEFAULT_PAGE_SIZE: number;
+        MAX_PAGE_SIZE: number;
+        MAX_AUTHORS_IN_SUMMARY: number;
+        MAX_ABSTRACT_LENGTH: number;
+        MAX_TOPICS: number;
+        MAX_KEYWORDS: number;
+        MAX_GRANTS: number;
+        MIN_CITATIONS_FOR_INFLUENTIAL: number;
+    };
+};
+//# sourceMappingURL=config.d.ts.map

package/build/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BlB,CAAC"}

package/build/config.js

@@ -0,0 +1,31 @@
+export const CONFIG = {
+    API: {
+        BASE_URL: 'https://api.openalex.org',
+        TIMEOUT: 30000,
+        RATE_LIMIT: {
+            REQUESTS_PER_SECOND: 10,
+            REQUESTS_PER_DAY: 100000,
+        },
+        RETRY: {
+            MAX_RETRIES: 3,
+            INITIAL_DELAY_MS: 1000,
+            MAX_DELAY_MS: 10000,
+            BACKOFF_FACTOR: 2,
+        },
+    },
+    CACHE: {
+        TTL_MS: 5 * 60 * 1000, // 5 minutes
+        MAX_SIZE: 1000,
+    },
+    MCP: {
+        DEFAULT_PAGE_SIZE: 10,
+        MAX_PAGE_SIZE: 200,
+        MAX_AUTHORS_IN_SUMMARY: 5,
+        MAX_ABSTRACT_LENGTH: 500,
+        MAX_TOPICS: 5,
+        MAX_KEYWORDS: 10,
+        MAX_GRANTS: 5,
+        MIN_CITATIONS_FOR_INFLUENTIAL: 50,
+    },
+};
+//# sourceMappingURL=config.js.map

package/build/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,GAAG,EAAE;QACH,QAAQ,EAAE,0BAA0B;QACpC,OAAO,EAAE,KAAK;QACd,UAAU,EAAE;YACV,mBAAmB,EAAE,EAAE;YACvB,gBAAgB,EAAE,MAAM;SACzB;QACD,KAAK,EAAE;YACL,WAAW,EAAE,CAAC;YACd,gBAAgB,EAAE,IAAI;YACtB,YAAY,EAAE,KAAK;YACnB,cAAc,EAAE,CAAC;SAClB;KACF;IACD,KAAK,EAAE;QACL,MAAM,EAAE,CAAC,GAAG,EAAE,GAAG,IAAI,EAAE,YAAY;QACnC,QAAQ,EAAE,IAAI;KACf;IACD,GAAG,EAAE;QACH,iBAAiB,EAAE,EAAE;QACrB,aAAa,EAAE,GAAG;QAClB,sBAAsB,EAAE,CAAC;QACzB,mBAAmB,EAAE,GAAG;QACxB,UAAU,EAAE,CAAC;QACb,YAAY,EAAE,EAAE;QAChB,UAAU,EAAE,CAAC;QACb,6BAA6B,EAAE,EAAE;KAClC;CACF,CAAC"}