Skip to content

DEVELOPMENT.md

Latest commit

 

History

History
178 lines (127 loc) · 3.86 KB

DEVELOPMENT.md

File metadata and controls

178 lines (127 loc) · 3.86 KB
Raw

Development Guide

Prerequisites

  • Python 3.12+
  • UV - Modern Python package manager (optional, but recommended)

Setup

# Clone the repository
git clone https://github.com/ivolnistov/youtrack-rocket-mcp.git
cd youtrack-rocket-mcp

# Install all dependencies including dev group for development
uv sync

# This will:
# - Create a virtual environment if it doesn't exist
# - Install all runtime dependencies
# - Install all dev group dependencies (pytest, ruff, mypy, etc.)
# - Install the package in editable mode

# Note: uv sync includes the dev group by default.
# To install without dev dependencies: uv sync --no-dev

Running the Server

From PyPI (after installation)

# Using uvx (no installation required)
uvx youtrack-rocket-mcp

# Or if installed with uv tool
uv tool install youtrack-rocket-mcp
youtrack-rocket-mcp

# Or if installed with pip
youtrack-rocket-mcp

During Development

# Run directly with UV (manages virtual environment automatically)
uv run python -m youtrack_rocket_mcp.server

# Or if virtual environment is activated
python -m youtrack_rocket_mcp.server

# Run tests
uv run pytest

# Format code
uv run ruff format src/

# Check linting
uv run ruff check src/

# Type checking
uv run mypy src/

Project Structure

youtrack-rocket-mcp/
├── src/                    # Source code (src-layout)
│   └── youtrack_rocket_mcp/       # Main package
│       ├── api/            # API client modules
│       ├── tools/          # MCP tools
│       └── server.py       # MCP server implementation
├── tests/                  # Test files
├── pyproject.toml          # Project configuration
└── .venv/                  # Virtual environment (managed by UV)

Why UV?

This project uses UV for dependency management because:

  • Fast: Written in Rust, significantly faster than pip
  • Modern: Follows latest Python packaging standards
  • Simple: No need to manually activate virtual environments
  • Reliable: Ensures consistent dependency resolution

Installing in Development Mode

The project is automatically installed in editable mode when you run uv sync.

Adding Dependencies

# Add a runtime dependency
uv add <package>

# Add a development dependency
uv add --group dev <package>

Environment Configuration

Set up your environment variables:

# Create .env file for YouTrack Cloud
cat > .env << EOF
YOUTRACK_API_TOKEN=perm:username.workspace.xxxxx
EOF

# Or for self-hosted YouTrack
cat > .env << EOF
YOUTRACK_URL=https://youtrack.example.com
YOUTRACK_API_TOKEN=perm:xxxxx
EOF

# Or export directly
export YOUTRACK_API_TOKEN="perm:username.workspace.xxxxx"

FastMCP Architecture

This project is built with FastMCP, which provides:

  • Automatic JSON Schema generation from Python type hints
  • Proper parameter validation
  • Correct parameter names in MCP Inspector (no more args/kwargs)
  • Full async support for optimal performance

The API layer uses httpx for HTTP operations with comprehensive error handling and retry logic.

Testing

# Run all tests with UV
uv run pytest

# Run with coverage
uv run pytest --cov=youtrack_rocket_mcp

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

# Run tests in verbose mode
uv run pytest -v

Code Quality

# Format code (auto-fix)
uv run ruff format src/

# Check linting
uv run ruff check src/

# Check linting with auto-fix
uv run ruff check src/ --fix

# Type checking
uv run mypy src/youtrack_rocket_mcp

Building and Publishing

# Build the package
uv build

# This creates wheel and source distributions in dist/
ls dist/
# youtrack_rocket_mcp-X.Y.Z.tar.gz
# youtrack_rocket_mcp-X.Y.Z-py3-none-any.whl

# The package is published automatically via GitHub Actions
# when a version tag is pushed (e.g., vX.Y.Z)