Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
251 lines (190 loc) · 7.09 KB

CONTRIBUTING.md

File metadata and controls

251 lines (190 loc) · 7.09 KB

Contributing to Qiskit MCP Servers

Thank you for your interest in contributing to Qiskit MCP Servers! This document provides guidelines and instructions for contributing to this project.

Code of Conduct

By participating in this project, you agree to abide by the Qiskit Code of Conduct. Please treat all community members with respect and create a welcoming environment for everyone.

Getting Started

Prerequisites

Before you begin, ensure you have the following installed:

  • Python 3.10+ (3.11+ recommended)
  • uv - Modern Python package manager
  • Git - Version control
  • IBM Quantum account - Get your API token from quantum.cloud.ibm.com

Development Setup

  1. Fork and clone the repository:

    git clone https://github.com/<your-username>/mcp-servers.git
cd mcp-servers

  2. Navigate to the server you want to work on:

    cd qiskit-mcp-server
# OR
cd qiskit-code-assistant-mcp-server
# OR
cd qiskit-ibm-runtime-mcp-server
# OR
cd qiskit-ibm-transpiler-mcp-server
# OR
cd qiskit-docs-mcp-server
# OR
cd qiskit-gym-mcp-server

  3. Install dependencies (make sure you're in a sub-package directory from step 2):

    uv sync --group dev --group test

  4. Configure environment variables (if the server requires authentication):

    cp .env.example .env  # where available
# Edit .env and add your IBM Quantum API token

  5. Run the server locally:

    uv run qiskit-mcp-server
# OR
uv run qiskit-code-assistant-mcp-server
# OR
uv run qiskit-ibm-runtime-mcp-server
# OR
uv run qiskit-ibm-transpiler-mcp-server
# OR
uv run qiskit-docs-mcp-server
# OR
uv run qiskit-gym-mcp-server

  6. Test interactively with MCP Inspector (requires Node.js):

    npx @modelcontextprotocol/inspector uv run qiskit-code-assistant-mcp-server

Contributing Workflow

1. Find or Create an Issue

  • Browse existing issues to find something to work on
  • If you have a new idea, create an issue first to discuss it
  • Assign yourself to the issue you're working on for visibility

2. Create a Feature Branch

# Ensure your main branch is up to date
git checkout main
git pull origin main

# Create a new branch with a descriptive name
git checkout -b feature/your-feature-name
# OR
git checkout -b fix/bug-description

3. Make Your Changes

  • Follow the code conventions below
  • Write tests for new functionality
  • Update documentation as needed

4. Run Tests and Quality Checks

Before submitting, ensure all checks pass:

# Run tests
./run_tests.sh
# OR
uv run pytest

# Format code
uv run ruff format src/ tests/

# Lint code
uv run ruff check src/ tests/

# Type check
uv run mypy src/

5. Commit Your Changes

Write clear, descriptive commit messages:

git add .
git commit -m "feat: description of what was added"
# OR
git commit -m "fix: description of bug that was fixed"

6. Submit a Pull Request

  1. Push your branch to your fork:

    git push origin feature/your-feature-name

  2. Open a Pull Request against the main branch

  3. Fill out the PR template with:

    • A summary of changes
    • Link to related issue(s)
    • Description of how it was tested

  4. Wait for review - at least one approval is required before merging

Code Conventions

Python Standards

  • Python version: 3.10+ features allowed
  • Async/await: Primary implementation for all MCP operations
  • Type hints: Required (mypy strict mode)
  • Naming: snake_case for functions/variables, PascalCase for classes
  • Docstrings: Google style for public functions

MCP Server Patterns

  • All servers use the FastMCP framework
  • Tools are defined with @mcp.tool() decorator
  • Resources are defined with @mcp.resource() decorator
  • Async functions for all MCP handlers
  • Use nest_asyncio when synchronous wrappers are needed for DSPy/Jupyter compatibility

Error Handling

  • Use appropriate HTTP status codes
  • Provide clear error messages
  • Log errors for debugging
  • Handle network failures gracefully
  • Validate inputs before API calls

Testing

  • Write tests in tests/ directory
  • Use pytest with async support (pytest-asyncio)
  • Mock external APIs (pytest-mock, respx for HTTP)
  • Target 65%+ code coverage

Project Structure

This is a monorepo with multiple independent MCP servers:

qiskit-mcp-servers/
├── qiskit-mcp-server/                   # Core Qiskit server with circuit utilities
├── qiskit-code-assistant-mcp-server/    # AI code completion server
├── qiskit-ibm-runtime-mcp-server/       # IBM Quantum cloud services
├── qiskit-ibm-transpiler-mcp-server/    # AI-powered transpilation
├── qiskit-docs-mcp-server/              # Documentation retrieval
├── qiskit-gym-mcp-server/               # RL-based circuit synthesis (community)
├── README.md                            # Main documentation
├── CONTRIBUTING.md                      # This file
├── AGENTS.md                            # AI assistant guidance
└── LICENSE                              # Apache 2.0

Each server follows this structure:

<server-name>/
├── src/<package_name>/
│   ├── __init__.py          # Main entry point
│   ├── server.py            # FastMCP server definition
│   ├── <core>.py            # Core async functionality
│   └── utils.py             # Utilities (optional)
├── tests/
│   ├── conftest.py          # Test fixtures
│   └── test_*.py            # Unit/integration tests
├── pyproject.toml           # Project metadata
├── README.md                # Server documentation
└── run_tests.sh             # Test runner

Adding New Features

Adding a New Tool

# In server.py
@mcp.tool()
async def my_new_tool(param: str) -> dict:
    """Tool description for AI assistant."""
    # Implementation
    return {"result": "data"}

Adding a New Resource

# In server.py
@mcp.resource("protocol://path")
async def my_resource() -> str:
    """Resource description."""
    return "resource content"

Getting Help

AI Development Assistants

This repository includes AGENTS.md which provides comprehensive guidance for AI coding assistants (like IBM Bob, Claude Code, GitHub Copilot, and others). If you're using an AI assistant to help with contributions, it will have context about the codebase structure, conventions, and best practices.

License

By contributing to Qiskit MCP Servers, you agree that your contributions will be licensed under the Apache License 2.0.