pdbe-mcp-server 1.0.0__tar.gz

pdbe_mcp_server-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,97 @@
+name: CI
+
+on:
+  push:
+    branches: [ main, develop, search ]
+    tags: [ 'v*' ]
+  pull_request:
+    branches: [ main, develop ]
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ['3.10', '3.11', '3.12']
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+      with:
+        version: "latest"
+
+    - name: Set up Python ${{ matrix.python-version }}
+      run: uv python install ${{ matrix.python-version }}
+
+    - name: Install dependencies
+      run: |
+        uv sync --all-extras --dev
+
+    - name: Run ruff linter
+      run: uv run ruff check .
+
+    - name: Run ruff formatter
+      run: uv run ruff format --check .
+
+    - name: Run type checker
+      run: uv run pyright
+
+    - name: Run tests with coverage
+      run: |
+        uv run pytest --cov=pdbe_mcp_server --cov-report=xml --cov-report=term
+
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v4
+      with:
+        file: ./coverage.xml
+        flags: unittests
+        name: codecov-umbrella
+        fail_ci_if_error: false
+
+  build:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    needs: test
+
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install uv
+      uses: astral-sh/setup-uv@v3
+
+    - name: Build package
+      run: uv build
+
+    - name: Check package
+      run: |
+        uv run twine check dist/*
+
+    - name: Upload artifacts
+      uses: actions/upload-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+  publish:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
+    runs-on: ubuntu-latest
+    needs: build
+    environment: release
+    permissions:
+      id-token: write
+
+    steps:
+    - name: Download artifacts
+      uses: actions/download-artifact@v4
+      with:
+        name: dist
+        path: dist/
+
+    - name: Publish package
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        user: ${{ secrets.PYPI_USERNAME }}
+        password: ${{ secrets.PYPI_PASSWORD }}

pdbe_mcp_server-1.0.0/.gitignore

@@ -0,0 +1,10 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv

pdbe_mcp_server-1.0.0/.nvmrc

@@ -0,0 +1 @@
+v20.10.0

pdbe_mcp_server-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,31 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-yaml
+      - id: check-added-large-files
+      - id: check-case-conflict
+      - id: check-docstring-first
+      - id: detect-private-key
+      - id: trailing-whitespace
+      - id: fix-byte-order-marker
+      - id: end-of-file-fixer
+        # args: ["--maxkb=3000"]
+      - id: check-ast
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.3.5 # Ruff version.
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/dzhu/rstfmt
+    rev: v0.0.14
+    hooks:
+      - id: rstfmt
+        name: rST Formatter
+  - repo: https://github.com/pycqa/isort
+    rev: 5.12.0
+    hooks:
+      - id: isort
+        name: isort (python)
+        args: ["--profile", "black"]

pdbe_mcp_server-1.0.0/.python-version

@@ -0,0 +1 @@
+3.13

pdbe_mcp_server-1.0.0/.vscode/settings.json

@@ -0,0 +1,11 @@
+{
+    "python.testing.unittestArgs": [
+        "-v",
+        "-s",
+        "./tests",
+        "-p",
+        "test_*.py"
+    ],
+    "python.testing.pytestEnabled": true,
+    "python.testing.unittestEnabled": false
+}

pdbe_mcp_server-1.0.0/CONTRIBUTING.md

@@ -0,0 +1,21 @@
+# Contributing to PDBe MCP Server
+
+Thank you for your interest in contributing to the PDBe MCP Server project!
+
+## How to Contribute
+
+- Fork the repository and create your branch from `main`.
+- Make your changes with clear commit messages.
+- Ensure your code follows the style and type hints used in the project.
+- Add or update documentation and tests as needed.
+- Open a pull request describing your changes.
+
+## Code of Conduct
+
+Please be respectful and considerate in your communications and contributions.
+
+## Initial Work
+
+This project was initially developed by:
+
+**Sreenath Sasidharan Nair** (<sreenath@ebi.ac.uk>)

pdbe_mcp_server-1.0.0/DEVELOPMENT.md

@@ -0,0 +1,351 @@
+# Development Guide
+
+This guide is for developers working on the PDBe MCP Servers project.
+
+## Table of Contents
+- [Setup](#setup)
+- [Development Workflow](#development-workflow)
+- [Testing](#testing)
+- [Code Quality](#code-quality)
+- [Building and Distribution](#building-and-distribution)
+- [Architecture](#architecture)
+
+## Setup
+
+### Prerequisites
+- Python 3.10 or higher
+- [uv](https://github.com/astral-sh/uv) package manager
+
+### Installation
+
+1. Clone the repository:
+```bash
+git clone https://github.com/PDBeurope/PDBe-MCP-Servers.git
+cd PDBe-MCP-Servers
+```
+
+2. Set up development environment:
+```bash
+make dev-setup
+# Or manually:
+uv sync --all-extras --dev
+```
+
+## Development Workflow
+
+### Quick Commands
+
+The project includes a Makefile for common tasks:
+
+```bash
+make help          # Show all available commands
+make install       # Install dependencies
+make test          # Run tests with coverage
+make lint          # Check code style
+make format        # Format code
+make typecheck     # Run type checker
+make all           # Run all checks (lint, format, type, test)
+```
+
+### Manual Commands
+
+If you prefer not to use Make:
+
+```bash
+# Install dependencies
+uv sync --dev
+
+# Run tests
+uv run pytest
+
+# Run linter
+uv run ruff check .
+
+# Format code
+uv run ruff format .
+
+# Type checking
+uv run pyright
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+# All tests with coverage
+make test
+
+# Fast tests (no coverage)
+make test-fast
+
+# Specific test file
+uv run pytest tests/test_utils.py
+
+# Specific test class
+uv run pytest tests/test_utils.py::TestHTMLStripper
+
+# Specific test
+uv run pytest tests/test_utils.py::TestHTMLStripper::test_strip_simple_tags
+
+# With verbose output
+uv run pytest -v
+
+# Stop on first failure
+uv run pytest -x
+```
+
+### Writing Tests
+
+- Place tests in the `tests/` directory
+- Name test files `test_*.py`
+- Name test classes `Test*`
+- Name test functions `test_*`
+- Use fixtures from `conftest.py`
+- Mock all external HTTP calls
+
+Example test:
+
+```python
+from unittest.mock import MagicMock, patch
+
+def test_example():
+    """Test description."""
+    # Arrange
+    mock_data = {"key": "value"}
+
+    # Act
+    result = function_under_test(mock_data)
+
+    # Assert
+    assert result == expected_value
+```
+
+### Test Coverage
+
+View coverage report:
+```bash
+make test
+# Open htmlcov/index.html in browser
+open htmlcov/index.html
+```
+
+Target: >80% coverage
+
+## Code Quality
+
+### Linting
+
+The project uses Ruff for linting:
+
+```bash
+# Check for issues
+make lint
+
+# Fix auto-fixable issues
+make lint-fix
+```
+
+### Formatting
+
+The project uses Ruff for formatting:
+
+```bash
+# Format code
+make format
+
+# Check formatting without changing files
+make format-check
+```
+
+### Type Checking
+
+The project uses Pyright for type checking:
+
+```bash
+# Run type checker
+make typecheck
+```
+
+All public APIs must have type annotations.
+
+### Pre-commit Checks
+
+Before committing, run:
+
+```bash
+make all
+```
+
+This runs linting, formatting checks, type checking, and tests.
+
+## Building and Distribution
+
+### Building the Package
+
+```bash
+# Build wheel and sdist
+make build
+
+# Check distribution files
+make check-dist
+```
+
+### Publishing
+
+```bash
+# Test on TestPyPI first
+make publish-test
+
+# Publish to PyPI
+make publish
+```
+
+## Architecture
+
+### Project Structure
+
+```
+pdbe_mcp_server/
+├── __init__.py          # Configuration management
+├── api_tools.py         # OpenAPI to MCP tool conversion
+├── config.yaml          # Configuration file
+├── graph_tools.py       # Graph database tools
+├── helper.py            # Helper utilities
+├── py.typed             # PEP 561 marker
+├── search_tools.py      # Search tools
+├── server.py            # Server orchestration
+└── utils.py             # Shared utilities
+
+tests/
+├── conftest.py          # Shared fixtures
+├── test_api_tools.py    # API tools tests
+├── test_graph_tools.py  # Graph tools tests
+├── test_search_tools.py # Search tools tests
+├── test_server.py       # Server tests
+└── test_utils.py        # Utils tests
+```
+
+### Key Design Patterns
+
+1. **Factory Pattern**: `MCPServerFactory` for creating servers
+2. **Strategy Pattern**: Dynamic OpenAPI tool generation
+3. **Adapter Pattern**: `HTTPClient` wrapper
+
+
+### Adding a New Server Type
+
+1. Create a builder function:
+```python
+def build_my_server() -> Server:
+    server = Server("my-server")
+
+    @server.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return [...]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any]) -> Sequence[...]:
+        # Implementation
+        pass
+
+    return server
+```
+
+2. Register with factory:
+```python
+factory.register("my_server", build_my_server)
+```
+
+3. Update CLI options in `main()`.
+
+### Adding Tests
+
+1. Create test file in `tests/`
+2. Add fixtures to `conftest.py` if reusable
+3. Mock external dependencies
+4. Test happy path and error cases
+
+## Best Practices
+
+### Code Style
+
+- Use type hints for all public APIs
+- Write docstrings for all public functions
+- Use descriptive variable names
+- Keep functions focused and small
+- Prefer composition over inheritance
+
+### Git Workflow
+
+1. Create a feature branch
+2. Make your changes
+3. Run `make all` to check everything
+4. Commit with descriptive message
+5. Push and create pull request
+
+### Commit Messages
+
+Follow conventional commits:
+
+```
+feat: add new search filter option
+fix: handle empty search results correctly
+docs: update architecture documentation
+test: add tests for graph tools
+refactor: simplify server factory logic
+```
+
+## Troubleshooting
+
+### Tests Failing
+
+```bash
+# Run with verbose output
+uv run pytest -v
+
+# Run single test to isolate issue
+uv run pytest tests/test_utils.py::TestHTMLStripper::test_strip_simple_tags -v
+
+# Check test isolation
+uv run pytest --lf  # Run last failed
+```
+
+### Type Errors
+
+```bash
+# Run type checker with verbose output
+uv run pyright --verbose
+
+# Check specific file
+uv run pyright pdbe_mcp_server/server.py
+```
+
+### Import Errors
+
+```bash
+# Reinstall dependencies
+uv sync --reinstall
+
+# Check installed packages
+uv pip list
+```
+
+## Resources
+
+- [Project README](README.md)
+- [MCP Documentation](https://modelcontextprotocol.io/)
+- [PDBe API](https://www.ebi.ac.uk/pdbe/api/)
+
+## Contributing
+
+1. Check existing issues/PRs
+2. Create an issue for discussion (for large changes)
+3. Fork and create a feature branch
+4. Make your changes with tests
+5. Ensure `make all` passes
+6. Submit a pull request
+
+## License
+
+Apache-2.0 - See LICENSE file for details.