Research MCP

# Project Structure ``` ResearchMCP/ ├── src/ │ ├── servers/ │ │ ├── arxiv-server.ts # arXiv MCP server implementation │ │ ├── semantic-scholar-server.ts # Semantic Scholar MCP server │ │ └── pubmed-server.ts # PubMed MCP server │ │ │ ├── examples/ │ │ └── multi-source-query.ts # Example workflow demonstrations │ │ │ ├── types.ts # TypeScript type definitions │ └── utils.ts # Shared utilities (rate limiting, dedup, BibTeX) │ ├── dist/ # Compiled JavaScript (generated by build) │ └── servers/ │ ├── arxiv-server.js │ ├── semantic-scholar-server.js │ └── pubmed-server.js │ ├── README.md # Main documentation ├── API_DOCUMENTATION.md # Detailed API reference ├── QUICKSTART.md # Quick start guide ├── LICENSE # MIT License │ ├── package.json # Project dependencies and scripts ├── tsconfig.json # TypeScript configuration ├── mcp-config.json # MCP client configuration example │ ├── .env.example # Environment variables template ├── .env # Your API keys (create this, not in git) └── .gitignore # Git ignore rules ``` ## File Descriptions ### Core Server Files **`src/servers/arxiv-server.ts`** - Implements arXiv API integration - Tools: search_arxiv, get_arxiv_paper, arxiv_to_bibtex - No API key required - Supports keyword, author, year, and category filtering **`src/servers/semantic-scholar-server.ts`** - Implements Semantic Scholar API integration - Tools: search_semantic_scholar, get_semantic_scholar_paper, get_paper_citations, semantic_scholar_to_bibtex - Optional API key for higher rate limits - Provides rich citation metadata **`src/servers/pubmed-server.ts`** - Implements PubMed/NCBI E-utilities integration - Tools: search_pubmed, get_pubmed_paper, pubmed_to_bibtex - Optional API key and email for better performance - Supports MeSH terms and biomedical search ### Utility Files **`src/types.ts`** - TypeScript interfaces for papers from all sources - Search parameters and configuration types - BibTeX and rate limiter interfaces **`src/utils.ts`** - `SimpleRateLimiter`: Automatic request throttling - `deduplicatePapers`: Remove duplicate results across sources - BibTeX generation: `arxivToBibTeX`, `semanticScholarToBibTeX`, `pubmedToBibTeX` - Query sanitization and error formatting - Text truncation and year parsing utilities **`src/examples/multi-source-query.ts`** - Example workflow for combining results from multiple sources - Unified paper format conversion - Sorting and ranking algorithms - Summary and trend generation - Example LLM conversation patterns ### Configuration Files **`package.json`** - Dependencies: MCP SDK, axios, xml2js, dotenv - Build scripts: `npm run build`, `npm run watch` - Server start scripts: `start:arxiv`, `start:semantic`, `start:pubmed` **`tsconfig.json`** - TypeScript compiler configuration - ES2022 target with Node16 modules - Strict type checking enabled - Output to `dist/` directory **`mcp-config.json`** - Example MCP client configuration - Command and arguments for each server - Environment variable setup **`.env.example`** - Template for API keys and configuration - Copy to `.env` and add your actual keys ### Documentation Files **`README.md`** - Project overview and features - Installation and setup instructions - Complete usage guide - Example queries and workflows - API response schemas - Contributing guidelines **`API_DOCUMENTATION.md`** - Detailed API reference for all tools - Request/response schemas - Error handling guide - Rate limit information - Best practices **`QUICKSTART.md`** - 5-minute setup guide - First query examples - Common use cases - Troubleshooting tips ## Key Features by File ### Rate Limiting (`utils.ts`) ```typescript SimpleRateLimiter(maxRequests: 3, windowSeconds: 1) - Automatic request throttling - Prevents API rate limit violations - Configurable limits per source ``` ### Deduplication (`utils.ts`) ```typescript deduplicatePapers(papers) - Title normalization and matching - Removes duplicates across sources - Preserves most complete metadata ``` ### BibTeX Generation (`utils.ts`) ```typescript arxivToBibTeX(paper) // arXiv → BibTeX semanticScholarToBibTeX() // Semantic Scholar → BibTeX pubmedToBibTeX() // PubMed → BibTeX - Automatic citation key generation - Proper field formatting - Complete metadata inclusion ``` ### Multi-Source Queries (`examples/multi-source-query.ts`) ```typescript combineResults() // Merge papers from all sources sortByRelevance() // Sort by citations/year generateSummary() // Create formatted summary extractTrends() // Analyze publication patterns ``` ## Build Output After running `npm run build`, the `dist/` directory contains: - Compiled JavaScript files - Source maps for debugging - Type declaration files (.d.ts) All servers are runnable from `dist/servers/*.js` ## Development Workflow 1. **Edit TypeScript**: Modify files in `src/` 2. **Build**: Run `npm run build` or `npm run watch` 3. **Test**: Start individual servers 4. **Deploy**: Use built files from `dist/` ## Adding New Features ### Add a New Research Source 1. Create `src/servers/newsource-server.ts` 2. Implement MCP server with tools 3. Add types to `src/types.ts` 4. Add BibTeX converter to `src/utils.ts` 5. Update documentation 6. Add start script to `package.json` ### Add New Tool to Existing Server 1. Define tool schema with inputSchema 2. Implement handler in CallToolRequestSchema 3. Add to tools array 4. Document in API_DOCUMENTATION.md ### Extend Utilities 1. Add functions to `src/utils.ts` 2. Export for use in servers 3. Add tests if applicable 4. Document usage ## Dependencies ### Production Dependencies - `@modelcontextprotocol/sdk`: MCP protocol implementation - `axios`: HTTP client for API requests - `xml2js`: XML parsing for arXiv/PubMed - `dotenv`: Environment variable management ### Development Dependencies - `typescript`: TypeScript compiler - `@types/node`: Node.js type definitions - `@types/xml2js`: xml2js type definitions ## Environment Variables Required for full functionality: - `SEMANTIC_SCHOLAR_API_KEY`: Higher rate limits - `PUBMED_API_KEY`: Higher rate limits - `PUBMED_EMAIL`: Required by NCBI All are optional but recommended for production use.