CzSkY

Live

🌍 Production: https://www.czsky.eu 🇨🇿 CZ version: https://www.czsky.cz

Prerequisites

Before running this project, install libicu-dev, which provides International Components for Unicode libraries. Below are installation steps for various operating systems.

Linux

For Debian-based distributions like Ubuntu:

sudo apt-get update
sudo apt-get install -y libicu-dev

For Red Hat-based distributions like CentOS or Fedora:

sudo yum install libicu-devel

macOS

Using Homebrew:

1.Install Homebrew if you haven't already. 2.Run:

brew install icu4c

Setting up

Clone the repository

$ git clone https://github.com/skybber/czsky.git
$ cd czsky

Initialize a virtual environment

Linux:

$ python3 -m venv venv; source venv/bin/activate

Windows:

$ python3 -m venv venv
$ venv\Scripts\activate.bat

Unix/MacOS:

$ python3 -m venv venv
$ source venv/bin/activate

Learn more in the documentation.

Note: if you are using a python before 3.3, it doesn't come with venv. Install virtualenv with pip instead.

(If you're on a Mac) Make sure xcode tools are installed

$ xcode-select --install

Add Environment Variables

Create a file called config.env that contains environment variables. Very important: do not include the config.env file in any commits. This should remain private. You will manually maintain this file locally, and keep it in sync on your host. To make it easy to set up this file with the required values, you can use config.env.example as a configuration template.

Variables declared in file have the following format: ENVIRONMENT_VARIABLE=value. You may also wrap values in double quotes like ENVIRONMENT_VARIABLE="value with spaces".

1. In order for Flask to run, there must be a SECRET_KEY variable declared. Generating one is simple with Python 3:

   $ python3 -c "import secrets; print(secrets.token_hex(16))"
   

   This will give you a 32-character string. Copy this string and add it to your config.env:

   SECRET_KEY=Generated_Random_String
   

2. The mailing environment variables can be set as the following. We recommend using Sendgrid for a mailing SMTP server, but anything else will work as well.

   MAIL_USERNAME=SendgridUsername
   MAIL_PASSWORD=SendgridPassword
   

Other useful variables include:

Variable	Default	Discussion
ADMIN_EMAIL	flask-base-admin@example.com	email for your first admin account
ADMIN_PASSWORD	password	password for your first admin account
DATABASE_URL	data-dev.sqlite	Database URL. Can be Postgres, sqlite, etc.
REDISTOGO_URL	http://localhost:6379	Redis To Go URL or any redis server url
RAYGUN_APIKEY	None	API key for Raygun, a crash and performance monitoring service
FLASK_CONFIG	default	can be development, production, default, heroku, unix, or testing. Most of the time you will use development or production.

Install the dependencies

$ pip install -r requirements.txt

Other dependencies for running locally

You need Redis. Chances are, these commands will work:

Redis:

Mac (using homebrew):

$ brew install redis

Linux:

$ sudo apt-get install redis-server

Initialize CzSkY project

$ ./recreate_all.sh

Running CzSkY

$ source venv/bin/activate
$ honcho start -e config.env -f Local

Running the MCP Sidecar

The MCP server runs as a separate sidecar process. It shares the Flask app factory, configuration, and database models, but it is not mounted into Flask routes.

$ source venv/bin/activate
$ python -m app.mcp_server

Useful environment variables:

Variable	Default	Discussion
MCP_TRANSPORT	streamable-http	Recommended MCP transport
MCP_HOST	127.0.0.1	Bind address for the MCP sidecar
MCP_PORT	8001	Port for the MCP sidecar
MCP_ENABLE_TOKEN_AUTH	1	Enable bearer token verification for MCP transport
MCP_AUTH_ISSUER_URL	derived from host/port	Optional OAuth issuer URL metadata
MCP_AUTH_RESOURCE_SERVER_URL	http://<host>:<port>/mcp	Optional protected resource metadata URL
FLASK_CONFIG	default	Reuses the standard Flask configuration selection
MCP_USER_ID	unset	Local fallback user id for wishlist tools when token auth is disabled

When MCP_ENABLE_TOKEN_AUTH=1, the MCP transport requires Authorization: Bearer <token>. Use a token generated in User settings -> MCP token.

Recent MCP updates add write-capable workflows on top of the original lookup tools. Clients can now search DSO catalogues, create and manage session plans, create and activate observing sessions, and create or update observation logs directly from the MCP sidecar. Wishlist support was also extended with lookup, bulk add/remove, and import/export operations, so external agents can cover a full planning flow from target discovery to observation logging.

Current MCP tools:

• resolve_sky_object
• resolve_sky_objects
• get_comet_recent_observations
• dso.find
• dso.list_sources
• session_plan.create
• session_plan.get
• session_plan.list
• session_plan.get_id_by_date
• session_plan.add_item
• session_plan.add_items
• session_plan.items
• session_plan.remove_item
• session_plan.remove_items
• session_plan.clear
• session_plan.get_dso_list_id_by_name
• observing_session.create
• observing_session.set_active
• observing_session.get_active
• observation_log.upsert
• wishlist.list
• wishlist.stats
• wishlist.contains
• wishlist.find
• wishlist.add
• wishlist.remove
• wishlist.bulk_add
• wishlist.bulk_remove
• wishlist.export
• wishlist.import

Opening CzSkY in Browser

To open the CzSkY home page in your browser, navigate to http://localhost:5000.

External Access

To enable access from an external computer, run CzSkY on all network devices. Modify the appropriate line in the Local file as follows:

web: flask --debug --app manage run --host=0.0.0.0 --port=5000 

Additional Catalogs of Stars Up to 17 Magnitude

To add extra catalogs of stars from Stellarium, download the catalogs in Stellarium and locate their storage directory (for Linux, this is ~/.stellarium/stars/default). Finally copy the downloaded catalogs to the data/ directory in the CzSkY project.

For Windows users having issues with binding to a redis port locally, refer to this issue.