Metadata-Version: 2.4
Name: mcp-server-ascom
Version: 0.2.2
Summary: MCP server for ASCOM astronomy equipment control
Author: Stellarpunk Collective
License-Expression: MIT
Project-URL: Homepage, https://github.com/stellarpunk/mcp-server-ascom
Project-URL: Bug Tracker, https://github.com/stellarpunk/mcp-server-ascom/issues
Project-URL: Repository, https://github.com/stellarpunk/mcp-server-ascom
Project-URL: Organization, https://github.com/stellarpunk
Keywords: mcp,ascom,astronomy,telescope,alpaca,stellarpunk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: alpyca>=2.0.0
Requires-Dist: astropy>=6.0.0
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# MCP Server for ASCOM

[![MCP](https://img.shields.io/badge/MCP-2025--06--18-brightgreen.svg)](https://modelcontextprotocol.io)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/mcp-server-ascom.svg)](https://pypi.org/project/mcp-server-ascom/)
[![Tests](https://github.com/stellarpunk/mcp-server-ascom/workflows/Test/badge.svg)](https://github.com/stellarpunk/mcp-server-ascom/actions)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

Control astronomy equipment through AI. MCP 2025-06-18 compliant.

## Features

- **Latest Protocol** - Structured outputs. Version negotiation.
- **Any ASCOM Device** - Telescopes. Cameras. Focusers. More.
- **Natural Language** - "Point at M31" just works.
- **Auto-Discovery** - Finds devices. No configuration.
- **Fast** - Async everywhere. Never blocks.
- **Secure** - OAuth ready. Off by default.
- **Extensible** - Add new device types easily.
- **Tested** - Full coverage. Type safe.

## Installation

### Option 1: pip install (Simplest)
```bash
pip install mcp-server-ascom
```

### Option 2: uvx (No install needed)
```bash
uvx mcp-server-ascom
```

### Option 3: From source
```bash
git clone https://github.com/stellarpunk/mcp-server-ascom.git
cd mcp-server-ascom
pip install -e .
```

**Note:** The `alpyca` package (ASCOM library) imports as `alpaca` in Python code.

## Configuration

### Claude Desktop

#### Quick Setup (Recommended)
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "ascom": {
      "command": "uvx",
      "args": ["mcp-server-ascom"]
    }
  }
}
```

This uses `uvx` to automatically handle Python environments and dependencies.

#### Alternative: Direct Installation
```bash
pip install mcp-server-ascom
```

Then use:
```json
{
  "mcpServers": {
    "ascom": {
      "command": "mcp-server-ascom"
    }
  }
}
```

### Running the Server

```bash
# Make sure virtual environment is activated
source .venv/bin/activate

# Run the server
python -m ascom_mcp
```

### MCP Inspector (Testing)
```bash
npm install -g @modelcontextprotocol/inspector

# With virtual environment
mcp-inspector .venv/bin/python -m ascom_mcp

# Or if mcp-server-ascom is in PATH
mcp-inspector mcp-server-ascom
```

## Usage

```
You: Connect to my telescope
AI: Found Seestar S50. Connected.

You: Point at the Orion Nebula
AI: Slewing to M42... Done.
```

## Supported Equipment

ASCOM Alpaca devices: Telescopes. Cameras. Focusers. Filter wheels. Domes.

## Tools

**Find devices**: `discover_ascom_devices`  
**Control telescope**: `connect` `goto` `goto_object` `park`  
**Use camera**: `connect` `capture` `get_status`

## Development

### Setup
```bash
git clone https://github.com/stellarpunk/mcp-server-ascom.git
cd mcp-server-ascom

# Create virtual environment (choose one)
uv venv                    # Using uv
python -m venv .venv       # Using standard venv

# Activate
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install with dev dependencies
pip install -e ".[dev]"    # or: uv pip install -e ".[dev]"
```

### Testing
```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=ascom_mcp

# Run specific test file
pytest tests/test_device_manager.py
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## Security

Off by default. Enable OAuth:

```bash
cp .env.example .env
# Edit .env: ASCOM_MCP_OAUTH_ENABLED=true
# Restart server
```

Done. See [security.py](src/ascom_mcp/security.py) for options.

## Troubleshooting

### ModuleNotFoundError: No module named 'alpyca'
The `alpyca` package installs as `alpaca`. Use:
```python
from alpaca import discovery  # NOT from alpyca
```

### Virtual Environment Issues
Always activate your virtual environment before running:
```bash
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate     # Windows
```

### No ASCOM devices found
1. Ensure devices are powered on and connected to network
2. Check firewall settings (UDP port 32227 for discovery)
3. Try manual discovery at known IP:
   ```bash
   curl http://device-ip:11111/api/v1/description
   ```

## License

MIT - see [LICENSE](LICENSE)

## See Also

- [Seestar S50 Integration Guide](docs/seestar_integration.md)
- [ASCOM Standards](https://ascom-standards.org/)
- [Alpaca API Reference](https://ascom-standards.org/api/)
