@zegazone_mcp/mcp 2.0.3 → 2.0.4

package/README.md

@@ -33,19 +33,26 @@ Set `ZEGA_API_BASE=https://api.zegaphone.com` in env if needed (defaults apply f
 - Keeps API as source of truth.
 - Applies safety defaults for destructive operations (`dry_run` when neither `confirm` nor `dry_run` is provided).
 - Adds `idempotency_key` automatically to mutating operations when absent.
+- **2.0.4+:** every MCP tool exposes a typed Zod input schema (field names, types, and descriptions) so weak models can call tools without guessing `args`.
 
 ## Tool mapping
 
 Examples:
 
 - `operations_list` -> `operations.list`
+- `collections_get` -> `collections.get`
+- `collections_get_by_slug` -> `collections.get_by_slug`
 - `collections_delete` -> `collections.delete`
+- `media_get` -> `media.get`
+- `media_search` -> `media.search` (requires `query`)
 - `media_delete` -> `media.delete`
 - `media_move` -> `media.move`
 - `media_reorder` -> `media.reorder`
 
 Also includes generic `thirdparty_call` for forward compatibility.
 
+**Lookup tip:** use `media_get` / `collections_get` when you know the id; use `media_search` when you only have a keyword.
+
 ## Configuration
 
 Copy `.env.example` to `.env.local`. You need `ZEGA_API_BASE` plus **either** a one-time OAuth pairing **or** a static access token.

package/dist/tool-schemas.js

@@ -14,11 +14,22 @@ const viewerEnum = z.enum([
     "html",
 ]);
 const shareAccessLevelEnum = z.enum(["private", "restricted", "registered", "public"]);
+const displayModeEnum = z.enum(["plain", "markdown", "code"]);
+const collectionsBrowseFilterEnum = z.enum(["own", "shared", "public", "following", "liked"]);
+const mediaIdSchema = z.number().int().positive().describe("Integer ID of the media item.");
+const collectionIdSchema = z.number().int().positive().describe("Integer ID of the collection.");
+const limitSchema = z.number().int().positive().optional();
+const offsetSchema = z.number().int().min(0).optional();
 const tagsSchema = z
     .array(z.string().min(1))
     .max(10)
     .optional()
     .describe("Highly encouraged for discovery and organization (max 10).");
+const emptyToolSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+})
+    .catchall(z.unknown());
 export const collectionsCreateSchema = z
     .object({
     args: z.record(z.unknown()).optional(),
@@ -43,7 +54,7 @@ export const collectionsCreateSchema = z
         .optional()
         .describe("Profile alias UUID; sets created_with_username publish handle."),
     playback_prefs: z.record(z.unknown()).optional().describe("JSON playback preferences."),
-    parent_collection_id: z.number().int().positive().optional(),
+    parent_collection_id: collectionIdSchema.optional(),
     link_position: z.number().int().min(0).optional(),
     link_description: z.string().max(4000).optional(),
 })
@@ -51,7 +62,7 @@ export const collectionsCreateSchema = z
 export const collectionsUpdateSchema = z
     .object({
     args: z.record(z.unknown()).optional(),
-    collection_id: z.number().int().positive(),
+    collection_id: collectionIdSchema,
     name: z.string().min(1).optional(),
     description: z.string().max(4000).nullable().optional(),
     tags: tagsSchema,
@@ -69,10 +80,125 @@ export const collectionsUpdateSchema = z
     playback_prefs: z.record(z.unknown()).nullable().optional(),
 })
     .catchall(z.unknown());
