# Skygems Full AI Agent Reference

This document provides a comprehensive reference for LLMs, AI agents, and developers interacting with the Skygems remote astronomy platform.

---

## 1. Model Context Protocol (MCP) Server

Skygems hosts an MCP server compliant with the Model Context Protocol.

- **HTTP Endpoint**: `POST https://app.skygems.io/mcp`
- **Transport**: MCP Streamable HTTP transport
- **Authentication**: OAuth 2.1 with PKCE (via Laravel Passport)
- **Required Scope**: `mcp:use`
- **Auto-Discovery Endpoints**:
  - `GET /.well-known/oauth-protected-resource`
  - `GET /.well-known/oauth-authorization-server`
  - `POST /oauth/register` (Dynamic Client Registration, RFC 7591)
- **Headless / Token Authentication**:
  For CLI tools, custom scripts, or desktop agents that do not support standard OAuth interactive redirects, users can generate a long-lived Personal Access Token (PAT) with the `mcp:use` scope via the **User Settings -> Developer & AI Tokens** tab in the UI. Alternatively, developers can generate it via CLI:
  `php artisan skygems:generate-agent-token --user={email_or_id}`
  Configure your agent to send the token in the `Authorization` header:
  `Authorization: Bearer <your_generated_token>`

---

## 2. MCP Tools Roster

### Public Tools (Unrestricted)

#### 1. `list_observatories`
List all available public telescopes, locations, and optical specifications (Field of View).
- **Parameters**: None

#### 2. `check_target_visibility`
Rank observatories by how well they can observe a target coordinate tonight.
- **Parameters**:
  - `ra` (number, required): Right ascension in decimal degrees (0–360).
  - `dec` (number, required): Declination in decimal degrees (-90 to +90).
  - `fov` (number, optional): Target angular size in degrees to check FOV compatibility.

#### 3. `get_observable_targets`
Get curated targets visible tonight from a specific observatory.
- **Parameters**:
  - `observatory_id` (integer, required): The target observatory ID.

#### 4. `ask_imaging_assistant`
Ask the imaging assistant free-text questions about what to observe (nebulae, galaxies, star clusters, planets).
- **Parameters**:
  - `message` (string, required): The query message.

---

### User-Specific Tools (Require Authentication)

#### 5. `get_user_profile`
Retrieve the authenticated user's name, email, and current credit balance.
- **Parameters**: None

#### 6. `list_imaging_requests`
List the user's imaging requests.
- **Parameters**:
  - `status` (string, optional): Filter by status (`pending`, `active`, `completed`, `paused`, `failed`).
  - `exclude_archived` (boolean, optional): Exclude archived requests.

#### 7. `create_imaging_request`
Create a new pending imaging request.
- **Parameters**:
  - `name` (string, required): A descriptive name.
  - `observatory_id` (integer, required): ID of the observatory.

#### 8. `pause_imaging_request`
Pause an active/running imaging request.
- **Parameters**:
  - `id` (integer, required): The ID of the imaging request to pause.

#### 9. `activate_imaging_request`
Activate/resume a pending or paused imaging request, submitting it to the observatory queue.
- **Parameters**:
  - `id` (integer, required): The ID of the imaging request to activate.

#### 10. `delete_imaging_request`
Delete (archive) an imaging request.
- **Parameters**:
  - `id` (integer, required): The ID of the imaging request to delete.

#### 11. `list_observations`
List completed observations for the authenticated user.
- **Parameters**: None

#### 12. `calculate_target_altitude`
Calculate target altitude profile tonight at a specific observatory.
- **Parameters**:
  - `observatory_id` (integer, required): Observatory ID.
  - `ra` (number, required): Right ascension.
  - `dec` (number, required): Declination.

#### 13. `list_fits_files`
List available FITS files and their calibration status.
- **Parameters**: None

#### 14. `list_master_frames`
List stacked master frames generated for the user's imaging requests.
- **Parameters**: None

---

## 3. Core REST API Overview (v1)

All endpoints live under `https://app.skygems.io/api/v1` and require token authorization.

- `GET /api/v1/imagingrequest` — List user's imaging requests
- `POST /api/v1/imagingrequest` — Submit/create a new imaging request
- `GET /api/v1/imagingrequest/activate?RID=<id>` — Activate an imaging request
- `GET /api/v1/imagingrequest/pause?RID=<id>` — Pause an imaging request
- `GET /api/v1/imagingrequest/delete?RID=<id>` — Delete/archive an imaging request
- `GET /api/v1/observatory` — List observatories
- `GET /api/v1/observations` — Retrieve observations list
- `GET /api/v1/getChargeForRequest` — Fetch pricing estimate for a request