CONTRIBUTING.md•8.87 kB
# Contributing to Research MCP
Thank you for your interest in contributing to Research MCP! This document provides guidelines for developers who want to contribute to the project.
## 🚀 Getting Started
### Prerequisites
- Node.js 18 or higher
- npm or yarn
- Git
- TypeScript knowledge
- Familiarity with MCP specification
### Development Setup
1. **Fork and Clone**
```bash
git clone https://github.com/YOUR_USERNAME/ResearchMCP.git
cd ResearchMCP
```
2. **Install Dependencies**
```bash
npm install
```
3. **Build the Project**
```bash
npm run build
```
4. **Watch Mode (Development)**
```bash
npm run watch
```
## 🏗️ Project Structure
```
src/
├── servers/ # MCP server implementations
├── types.ts # TypeScript type definitions
├── utils.ts # Shared utilities
└── examples/ # Example workflows
dist/ # Compiled output (generated)
```
## 📝 Development Workflow
### 1. Create a Feature Branch
```bash
git checkout -b feature/your-feature-name
```
### 2. Make Your Changes
- Edit TypeScript files in `src/`
- Follow existing code style
- Add types for everything (no `any` types)
- Document public APIs with JSDoc comments
### 3. Build and Test
```bash
# Build
npm run build
# Test individual servers
npm run start:arxiv
npm run start:semantic
npm run start:pubmed
```
### 4. Test with MCP Client
Configure your MCP client to use the local build:
```json
{
"mcpServers": {
"research-arxiv": {
"command": "node",
"args": ["./dist/servers/arxiv-server.js"],
"cwd": "/path/to/your/ResearchMCP"
}
}
}
```
### 5. Commit Your Changes
```bash
git add .
git commit -m "feat: add your feature description"
```
**Commit Message Format:**
- `feat:` - New feature
- `fix:` - Bug fix
- `docs:` - Documentation changes
- `refactor:` - Code refactoring
- `test:` - Adding tests
- `chore:` - Maintenance tasks
### 6. Push and Create PR
```bash
git push origin feature/your-feature-name
```
Then create a Pull Request on GitHub.
## 🎯 Contribution Areas
### High Priority
1. **Add New Research Sources**
- IEEE Xplore
- ACM Digital Library
- Google Scholar
- bioRxiv/medRxiv
2. **Enhanced Features**
- Full-text search
- Advanced citation analysis
- Paper recommendation system
- Duplicate detection improvements
3. **Performance**
- Caching layer
- Parallel requests
- Response streaming
### Code Quality
1. **Testing**
- Unit tests for utilities
- Integration tests for servers
- E2E testing with MCP clients
2. **Documentation**
- API documentation
- Code comments
- Usage examples
- Troubleshooting guides
3. **Type Safety**
- Improve type definitions
- Remove any remaining `any` types
- Add stricter type checks
## 📐 Code Style Guidelines
### TypeScript
```typescript
// ✅ Good: Explicit types, clear naming
async function searchPapers(params: SearchParams): Promise<Paper[]> {
const results = await api.search(params);
return results.map(formatPaper);
}
// ❌ Bad: Implicit any, unclear names
async function search(p) {
const r = await api.search(p);
return r.map(f);
}
```
### Error Handling
```typescript
// ✅ Good: Proper error handling
try {
const result = await externalAPI();
return { success: true, data: result };
} catch (error) {
if (axios.isAxiosError(error)) {
return { error: `API error: ${error.message}` };
}
return { error: formatError(error) };
}
// ❌ Bad: Silent failures
try {
await externalAPI();
} catch (e) {
return null;
}
```
### Documentation
```typescript
/**
* Search for academic papers with filters
*
* @param query - Search keywords or phrases
* @param options - Optional filter parameters
* @returns Array of paper objects with metadata
* @throws {Error} If query is empty or API is unavailable
*
* @example
* ```typescript
* const papers = await searchPapers('machine learning', {
* startYear: 2023,
* maxResults: 10
* });
* ```
*/
async function searchPapers(
query: string,
options?: SearchOptions
): Promise<Paper[]> {
// Implementation
}
```
## 🔧 Adding a New Research Source
### Step 1: Create Server File
Create `src/servers/newsource-server.ts`:
```typescript
#!/usr/bin/env node
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { CallToolRequestSchema, ListToolsRequestSchema, Tool } from '@modelcontextprotocol/sdk/types.js';
// Define your tools
const tools: Tool[] = [
{
name: 'search_newsource',
description: 'Search papers in NewSource',
inputSchema: {
type: 'object',
properties: {
query: { type: 'string', description: 'Search query' }
},
required: ['query']
}
}
];
// Create server
const server = new Server(
{ name: 'newsource-server', version: '1.0.0' },
{ capabilities: { tools: {} } }
);
// Implement handlers
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools }));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
// Handle tool calls
});
// Start server
async function main() {
const transport = new StdioServerTransport();
await server.connect(transport);
console.error('NewSource MCP Server running');
}
main().catch(console.error);
```
### Step 2: Add Types
Add to `src/types.ts`:
```typescript
export interface NewSourcePaper {
id: string;
title: string;
authors: string[];
abstract: string;
// ... other fields
}
```
### Step 3: Add Utilities
Add to `src/utils.ts` (if needed):
```typescript
export function newSourceToBibTeX(paper: NewSourcePaper): string {
// Generate BibTeX citation
}
```
### Step 4: Update package.json
```json
{
"bin": {
"researchmcp-newsource": "./dist/servers/newsource-server.js"
},
"scripts": {
"start:newsource": "node dist/servers/newsource-server.js"
}
}
```
### Step 5: Document
Update:
- `README.md` - Add to features list
- `API_DOCUMENTATION.md` - Document all tools
- `QUICKSTART.md` - Add usage examples
### Step 6: Test
```bash
npm run build
npm run start:newsource
```
## 🧪 Testing Guidelines
### Manual Testing
1. **Build successfully**
```bash
npm run build
```
2. **No TypeScript errors**
```bash
npx tsc --noEmit
```
3. **Server starts without errors**
```bash
npm run start:arxiv
# Should output: "arXiv MCP Server running on stdio"
```
4. **Test with MCP client**
- Configure in Claude Desktop or Cline
- Run sample queries
- Verify responses are correct
### Integration Testing
Test with real MCP clients:
- Claude Desktop
- Cline (VS Code)
- Other MCP-compatible tools
## 📋 Pull Request Checklist
Before submitting a PR, ensure:
- [ ] Code builds without errors (`npm run build`)
- [ ] TypeScript has no errors (`npx tsc --noEmit`)
- [ ] No `any` types added (use explicit types)
- [ ] All new functions have JSDoc comments
- [ ] README updated (if adding features)
- [ ] API_DOCUMENTATION updated (if adding tools)
- [ ] Tested manually with MCP client
- [ ] Commit messages follow convention
- [ ] Branch is up to date with main
## 🐛 Bug Reports
When reporting bugs, include:
1. **Description** - What happened vs. what you expected
2. **Reproduction Steps** - How to reproduce the issue
3. **Environment**
- Node.js version
- Operating system
- MCP client used
4. **Logs** - Error messages or console output
5. **Code Sample** - Minimal code to reproduce (if applicable)
## 💡 Feature Requests
When suggesting features:
1. **Use Case** - Why is this feature needed?
2. **Proposed Solution** - How should it work?
3. **Alternatives** - Other approaches considered?
4. **Implementation** - Any ideas on implementation?
## 📚 Resources
### MCP Documentation
- [MCP Specification](https://modelcontextprotocol.io/)
- [MCP SDK Documentation](https://github.com/modelcontextprotocol/sdk)
### API Documentation
- [arXiv API](https://arxiv.org/help/api)
- [Semantic Scholar API](https://api.semanticscholar.org/)
- [PubMed E-utilities](https://www.ncbi.nlm.nih.gov/books/NBK25501/)
### TypeScript
- [TypeScript Handbook](https://www.typescriptlang.org/docs/)
- [TypeScript Best Practices](https://typescript-eslint.io/rules/)
## 🤝 Code of Conduct
- Be respectful and inclusive
- Focus on constructive feedback
- Help others learn and grow
- Follow project guidelines
## ⚖️ License
By contributing, you agree that your contributions will be licensed under the MIT License.
## 💬 Questions?
- Open an issue for bugs or feature requests
- Start a discussion for general questions
- Check existing issues before creating new ones
---
**Thank you for contributing to Research MCP!** 🎉