Metadata-Version: 2.4
Name: genome-mcp
Version: 0.1.3
Summary: Genome Model Context Protocol (MCP) server for genomic data access
Author-email: gqy20 <qingyu_ge@foxmail.com>
Maintainer-email: gqy20 <qingyu_ge@foxmail.com>
License: MIT
Project-URL: Homepage, https://github.com/gqy20/genome-mcp
Project-URL: Documentation, https://github.com/gqy20/genome-mcp#readme
Project-URL: Repository, https://github.com/gqy20/genome-mcp.git
Project-URL: Bug Tracker, https://github.com/gqy20/genome-mcp/issues
Keywords: genomics,mcp,bioinformatics,api,ncbi,gene
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.8.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: structlog>=23.0.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: fastmcp>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: isort>=5.12.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"

# Genome MCP - Model Context Protocol Server for Genomic Data

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Publish](https://github.com/gqy20/genome-mcp/workflows/Publish/badge.svg)](https://github.com/gqy20/genome-mcp/actions/workflows/publish.yml)
[![Code Quality](https://github.com/gqy20/genome-mcp/workflows/Quality/badge.svg)](https://github.com/gqy20/genome-mcp/actions/workflows/quality.yml)
[![PyPI version](https://badge.fury.io/py/genome-mcp.svg)](https://badge.fury.io/py/genome-mcp)

A Model Context Protocol (MCP) server that provides unified access to genomic databases through a standardized API interface. Built with async architecture and designed for AI-tool integration using the FastMCP framework.

## Features

- **MCP Server Architecture**: Built on Model Context Protocol for seamless AI-tool integration
- **NCBI Database Integration**: Full access to NCBI Gene database via EUtils API
- **Async Performance**: High-performance async/await architecture
- **Rate Limiting & Caching**: Built-in request optimization and response caching
- **Type Safety**: Full type hints with Pydantic models
- **FastMCP Framework**: Built on FastMCP for standardized MCP protocol implementation
- **Modern Python**: Uses uv for dependency management and modern packaging

## Installation

### Using uv (Recommended)

```bash
# Install with uv
uv add genome-mcp

# Or run directly without installation
uv run genome-mcp --help
```

### Using pip

```bash
pip install genome-mcp
```

## Quick Start

### Running as MCP Server

```bash
# Run as stdio MCP server (for AI tools like Claude Desktop)
genome-mcp --transport stdio

# Run as SSE server (for web applications)
genome-mcp --transport sse --host localhost --port 8080

# Run as Streamable HTTP server (for API integration)
genome-mcp --transport streamable-http --host localhost --port 8080
```

### Python API

```python
import asyncio
from main import get_gene_info, search_genes

async def main():
    # Get gene information
    gene_info = await get_gene_info("7157")  # TP53
    print(f"Gene: {gene_info['info']['name']}")
    print(f"Description: {gene_info['info']['description']}")
    
    # Search for genes
    search_results = await search_genes("cancer", species="human")
    print(f"Found {len(search_results['results'])} genes")

if __name__ == "__main__":
    asyncio.run(main())
```

## Configuration

### Environment Variables

```bash
# NCBI API key (optional but recommended for higher rate limits)
export NCBI_API_KEY="your_ncbi_api_key"

# Email for NCBI API (required for some operations)
export NCBI_EMAIL="your_email@example.com"
```

### Project Configuration

The project includes a comprehensive configuration file (`project_config.json`) that defines:

- Server settings and capabilities
- Rate limiting and caching configuration
- Logging and monitoring settings
- Development and deployment options

### Configuration File

Create a configuration file at `~/.genome_mcp/config.json`:

```json
{
  "servers": {
    "ncbi_gene": {
      "base_url": "https://eutils.ncbi.nlm.nih.gov/entrez/eutils",
      "rate_limit": {
        "requests_per_second": 3,
        "burst_limit": 10
      },
      "cache": {
        "enabled": true,
        "ttl": 3600
      }
    }
  },
  "logging": {
    "level": "INFO",
    "format": "json"
  }
}
```

## Development

### Setup Development Environment

```bash
# Clone the repository
git clone https://github.com/your-org/genome-mcp.git
cd genome-mcp

# Install with uv
uv sync --dev

# Install pre-commit hooks
uv run pre-commit install
```

### Running Tests

```bash
# Run all tests
uv run pytest

# Run with coverage
uv run pytest --cov=src --cov-report=html

# Run specific test file
uv run pytest tests/test_ncbi_gene_server.py
```

### Code Quality

```bash
# Format code
uv run black src/ tests/

# Sort imports
uv run isort src/ tests/

# Type checking
uv run mypy src/

# Linting
uv run ruff check src/ tests/
```

## Configuring MCP Integration

### For Claude Desktop

Add the following configuration to your Claude Desktop settings:

```json
{
  "mcpServers": {
    "genome-mcp": {
      "command": "uvx",
      "args": [
        "genome-mcp"
      ],
      "env": {}
    }
  }
}
```

### For Cherry Studio

Add the following configuration to your Cherry Studio settings:

```json
{
  "mcpServers": {
    "genome-mcp": {
      "command": "uvx",
      "args": [
        "genome-mcp",
        "stdio"
      ],
      "env": {}
    }
  }
}
```

### Manual Configuration

You can also run the MCP server manually:

```bash
# Run as stdio MCP server (for AI tools like Claude Desktop)
genome-mcp --transport stdio

# Run as SSE server (for web applications)
genome-mcp --transport sse --host localhost --port 8080

# Run as Streamable HTTP server (for API integration)
genome-mcp --transport streamable-http --host localhost --port 8080
```

## Project Structure

```
genome-mcp/
  main.py                  # FastMCP server entry point
  src/                     # Source code
    servers/               # MCP server implementations
      base.py            # Base MCP server class
      ncbi/              # NCBI server implementations
        gene.py         # NCBI Gene server
    configuration.py       # Configuration management
    http_utils/            # HTTP utilities
    data/                  # Data processing
    core/                  # Core utilities
    exceptions.py          # Exception definitions
  tests/                   # Test code
  docs/                    # Documentation
  examples/               # Example code
  .github/                # GitHub Actions workflows
  project_config.json      # Project configuration
```

## Architecture

### FastMCP Server Architecture

- **FastMCP Framework**: Built on the FastMCP framework for MCP protocol implementation
- **NCBIGeneServer**: Implementation for NCBI Gene database access
- **MCP Tools**: Expose genomic data functions as MCP tools
- **Async Design**: Full async/await support for high performance
- **Rate Limiting**: Built-in request rate limiting with Token Bucket algorithm
- **Caching**: Optional response caching to improve performance
- **Error Handling**: Comprehensive error handling and logging

### Key Components

- **main.py**: FastMCP server entry point with tool decorators
- **NCBIGeneServer**: NCBI Gene database access implementation
- **MCP Transport**: Support for stdio, SSE, and Streamable HTTP transports
- **Request Execution**: Support for single and batch requests
- **Configuration Management**: JSON-based configuration system

## Contributing

We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Citation

If you use Genome MCP in your research, please cite:

```bibtex
@software{genome_mcp,
  title={Genome MCP: Model Context Protocol Server for Genomic Data},
  author={gqy20},
  year={2025},
  url={https://github.com/gqy20/genome-mcp}
}
```

## Support

- **Documentation**: [https://github.com/gqy20/genome-mcp#readme](https://github.com/gqy20/genome-mcp#readme)
- **Issues**: [https://github.com/gqy20/genome-mcp/issues](https://github.com/gqy20/genome-mcp/issues)
- **Discussions**: [https://github.com/gqy20/genome-mcp/discussions](https://github.com/gqy20/genome-mcp/discussions)

## Acknowledgments

- [NCBI](https://www.ncbi.nlm.nih.gov/) for providing comprehensive genomic databases
- [Model Context Protocol](https://modelcontextprotocol.io/) for enabling AI-tool integration
- [FastMCP](https://github.com/gofastmcp/fastmcp) for the MCP framework implementation
- [uv](https://github.com/astral-sh/uv) for modern Python package management
