@socialseal/mcp-server 0.1.0 → 0.1.2

package/dist/registry.js

@@ -23,6 +23,7 @@ export const TOOL_REGISTRY = [
         category: "export",
         description: "Generate report exports as csv, json, markdown, html, or excel_data.",
         workspaceScoped: true,
+        notes: "reportType search_results_enriched is csv-only and is fulfilled through export-data with the tracking_ranked_videos_raw template.",
     },
     {
         name: "export_tracking_data",
@@ -62,6 +63,69 @@ export const TOOL_REGISTRY = [
         description: "Manage tracking items.",
         workspaceScoped: true,
     },
+    {
+        name: "tracked-video-extract",
+        category: "video",
+        description: "Resolve tracked videos or ad hoc public URLs into analysis and asset status.",
+        workspaceScoped: true,
+        notes: "Accepts tracked identifiers or public URL items with allowUntracked=true; poll read-only status with videoUid or platformVideoId.",
+    },
+    {
+        name: "vnext-clips-read",
+        category: "asset-studio",
+        description: "List workspace clip-library items and optionally sign selected source videos.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-clips-create",
+        category: "asset-studio",
+        description: "Create signed clip upload targets and finalize uploaded clip metadata.",
+        workspaceScoped: true,
+        notes: "The create action returns signed upload URLs; upload bytes to storage before calling finalize.",
+    },
+    {
+        name: "vnext-clip-shot-mappings-read",
+        category: "asset-studio",
+        description: "Read clip-to-blueprint shot mappings for Asset Studio.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-clip-shot-mappings-write",
+        category: "asset-studio",
+        description: "Upsert or delete clip-to-blueprint shot mappings for Asset Studio.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-generated-assets-read",
+        category: "asset-studio",
+        description: "List generated rough cuts for a blueprint or read one generated asset.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-generated-asset-create",
+        category: "asset-studio",
+        description: "Create a generated rough-cut asset from an edit spec.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-generated-asset-optimize",
+        category: "asset-studio",
+        description: "Optimize a generated asset or create a new revision.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-generated-asset-export",
+        category: "asset-studio",
+        description: "Export a generated rough cut as FCPXML.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-generated-asset-share",
+        category: "asset-studio",
+        description: "Create, read, or revoke generated-asset share links.",
+        workspaceScoped: false,
+        notes: "create/revoke require workspaceId in the body; read uses shareToken and does not require workspace scope.",
+    },
     {
         name: "search-journey-run",
         category: "vnext",
@@ -75,12 +139,54 @@ export const TOOL_REGISTRY = [
         description: "Read vNext blueprint history and specific versions.",
         workspaceScoped: true,
     },
+    {
+        name: "vnext-blueprints-create",
+        category: "vnext",
+        description: "Create a vNext blueprint from grounded evidence.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-blueprints-generate",
+        category: "vnext",
+        description: "Generate a vNext blueprint from workspace opportunity data.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-blueprints-shots-read",
+        category: "video-production",
+        description: "Read shot-lift and pinned shot assets for a blueprint.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-blueprints-shots-refresh",
+        category: "video-production",
+        description: "Queue a refresh for blueprint shot assets.",
+        workspaceScoped: true,
+    },
     {
         name: "vnext-briefs-read",
         category: "vnext",
         description: "Read generated vNext briefs and version history.",
         workspaceScoped: true,
     },
+    {
+        name: "vnext-briefs-create",
+        category: "vnext",
+        description: "Create a vNext brief record.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-briefs-generate",
+        category: "vnext",
+        description: "Generate a vNext brief from a blueprint or opportunity.",
+        workspaceScoped: true,
+    },
+    {
+        name: "vnext-briefs-export",
+        category: "video-production",
+        description: "Export a generated vNext brief as markdown.",
+        workspaceScoped: true,
+    },
     {
         name: "vnext-journeys",
         category: "vnext",
@@ -193,6 +299,531 @@ export const TOOL_SCHEMA_HINTS = {
             "socialseal tools status 6809 --kind google_ai_run",
         ],
     },
+    "group-management": {
+        summary: "Manage single-platform tracking groups and memberships.",
+        operations: [
+            {
+                action: "create",
+                required: ["action=create", "name", "workspaceId (or workspace default)"],
+                optional: ["platform (defaults to tiktok)", "description", "refresh_frequency", "next_refresh_at", "brand_id"],
+                example: {
+                    action: "create",
+                    name: "YouTube competitor searches",
+                    platform: "youtube",
+                },
+            },
+            {
+                action: "add_item",
+                required: ["action=add_item", "group_id", "item_id or track_type+track_value"],
+                optional: ["name", "region", "platform", "refresh_frequency"],
+                example: {
+                    action: "add_item",
+                    group_id: 123,
+                    item_id: 456,
+                },
+            },
+            {
+                action: "add_items",
+                required: ["action=add_items", "group_id", "item_ids or items"],
+                optional: ["platform for item payload defaults"],
+                example: {
+                    action: "add_items",
+                    group_id: 123,
+                    items: [
+                        {
+                            name: "best kenya safari",
+                            type: "keyword",
+                            value: "best kenya safari",
+                            region: "US",
+                        },
+                    ],
+                },
+            },
+            {
+                action: "list | get | update | delete | refresh | list_items | remove_item | completeness",
+                required: ["action", "group_id (except list)"],
+                optional: ["item_id (remove_item)", "expected_items (completeness)", "page", "limit"],
+                example: {
+                    action: "refresh",
+                    group_id: 123,
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function group-management --workspace-id <workspace-uuid> --body '{\"action\":\"create\",\"name\":\"YouTube group\",\"platform\":\"youtube\"}'",
+            "socialseal tools call --function group-management --workspace-id <workspace-uuid> --body '{\"action\":\"add_items\",\"group_id\":123,\"items\":[{\"name\":\"best kenya safari\",\"type\":\"keyword\",\"value\":\"best kenya safari\",\"region\":\"US\"}]}'",
+        ],
+    },
+    tracking: {
+        summary: "Manage tracking items (keywords, hashtags, creators).",
+        operations: [
+            {
+                action: "create",
+                required: ["action=create", "track_type (keyword/search, hashtag, account/creator)", "track_value"],
+                optional: ["name", "region", "platform", "refresh_frequency", "next_refresh_at", "brand_ids"],
+                example: {
+                    action: "create",
+                    track_type: "search",
+                    track_value: "best kenya safari",
+                    region: "US",
+                    platform: "tiktok",
+                },
+            },
+            {
+                action: "refresh",
+                required: ["action=refresh", "item_id (numeric)"],
+                optional: [],
+                example: {
+                    action: "refresh",
+                    item_id: 35854,
+                },
+            },
+            {
+                action: "list | get | resolve | update | delete",
+                required: ["action", "item_id (get/update/delete)", "track_type+track_value (resolve)"],
+                optional: ["limit", "page", "offset", "include_inactive", "platform", "region"],
+                example: {
+                    action: "list",
+                    limit: 20,
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function tracking --workspace-id <workspace-uuid> --body '{\"action\":\"create\",\"track_type\":\"search\",\"track_value\":\"best kenya safari\",\"region\":\"US\"}'",
+            "socialseal tools call --function tracking --workspace-id <workspace-uuid> --body '{\"action\":\"refresh\",\"item_id\":35854}'",
+        ],
+    },
+    "tracked-video-extract": {
+        summary: "Extract assets and queue/read analysis for tracked identifiers or ad hoc public video URLs.",
+        operations: [
+            {
+                action: "extract-tracked",
+                required: ["workspaceId (or workspace default)", "items[] with exactly one tracked selector"],
+                optional: [
+                    "items[].searchResultId",
+                    "items[].videoId",
+                    "items[].videoUid",
+                    "items[].platformVideoId",
+                    "items[].platformId",
+                    "ensureAnalysis",
+                    "includeAssets",
+                    "includeRawAnalysis",
+                    "includeSourceVideo",
+                    "frameStrategy",
+                    "frameCount",
+                    "signedUrlSeconds",
+                ],
+                example: {
+                    items: [
+                        {
+                            videoUid: "11111111-1111-4111-8111-111111111111",
+                        },
+                    ],
+                    ensureAnalysis: true,
+                    includeAssets: true,
+                },
+            },
+            {
+                action: "extract-url",
+                required: ["workspaceId (or workspace default)", "allowUntracked=true", "items[].url"],
+                optional: [
+                    "ensureAnalysis",
+                    "includeAssets",
+                    "includeRawAnalysis",
+                    "includeSourceVideo",
+                    "frameStrategy",
+                    "frameCount",
+                    "signedUrlSeconds",
+                ],
+                example: {
+                    allowUntracked: true,
+                    ensureAnalysis: true,
+                    items: [
+                        {
+                            url: "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
+                        },
+                    ],
+                },
+            },
+            {
+                action: "queue-analysis",
+                required: ["workspaceId (or workspace default)", "items[] with exactly one selector"],
+                optional: ["allowUntracked for URL items", "queueOnly", "includeRawAnalysis"],
+                example: {
+                    allowUntracked: true,
+                    ensureAnalysis: true,
+                    queueOnly: true,
+                    includeAssets: false,
+                    includeRawAnalysis: false,
+                    includeSourceVideo: false,
+                    items: [
+                        {
+                            url: "https://www.instagram.com/reel/SHORTCODE/",
+                        },
+                    ],
+                },
+            },
+            {
+                action: "status",
+                required: [
+                    "socialseal_get_tool_status kind=video_analysis with videoUid UUID or platformVideoId",
+                ],
+                optional: ["includeResults"],
+                example: {
+                    id: "11111111-1111-4111-8111-111111111111",
+                    kind: "video_analysis",
+                    includeResults: true,
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal video extract --url https://www.youtube.com/watch?v=dQw4w9WgXcQ --allow-untracked --wait --out-dir ./video-assets --workspace-id <workspace-uuid>",
+            "socialseal video queue-analysis --url https://www.tiktok.com/@creator/video/7348293840000000000 --allow-untracked --wait --workspace-id <workspace-uuid>",
+            "socialseal video extract --video-uid <video-uuid> --wait --workspace-id <workspace-uuid>",
+            "socialseal tools call --function tracked-video-extract --workspace-id <workspace-uuid> --body '{\"allowUntracked\":true,\"items\":[{\"url\":\"https://www.instagram.com/reel/SHORTCODE/\"}]}'",
+        ],
+    },
+    "vnext-clips-read": {
+        summary: "List Asset Studio clip-library items and optionally sign selected video URLs.",
+        operations: [
+            {
+                action: "list",
+                required: ["workspaceId (or workspace default)"],
+                optional: ["videoClipIds[]"],
+                example: {
+                    videoClipIds: ["11111111-1111-4111-8111-111111111111"],
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-clips-read --workspace-id <workspace-uuid> --body '{\"videoClipIds\":[\"<clip-uuid>\"]}'",
+        ],
+    },
+    "vnext-clips-create": {
+        summary: "Create signed upload targets for clips and finalize uploaded clip metadata.",
+        operations: [
+            {
+                action: "create",
+                required: ["action=create", "workspaceId (or workspace default)", "fileName", "mimeType"],
+                optional: [],
+                example: {
+                    action: "create",
+                    fileName: "hero-shot.mp4",
+                    mimeType: "video/mp4",
+                },
+            },
+            {
+                action: "finalize",
+                required: [
+                    "action=finalize",
+                    "workspaceId (or workspace default)",
+                    "clipId",
+                    "fileName",
+                    "storagePath",
+                    "mimeType",
+                    "sizeBytes",
+                    "rightsAttested=true",
+                ],
+                optional: ["durationSeconds", "width", "height", "posterPath"],
+                example: {
+                    action: "finalize",
+                    clipId: "11111111-1111-4111-8111-111111111111",
+                    fileName: "hero-shot.mp4",
+                    storagePath: "workspace-00000000-0000-4000-8000-000000000000/11111111-1111-4111-8111-111111111111.mp4",
+                    mimeType: "video/mp4",
+                    sizeBytes: 1048576,
+                    rightsAttested: true,
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-clips-create --workspace-id <workspace-uuid> --body '{\"action\":\"create\",\"fileName\":\"hero-shot.mp4\",\"mimeType\":\"video/mp4\"}'",
+            "socialseal tools call --function vnext-clips-create --workspace-id <workspace-uuid> --body @clip-finalize.json",
+        ],
+    },
+    "vnext-clip-shot-mappings-read": {
+        summary: "Read Asset Studio clip-to-shot mappings for a blueprint.",
+        operations: [
+            {
+                action: "read",
+                required: ["workspaceId (or workspace default)", "blueprintId"],
+                optional: [],
+                example: {
+                    blueprintId: "22222222-2222-4222-8222-222222222222",
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-clip-shot-mappings-read --workspace-id <workspace-uuid> --body '{\"blueprintId\":\"<blueprint-uuid>\"}'",
+        ],
+    },
+    "vnext-clip-shot-mappings-write": {
+        summary: "Upsert or delete Asset Studio clip-to-shot mappings.",
+        operations: [
+            {
+                action: "upsert",
+                required: ["action=upsert", "workspaceId (or workspace default)", "blueprintId", "panelId", "clipId"],
+                optional: ["source", "score"],
+                example: {
+                    action: "upsert",
+                    blueprintId: "22222222-2222-4222-8222-222222222222",
+                    panelId: "panel-1",
+                    clipId: "11111111-1111-4111-8111-111111111111",
+                    source: "override",
+                },
+            },
+            {
+                action: "delete",
+                required: ["action=delete", "workspaceId (or workspace default)", "blueprintId", "panelId"],
+                optional: [],
+                example: {
+                    action: "delete",
+                    blueprintId: "22222222-2222-4222-8222-222222222222",
+                    panelId: "panel-1",
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-clip-shot-mappings-write --workspace-id <workspace-uuid> --body '{\"action\":\"upsert\",\"blueprintId\":\"<blueprint-uuid>\",\"panelId\":\"panel-1\",\"clipId\":\"<clip-uuid>\"}'",
+        ],
+    },
+    "vnext-generated-assets-read": {
+        summary: "List generated rough cuts for a blueprint or read one generated asset.",
+        operations: [
+            {
+                action: "list",
+                required: ["action=list", "workspaceId (or workspace default)", "blueprintId"],
+                optional: [],
+                example: {
+                    action: "list",
+                    blueprintId: "22222222-2222-4222-8222-222222222222",
+                },
+            },
+            {
+                action: "detail",
+                required: ["action=detail", "workspaceId (or workspace default)", "assetId"],
+                optional: [],
+                example: {
+                    action: "detail",
+                    assetId: "33333333-3333-4333-8333-333333333333",
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-generated-assets-read --workspace-id <workspace-uuid> --body '{\"action\":\"list\",\"blueprintId\":\"<blueprint-uuid>\"}'",
+            "socialseal tools call --function vnext-generated-assets-read --workspace-id <workspace-uuid> --body '{\"action\":\"detail\",\"assetId\":\"<asset-uuid>\"}'",
+        ],
+    },
+    "vnext-generated-asset-create": {
+        summary: "Create a generated rough cut from an Asset Studio edit spec.",
+        operations: [
+            {
+                action: "create",
+                required: ["workspaceId (or workspace default)", "blueprintId", "title", "editSpec"],
+                optional: [],
+                example: {
+                    blueprintId: "22222222-2222-4222-8222-222222222222",
+                    title: "Homepage rough cut",
+                    editSpec: {
+                        version: 1,
+                        fps: 30,
+                        width: 1080,
+                        height: 1920,
+                        totalDurationSeconds: 3,
+                        shots: [
+                            {
+                                panelId: "panel-1",
+                                clipId: "11111111-1111-4111-8111-111111111111",
+                                title: "Opening hook",
+                                kind: "hook",
+                                shotLabel: "Hero exterior",
+                                sourceStartSeconds: 0,
+                                durationSeconds: 3,
+                                evidenceIds: [],
+                            },
+                        ],
+                    },
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-generated-asset-create --workspace-id <workspace-uuid> --body @edit-spec.json",
+        ],
+    },
+    "vnext-generated-asset-optimize": {
+        summary: "Optimize a generated asset or create a new revision.",
+        operations: [
+            {
+                action: "optimize",
+                required: ["action=optimize", "workspaceId (or workspace default)", "assetId"],
+                optional: [],
+                example: {
+                    action: "optimize",
+                    assetId: "33333333-3333-4333-8333-333333333333",
+                },
+            },
+            {
+                action: "create-revision",
+                required: ["action=create-revision", "workspaceId (or workspace default)", "assetId"],
+                optional: [],
+                example: {
+                    action: "create-revision",
+                    assetId: "33333333-3333-4333-8333-333333333333",
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-generated-asset-optimize --workspace-id <workspace-uuid> --body '{\"action\":\"optimize\",\"assetId\":\"<asset-uuid>\"}'",
+        ],
+    },
+    "vnext-generated-asset-export": {
+        summary: "Export a generated rough cut as FCPXML.",
+        operations: [
+            {
+                action: "export",
+                required: ["workspaceId (or workspace default)", "assetId"],
+                optional: ["format=fcpxml"],
+                example: {
+                    assetId: "33333333-3333-4333-8333-333333333333",
+                    format: "fcpxml",
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-generated-asset-export --workspace-id <workspace-uuid> --body '{\"assetId\":\"<asset-uuid>\",\"format\":\"fcpxml\"}'",
+        ],
+    },
+    "vnext-generated-asset-share": {
+        summary: "Create, read, or revoke generated rough-cut share links.",
+        operations: [
+            {
+                action: "create",
+                required: ["action=create", "workspaceId", "assetId"],
+                optional: ["ttlSeconds", "shareBaseUrl"],
+                example: {
+                    action: "create",
+                    workspaceId: "00000000-0000-4000-8000-000000000000",
+                    assetId: "33333333-3333-4333-8333-333333333333",
+                    ttlSeconds: 604800,
+                },
+            },
+            {
+                action: "read",
+                required: ["action=read", "shareToken"],
+                optional: [],
+                example: {
+                    action: "read",
+                    shareToken: "0123456789abcdef0123456789abcdef",
+                },
+            },
+            {
+                action: "revoke",
+                required: ["action=revoke", "workspaceId", "shareLinkId"],
+                optional: [],
+                example: {
+                    action: "revoke",
+                    workspaceId: "00000000-0000-4000-8000-000000000000",
+                    shareLinkId: "44444444-4444-4444-8444-444444444444",
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-generated-asset-share --body '{\"action\":\"create\",\"workspaceId\":\"<workspace-uuid>\",\"assetId\":\"<asset-uuid>\"}'",
+            "socialseal tools call --function vnext-generated-asset-share --body '{\"action\":\"read\",\"shareToken\":\"<share-token>\"}'",
+        ],
+    },
+    "vnext-blueprints-shots-read": {
+        summary: "Read blueprint shot-lift rows and pinned shot assets with signed URLs.",
+        operations: [
+            {
+                action: "read",
+                required: ["workspaceId (or workspace default)", "blueprintId"],
+                optional: ["signedUrlSeconds"],
+                example: {
+                    blueprintId: "22222222-2222-4222-8222-222222222222",
+                    signedUrlSeconds: 3600,
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-blueprints-shots-read --workspace-id <workspace-uuid> --body '{\"blueprintId\":\"<blueprint-uuid>\"}'",
+        ],
+    },
+    "vnext-blueprints-shots-refresh": {
+        summary: "Queue a refresh for blueprint shot assets.",
+        operations: [
+            {
+                action: "refresh",
+                required: ["workspaceId (or workspace default)", "blueprintId"],
+                optional: [],
+                example: {
+                    blueprintId: "22222222-2222-4222-8222-222222222222",
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-blueprints-shots-refresh --workspace-id <workspace-uuid> --body '{\"blueprintId\":\"<blueprint-uuid>\"}'",
+        ],
+    },
+    "vnext-briefs-export": {
+        summary: "Export the latest or selected generated vNext brief as markdown.",
+        operations: [
+            {
+                action: "export",
+                required: ["workspaceId (or workspace default)", "opportunityKey"],
+                optional: ["version"],
+                example: {
+                    opportunityKey: "opportunity-key",
+                    version: 1,
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal tools call --function vnext-briefs-export --workspace-id <workspace-uuid> --body '{\"opportunityKey\":\"<opportunity-key>\"}'",
+        ],
+    },
+    export_tracking_data: {
+        summary: "Stream tracking exports as CSV for a tracking group or single tracking item.",
+        operations: [
+            {
+                action: "export",
+                required: ["group_id (numeric tracking_group id) or tracking_item_id"],
+                optional: ["time_period", "workspace_id (defaults to resolved workspace)"],
+                example: {
+                    group_id: 436,
+                    time_period: "30d",
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal data export-tracking --group-id 436 --workspace-id <workspace-uuid>",
+            "socialseal tools call --function export_tracking_data --workspace-id <workspace-uuid> --body '{\"group_id\":436}'",
+        ],
+    },
+    "export-report": {
+        summary: "Generate report exports; search_results_enriched is fulfilled through export-data.",
+        operations: [
+            {
+                action: "export",
+                required: [
+                    "reportType (keyword_universe | cluster_insights | creator_signatures | post_publish | quick_audit | search_results_enriched)",
+                    "payload (shape depends on reportType)",
+                ],
+                optional: ["format (csv | json | markdown | html | excel_data; search_results_enriched is csv-only)"],
+                example: {
+                    reportType: "search_results_enriched",
+                    format: "csv",
+                    payload: {
+                        groupIds: [436],
+                    },
+                },
+            },
+        ],
+        cliExamples: [
+            "socialseal data export-report --report-type search_results_enriched --format csv --payload '{\"groupIds\":[436]}' --workspace-id <workspace-uuid>",
+            "socialseal data export-search-results --group-ids 436 --workspace-id <workspace-uuid>",
+        ],
+    },
 };
 const TOOL_BY_NAME = new Map(TOOL_REGISTRY.map((entry) => [entry.name, entry]));
 export function getToolEntry(toolName) {