hetu-project/openresearch-mcp-server

OpenResearch MCP Server

An AI-powered academic research platform that provides MCP (Model Context Protocol) server capabilities for structuring academic papers into knowledge graphs and enabling automated paper review and generation.

🚀 Features

• Academic Paper Processing: Structure academic papers into knowledge graphs
• Automated Research Tools: AI-powered paper review and generation capabilities
• MCP Protocol Support: Full compatibility with Model Context Protocol
• Go Service Integration: High-performance backend services written in Go
• Asynchronous Architecture: Built with Python asyncio for optimal performance
• Comprehensive Logging: Structured logging with detailed error tracking

📋 Requirements

• Python 3.10
• Dependencies listed in requirements.txt

🛠️ Installation

1. Clone the repository

git clone https://github.com/yourusername/openresearch-mcp-server.git
cd openresearch-mcp-server

2. Install Python dependencies

pip install -r requirements.txt

🚀 Quick Start

Running the MCP Server

python src/main.py

The server will start and listen for MCP protocol connections via stdio.

Configuration

The server uses configuration settings from src/config.py. Key settings include:

• server_name: Name of the MCP server
• Logging configuration
• Service endpoints and timeouts

🏗️ Architecture

Core Components

• AcademicMCPServer: Main server class handling MCP protocol
• GoServiceClient: Client for communicating with Go backend services
• DataProcessor: Handles academic data processing and analysis
• Tool Registry: Dynamic tool registration and execution system

Project Structure

openresearch-mcp-server/
├── src/
│   ├── server/
│   │   └── mcp_server.py      # Main MCP server implementation
│   ├── clients/
│   │   └── go_client.py       # Go service client
│   ├── services/
│   │   └── data_processor.py  # Data processing services
│   ├── core/
│   │   └── tools.py           # Tool definitions and registry
│   ├── utils/
│   │   └── logging_config.py  # Logging configuration
│   ├── config.py              # Application configuration
│   └── main.py                # Application entry point
├── scripts/                   # Utility scripts
├── requirements.txt           # Python dependencies
└── README.md                  # This file

🔧 Available Tools

The server provides various research tools accessible via MCP protocol:

• Paper Analysis: Extract and analyze academic paper content
• Knowledge Graph Generation: Convert papers into structured knowledge graphs
• Research Synthesis: Automated literature review and synthesis
• Citation Analysis: Analyze citation networks and relationships

📡 MCP Protocol Support

Supported Capabilities

• Tools: Dynamic tool listing and execution
• Error Handling: Comprehensive error reporting and recovery
• Async Operations: Full asynchronous operation support

Tool Execution

Tools are executed via the MCP call_tool method:

{
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "param1": "value1",
      "param2": "value2"
    }
  }
}

🔍 Logging and Monitoring

The server uses structured logging with the following features:

• Structured Logs: JSON-formatted logs with contextual information
• Error Tracking: Detailed error reporting with stack traces
• Performance Monitoring: Tool execution timing and performance metrics
• Debug Support: Configurable log levels for development and production

🛡️ Error Handling

Robust error handling includes:

• Tool Validation: Verification of tool existence before execution
• Input Validation: Argument validation for all tool calls
• Graceful Degradation: Proper error responses via MCP protocol
• Resource Cleanup: Automatic cleanup of resources on shutdown

🔄 Development Workflow

Running in Development Mode

# Set development environment
export PYTHONPATH="${PYTHONPATH}:$(pwd)"
python src/main.py

Testing Tools

# List available tools
# (via MCP client)

# Execute a specific tool
# (via MCP client with tool parameters)

📊 Performance Considerations

• Async Architecture: Non-blocking I/O operations
• Connection Pooling: Efficient Go service client connections
• Resource Management: Proper cleanup and resource management
• Error Recovery: Automatic recovery from transient failures

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📝 License

This project is licensed under the MIT License - see the file for details.

🆘 Support

For support and questions:

• Create an issue on GitHub
• Check the documentation in the docs/ directory
• Review the code comments for implementation details

🔮 Roadmap

• Enhanced paper parsing capabilities
• Additional knowledge graph formats
• Real-time collaboration features
• Advanced citation analysis
• Integration with more academic databases

⚡ Performance Tips

1. Connection Management: The server uses async context managers for efficient resource handling
2. Tool Caching: Frequently used tools benefit from result caching
3. Batch Processing: Process multiple papers in batches for better performance

Built with ❤️ for the academic research community