Siril MCP Server

⚠️ Work in Progress: This project is under active development and not yet ready for production use. APIs may change without notice.

A Model Context Protocol (MCP) server that provides tools for working with Siril astronomical image processing software and Seestar telescope data.

🚧 Current Status

This project is in early development. Current features include:

• ✅ Siril Binary Detection: Smart detection of Siril installations across platforms
• ✅ Version Checking: Check your installed Siril version
• ✅ Basic Mosaic Processing: Process Seestar S30/S50 telescope images
• ✅ Filter Support: Supports both broadband and narrowband processing
• ✅ Auto Script Creation: Automatically creates required SSF scripts
• ✅ FastMCP Integration: Proper async logging and error handling
• 🔄 Script Updates: Download latest scripts from Naztronomy repository
• 🔄 Project Analysis: Check project structure and file organization
• ❌ GUI Integration: Headless preprocessing tools (planned)
• ❌ PyPI Package: Not yet published

Prerequisites

• Python 3.10+
• Siril astronomical image processing software

Siril Installation & Detection

The server automatically detects Siril installations in the following order:

1. Custom Path: Set SIRIL_BINARY environment variable to specify a custom location
2. System PATH: Checks if siril command is available in your PATH
3. macOS App Bundle: /Applications/Siril.app/Contents/MacOS/Siril
4. Common Locations: /usr/bin/siril, /usr/local/bin/siril, /opt/homebrew/bin/siril

macOS Users: If you installed Siril as an application, no additional setup is needed - it will be detected automatically.

Custom Installation: For non-standard installations, set the environment variable:

export SIRIL_BINARY="/path/to/your/siril/binary"

Installation

Note: This package is not yet published to PyPI. Install from source for now.

From Source (Development)

git clone https://github.com/taco-ops/siril-mcp
cd siril-mcp

# Using pipenv (recommended)
pipenv install --dev
pipenv shell

# Or using pip
pip install -e .

Future PyPI Installation

Once published, you'll be able to install via:

# Using pip
pip install siril-mcp

# Using pipenv
pipenv install siril-mcp

Development Setup

This project uses Pipenv for Python dependency management and npm for MCP testing tools. Make sure you have both installed:

pip install pipenv
# Node.js and npm should be installed for MCP integration testing

Setting up the development environment:

# Clone the repository
git clone https://github.com/taco-ops/siril-mcp
cd siril-mcp

# Install Python dependencies and create virtual environment
pipenv install --dev

# Install Node.js dependencies for MCP testing
npm install

# Activate the virtual environment
pipenv shell

# Install the package in development mode
pipenv install -e .

# Validate setup
npm run validate-ci

Available scripts:

Python (Pipenv):

# Build the package
pipenv run build

# Run Python tests
pipenv run test

# Format code with Black
pipenv run format

# Lint code with Flake8
pipenv run lint

# Upload to Test PyPI
pipenv run upload-test

# Upload to production PyPI
pipenv run upload

MCP Testing (npm):

# Run basic MCP functionality tests
npm run test

# Run MCP integration tests
npm run test:integration

# Run all MCP tests
npm run test:all

# Validate CI setup readiness
npm run validate-ci

Release Management (npm):

# Test release process (dry run)
npm run release:dry

# Create actual releases
npm run release:patch    # Bug fixes (1.0.0 → 1.0.1)
npm run release:minor    # New features (1.0.0 → 1.1.0)
npm run release:major    # Breaking changes (1.0.0 → 2.0.0)

# General release (auto-detects type)
npm run release

Local Development Workflow

Pre-commit Hooks (Recommended)

This project uses pre-commit hooks to ensure code quality. Install them for automatic checks:

# Install pre-commit hooks (one-time setup)
pipenv run pre-commit install

# Now all commits will automatically run:
# - Black formatting
# - isort import sorting
# - flake8 linting
# - pytest tests

Manual Quality Checks

You can also run quality checks manually:

# Run all pre-commit hooks on all files
pipenv run pre-commit run --all-files

# Run specific checks
pipenv run pre-commit run black        # Format code
pipenv run pre-commit run flake8       # Lint code
pipenv run pre-commit run pytest      # Run tests

