mcp-stargazing 0.1.6__tar.gz

mcp_stargazing-0.1.6/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 stargazer95
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_stargazing-0.1.6/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: mcp-stargazing
+Version: 0.1.6
+Summary: This is a mcp server Calculate celestial object positions and rise/set times
+Author-email: Henry Gong <zhao.gong@outlook.com>
+Project-URL: Homepage, https://github.com/StarGazer1995/mcp-stargazing
+Project-URL: Issues, https://github.com/StarGazer1995/mcp-stargazing/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp
+Requires-Dist: astropy>=5.0
+Requires-Dist: pytz
+Requires-Dist: numpy
+Requires-Dist: astroquery
+Requires-Dist: rasterio
+Requires-Dist: tzlocal
+Requires-Dist: geopy
+Requires-Dist: stargazing-place-finder>=0.3.0
+Dynamic: license-file
+
+# mcp-stargazing
+
+Calculate the altitude, rise, and set times of celestial objects (Sun, Moon, planets, stars, and deep-space objects) for any location on Earth, with optional light pollution analysis.
+
+## Features
+
+- **Altitude/Azimuth Calculation**: Get elevation and compass direction for any celestial object.
+- **Rise/Set Times**: Determine when objects appear/disappear above the horizon.
+- **Light Pollution Analysis**: Load and analyze light pollution maps (GeoTIFF format).
+- **Code Execution Ready**:
+  - **Serializable Returns**: All tools return JSON-serializable data (ISO strings for dates), making them directly usable by LLMs.
+  - **Pagination**: `analysis_area` supports paging (`page`, `page_size`) to handle large datasets efficiently.
+  - **Standardized Responses**: Uniform response format `{ "data": ..., "_meta": ... }` for better observability and error handling.
+- **Performance**:
+  - **Async Execution**: Non-blocking celestial calculations.
+  - **Caching**: Intelligent caching for Simbad queries and regional analysis.
+  - **Proxy Support**: Native support for HTTP/HTTPS proxies (useful for downloading astronomical data).
+- **Time Zone Aware**: Works with local or UTC times.
+
+## Installation
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management.
+
+1. **Install `uv`**:
+   ```bash
+   pip install uv
+   ```
+
+2. **Sync dependencies**:
+   ```bash
+   uv sync
+   ```
+   This will create a virtual environment in `.venv` and install all dependencies defined in `pyproject.toml`.
+
+3. **Activate the environment**:
+   ```bash
+   source .venv/bin/activate
+   ```
+
+## MCP Server Usage
+
+Start the MCP server to expose tools to AI agents or other clients.
+
+### 1. Environment Setup
+
+Create a `.env` file or export variables:
+
+```bash
+# Required for weather tools
+export QWEATHER_API_KEY="your_api_key"
+
+# Optional: Proxy for downloading astronomical data (Simbad/IERS)
+# Highly recommended if you are in a restricted network environment
+export HTTP_PROXY="http://127.0.0.1:7890"
+export HTTPS_PROXY="http://127.0.0.1:7890"
+```
+
+### 2. Start Server
+
+**Streamable HTTP (SHTTP) mode** (Recommended for most agents):
+
+```bash
+# Basic start
+python -m src.main --mode shttp --port 3001 --path /shttp
+
+# With proxy explicitly passed (overrides env vars)
+python -m src.main --mode shttp --port 3001 --path /shttp --proxy http://127.0.0.1:7890
+```
+
+**SSE mode**:
+
+```bash
+python -m src.main --mode sse --port 3001 --path /sse
+```
+
+### 3. Response Format
+
+All tools return data in a standardized JSON format:
+
+```json
+{
+  "data": {
+    // Tool-specific return data
+    "altitude": 45.5,
+    "azimuth": 180.0
+  },
+  "_meta": {
+    "version": "1.0.0",
+    "status": "success"
+  }
+}
+```
+
+### 4. Available Tools
+
+- **`get_celestial_pos`**: Calculate altitude/azimuth.
+- **`get_celestial_rise_set`**: Calculate rise/set times (Returns ISO strings).
+- **`get_weather_by_name` / `get_weather_by_position`**: Fetch current weather.
+- **`get_local_datetime_info`**: Get current local time information.
+- **`analysis_area`**: Find best stargazing spots in a region.
+  - **Inputs**: `top_left`, `bottom_right`, `time`, `page`, `page_size`.
+  - **Returns**: List of spots with viewing conditions, plus pagination metadata (`total`, `resource_id`).
+
+## Examples
+
+- **Orchestration**: `python examples/code_execution_orchestration.py`
+  - Demonstrates a full workflow: Get time -> Get Celestial Pos -> Check Weather -> Find Spots.
+  - Shows how to handle the standardized response format programmatically.
+
+- **Pagination**: `python examples/pagination_demo.py`
+  - Demonstrates fetching large result sets page by page using the `resource_id`.
+
+## Project Structure
+
+The project is modularized for better maintainability and code execution support:
+
+```
+.
+├── src/
+│   ├── functions/            # Tool implementations grouped by domain
+│   │   ├── celestial/        # Celestial calculations (pos, rise/set)
+│   │   ├── weather/          # Weather API integration
+│   │   ├── places/           # Location and area analysis
+│   │   └── time/             # Time utilities
+│   ├── cache.py              # Caching logic for analysis results
+│   ├── response.py           # Standardized response formatting
+│   ├── server_instance.py    # FastMCP server instance (avoids circular imports)
+│   ├── main.py               # Entry point and tool registration
+│   ├── celestial.py          # Core astronomy logic (Astropy wrappers)
+│   ├── placefinder.py        # Grid analysis logic
+│   └── qweather_interaction.py # Weather API client
+├── tests/                    # Unified test suite
+│   ├── test_celestial.py
+│   ├── test_weather.py
+│   ├── test_serialization.py # Validates JSON return formats
+│   └── test_integration.py   # End-to-end flow tests
+├── examples/                 # Usage examples
+├── docs/                     # Documentation and improvement plans
+└── pyproject.toml            # Project configuration and dependencies
+```
+
+## Testing
+
+Run the unified test suite:
+
+```bash
+pytest tests/
+```
+
+Key tests include:
+- `test_serialization.py`: Ensures all tools return valid JSON with the correct schema.
+- `test_integration.py`: Mocks external APIs to verify the entire toolchain.
+
+## Contributing
+
+1.  Follow the [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) best practices.
+2.  Ensure all new tools return standard JSON responses using `src.response.format_response`.
+3.  Add tests in `tests/` for any new functionality.