+export const collectionsListSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    parent_collection_id: collectionIdSchema.optional(),
+    include_archived: z.boolean().optional(),
+    limit: limitSchema,
+    offset: offsetSchema,
+})
+    .catchall(z.unknown());
+export const collectionsBatchGetSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_ids: z.array(collectionIdSchema).min(1),
+})
+    .catchall(z.unknown());
+export const collectionsExportSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+})
+    .catchall(z.unknown());
+export const collectionsStatsGetSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+})
+    .catchall(z.unknown());
+export const collectionsShareUrlSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+})
+    .catchall(z.unknown());
+export const collectionsDeleteSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+    dry_run: z.boolean().optional(),
+    confirm: z.boolean().optional(),
+})
+    .catchall(z.unknown());
+export const collectionsRestoreSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+})
+    .catchall(z.unknown());
+export const collectionsArchiveSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+})
+    .catchall(z.unknown());
+export const collectionsUnarchiveSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+})
+    .catchall(z.unknown());
+export const collectionsReorderSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+    ordered_ids: z.array(z.number().int().positive()).min(1),
+})
+    .catchall(z.unknown());
+export const collectionsPublishSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+    slug: z.string().min(1),
+    handle: z.string().min(1).optional(),
+})
+    .catchall(z.unknown());
+export const collectionsUnpublishSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+})
+    .catchall(z.unknown());
+export const collectionsLikeSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+})
+    .catchall(z.unknown());
+export const collectionsUnlikeSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+})
+    .catchall(z.unknown());
+export const collectionsLikedListSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    limit: limitSchema,
+    offset: offsetSchema,
+})
+    .catchall(z.unknown());
+export const collectionsSearchSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    query: z.string().min(3),
+    limit: limitSchema,
+    offset: offsetSchema,
+})
+    .catchall(z.unknown());
+export const collectionsBrowseSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    filter: collectionsBrowseFilterEnum,
+    limit: limitSchema,
+    offset: offsetSchema,
+})
+    .catchall(z.unknown());
 export const mediaCreateSchema = z
     .object({
     args: z.record(z.unknown()).optional(),
-    collection_id: z.number().int().positive(),
+    collection_id: collectionIdSchema,
     source_url: z.string().url(),
     viewer: viewerEnum.describe("Hint for which viewer to use (required)."),
     name: z.string().max(180).optional(),
@@ -89,13 +215,13 @@ export const mediaCreateSchema = z
     screenshot_url: z.string().url().optional(),
     background_image_url: z.string().url().optional(),
     locked_for_collaborators: z.boolean().optional(),
-    subcollection_collection_id: z.number().int().positive().nullable().optional(),
+    subcollection_collection_id: collectionIdSchema.nullable().optional(),
 })
     .catchall(z.unknown());
 export const mediaUpdateSchema = z
     .object({
     args: z.record(z.unknown()).optional(),
-    media_id: z.number().int().positive(),
+    media_id: mediaIdSchema,
     name: z.string().max(180).optional(),
     description: z.string().max(4000).nullable().optional(),
     position: z.number().int().min(0).optional(),
@@ -110,18 +236,18 @@ export const mediaUpdateSchema = z
     type: z.string().optional(),
     tags: tagsSchema,
     text_note: z.string().max(524288).optional(),
-    display_mode: z.enum(["plain", "markdown", "code"]).optional(),
+    display_mode: displayModeEnum.optional(),
     screenshot_url: z.string().url().nullable().optional(),
     background_image_url: z.string().url().nullable().optional(),
     locked_for_collaborators: z.boolean().optional(),
-    subcollection_collection_id: z.number().int().positive().nullable().optional(),
+    subcollection_collection_id: collectionIdSchema.nullable().optional(),
 })
     .catchall(z.unknown());
 export const uiStateSetSchema = z
     .object({
     args: z.record(z.unknown()).optional(),
-    collection_id: z.number().int().positive().nullable().optional(),
-    media_id: z.number().int().positive().nullable().optional(),
+    collection_id: collectionIdSchema.nullable().optional(),
+    media_id: mediaIdSchema.nullable().optional(),
     source: z.enum(["agent", "user"]).optional(),
     agent_id: z.string().nullable().optional(),
     view_mode: z.enum(["carousel", "grid"]).nullable().optional(),
@@ -133,19 +259,19 @@ export const uiStateSetSchema = z
 export const mediaDescribeSchema = z
     .object({
     args: z.record(z.unknown()).optional(),
-    media_id: z.number().int().positive(),
+    media_id: mediaIdSchema,
 })
     .catchall(z.unknown());
 export const mediaGetSchema = z
     .object({
     args: z.record(z.unknown()).optional(),
-    media_id: z.number().int().positive(),
+    media_id: mediaIdSchema,
 })
     .catchall(z.unknown());
 export const collectionsGetSchema = z
     .object({
     args: z.record(z.unknown()).optional(),
-    collection_id: z.number().int().positive(),
+    collection_id: collectionIdSchema,
 })
     .catchall(z.unknown());
 export const collectionsGetBySlugSchema = z
@@ -159,16 +285,16 @@ export const mediaSearchSchema = z
     .object({
     args: z.record(z.unknown()).optional(),
     query: z.string().min(1).describe("Search text matched against name, description, and tags."),
-    collection_id: z.number().int().positive().optional(),
+    collection_id: collectionIdSchema.optional(),
     include_archived: z.boolean().optional(),
-    limit: z.number().int().positive().optional(),
-    offset: z.number().int().min(0).optional(),
+    limit: limitSchema,
+    offset: offsetSchema,
 })
     .catchall(z.unknown());
 export const mediaListSchema = z
     .object({
     args: z.record(z.unknown()).optional(),
-    collection_id: z.number().int().positive().optional(),
+    collection_id: collectionIdSchema.optional(),
     tag: z.string().optional(),
     tags: tagsSchema,
     name_contains: z.string().optional(),
@@ -179,20 +305,243 @@ export const mediaListSchema = z
     created_before: z.string().optional(),
     is_nsfw: z.boolean().optional(),
     include_archived: z.boolean().optional(),
-    limit: z.number().int().positive().optional(),
-    offset: z.number().int().min(0).optional(),
+    limit: limitSchema,
+    offset: offsetSchema,
+})
+    .catchall(z.unknown());
+export const mediaBatchListSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_ids: z.array(mediaIdSchema).min(1),
+})
+    .catchall(z.unknown());
+export const mediaDownloadSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_id: mediaIdSchema,
+})
+    .catchall(z.unknown());
+export const mediaReplaceSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_id: mediaIdSchema,
+    source_url: z.string().url(),
+    viewer: viewerEnum.optional(),
+    type: z.string().optional(),
+})
+    .catchall(z.unknown());
+export const mediaDeleteSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_id: mediaIdSchema,
+    dry_run: z.boolean().optional(),
+    confirm: z.boolean().optional(),
+})
+    .catchall(z.unknown());
+export const mediaRestoreSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_id: mediaIdSchema,
+})
+    .catchall(z.unknown());
+export const mediaMoveSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_id: mediaIdSchema,
+    collection_id: collectionIdSchema,
+    position: z.number().int().min(0).optional(),
+})
+    .catchall(z.unknown());
+export const mediaCopySchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_id: mediaIdSchema,
+    collection_id: collectionIdSchema,
+    position: z.number().int().min(0).optional(),
+})
+    .catchall(z.unknown());
+export const mediaReorderSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+    ordered_ids: z.array(mediaIdSchema).min(1),
+})
+    .catchall(z.unknown());
+export const mediaArchiveSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_id: mediaIdSchema,
+})
+    .catchall(z.unknown());
+export const mediaUnarchiveSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_id: mediaIdSchema,
+})
+    .catchall(z.unknown());
+export const mediaTextNoteAddSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+    name: z.string().min(1),
+    body: z.string(),
+    display_mode: displayModeEnum.optional(),
+    position: z.number().int().min(0).optional(),
+})
+    .catchall(z.unknown());
+export const mediaTextNoteGetSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_id: mediaIdSchema,
+})
+    .catchall(z.unknown());
+export const mediaTextNoteUpdateSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_id: mediaIdSchema,
+    body: z.string().optional(),
+    name: z.string().min(1).optional(),
+    display_mode: displayModeEnum.optional(),
+    thumbnail_url: z.string().url().optional(),
+})
+    .catchall(z.unknown());
+export const mediaTextNoteDeleteSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    media_id: mediaIdSchema,
+    dry_run: z.boolean().optional(),
+    confirm: z.boolean().optional(),
+})
+    .catchall(z.unknown());
+export const profileUpdateSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    display_name: z.string().optional(),
+    bio: z.string().optional(),
+})
+    .catchall(z.unknown());
+export const aliasesFollowSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    handle: z.string().min(1),
+})
+    .catchall(z.unknown());
+export const aliasesUnfollowSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    handle: z.string().min(1),
+})
+    .catchall(z.unknown());
+export const aliasesFollowingListSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    limit: limitSchema,
+    offset: offsetSchema,
+})
+    .catchall(z.unknown());
+export const collaboratorsListSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+})
+    .catchall(z.unknown());
+export const collaboratorsInviteSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+    username: z.string().min(1),
+})
+    .catchall(z.unknown());
+export const collaboratorsRevokeSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+    username: z.string().min(1),
+})
+    .catchall(z.unknown());
+export const collaboratorsInvitesListSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    collection_id: collectionIdSchema,
+})
+    .catchall(z.unknown());
+export const collaboratorsInviteAcceptSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    invite_id: z.string().min(1),
+})
+    .catchall(z.unknown());
+export const collaboratorsInviteDeclineSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    invite_id: z.string().min(1),
+})
+    .catchall(z.unknown());
+export const operationDescribeSchema = z
+    .object({
+    args: z.record(z.unknown()).optional(),
+    name: z.string().min(1).describe("Operation name from operations_list, e.g. collections.list."),
 })
     .catchall(z.unknown());
 export const TYPED_TOOL_SCHEMAS = {
-    collections_create: collectionsCreateSchema,
-    collections_update: collectionsUpdateSchema,
+    ping: emptyToolSchema,
+    schema_get: emptyToolSchema,
+    operations_list: emptyToolSchema,
+    operation_describe: operationDescribeSchema,
+    ui_state_get: emptyToolSchema,
+    ui_state_set: uiStateSetSchema,
+    collections_list: collectionsListSchema,
     collections_get: collectionsGetSchema,
     collections_get_by_slug: collectionsGetBySlugSchema,
-    media_create: mediaCreateSchema,
-    media_update: mediaUpdateSchema,
+    collections_batch_get: collectionsBatchGetSchema,
+    collections_export: collectionsExportSchema,
+    collections_create: collectionsCreateSchema,
+    collections_update: collectionsUpdateSchema,
+    collections_delete: collectionsDeleteSchema,
+    collections_restore: collectionsRestoreSchema,
+    collections_reorder: collectionsReorderSchema,
+    collections_archive: collectionsArchiveSchema,
+    collections_unarchive: collectionsUnarchiveSchema,
+    collections_like: collectionsLikeSchema,
+    collections_unlike: collectionsUnlikeSchema,
+    collections_liked_list: collectionsLikedListSchema,
+    collections_search: collectionsSearchSchema,
+    collections_browse: collectionsBrowseSchema,
+    collections_stats_get: collectionsStatsGetSchema,
+    collections_share_url: collectionsShareUrlSchema,
+    collections_publish: collectionsPublishSchema,
+    collections_unpublish: collectionsUnpublishSchema,
+    aliases_list: emptyToolSchema,
+    aliases_follow: aliasesFollowSchema,
+    aliases_unfollow: aliasesUnfollowSchema,
+    aliases_following_list: aliasesFollowingListSchema,
+    profile_get: emptyToolSchema,
+    profile_update: profileUpdateSchema,
+    collaborators_list: collaboratorsListSchema,
+    collaborators_invite: collaboratorsInviteSchema,
+    collaborators_revoke: collaboratorsRevokeSchema,
+    collaborators_invites_list: collaboratorsInvitesListSchema,
+    collaborators_invites_received: emptyToolSchema,
+    collaborators_invite_accept: collaboratorsInviteAcceptSchema,
+    collaborators_invite_decline: collaboratorsInviteDeclineSchema,
     media_list: mediaListSchema,
     media_get: mediaGetSchema,
     media_search: mediaSearchSchema,
-    ui_state_set: uiStateSetSchema,
+    media_batch_list: mediaBatchListSchema,
+    media_download: mediaDownloadSchema,
+    media_create: mediaCreateSchema,
+    media_update: mediaUpdateSchema,
     media_describe: mediaDescribeSchema,
+    media_replace: mediaReplaceSchema,
+    media_delete: mediaDeleteSchema,
+    media_restore: mediaRestoreSchema,
+    media_move: mediaMoveSchema,
+    media_copy: mediaCopySchema,
+    media_reorder: mediaReorderSchema,
+    media_archive: mediaArchiveSchema,
+    media_unarchive: mediaUnarchiveSchema,
+    media_text_note_add: mediaTextNoteAddSchema,
+    media_text_note_get: mediaTextNoteGetSchema,
+    media_text_note_update: mediaTextNoteUpdateSchema,
+    media_text_note_delete: mediaTextNoteDeleteSchema,
 };

