Contributing to IoWarp MCPs

Thank you for your interest in contributing to the IoWarp MCPs project! This document provides guidelines for contributing new MCP servers and improvements to existing ones.

Adding New MCPs

To add a new MCP server:

1. Create directory: Add your server to mcps/YourNewServer/
2. Add pyproject.toml: Include entry point like your-server-mcp = "module:main"
3. That's it! The launcher will auto-discover it

No manual mapping required - the system automatically finds all servers in the mcps/ folder.

Development Process

Current Development Status

All MCP implementations follow this development lifecycle:

Status Options:

• active development: Core functionality being built
• descriptions: Needs description updates
• documentation: Ready for documentation phase
• testing: Ready for testing phase

Getting Started

1. Prerequisites

   • Python 3.10 or higher
   • uv package manager
   • Linux/macOS environment (for optimal compatibility)

2. Clone and Setup

   git clone https://github.com/iowarp/scientific-mcps.git
   cd scientific-mcps
   
   # Create and activate environment
   python3 -m venv mcp-server
   source mcp-server/bin/activate  # On macOS/Linux
   
   # Install uv
   pip install uv
   

3. Install Dependencies

   # Install all MCPs
   uv pip install --requirement pyproject.toml
   
   # Or install specific MCPs as needed
   

MCP Server Structure

Each MCP server should follow this structure:

mcps/YourNewServer/
├── pyproject.toml          # Package configuration with entry point
├── README.md              # Server-specific documentation
├── src/
│   └── your_server/
│       ├── __init__.py
│       └── server.py      # Main server implementation
└── tests/                 # Test files

Testing Your MCP

1. Test with Universal Client:

   # Install client dependencies
   uv pip install -r bin/requirements.txt
   
   # Run with your preferred LLM provider
   python bin/wrp.py --conf=bin/confs/Gemini.yaml
   

2. Test Direct Server Execution:

   cd mcps/YourNewServer
   uv run your-server-mcp
   

3. Test with Unified Launcher:

   uvx iowarp-mcps your-server
   

Code Standards

• Follow Python PEP 8 style guidelines
• Include comprehensive docstrings
• Add type hints where appropriate
• Write tests for your MCP functionality
• Update documentation as needed

Submitting Changes

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-new-mcp)
3. Make your changes
4. Test thoroughly
5. Commit your changes (git commit -m 'Add YourNewServer MCP')
6. Push to the branch (git push origin feature/your-new-mcp)
7. Create a Pull Request

Pull Request Guidelines

• Provide a clear description of the changes
• Include any relevant issue numbers
• Ensure all tests pass
• Update documentation if needed
• Follow the existing code style

Support

For questions or help with contributions:

• Create an issue in the GitHub repository
• Check existing documentation in individual MCP README files
• Review the main project README for setup instructions

MCP Implementation Guidelines

For detailed implementation guidance, see these focused guides:

• MCP Architecture - Understanding MCP protocol and components
• Testing Guidelines - Unit and integration testing strategies
• Documentation Standards - README requirements and code documentation
• Contributing Workflow - Issue creation and development process

License

By contributing to this project, you agree that your contributions will be licensed under the same license as the project.