mcp_stargazing-0.1.6/README.md

@@ -0,0 +1,158 @@
+# mcp-stargazing
+
+Calculate the altitude, rise, and set times of celestial objects (Sun, Moon, planets, stars, and deep-space objects) for any location on Earth, with optional light pollution analysis.
+
+## Features
+
+- **Altitude/Azimuth Calculation**: Get elevation and compass direction for any celestial object.
+- **Rise/Set Times**: Determine when objects appear/disappear above the horizon.
+- **Light Pollution Analysis**: Load and analyze light pollution maps (GeoTIFF format).
+- **Code Execution Ready**:
+  - **Serializable Returns**: All tools return JSON-serializable data (ISO strings for dates), making them directly usable by LLMs.
+  - **Pagination**: `analysis_area` supports paging (`page`, `page_size`) to handle large datasets efficiently.
+  - **Standardized Responses**: Uniform response format `{ "data": ..., "_meta": ... }` for better observability and error handling.
+- **Performance**:
+  - **Async Execution**: Non-blocking celestial calculations.
+  - **Caching**: Intelligent caching for Simbad queries and regional analysis.
+  - **Proxy Support**: Native support for HTTP/HTTPS proxies (useful for downloading astronomical data).
+- **Time Zone Aware**: Works with local or UTC times.
+
+## Installation
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management.
+
+1. **Install `uv`**:
+   ```bash
+   pip install uv
+   ```
+
+2. **Sync dependencies**:
+   ```bash
+   uv sync
+   ```
+   This will create a virtual environment in `.venv` and install all dependencies defined in `pyproject.toml`.
+
+3. **Activate the environment**:
+   ```bash
+   source .venv/bin/activate
+   ```
+
+## MCP Server Usage
+
+Start the MCP server to expose tools to AI agents or other clients.
+
+### 1. Environment Setup
+
+Create a `.env` file or export variables:
+
+```bash
+# Required for weather tools
+export QWEATHER_API_KEY="your_api_key"
+
+# Optional: Proxy for downloading astronomical data (Simbad/IERS)
+# Highly recommended if you are in a restricted network environment
+export HTTP_PROXY="http://127.0.0.1:7890"
+export HTTPS_PROXY="http://127.0.0.1:7890"
+```
+
+### 2. Start Server
+
+**Streamable HTTP (SHTTP) mode** (Recommended for most agents):
+
+```bash
+# Basic start
+python -m src.main --mode shttp --port 3001 --path /shttp
+
+# With proxy explicitly passed (overrides env vars)
+python -m src.main --mode shttp --port 3001 --path /shttp --proxy http://127.0.0.1:7890
+```
+
+**SSE mode**:
+
+```bash
+python -m src.main --mode sse --port 3001 --path /sse
+```
+
+### 3. Response Format
+
+All tools return data in a standardized JSON format:
+
+```json
+{
+  "data": {
+    // Tool-specific return data
+    "altitude": 45.5,
+    "azimuth": 180.0
+  },
+  "_meta": {
+    "version": "1.0.0",
+    "status": "success"
+  }
+}
+```
+
+### 4. Available Tools
+
+- **`get_celestial_pos`**: Calculate altitude/azimuth.
+- **`get_celestial_rise_set`**: Calculate rise/set times (Returns ISO strings).
+- **`get_weather_by_name` / `get_weather_by_position`**: Fetch current weather.
+- **`get_local_datetime_info`**: Get current local time information.
+- **`analysis_area`**: Find best stargazing spots in a region.
+  - **Inputs**: `top_left`, `bottom_right`, `time`, `page`, `page_size`.
+  - **Returns**: List of spots with viewing conditions, plus pagination metadata (`total`, `resource_id`).
+
+## Examples
+
+- **Orchestration**: `python examples/code_execution_orchestration.py`
+  - Demonstrates a full workflow: Get time -> Get Celestial Pos -> Check Weather -> Find Spots.
+  - Shows how to handle the standardized response format programmatically.
+
+- **Pagination**: `python examples/pagination_demo.py`
+  - Demonstrates fetching large result sets page by page using the `resource_id`.
+
+## Project Structure
+
+The project is modularized for better maintainability and code execution support:
+
+```
+.
+├── src/
+│   ├── functions/            # Tool implementations grouped by domain
+│   │   ├── celestial/        # Celestial calculations (pos, rise/set)
+│   │   ├── weather/          # Weather API integration
+│   │   ├── places/           # Location and area analysis
+│   │   └── time/             # Time utilities
+│   ├── cache.py              # Caching logic for analysis results
+│   ├── response.py           # Standardized response formatting
+│   ├── server_instance.py    # FastMCP server instance (avoids circular imports)
+│   ├── main.py               # Entry point and tool registration
+│   ├── celestial.py          # Core astronomy logic (Astropy wrappers)
+│   ├── placefinder.py        # Grid analysis logic
+│   └── qweather_interaction.py # Weather API client
+├── tests/                    # Unified test suite
+│   ├── test_celestial.py
+│   ├── test_weather.py
+│   ├── test_serialization.py # Validates JSON return formats
+│   └── test_integration.py   # End-to-end flow tests
+├── examples/                 # Usage examples
+├── docs/                     # Documentation and improvement plans
+└── pyproject.toml            # Project configuration and dependencies
+```
+
+## Testing
+
+Run the unified test suite:
+
+```bash
+pytest tests/
+```
+
+Key tests include:
+- `test_serialization.py`: Ensures all tools return valid JSON with the correct schema.
+- `test_integration.py`: Mocks external APIs to verify the entire toolchain.
+
+## Contributing
+
+1.  Follow the [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) best practices.
+2.  Ensure all new tools return standard JSON responses using `src.response.format_response`.
+3.  Add tests in `tests/` for any new functionality.

