Tool reference - Nebyoulous

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 exposes the same hosted tools and adds 8 local tools 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.

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
`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`

​Account

​getMe

​Integration sets

​listIntegrationSets

​getIntegrationSet

​createIntegrationSet

​updateIntegrationSet

​deleteIntegrationSet

​listIntegrationSetAssets

​deleteIntegrationSetFolder

​deleteIntegrationAssets

​Uploads and downloads

​presignUploadBatch

​completeUploadBatch

​presignDownloadBatch

​Gear and rigs

​listGearItems

​getGearItem

​createGearItem

​updateGearItem

​deleteGearItem

​listGearProfiles

​getGearProfile

​createGearProfile

​updateGearProfile

​setGearProfileMembers

​deleteGearProfile

​listIntegrationSetGearProfiles

​setIntegrationSetGearProfiles

​Stacking

​recommendStackConfig

​startStack

​listStacks

​getStackStatus

​cancelStack

​deleteStack

​Frame QA and analysis

​startFrameQa

​getFrameQaResults

​getFrameAnalysisMetrics

​Posts and comments

​listPosts

​getPost

​createPost

​updatePost

​deletePost

​getPostImagePreview

​getPostImageViewUrl

​addPostComment

​listPostComments

​deletePostComment

​Catalog

​queryDSOCatalog

​Local tools (CLI server only)

​listVolumes

​listLocalDestinationAssets

​scanFolder

​peekFitsHeader

​classifyFrameType

​planSync

​executeSync

​executeLocalSync

​Deprecated aliases

Account

`getMe`

Integration sets

`listIntegrationSets`

`getIntegrationSet`

`createIntegrationSet`

`updateIntegrationSet`

`deleteIntegrationSet`

`listIntegrationSetAssets`

`deleteIntegrationSetFolder`

`deleteIntegrationAssets`

Uploads and downloads

`presignUploadBatch`

`completeUploadBatch`

`presignDownloadBatch`

Gear and rigs

`listGearItems`

`getGearItem`

`createGearItem`

`updateGearItem`

`deleteGearItem`

`listGearProfiles`

`getGearProfile`

`createGearProfile`

`updateGearProfile`

`setGearProfileMembers`

`deleteGearProfile`

`listIntegrationSetGearProfiles`

`setIntegrationSetGearProfiles`

Stacking

`recommendStackConfig`

`startStack`

`listStacks`

`getStackStatus`

`cancelStack`

`deleteStack`

Frame QA and analysis

`startFrameQa`

`getFrameQaResults`

`getFrameAnalysisMetrics`

Posts and comments

`listPosts`

`getPost`

`createPost`

`updatePost`

`deletePost`

`getPostImagePreview`

`getPostImageViewUrl`

`addPostComment`

`listPostComments`

`deletePostComment`

Catalog

`queryDSOCatalog`

Local tools (CLI server only)

`listVolumes`

`listLocalDestinationAssets`

`scanFolder`

`peekFitsHeader`

`classifyFrameType`

`planSync`

`executeSync`

`executeLocalSync`

Deprecated aliases