> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nebyoulous.space/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool reference

> Every tool the Nebyoulous MCP server exposes: 45 hosted tools, plus 8 local tools on the CLI server.

The hosted server at `https://api.nebyoulous.space/mcp` exposes 45 tools: 21 read-only, 15 that write data, and 9 destructive. The [CLI server](/mcp/local) exposes the same hosted tools and adds 8 [local tools](#local-tools-cli-server-only) that work with files on your machine.

Every tool acts as the signed-in user. Identity comes from the token, never from an argument, so a tool can only see and change your own data.

> [!NOTE]
>
> Each tool carries the MCP `readOnlyHint` and `destructiveHint` annotations. Hosts such as Claude Code and Cursor use them to ask you before a destructive call runs.

## Account

### `getMe`

**Read-only.** Return the authenticated Nebyoulous user profile (id, email, name, image, username).

No arguments.

## Integration sets

### `listIntegrationSets`

**Read-only.** List integration sets for the authenticated Nebyoulous user.

No arguments.

### `getIntegrationSet`

**Read-only.** Fetch a single integration set owned by the authenticated user.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |

### `createIntegrationSet`

**Writes data.** Create a new integration set owned by the authenticated user.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `title` | string | Yes | Up to 500 characters. |
| `notes` | string or null | No | |

### `updateIntegrationSet`

**Writes data.** Update the title and/or notes on an integration set owned by the authenticated user.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |
| `title` | string | No | Up to 500 characters. |
| `notes` | string or null | No | |

### `deleteIntegrationSet`

**Destructive. MCP hosts ask before running it.** Delete an integration set owned by the authenticated user. Removes assets and export artifacts from S3.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |

### `listIntegrationSetAssets`

**Read-only.** List uploaded assets in an integration set with an inventory summary (by folder, by file type).

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |

### `deleteIntegrationSetFolder`

**Destructive. MCP hosts ask before running it.** Delete all uploaded integration assets under a folder path within an integration set.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |
| `folderPath` | string | Yes | Up to 2048 characters. |

### `deleteIntegrationAssets`

**Destructive. MCP hosts ask before running it.** Delete specific uploaded assets in one integration set. Each item is an asset id or a relativePath (exactly one), at most 100 items per call. Returns one result per item: deleted, not\_found, or forbidden. Another user's asset is forbidden. A registered frame under a live analysis is forbidden; delete that analysis folder instead.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |
| `items` | object\[] | Yes | At least 1, at most 100 items. |

## Uploads and downloads

### `presignUploadBatch`

**Writes data.** Create presigned upload targets for one or more files. Each item is presigned independently; per-item failures appear inline.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `items` | object\[] | Yes | At least 1, at most 500 items. |

### `completeUploadBatch`

**Writes data.** Mark one or more presigned uploads as complete. Per-item failures appear inline.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `items` | object\[] | Yes | At least 1, at most 500 items. |

### `presignDownloadBatch`

**Read-only.** Generate presigned S3 GET URLs for one or more uploaded assets owned by the authenticated user. Per-item failures appear inline. Accepts up to 500 items, the same limit as presignUploadBatch, so a full light set fits in one call.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `items` | object\[] | Yes | Up to 500 assets, the same limit as presignUploadBatch. At least 1, at most 500 items. |

## Gear and rigs

### `listGearItems`

**Read-only.** List equipment items owned by the authenticated user. Optionally filter by category.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `category` | `CAMERA` \| `TELESCOPE` \| `MOUNT` \| `GUIDER` \| `FILTER` \| `ACCESSORY` \| `SOFTWARE` \| `OTHER` | No | |

### `getGearItem`

**Read-only.** Fetch a single equipment item by ID owned by the authenticated user.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `gearItemId` | string (uuid) | Yes | |

### `createGearItem`

**Writes data.** Create a new equipment item (telescope, camera, mount, filter, etc.) for the authenticated user.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `category` | `CAMERA` \| `TELESCOPE` \| `MOUNT` \| `GUIDER` \| `FILTER` \| `ACCESSORY` \| `SOFTWARE` \| `OTHER` | Yes | |
| `manufacturer` | string | Yes | Up to 200 characters. |
| `model` | string | Yes | Up to 200 characters. |
| `displayName` | string or null | No | |
| `notes` | string or null | No | |

### `updateGearItem`

**Writes data.** Update an equipment item owned by the authenticated user.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `gearItemId` | string (uuid) | Yes | |
| `manufacturer` | string | No | Up to 200 characters. |
| `model` | string | No | Up to 200 characters. |
| `displayName` | string or null | No | |
| `notes` | string or null | No | |

### `deleteGearItem`

**Destructive. MCP hosts ask before running it.** Archive (soft-delete) an equipment item owned by the authenticated user.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `gearItemId` | string (uuid) | Yes | |

### `listGearProfiles`

**Read-only.** List rigs (gear profiles) owned by the authenticated user, including each rig's members.

No arguments.

### `getGearProfile`

**Read-only.** Fetch a rig (gear profile) by ID owned by the authenticated user, including its members.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `gearProfileId` | string (uuid) | Yes | |

### `createGearProfile`

**Writes data.** Create a rig (gear profile) for the authenticated user. Optional members are saved in the same call; if any gear item is missing or not owned, nothing is created.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `name` | string | Yes | Up to 200 characters. |
| `description` | string or null | No | |
| `members` | object\[] | No | At most 100 items. |

### `updateGearProfile`

**Writes data.** Update the name or description of a rig (gear profile) owned by the authenticated user.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `gearProfileId` | string (uuid) | Yes | |
| `name` | string | No | Up to 200 characters. |
| `description` | string or null | No | |

### `setGearProfileMembers`

**Writes data.** Replace every member of a rig (gear profile) owned by the authenticated user. The new member list is applied in one step.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `gearProfileId` | string (uuid) | Yes | |
| `members` | object\[] | Yes | At most 100 items. |

### `deleteGearProfile`

**Destructive. MCP hosts ask before running it.** Delete a rig (gear profile) owned by the authenticated user, including its members and integration-set links.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `gearProfileId` | string (uuid) | Yes | |

### `listIntegrationSetGearProfiles`

**Read-only.** List rigs (gear profiles) linked to an integration set owned by the authenticated user.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |

### `setIntegrationSetGearProfiles`

**Writes data.** Replace the rigs linked to an integration set owned by the authenticated user. Each link may mark one rig as primary.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |
| `links` | object\[] | Yes | At most 50 items. |

## Stacking

### `recommendStackConfig`

**Read-only.** Propose a sensible staged stacking `config` and frame `groups` for an integration set owned by the authenticated user, derived deterministically from the set's data (frame paths per role, inferred sensor, prior run reports). Flat-darks in a `flat-darks/` folder, or darks whose filename exposure matches the flats, are routed to `groups.darkflat` instead of `groups.dark`. The returned `config` and `groups` are the same shape `startStack` accepts — submit them as-is or tweak first. Read-only: nothing is dispatched.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |

### `startStack`

**Writes data.** Submit a stacking job for an integration set owned by the authenticated user. Select frames by relativePath per role (light required; dark/flat/bias/darkflat optional). `darkflat` is flat-darks (darks at the flat exposure): they calibrate the flats and are not mixed into the light-exposure dark. Prefer a staged `config` (\{version,calibrate,register,stack}). Top-level `params` and `referencePath` are deprecated: `config` wins over `params`, and `config.register.referencePath` wins over top-level `referencePath`. Both are optional — the API fills defaults and clamps values; the engine is always Siril. Refine re-stacks are not available here: this tool does not accept `sourceAnalysisId` or `excludedFrames`, because no MCP tool returns an analysis id.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `groups` | object | Yes | |
| `config` | object | No | |
| `params` | object | No | Deprecated. Legacy flat stacking params. Prefer staged `config`. If both are set, `config` wins. The engine is always Siril and is not an input. |
| `referencePath` | string | No | Deprecated. Prefer `config.register.referencePath`. If both are set, the staged config path wins. Must be one of the selected light frames. Up to 1024 characters. |
| `integrationSetId` | string (uuid) | Yes | |

### `listStacks`

**Read-only.** List stack jobs for an integration set owned by the authenticated user, most recent first.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |

### `getStackStatus`

**Read-only.** Get a stack job's status and frame counts. Includes a presigned master-FITS downloadUrl when READY and an errorMessage when FAILED.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |
| `jobId` | string (uuid) | Yes | |

### `cancelStack`

**Destructive. MCP hosts ask before running it.** Cancel an in-progress stack job for an integration set owned by the authenticated user. Returns the updated job status.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |
| `jobId` | string (uuid) | Yes | |

### `deleteStack`

**Destructive. MCP hosts ask before running it.** Delete a terminal stack job and its output artifacts for an integration set owned by the authenticated user. This is permanent.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |
| `jobId` | string (uuid) | Yes | |

## Frame QA and analysis

### `startFrameQa`

**Writes data.** Start a frame-QA job for the light frames directly under one folder of an integration set owned by the authenticated user. This writes a new job. It does not delete frames.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `folder` | string | Yes | Up to 1024 characters. |
| `integrationSetId` | string (uuid) | Yes | |

### `getFrameQaResults`

**Read-only.** Read the newest frame-QA run for one folder of an integration set owned by the authenticated user, or a jobId when one is given. When no run exists, job is null. When the run is not READY, metricsAvailable is false and frames is empty. When READY, returns counts, the thresholds that were used, and one page of rejected or failed frames (default 20, max 50). Pass offset=nextOffset for the next page. This does not delete or exclude frames.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |
| `folder` | string | Yes | Folder inside the set, e.g. lights-120s. Lights directly under this folder were scored. Up to 1024 characters. |
| `jobId` | string (uuid) | No | A specific frame-QA job for this folder. When omitted, the newest run is used. |
| `offset` | integer | No | Min 0, max 9007199254740991. |
| `limit` | integer | No | Min 1, max 50. |

### `getFrameAnalysisMetrics`

**Read-only.** Read Siril registration metrics for one analyze job on an integration set owned by the authenticated user. When the job is not READY, metricsAvailable is false and frames is empty. When READY, returns one page of frames (default 20, max 50) with fwhm, wfwhm, roundness, background, nbstars, quality, and included. Pass offset=nextOffset for the next page.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `integrationSetId` | string (uuid) | Yes | |
| `jobId` | string (uuid) | Yes | |
| `offset` | integer | No | Min 0, max 9007199254740991. |
| `limit` | integer | No | Min 1, max 50. |

## Posts and comments

### `listPosts`

**Read-only.** List all posts (drafts and published) owned by the authenticated user.

No arguments.

### `getPost`

**Read-only.** Fetch a single post by ID owned by the authenticated user.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `postId` | string (uuid) | Yes | |

### `createPost`

**Writes data.** Create a new draft post. Optionally link integration sets by ID. Returns the created draft. Catalog object types and post targetType are different enums. Map a catalog type to a post targetType as: galaxy → GALAXY, nebula → NEBULA, open\_cluster → STAR\_CLUSTER, globular\_cluster → STAR\_CLUSTER, planetary\_nebula → PLANETARY\_NEBULA, dark\_nebula → NEBULA, galaxy\_cluster → OTHER, supernova\_remnant → NEBULA, double\_star → OTHER, other → OTHER.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `title` | string | Yes | Up to 500 characters. |
| `description` | string or null | No | |
| `targetName` | string or null | No | |
| `targetType` | `GALAXY` \| `NEBULA` \| `STAR_CLUSTER` \| `PLANETARY_NEBULA` \| `OTHER` or null | No | Catalog object types and post targetType are different enums. Map a catalog type to a post targetType as: galaxy → GALAXY, nebula → NEBULA, open\_cluster → STAR\_CLUSTER, globular\_cluster → STAR\_CLUSTER, planetary\_nebula → PLANETARY\_NEBULA, dark\_nebula → NEBULA, galaxy\_cluster → OTHER, supernova\_remnant → NEBULA, double\_star → OTHER, other → OTHER. |
| `captureDate` | string or null | No | |
| `bortle` | integer or null | No | |
| `integrationSetIds` | string (uuid)\[] | No | |

### `updatePost`

**Writes data.** Update a draft post's fields, linked integration sets, or publish it. Set publish: true to publish. Catalog object types and post targetType are different enums. Map a catalog type to a post targetType as: galaxy → GALAXY, nebula → NEBULA, open\_cluster → STAR\_CLUSTER, globular\_cluster → STAR\_CLUSTER, planetary\_nebula → PLANETARY\_NEBULA, dark\_nebula → NEBULA, galaxy\_cluster → OTHER, supernova\_remnant → NEBULA, double\_star → OTHER, other → OTHER.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `postId` | string (uuid) | Yes | |
| `title` | string | No | Up to 500 characters. |
| `description` | string or null | No | |
| `targetName` | string or null | No | |
| `targetType` | `GALAXY` \| `NEBULA` \| `STAR_CLUSTER` \| `PLANETARY_NEBULA` \| `OTHER` or null | No | Catalog object types and post targetType are different enums. Map a catalog type to a post targetType as: galaxy → GALAXY, nebula → NEBULA, open\_cluster → STAR\_CLUSTER, globular\_cluster → STAR\_CLUSTER, planetary\_nebula → PLANETARY\_NEBULA, dark\_nebula → NEBULA, galaxy\_cluster → OTHER, supernova\_remnant → NEBULA, double\_star → OTHER, other → OTHER. |
| `captureDate` | string or null | No | |
| `bortle` | integer or null | No | |
| `integrationSetIds` | string (uuid)\[] | No | |
| `publish` | boolean | No | |

### `deletePost`

**Destructive. MCP hosts ask before running it.** Delete a post and its associated final images. This is permanent.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `postId` | string (uuid) | Yes | |

### `getPostImagePreview`

**Read-only.** Fetch a post's thumbnail or full final image and return it as an inline image for Claude to render. Use kind='thumbnail' (default) for fast previews; kind='full' for the full final image (capped at 5 MB).

| Argument | Type | Required | Notes |
| - | - | - | - |
| `postId` | string (uuid) | Yes | |
| `kind` | `thumbnail` \| `full` | No | Default `"thumbnail"`. |

### `getPostImageViewUrl`

**Read-only.** Return a presigned URL for a post's thumbnail or full final image so clients can render it inline (e.g. markdown !\[title]\(url)). Use kind='thumbnail' (default) for fast previews; kind='full' for the full final image. URL expires in 1 hour.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `postId` | string (uuid) | Yes | |
| `kind` | `thumbnail` \| `full` | No | Default `"thumbnail"`. |

### `addPostComment`

**Writes data.** Add a whole-post comment (annotation thread without a region anchor) to a published post.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `postId` | string (uuid) | Yes | |
| `body` | string | Yes | Up to 10000 characters. |

### `listPostComments`

**Read-only.** List all top-level comments on a published post.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `postId` | string (uuid) | Yes | |

### `deletePostComment`

**Destructive. MCP hosts ask before running it.** Delete a comment (annotation thread) on a published post. Only the comment author or post owner can delete.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `postId` | string (uuid) | Yes | |
| `commentId` | string (uuid) | Yes | |

## Catalog

### `queryDSOCatalog`

**Read-only.** Search the Deep Sky Object catalog by name, catalog designation, object type, constellation, or magnitude. Catalog ids such as M31, NGC 224, IC 1318, and C14 resolve to that object. Each result includes cross-designations so a Messier number can be confirmed. Useful for target planning and linking posts to known objects. Catalog object types and post targetType are different enums. Map a catalog type to a post targetType as: galaxy → GALAXY, nebula → NEBULA, open\_cluster → STAR\_CLUSTER, globular\_cluster → STAR\_CLUSTER, planetary\_nebula → PLANETARY\_NEBULA, dark\_nebula → NEBULA, galaxy\_cluster → OTHER, supernova\_remnant → NEBULA, double\_star → OTHER, other → OTHER.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `q` | string | No | Up to 120 characters. |
| `catalog` | `NGC` \| `IC` \| `M` \| `C` \| `UGC` \| `PGC` \| `Abell` \| `Barnard` \| `Lynds` | No | |
| `type` | `galaxy` \| `nebula` \| `open_cluster` \| `globular_cluster` \| `planetary_nebula` \| `dark_nebula` \| `galaxy_cluster` \| `supernova_remnant` \| `double_star` \| `other` | No | Catalog object types and post targetType are different enums. Map a catalog type to a post targetType as: galaxy → GALAXY, nebula → NEBULA, open\_cluster → STAR\_CLUSTER, globular\_cluster → STAR\_CLUSTER, planetary\_nebula → PLANETARY\_NEBULA, dark\_nebula → NEBULA, galaxy\_cluster → OTHER, supernova\_remnant → NEBULA, double\_star → OTHER, other → OTHER. |
| `constellation` | string | No | Up to 80 characters. |
| `mag_max` | number | No | |
| `limit` | integer | No | Min 1, max 50. Default `20`. |
| `offset` | integer | No | Min 0, max 9007199254740991. Default `0`. |

## Local tools (CLI server only)

`nebyoulous mcp:serve` runs these in the CLI process, so they can read your disks. They are not on the hosted server.

### `listVolumes`

**Read-only.** List likely camera or removable-media sources mounted on the host. Returns mount path, label, capacity, and camera-media signals.

No arguments.

### `listLocalDestinationAssets`

**Read-only.** Walk a local destination folder and return relativePath + sizeBytes entries suitable for planSync existingAssets. Missing destinations return an empty list.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `destPath` | string | Yes | |

### `scanFolder`

**Read-only.** Walk a folder and summarise files by extension, folder signals (DCIM/LIGHT/DARK/BIAS/FLAT), mtime range, and a sample of FITS primary-HDU headers.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `path` | string | Yes | |
| `include` | string\[] | No | |
| `exclude` | string\[] | No | |
| `maxDepth` | integer | No | Min 0, max 9007199254740991. |
| `followSymlinks` | boolean | No | |
| `fitsSampleCap` | integer | No | Min 0, max 9007199254740991. |

### `peekFitsHeader`

**Read-only.** Read the FITS primary-HDU header for a file and return well-known keywords (IMAGETYP, OBJECT, EXPTIME, FILTER, DATE-OBS, INSTRUME) plus the raw value cards. Returns null if the file is not a parseable FITS file.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `path` | string | Yes | |
| `maxBytes` | integer | No | Max 9007199254740991. |

### `classifyFrameType`

**Read-only.** Classify a file as LIGHT, DARK, BIAS, or FLAT. Prefers the FITS IMAGETYP value; falls back to filename/folder heuristics. Returns null if no signal is confident.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `relativePath` | string | Yes | |
| `filename` | string | Yes | |
| `fitsImageType` | string or null | Yes | |

### `planSync`

**Read-only.** Walk a source folder, classify candidate files, and partition them into (a) uploads to perform and (b) skipped files with reasons (dedupe against server + local manifest, frame-type filter, size cap).

| Argument | Type | Required | Notes |
| - | - | - | - |
| `sourcePath` | string | Yes | |
| `relativePathPrefix` | string | No | |
| `walkOptions` | object | No | |
| `existingAssets` | object\[] | Yes | |
| `frameType` | `LIGHT` \| `DARK` \| `BIAS` \| `FLAT` | No | |
| `includeAmbiguous` | boolean | No | |
| `maxBytes` | integer | Yes | Max 9007199254740991. |

### `executeSync`

**Destructive. MCP hosts ask before running it.** Drive the upload pipeline for a planned set of files: presign in batches, PUT to S3 with capped concurrency, complete batches, and record manifest entries. Returns per-file outcomes; partial failures are reported, not thrown.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `uploads` | object\[] | Yes | |
| `integrationSetId` | string (uuid) | Yes | |
| `batchSize` | integer | No | Max 9007199254740991. |
| `concurrency` | integer | No | Max 9007199254740991. |

### `executeLocalSync`

**Destructive. MCP hosts ask before running it.** Copy a planned set of files from their source paths into a local destination folder via atomic temp+rename. Files land directly under destPath using each upload's relativePath; subdirectories are created as needed. Returns per-file outcomes; partial failures are reported, not thrown. Runs entirely offline — no auth, no API or MCP calls. When sourcePath is provided, records successes in the local sync manifest for that source/destination pair.

| Argument | Type | Required | Notes |
| - | - | - | - |
| `uploads` | object\[] | Yes | |
| `destPath` | string | Yes | |
| `sourcePath` | string | No | |
| `concurrency` | integer | No | Max 9007199254740991. |

## Deprecated aliases

These snake\_case names still work for older prompts and configs. Use the camelCase tool instead.

| Alias | Use instead |
| - | - |
| `start_stack` | `startStack` |
| `list_stacks` | `listStacks` |
| `get_stack_status` | `getStackStatus` |
| `cancel_stack` | `cancelStack` |
| `delete_stack` | `deleteStack` |
| `recommend_stack_config` | `recommendStackConfig` |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.