Release Testing Locally

Test the release process without actually releasing:

# Install Node.js dependencies
npm install

# Test what a release would look like
npm run release:dry

# Test specific release types
npm run release:patch --dry-run
npm run release:minor --dry-run
npm run release:major --dry-run

🧪 Testing & Quality Assurance

This project includes comprehensive testing with both Python unit tests and MCP integration testing.

Test Suites

Python Unit Tests

Traditional pytest-based testing for core functionality:

# Run all Python tests
pipenv run test

# Run tests with coverage
pipenv run python -m pytest tests/ --cov=siril_mcp --cov-report=html

# Run specific test
pipenv run python -m pytest tests/test_server.py::test_find_siril_binary_macos_location -v

MCP Integration Tests

Node.js-based testing that validates the complete MCP server functionality:

# Install Node.js dependencies
npm install

# Run basic functionality tests
npm run test

# Run MCP protocol integration tests
npm run test:integration

# Run all MCP tests
npm run test:all

# Validate CI readiness
npm run validate-ci

CI/CD Pipeline

The project uses GitHub Actions for automated testing and releases:

Continuous Integration

• Triggers: Every push and PR to main and develop branches
• Python Versions: Tests across Python 3.10, 3.11, and 3.12
• Test Coverage: Code formatting, linting, Python tests, and MCP integration tests
• Environment Adaptive: Tests automatically adapt to CI environments where Siril isn't available

Release Pipeline

• Triggers: When version tags (v*) are pushed
• Pre-Release Validation: Comprehensive testing across all Python versions
• MCP Protocol Validation: Ensures MCP server functionality before release
• Automated Publishing: Builds and publishes to PyPI only after all tests pass

Test Coverage Includes

• ✅ Siril binary detection across platforms
• ✅ Version checking and error handling
• ✅ SSF script content validation
• ✅ Project structure validation
• ✅ MCP protocol compliance and tool registration
• ✅ Complete MCP server initialization and tool execution
• ✅ Filter type processing differences
• ✅ Environment variable handling
• ✅ CI/CD environment adaptation
• ✅ Error conditions and edge cases

Local Development Testing

# Quick validation of local setup
npm run validate-ci

# Test in CI mode locally (simulates GitHub Actions)
CI=true npm run test:all

# Full local testing
pipenv run test && npm run test:all

For detailed testing documentation, see CI_TESTING.md.

Usage

As an MCP Server

Run the server directly:

# If installed globally
siril-mcp

# If using pipenv
pipenv run siril-mcp

# Or activate the environment first
pipenv shell
siril-mcp

With Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "siril": {
      "command": "siril-mcp"
    }
  }
}

Project Structure

Your Seestar project should be organized like this:

project_root/
├── lights/                 # Your FITS files go here
│   ├── Light_001.fits
│   ├── Light_002.fits
│   └── ...
└── process/               # Output directory (created automatically)
    └── mosaic.fits        # Final processed mosaic

Note: The SSF script files are created automatically - you don't need to download them manually!

Available Tools

find_siril_binary()

Locates and validates the Siril binary on your system. Useful for troubleshooting installation issues.

validate_siril_binary(binary_path)

Tests whether a specific Siril binary path works correctly. Useful for validating custom installations.

check_siril_version()

Returns the version of your installed Siril software.

process_seestar_mosaic(project_dir, filter_type)

Processes FITS files in the project directory using the appropriate Siril script.

• project_dir: Path to your project root
• filter_type: Either "broadband" or "narrowband"

The function automatically creates the required SSF scripts, so you don't need to download anything manually.

check_project_structure(project_dir)

Analyzes your project directory and shows what files are present and what might be missing.

download_latest_ssf_scripts(project_dir)

Downloads the latest SSF script files from the naztronaut/siril-scripts repository.

preprocess_with_gui(project_dir) (Planned)

Future feature to launch Naztronomy Smart Telescope preprocessing GUI in headless mode.

Filter Types Available

• broadband: For UV/IR block filters (most common)
• narrowband: For light pollution (LP) filters

🚀 Releases & CI/CD

Automated Release Process