mcp_stargazing-0.1.6/mcp_stargazing.egg-info/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: mcp-stargazing
+Version: 0.1.6
+Summary: This is a mcp server Calculate celestial object positions and rise/set times
+Author-email: Henry Gong <zhao.gong@outlook.com>
+Project-URL: Homepage, https://github.com/StarGazer1995/mcp-stargazing
+Project-URL: Issues, https://github.com/StarGazer1995/mcp-stargazing/issues
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp
+Requires-Dist: astropy>=5.0
+Requires-Dist: pytz
+Requires-Dist: numpy
+Requires-Dist: astroquery
+Requires-Dist: rasterio
+Requires-Dist: tzlocal
+Requires-Dist: geopy
+Requires-Dist: stargazing-place-finder>=0.3.0
+Dynamic: license-file
+
+# mcp-stargazing
+
+Calculate the altitude, rise, and set times of celestial objects (Sun, Moon, planets, stars, and deep-space objects) for any location on Earth, with optional light pollution analysis.
+
+## Features
+
+- **Altitude/Azimuth Calculation**: Get elevation and compass direction for any celestial object.
+- **Rise/Set Times**: Determine when objects appear/disappear above the horizon.
+- **Light Pollution Analysis**: Load and analyze light pollution maps (GeoTIFF format).
+- **Code Execution Ready**:
+  - **Serializable Returns**: All tools return JSON-serializable data (ISO strings for dates), making them directly usable by LLMs.
+  - **Pagination**: `analysis_area` supports paging (`page`, `page_size`) to handle large datasets efficiently.
+  - **Standardized Responses**: Uniform response format `{ "data": ..., "_meta": ... }` for better observability and error handling.
+- **Performance**:
+  - **Async Execution**: Non-blocking celestial calculations.
+  - **Caching**: Intelligent caching for Simbad queries and regional analysis.
+  - **Proxy Support**: Native support for HTTP/HTTPS proxies (useful for downloading astronomical data).
+- **Time Zone Aware**: Works with local or UTC times.
+
+## Installation
+
+This project uses [uv](https://github.com/astral-sh/uv) for dependency management.
+
+1. **Install `uv`**:
+   ```bash
+   pip install uv
+   ```
+
+2. **Sync dependencies**:
+   ```bash
+   uv sync
+   ```
+   This will create a virtual environment in `.venv` and install all dependencies defined in `pyproject.toml`.
+
+3. **Activate the environment**:
+   ```bash
+   source .venv/bin/activate
+   ```
+
+## MCP Server Usage
+
+Start the MCP server to expose tools to AI agents or other clients.
+
+### 1. Environment Setup
+
+Create a `.env` file or export variables:
+
+```bash
+# Required for weather tools
+export QWEATHER_API_KEY="your_api_key"
+
+# Optional: Proxy for downloading astronomical data (Simbad/IERS)
+# Highly recommended if you are in a restricted network environment
+export HTTP_PROXY="http://127.0.0.1:7890"
+export HTTPS_PROXY="http://127.0.0.1:7890"
+```
+
+### 2. Start Server
+
+**Streamable HTTP (SHTTP) mode** (Recommended for most agents):
+
+```bash
+# Basic start
+python -m src.main --mode shttp --port 3001 --path /shttp
+
+# With proxy explicitly passed (overrides env vars)
+python -m src.main --mode shttp --port 3001 --path /shttp --proxy http://127.0.0.1:7890
+```
+
+**SSE mode**:
+
+```bash
+python -m src.main --mode sse --port 3001 --path /sse
+```
+
+### 3. Response Format
+
+All tools return data in a standardized JSON format:
+
+```json
+{
+  "data": {
+    // Tool-specific return data
+    "altitude": 45.5,
+    "azimuth": 180.0
+  },
+  "_meta": {
+    "version": "1.0.0",
+    "status": "success"
+  }
+}
+```
+
+### 4. Available Tools
+
+- **`get_celestial_pos`**: Calculate altitude/azimuth.
+- **`get_celestial_rise_set`**: Calculate rise/set times (Returns ISO strings).
+- **`get_weather_by_name` / `get_weather_by_position`**: Fetch current weather.
+- **`get_local_datetime_info`**: Get current local time information.
+- **`analysis_area`**: Find best stargazing spots in a region.
+  - **Inputs**: `top_left`, `bottom_right`, `time`, `page`, `page_size`.
+  - **Returns**: List of spots with viewing conditions, plus pagination metadata (`total`, `resource_id`).
+
+## Examples
+
+- **Orchestration**: `python examples/code_execution_orchestration.py`
+  - Demonstrates a full workflow: Get time -> Get Celestial Pos -> Check Weather -> Find Spots.
+  - Shows how to handle the standardized response format programmatically.
+
+- **Pagination**: `python examples/pagination_demo.py`
+  - Demonstrates fetching large result sets page by page using the `resource_id`.
+
+## Project Structure
+
+The project is modularized for better maintainability and code execution support:
+
+```
+.
+├── src/
+│   ├── functions/            # Tool implementations grouped by domain
+│   │   ├── celestial/        # Celestial calculations (pos, rise/set)
+│   │   ├── weather/          # Weather API integration
+│   │   ├── places/           # Location and area analysis
+│   │   └── time/             # Time utilities
+│   ├── cache.py              # Caching logic for analysis results
+│   ├── response.py           # Standardized response formatting
+│   ├── server_instance.py    # FastMCP server instance (avoids circular imports)
+│   ├── main.py               # Entry point and tool registration
+│   ├── celestial.py          # Core astronomy logic (Astropy wrappers)
+│   ├── placefinder.py        # Grid analysis logic
+│   └── qweather_interaction.py # Weather API client
+├── tests/                    # Unified test suite
+│   ├── test_celestial.py
+│   ├── test_weather.py
+│   ├── test_serialization.py # Validates JSON return formats
+│   └── test_integration.py   # End-to-end flow tests
+├── examples/                 # Usage examples
+├── docs/                     # Documentation and improvement plans
+└── pyproject.toml            # Project configuration and dependencies
+```
+
+## Testing
+
+Run the unified test suite:
+
+```bash
+pytest tests/
+```
+
+Key tests include:
+- `test_serialization.py`: Ensures all tools return valid JSON with the correct schema.
+- `test_integration.py`: Mocks external APIs to verify the entire toolchain.
+
+## Contributing
+
+1.  Follow the [Code Execution with MCP](https://www.anthropic.com/engineering/code-execution-with-mcp) best practices.
+2.  Ensure all new tools return standard JSON responses using `src.response.format_response`.
+3.  Add tests in `tests/` for any new functionality.

mcp_stargazing-0.1.6/mcp_stargazing.egg-info/SOURCES.txt

@@ -0,0 +1,33 @@
+LICENSE
+README.md
+pyproject.toml
+mcp_stargazing.egg-info/PKG-INFO
+mcp_stargazing.egg-info/SOURCES.txt
+mcp_stargazing.egg-info/dependency_links.txt
+mcp_stargazing.egg-info/entry_points.txt
+mcp_stargazing.egg-info/requires.txt
+mcp_stargazing.egg-info/top_level.txt
+src/__init__.py
+src/cache.py
+src/celestial.py
+src/main.py
+src/placefinder.py
+src/qweather_interaction.py
+src/response.py
+src/server_instance.py
+src/utils.py
+src/functions/__init__.py
+src/functions/celestial/__init__.py
+src/functions/celestial/impl.py
+src/functions/places/__init__.py
+src/functions/places/impl.py
+src/functions/time/__init__.py
+src/functions/time/impl.py
+src/functions/weather/__init__.py
+src/functions/weather/impl.py
+tests/test_celestial.py
+tests/test_integration.py
+tests/test_placefinder.py
+tests/test_serialization.py
+tests/test_utils.py
+tests/test_weather.py

mcp_stargazing-0.1.6/mcp_stargazing.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

mcp_stargazing-0.1.6/mcp_stargazing.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcp-stargazing = src.main:main

mcp_stargazing-0.1.6/mcp_stargazing.egg-info/requires.txt

@@ -0,0 +1,9 @@
+fastmcp
+astropy>=5.0
+pytz
+numpy
+astroquery
+rasterio
+tzlocal
+geopy
+stargazing-place-finder>=0.3.0

mcp_stargazing-0.1.6/mcp_stargazing.egg-info/top_level.txt

@@ -0,0 +1 @@
+src

mcp_stargazing-0.1.6/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=42", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mcp-stargazing"
+version = "0.1.6"
+description = "This is a mcp server Calculate celestial object positions and rise/set times"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [
+    { name = "Henry Gong", email = "zhao.gong@outlook.com" },
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Astronomy",
+]
+dependencies = [
+    "fastmcp",
+    "astropy>=5.0",
+    "pytz",
+    "numpy",
+    "astroquery",
+    "rasterio",
+    "tzlocal",
+    "geopy",
+    "stargazing-place-finder>=0.3.0"
+]
+
+[project.scripts]
+mcp-stargazing = "src.main:main"
+
+[project.urls]
+Homepage = "https://github.com/StarGazer1995/mcp-stargazing"
+Issues = "https://github.com/StarGazer1995/mcp-stargazing/issues"
+
+[tool.setuptools.packages.find]
+include = ["src*"]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]

mcp_stargazing-0.1.6/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mcp_stargazing-0.1.6/src/__init__.py

@@ -0,0 +1,5 @@
+from . import celestial
+from . import main
+from . import utils
+from . import qweather_interaction
+from . import placefinder