package/package.json

@@ -1,37 +1,37 @@
-{
-  "name": "@zegazone_mcp/mcp",
-  "version": "2.0.3",
-  "type": "module",
-  "description": "MCP server wrapper for Zegazone thirdparty-v1 API",
-  "publishConfig": {
-    "access": "public"
-  },
-  "bin": {
-    "zegazone-mcp": "dist/index.js"
-  },
-  "files": [
-    "dist/",
-    "README.md",
-    "scripts/oauth-pair.mjs"
-  ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json && node scripts/add-shebang.mjs",
-    "start": "node dist/index.js",
-    "dev": "tsx src/index.ts",
-    "oauth-pair": "node scripts/oauth-pair.mjs",
-    "smoke": "node tests/smoke.mjs",
-    "smoke:full": "node tests/smoke-thirdparty-v1.mjs",
-    "test:error-format": "npm run build && node tests/error-format.mjs",
-    "test:token-provider": "npm run build && node tests/token-provider-file-priority.mjs",
-    "test": "npm run build && node tests/error-format.mjs && node tests/token-provider-file-priority.mjs"
-  },
-  "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.12.0",
-    "zod": "^3.24.1"
-  },
-  "devDependencies": {
-    "@types/node": "^22.10.2",
-    "tsx": "^4.19.2",
-    "typescript": "^5.8.3"
-  }
-}
+{
+  "name": "@zegazone_mcp/mcp",
+  "version": "2.0.4",
+  "type": "module",
+  "description": "MCP server wrapper for Zegazone thirdparty-v1 API",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "zegazone-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "scripts/oauth-pair.mjs"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/add-shebang.mjs",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "oauth-pair": "node scripts/oauth-pair.mjs",
+    "smoke": "node tests/smoke.mjs",
+    "smoke:full": "node tests/smoke-thirdparty-v1.mjs",
+    "test:error-format": "npm run build && node tests/error-format.mjs",
+    "test:token-provider": "npm run build && node tests/token-provider-file-priority.mjs",
+    "test": "npm run build && node tests/error-format.mjs && node tests/token-provider-file-priority.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.8.3"
+  }
+}