This project features a fully automated release system with two approaches:

Option 1: GitHub Actions Release (Recommended)

1. Go to: GitHub Actions
2. Select: "Release with release-it" workflow
3. Click: "Run workflow"
4. Choose: Release type:
   • Patch (1.0.0 → 1.0.1) - Bug fixes
   • Minor (1.0.0 → 1.1.0) - New features
   • Major (1.0.0 → 2.0.0) - Breaking changes

Option 2: Traditional Tag-Based Release

# Create and push a new version tag
git tag v1.0.0
git push origin v1.0.0

Both methods trigger the complete release pipeline:

Pre-Release Validation

1. ✅ Code Quality: Automated linting and formatting checks
2. ✅ Multi-Python Testing: Tests across Python 3.10, 3.11, and 3.12
3. ✅ Python Unit Tests: Complete pytest suite validation
4. ✅ MCP Integration Tests: Full MCP protocol and tool functionality testing
5. ✅ Package Building: Wheel and source distribution validation

Release Execution

6. ✅ Version Management: Automatic version synchronization across all files
7. ✅ Changelog Generation: Conventional changelog with commit links
8. ✅ GitHub Release: Automated release creation with artifacts
9. ✅ PyPI Publishing: Automatic publishing to PyPI (for stable releases)

Advanced Release Features

• 🔄 Version Synchronization: Automatically syncs versions between package.json and pyproject.toml
• 📝 Conventional Changelogs: Auto-generated changelogs from commit messages
• 🏷️ Smart Tagging: Automatic git tagging with proper semantic versioning
• 📦 Asset Management: Release artifacts automatically attached to GitHub releases
• ✨ Pre-commit Hooks: Quality checks run automatically before releases

Quality Gates

No release proceeds unless ALL tests pass, ensuring every published version is:

• ✅ Properly formatted and linted
• ✅ Compatible across supported Python versions
• ✅ Functionally validated with unit tests
• ✅ MCP protocol compliant
• ✅ Tool functionality verified
• ✅ Package integrity confirmed

CI Status Badges

The repository includes live status badges showing:

• Continuous Integration: Current build status
• Release Pipeline: Latest release status

🤝 Contributing

This project is in early development and contributions are welcome! Here's how to get started:

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Install development dependencies:

   pipenv install --dev  # Python dependencies
   npm install           # Node.js testing dependencies
   

Making Changes

4. Make your changes and add tests
   • Add Python unit tests in tests/ directory
   • Update MCP integration tests if modifying tool functionality
5. Run the complete test suite:

   pipenv run test      # Python tests
   npm run test:all     # MCP integration tests
   npm run validate-ci  # CI readiness check
   

6. Format and lint your code:

   pipenv run format    # Black formatting
   pipenv run lint      # Flake8 linting
   

Submitting Changes

7. Commit your changes: git commit -m 'Add amazing feature'
8. Push to the branch: git push origin feature/amazing-feature
9. Open a Pull Request

Pull Request Requirements

All PRs must pass:

• ✅ Code Formatting: Black formatting compliance
• ✅ Linting: Flake8 validation without errors
• ✅ Python Tests: All pytest unit tests passing
• ✅ MCP Integration: All MCP protocol tests passing
• ✅ Multi-Python: Tests passing on Python 3.10, 3.11, and 3.12
• ✅ CI Validation: All GitHub Actions workflows passing

Testing Your Changes Locally

Before submitting a PR, ensure everything works:

# Quick validation (like CI will run)
npm run validate-ci

# Complete local testing
pipenv run test && npm run test:all

# Test CI mode locally
CI=true npm run test:all

Development Roadmap

• [ ] Complete GUI integration for preprocessing tools
• [ ] Add support for additional telescope types
• [ ] Implement batch processing capabilities
• [ ] Add image quality assessment tools
• [ ] Create comprehensive documentation site
• [ ] Publish to PyPI for stable releases
• [ ] Add Docker container support

Filter Types Available

Credits

This MCP server uses SSF scripts from the naztronomy/siril-scripts repository by Nazmus Nasir (Naztronomy.com), used under the GPL-3.0 license.

License

MIT License - see LICENSE file for details.