@socialneuron/mcp-server 1.4.1 → 1.5.0

package/CHANGELOG.md

@@ -2,6 +2,23 @@
 
 All notable changes to `@socialneuron/mcp-server` will be documented in this file.
 
+## [1.5.0] - 2026-03-19
+
+### Changed
+- **LLM-optimized tool descriptions**: Rewrote 27 tool descriptions and enriched 15 parameters for agent comprehension. Every tool now answers "when to call", "what to pass", and "what comes next" — following Arcade ToolBench patterns (Tool Description, Constrained Input, Dependency Hint, Performance Hint).
+- **API key cache TTL**: Reduced from 60s to 10s to limit revocation exposure window.
+- **OAuth issuer URL**: Production metadata now derives from `MCP_SERVER_URL` instead of defaulting to localhost.
+- **SECURITY.md**: Updated supported versions, added scanner false-positive documentation.
+- **CLI setup URL**: Fixed `app.socialneuron.com` → `www.socialneuron.com`.
+
+### Dependencies
+- `@supabase/supabase-js` 2.98.0 → 2.99.2
+- `open` 10.0.0 → 11.0.0 (requires Node.js 20+)
+- `posthog-node` 5.28.1 → 5.28.3
+- `vitest` 3.2.4 → 4.1.0
+- `esbuild` 0.27.3 → 0.27.4
+- `@types/node` 25.4.0 → 25.5.0
+
 ## [1.4.0] - 2026-03-13
 
 ### Changed

package/dist/http.js

@@ -393,7 +393,9 @@ async function getDefaultUserId() {
   if (authenticatedUserId) return authenticatedUserId;
   const envUserId = process.env.SOCIALNEURON_USER_ID;
   if (envUserId) return envUserId;
-  throw new Error("No user ID available. Set SOCIALNEURON_USER_ID or authenticate via API key.");
+  throw new Error(
+    "No user ID available. Set SOCIALNEURON_USER_ID or authenticate via API key."
+  );
 }
 async function getDefaultProjectId() {
   const userId = await getDefaultUserId().catch(() => null);
@@ -437,7 +439,9 @@ async function initializeAuth() {
       console.error("[MCP] Scopes: " + authenticatedScopes.join(", "));
       if (authenticatedExpiresAt) {
         const expiresMs = new Date(authenticatedExpiresAt).getTime();
-        const daysLeft = Math.ceil((expiresMs - Date.now()) / (1e3 * 60 * 60 * 24));
+        const daysLeft = Math.ceil(
+          (expiresMs - Date.now()) / (1e3 * 60 * 60 * 24)
+        );
         console.error("[MCP] Key expires: " + authenticatedExpiresAt);
         if (daysLeft <= 7) {
           console.error(
@@ -460,8 +464,12 @@ async function initializeAuth() {
     console.error(
       "[MCP] \u26A0 DEPRECATED: Service role keys grant full admin access to your database."
     );
-    console.error("[MCP]   Migrate to API key auth: npx @socialneuron/mcp-server setup");
-    console.error("[MCP]   Then remove SOCIALNEURON_SERVICE_KEY from your environment.");
+    console.error(
+      "[MCP]   Migrate to API key auth: npx @socialneuron/mcp-server setup"
+    );
+    console.error(
+      "[MCP]   Then remove SOCIALNEURON_SERVICE_KEY from your environment."
+    );
     if (!process.env.SOCIALNEURON_USER_ID) {
       console.error(
         "[MCP] Warning: SOCIALNEURON_USER_ID not set. Tools requiring a user will fail."
@@ -848,10 +856,10 @@ init_supabase();
 function registerIdeationTools(server) {
   server.tool(
     "generate_content",
-    "Generate AI-powered content (scripts, captions, hooks, blog posts) using Google Gemini or Anthropic Claude. Provide a detailed prompt describing what you need, choose the content type, and optionally specify a target platform and brand voice guidelines.",
+    "Create a script, caption, hook, or blog post tailored to a specific platform. Pass project_id to auto-load brand profile and performance context, or call get_ideation_context first for full context. Output is draft text ready for quality_check then schedule_post.",
     {
       prompt: z.string().max(1e4).describe(
-        "Detailed prompt describing the content to generate. Include context like topic, angle, audience, and any specific requirements."
+        'Detailed content prompt. Include topic, angle, audience, and requirements. Example: "LinkedIn post about AI productivity for CTOs, 300 words, include 3 actionable tips, conversational tone." Richer prompts produce better results.'
       ),
       content_type: z.enum(["script", "caption", "blog", "hook"]).describe(
         'Type of content to generate. "script" for video scripts, "caption" for social media captions, "blog" for blog posts, "hook" for attention-grabbing hooks.'
@@ -869,7 +877,7 @@ function registerIdeationTools(server) {
         "Target social media platform. Helps tailor tone, length, and format."
       ),
       brand_voice: z.string().max(500).optional().describe(
-        'Brand voice guidelines to follow (e.g. "professional and empathetic", "playful and Gen-Z"). Leave blank to use a neutral tone.'
+        'Tone directive (e.g. "direct, no jargon, second person" or "witty Gen-Z energy with emoji"). Leave blank to auto-load from project brand profile if project_id is set.'
       ),
       model: z.enum(["gemini-2.0-flash", "gemini-2.5-flash", "gemini-2.5-pro"]).optional().describe(
         "AI model to use. Defaults to gemini-2.5-flash. Use gemini-2.5-pro for highest quality."
@@ -1025,7 +1033,7 @@ Content Type: ${content_type}`;
   );
   server.tool(
     "fetch_trends",
-    "Fetch current trending topics from YouTube, Google Trends, RSS feeds, or a custom URL. Results are cached for efficiency. Use this to discover what is popular right now for content ideation.",
+    'Get current trending topics for content inspiration. Source "youtube" returns trending videos with view counts, "google_trends" returns rising search terms, "rss"/"url" extracts topics from any feed or page. Results cached 1 hour \u2014 set force_refresh=true for real-time. Feed results into generate_content or plan_content_week.',
     {
       source: z.enum(["youtube", "google_trends", "rss", "url"]).describe(
         'Data source. "youtube" fetches trending videos, "google_trends" fetches daily search trends, "rss" fetches from a custom RSS feed URL, "url" extracts trend data from a web page.'
@@ -1111,7 +1119,7 @@ Content Type: ${content_type}`;
   );
   server.tool(
     "adapt_content",
-    "Adapt existing content for a different social media platform. Rewrites content to match the target platform's norms including character limits, hashtag style, tone, and CTA conventions.",
+    "Rewrite existing content for a different platform \u2014 adjusts character limits, hashtag style, tone, and CTA format automatically. Use after generate_content when you need the same message across multiple platforms. Pass project_id to apply platform-specific voice overrides from your brand profile.",
     {
       content: z.string().max(5e3).describe(
         "The content to adapt. Can be a caption, script, blog excerpt, or any text."
@@ -1304,7 +1312,7 @@ function sanitizeDbError(error) {
 init_request_context();
 
 // src/lib/version.ts
-var MCP_VERSION = "1.4.1";
+var MCP_VERSION = "1.5.0";
 
 // src/tools/content.ts
 var MAX_CREDITS_PER_RUN = Math.max(
@@ -1412,10 +1420,10 @@ function checkAssetBudget() {
 function registerContentTools(server) {
   server.tool(
     "generate_video",
-    "Start an AI video generation job. This is an async operation -- it returns a job_id immediately. Use check_status to poll for completion. Supports Veo 3, Runway, Sora 2, Kling 2.6, and Kling 3.0 models via the Kie.ai API.",
+    "Start an async AI video generation job \u2014 returns a job_id immediately. Poll with check_status every 10-30s until complete. Cost varies by model: veo3-fast (~15 credits/5s), kling-3 (~30 credits/5s), sora2-pro (~60 credits/10s). Check get_credit_balance first for expensive generations.",
     {
       prompt: z2.string().max(2500).describe(
-        "Text prompt describing the video to generate. Be specific about visual style, camera angles, movement, lighting, and mood."
+        'Video prompt \u2014 be specific about visual style, camera movement, lighting, and mood. Example: "Aerial drone shot of coastal cliffs at golden hour, slow dolly forward, cinematic 24fps, warm color grading." Vague prompts produce generic results.'
       ),
       model: z2.enum([
         "veo3-fast",
@@ -1427,13 +1435,13 @@ function registerContentTools(server) {
         "kling-3",
         "kling-3-pro"
       ]).describe(
-        "Video generation model. veo3-fast is fastest (~60s), veo3-quality is highest quality (~120s). sora2-pro is OpenAI Sora premium tier. kling-3 is Kling 3.0 standard (4K, 15s, audio). kling-3-pro is Kling 3.0 pro (higher quality)."
+        "Video model. veo3-fast: fastest (~15 credits/5s, ~60s render). veo3-quality: highest quality (~20 credits/5s, ~120s). sora2-pro: OpenAI premium (~60 credits/10s). kling-3: 4K with audio (~30 credits/5s). kling-3-pro: best Kling quality (~40 credits/5s)."
       ),
       duration: z2.number().min(3).max(30).optional().describe(
         "Video duration in seconds. kling: 5-30s, kling-3/kling-3-pro: 3-15s, sora2: 10-15s. Defaults to 5 seconds."
       ),
       aspect_ratio: z2.enum(["16:9", "9:16", "1:1"]).optional().describe(
-        "Aspect ratio. 16:9 for landscape/YouTube, 9:16 for vertical/Reels/TikTok, 1:1 for square. Defaults to 16:9."
+        "Video aspect ratio. 16:9 for YouTube/landscape, 9:16 for TikTok/Reels/Shorts, 1:1 for Instagram feed/square. Defaults to 16:9."
       ),
       enable_audio: z2.boolean().optional().describe(
         "Enable native audio generation. Kling 2.6: doubles cost. Kling 3.0: 50% more (std 30/sec, pro 40/sec). 5+ languages."
@@ -1620,7 +1628,7 @@ function registerContentTools(server) {
   );
   server.tool(
     "generate_image",
-    "Start an AI image generation job. This is an async operation -- it returns a job_id immediately. Use check_status to poll for completion. Supports Midjourney, Imagen 4, Flux, GPT-4o Image, and Seedream models.",
+    "Start an async AI image generation job \u2014 returns a job_id immediately. Poll with check_status every 5-15s until complete. Costs 2-10 credits depending on model. Use for social media posts, carousel slides, or as input to generate_video (image-to-video).",
     {
       prompt: z2.string().max(2e3).describe(
         "Text prompt describing the image to generate. Be specific about style, composition, colors, lighting, and subject matter."
@@ -1800,7 +1808,7 @@ function registerContentTools(server) {
   );
   server.tool(
     "check_status",
-    "Check the status of an async generation job (video or image). Returns the current status, progress percentage, and result URL when complete. Call this tool periodically after generate_video or generate_image.",
+    'Poll an async job started by generate_video or generate_image. Returns status (queued/processing/completed/failed), progress %, and result URL on completion. Poll every 10-30s for video, 5-15s for images. On "failed" status, the error field explains why \u2014 check credits or try a different model.',
     {
       job_id: z2.string().describe(
         "The job ID returned by generate_video or generate_image. This is the asyncJobId or taskId value."
@@ -1976,7 +1984,7 @@ function registerContentTools(server) {
   );
   server.tool(
     "create_storyboard",
-    "Generate a structured scene-by-scene storyboard for video production. Returns an array of StoryboardFrames with prompts, durations, captions, and voiceover text. Use the output to drive image/video generation.",
+    "Plan a multi-scene video storyboard with AI-generated prompts, durations, captions, and voiceover text per frame. Use before generate_video or generate_image to create cohesive multi-shot content. Include brand_context from get_brand_profile for consistent visual branding across frames.",
     {
       concept: z2.string().max(2e3).describe(
         'The video concept/idea. Include: hook, key messages, target audience, and desired outcome (e.g., "TikTok ad for VPN app targeting privacy-conscious millennials, hook with shocking stat about data leaks").'
@@ -2163,7 +2171,7 @@ Return ONLY valid JSON in this exact format:
   );
   server.tool(
     "generate_voiceover",
-    "Generate a professional voiceover audio file using ElevenLabs TTS. Returns an audio URL stored in R2. Use this for narration in video production.",
+    "Generate a voiceover audio file for video narration. Returns an R2-hosted audio URL. Use after create_storyboard to add narration to each scene, or standalone for podcast intros and ad reads. Costs ~2 credits per generation.",
     {
       text: z2.string().max(5e3).describe("The script/text to convert to speech."),
       voice: z2.enum([
@@ -2314,10 +2322,10 @@ Return ONLY valid JSON in this exact format:
   );
   server.tool(
     "generate_carousel",
-    "Generate an Instagram carousel with AI-powered slide content. Supports multiple templates including Hormozi-style authority carousels. Returns slide data (headlines, body text, emphasis words). Use schedule_post with media_urls to publish the carousel to Instagram.",
+    "Generate carousel slide content (headlines, body text, emphasis words per slide). Supports Hormozi-style authority format and educational templates. Returns structured slide data \u2014 render visually then publish via schedule_post with media_type=CAROUSEL_ALBUM and 2-10 media_urls on Instagram.",
     {
       topic: z2.string().max(200).describe(
-        'The carousel topic/subject. Be specific about the angle or hook. Example: "5 reasons your startup will fail in 2026"'
+        'Carousel hook/angle \u2014 specific beats general. Example: "5 pricing mistakes that kill SaaS startups" beats "SaaS tips". Include a curiosity gap or strong opinion for better Hook Strength scores.'
       ),
       template_id: z2.enum([
         "educational-series",
@@ -2645,14 +2653,12 @@ function asEnvelope2(data) {
 function registerDistributionTools(server) {
   server.tool(
     "schedule_post",
-    "Schedule or immediately publish a post to one or more social media platforms. Requires the target platforms to have active OAuth connections configured in Social Neuron Settings. Supports YouTube, TikTok, Instagram, Facebook, LinkedIn, Twitter, Threads, and Bluesky. For Instagram carousels, provide media_urls (2-10 image URLs) and set media_type to CAROUSEL_ALBUM.",
+    'Publish or schedule a post to connected social platforms. Check list_connected_accounts first to verify active OAuth for each target platform. For Instagram carousels: use media_type=CAROUSEL_ALBUM with 2-10 media_urls. For YouTube: title is required. schedule_at uses ISO 8601 (e.g. "2026-03-20T14:00:00Z") \u2014 omit to post immediately.',
     {
       media_url: z3.string().optional().describe(
         "Optional URL of the media file (video or image) to post. This should be a publicly accessible URL or a Cloudflare R2 signed URL from a previous generation. Required for platforms that enforce media uploads. Not needed if media_urls is provided."
       ),
-      media_urls: z3.array(z3.string()).optional().describe(
-        "Array of image URLs for Instagram carousel posts (2-10 images). Each URL should be publicly accessible or a Cloudflare R2 URL. When provided with media_type=CAROUSEL_ALBUM, creates an Instagram carousel."
-      ),
+      media_urls: z3.array(z3.string()).optional().describe("Array of 2-10 image URLs for Instagram carousel posts. Each URL must be publicly accessible or a Cloudflare R2 signed URL. Use with media_type=CAROUSEL_ALBUM."),
       media_type: z3.enum(["IMAGE", "VIDEO", "CAROUSEL_ALBUM"]).optional().describe(
         "Media type. Set to CAROUSEL_ALBUM with media_urls for Instagram carousels. Default: auto-detected from media_url."
       ),
@@ -2668,16 +2674,10 @@ function registerDistributionTools(server) {
           "threads",
           "bluesky"
         ])
-      ).min(1).describe(
-        "Target platforms to post to. Each must have an active OAuth connection."
-      ),
+      ).min(1).describe("Target platforms (array). Each must have active OAuth \u2014 check list_connected_accounts first. Values: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky."),
       title: z3.string().optional().describe("Post title (used by YouTube and some other platforms)."),
-      hashtags: z3.array(z3.string()).optional().describe(
-        'Hashtags to append to the caption. Include or omit the "#" prefix.'
-      ),
-      schedule_at: z3.string().optional().describe(
-        'ISO 8601 datetime for scheduled posting (e.g. "2026-03-15T14:00:00Z"). Omit for immediate posting.'
-      ),
+      hashtags: z3.array(z3.string()).optional().describe('Hashtags to append to caption. Include or omit the "#" prefix \u2014 both work. Example: ["ai", "contentcreator"] or ["#ai", "#contentcreator"].'),
+      schedule_at: z3.string().optional().describe('ISO 8601 UTC datetime for scheduled posting (e.g. "2026-03-20T14:00:00Z"). Omit to post immediately. Must be in the future.'),
       project_id: z3.string().optional().describe("Social Neuron project ID to associate this post with."),
       response_format: z3.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text."),
       attribution: z3.boolean().optional().describe(
@@ -2831,7 +2831,7 @@ Created with Social Neuron`;
   );
   server.tool(
     "list_connected_accounts",
-    "List all social media accounts connected to Social Neuron via OAuth. Shows which platforms are available for posting.",
+    "Check which social platforms have active OAuth connections for posting. Call this before schedule_post to verify credentials. If a platform is missing or expired, the user needs to reconnect at socialneuron.com/settings/connections.",
     {
       response_format: z3.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
@@ -2896,7 +2896,7 @@ Created with Social Neuron`;
   );
   server.tool(
     "list_recent_posts",
-    "List recent posts from Social Neuron. Shows status, platform, title, and timestamps. Useful for checking what has been published or scheduled recently.",
+    "List recent published and scheduled posts with status, platform, title, and timestamps. Use to check what has been posted before planning new content, or to find post IDs for fetch_analytics. Filter by platform or status to narrow results.",
     {
       platform: z3.enum([
         "youtube",
@@ -3735,7 +3735,7 @@ function registerAnalyticsTools(server) {
         "threads",
         "bluesky"
       ]).optional().describe("Filter analytics to a specific platform."),
-      days: z4.number().min(1).max(365).optional().describe("Number of days to look back. Defaults to 30. Max 365."),
+      days: z4.number().min(1).max(365).optional().describe("Lookback window in days (1-365). Default 30. Use 7 for weekly review, 30 for monthly summary, 90 for quarterly trends."),
       content_id: z4.string().uuid().optional().describe(
         "Filter to a specific content_history ID to see performance of one piece of content."
       ),
@@ -3915,7 +3915,7 @@ function registerAnalyticsTools(server) {
   );
   server.tool(
     "refresh_platform_analytics",
-    "Trigger an analytics refresh for all recently posted content across all connected platforms. Queues analytics fetch jobs for posts from the last 7 days.",
+    "Queue analytics refresh jobs for all posts from the last 7 days across connected platforms. Call this before fetch_analytics if you need fresh data. Returns immediately \u2014 data updates asynchronously over the next 1-5 minutes.",
     {
       response_format: z4.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
@@ -5845,13 +5845,11 @@ function asEnvelope6(data) {
 function registerCommentsTools(server) {
   server.tool(
     "list_comments",
-    "List YouTube comments. Without a video_id, returns recent comments across all channel videos. With a video_id, returns comments for that specific video.",
+    'List YouTube comments \u2014 pass video_id (11-char string, e.g. "dQw4w9WgXcQ") for a specific video, or omit for recent comments across all channel videos. Returns comment text, author, like count, and reply count. Use page_token from previous response for pagination.',
     {
-      video_id: z10.string().optional().describe(
-        "YouTube video ID. If omitted, returns comments across all channel videos."
-      ),
+      video_id: z10.string().optional().describe('YouTube video ID \u2014 the 11-character string from the URL (e.g. "dQw4w9WgXcQ" from youtube.com/watch?v=dQw4w9WgXcQ). Omit to get recent comments across all channel videos.'),
       max_results: z10.number().min(1).max(100).optional().describe("Maximum number of comments to return. Defaults to 50."),
-      page_token: z10.string().optional().describe("Pagination token from a previous list_comments call."),
+      page_token: z10.string().optional().describe("Pagination cursor from previous list_comments response nextPageToken field. Omit for first page of results."),
       response_format: z10.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
     async ({ video_id, max_results, page_token, response_format }) => {
@@ -5916,7 +5914,7 @@ function registerCommentsTools(server) {
   );
   server.tool(
     "reply_to_comment",
-    "Reply to a YouTube comment. Requires the parent comment ID and reply text.",
+    "Reply to a YouTube comment. Get the parent_id from list_comments results. Reply appears as the authenticated channel. Use for community engagement after checking list_comments for questions or feedback.",
     {
       parent_id: z10.string().describe(
         "The ID of the parent comment to reply to (from list_comments)."
@@ -6447,7 +6445,7 @@ function asEnvelope8(data) {
 function registerCreditsTools(server) {
   server.tool(
     "get_credit_balance",
-    "Get current subscription credit balance and plan.",
+    "Check remaining credits, monthly limit, spending cap, and plan tier. Call this before expensive operations \u2014 generate_video costs 15-80 credits, generate_image costs 2-10. Returns current balance, monthly allocation, and spending cap (2.5x allocation).",
     {
       response_format: z12.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
@@ -6500,7 +6498,7 @@ Monthly used: ${payload.monthlyUsed}` + (payload.monthlyLimit ? ` / ${payload.mo
   );
   server.tool(
     "get_budget_status",
-    "Get current MCP run budget consumption for credits/assets.",
+    "Check how much of the per-session budget has been consumed. Tracks credits spent and assets created in this MCP session against configured limits. Use to avoid hitting budget caps mid-workflow.",
     {
       response_format: z12.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
@@ -6743,7 +6741,7 @@ function asEnvelope11(data) {
 function registerAutopilotTools(server) {
   server.tool(
     "list_autopilot_configs",
-    "List all autopilot configurations for your account. Shows active schedules, associated recipes, credit budgets, and last run times.",
+    "List autopilot configurations showing schedules, credit budgets, last run times, and active/inactive status. Use to check what is automated before creating new configs, or to find config_id for update_autopilot_config.",
     {
       active_only: z15.boolean().optional().describe("If true, only return active configs. Defaults to false (show all)."),
       response_format: z15.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
@@ -6889,7 +6887,7 @@ Schedule: ${JSON.stringify(updated.schedule_config)}`
   );
   server.tool(
     "get_autopilot_status",
-    "Get the current status of your autopilot system, including active configs, recent runs, and next scheduled execution.",
+    "Get autopilot system overview: active config count, recent execution results, credits consumed, and next scheduled run time. Use as a dashboard check before modifying autopilot settings.",
     {
       response_format: z15.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
@@ -7006,7 +7004,7 @@ ${content.suggested_hooks.map((h) => `  - ${h}`).join("\n")}`
 function registerExtractionTools(server) {
   server.tool(
     "extract_url_content",
-    "Extract content from a URL (YouTube video transcript, article text, product page). Routes to scrape-youtube for YouTube URLs or fetch-url-content for other URLs.",
+    "Extract text content from any URL \u2014 YouTube video transcripts, article text, or product page features/benefits/USP. YouTube URLs auto-route to transcript extraction with optional comments. Use before generate_content to repurpose existing content, or before plan_content_week to base a content plan on a source URL.",
     {
       url: z16.string().url().describe("URL to extract content from"),
       extract_type: z16.enum(["auto", "transcript", "article", "product"]).default("auto").describe("Type of extraction"),
@@ -7204,9 +7202,9 @@ function asEnvelope13(data) {
 function registerQualityTools(server) {
   server.tool(
     "quality_check",
-    "Score a single post's content quality across 7 categories (Hook Strength, Message Clarity, Platform Fit, Brand Alignment, Novelty, CTA Strength, Safety/Claims). Returns pass/fail with per-category scores.",
+    "Score post quality across 7 categories: Hook Strength, Message Clarity, Platform Fit, Brand Alignment, Novelty, CTA Strength, and Safety/Claims. Each scored 0-5, total 35. Default pass threshold is 26 (~75%). Run after generate_content and before schedule_post. Include hashtags in caption if they will be published \u2014 they affect Platform Fit and Safety scores.",
     {
-      caption: z17.string().describe("Post caption/body text"),
+      caption: z17.string().describe("The post text to score. Include hashtags if they will be published \u2014 they affect Platform Fit and Safety/Claims scores."),
       title: z17.string().optional().describe("Post title (important for YouTube)"),
       platforms: z17.array(
         z17.enum([
@@ -7220,7 +7218,7 @@ function registerQualityTools(server) {
           "bluesky"
         ])
       ).min(1).describe("Target platforms"),
-      threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass"),
+      threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass (max 35, scored across 7 categories at 0-5 each). Default 26 (~75%). Use 20 for rough drafts, 28+ for final posts going to large audiences."),
       brand_keyword: z17.string().optional().describe("Brand keyword for alignment check"),
       brand_avoid_patterns: z17.array(z17.string()).optional(),
       custom_banned_terms: z17.array(z17.string()).optional(),
@@ -7291,7 +7289,7 @@ function registerQualityTools(server) {
   );
   server.tool(
     "quality_check_plan",
-    "Run quality checks on all posts in a content plan. Returns per-post scores and aggregate summary.",
+    "Batch quality check all posts in a content plan. Returns per-post scores and aggregate pass/fail summary. Use after plan_content_week and before schedule_content_plan to catch low-quality posts before publishing.",
     {
       plan: z17.object({
         posts: z17.array(
@@ -7303,7 +7301,7 @@ function registerQualityTools(server) {
           })
         )
       }).passthrough().describe("Content plan with posts array"),
-      threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass"),
+      threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass (max 35, scored across 7 categories at 0-5 each). Default 26 (~75%). Use 20 for rough drafts, 28+ for final posts going to large audiences."),
       response_format: z17.enum(["text", "json"]).default("text")
     },
     async ({ plan, threshold, response_format }) => {
@@ -7484,7 +7482,7 @@ function formatPlanAsText(plan) {
 function registerPlanningTools(server) {
   server.tool(
     "plan_content_week",
-    "Generate a full week's content plan with platform-specific drafts. Takes a topic or source URL, loads brand context and performance insights, and returns structured posts with hooks, angles, captions, and suggested schedule times.",
+    "Generate a full content plan with platform-specific drafts, hooks, angles, and optimal schedule times. Pass a topic or source_url \u2014 brand context and performance insights auto-load via project_id. Output feeds directly into quality_check_plan then schedule_content_plan. Costs ~5-15 credits depending on post count.",
     {
       topic: z18.string().describe("Main topic or content theme"),
       source_url: z18.string().optional().describe("URL to extract content from (YouTube, article)"),
@@ -7820,7 +7818,7 @@ ${rawText.slice(0, 1e3)}`
   );
   server.tool(
     "save_content_plan",
-    "Persist a content plan payload for later review, approvals, and scheduling.",
+    "Save a content plan to the database for team review, approval workflows, and scheduled publishing. Creates a plan_id you can reference in get_content_plan, update_content_plan, and schedule_content_plan.",
     {
       plan: z18.object({
         topic: z18.string(),
@@ -8833,7 +8831,7 @@ function searchTools(query) {
 function registerDiscoveryTools(server) {
   server.tool(
     "search_tools",
-    'Search and discover available MCP tools. Use detail level to control token usage: "name" (~50 tokens), "summary" (~500 tokens), "full" (complete schemas).',
+    'Search available tools by name, description, module, or scope. Use "name" detail (~50 tokens) for quick lookup, "summary" (~500 tokens) for descriptions, "full" for complete input schemas. Start here if unsure which tool to call \u2014 filter by module (e.g. "planning", "content", "analytics") to narrow results.',
     {
       query: z20.string().optional().describe("Search query to filter tools by name or description"),
       module: z20.string().optional().describe('Filter by module name (e.g. "planning", "content", "analytics")'),
@@ -8960,7 +8958,7 @@ function getJWKS(supabaseUrl) {
   return jwks;
 }
 var apiKeyCache = /* @__PURE__ */ new Map();
-var API_KEY_CACHE_TTL_MS = 6e4;
+var API_KEY_CACHE_TTL_MS = 1e4;
 function createTokenVerifier(options) {
   const { supabaseUrl, supabaseAnonKey } = options;
   return {
@@ -9061,7 +9059,30 @@ var PORT = parseInt(process.env.PORT ?? "8080", 10);
 var SUPABASE_URL2 = process.env.SUPABASE_URL ?? "";
 var SUPABASE_ANON_KEY = process.env.SUPABASE_ANON_KEY ?? "";
 var MCP_SERVER_URL = process.env.MCP_SERVER_URL ?? `http://localhost:${PORT}/mcp`;
+var APP_BASE_URL = process.env.APP_BASE_URL ?? "https://www.socialneuron.com";
 var NODE_ENV = process.env.NODE_ENV ?? "development";
+function deriveOAuthIssuerUrl() {
+  if (process.env.OAUTH_ISSUER_URL) {
+    return process.env.OAUTH_ISSUER_URL;
+  }
+  try {
+    const mcpUrl = new URL(MCP_SERVER_URL);
+    const isLocalhost = mcpUrl.hostname === "localhost" || mcpUrl.hostname === "127.0.0.1";
+    if (isLocalhost) {
+      if (NODE_ENV === "development") {
+        return `${mcpUrl.protocol}//${mcpUrl.host}`;
+      }
+    } else {
+      return `${mcpUrl.protocol}//${mcpUrl.host}`;
+    }
+  } catch {
+  }
+  if (APP_BASE_URL && !APP_BASE_URL.includes("localhost")) {
+    return APP_BASE_URL;
+  }
+  return "https://mcp.socialneuron.com";
+}
+var OAUTH_ISSUER_URL = deriveOAuthIssuerUrl();
 if (!SUPABASE_URL2 || !SUPABASE_ANON_KEY) {
   console.error("[MCP HTTP] Missing SUPABASE_URL or SUPABASE_ANON_KEY");
   process.exit(1);

package/dist/index.js

@@ -14,7 +14,7 @@ var MCP_VERSION;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    MCP_VERSION = "1.4.1";
+    MCP_VERSION = "1.5.0";
   }
 });
 
@@ -400,7 +400,9 @@ async function getDefaultUserId() {
   if (authenticatedUserId) return authenticatedUserId;
   const envUserId = process.env.SOCIALNEURON_USER_ID;
   if (envUserId) return envUserId;
-  throw new Error("No user ID available. Set SOCIALNEURON_USER_ID or authenticate via API key.");
+  throw new Error(
+    "No user ID available. Set SOCIALNEURON_USER_ID or authenticate via API key."
+  );
 }
 async function getDefaultProjectId() {
   const userId = await getDefaultUserId().catch(() => null);
@@ -444,7 +446,9 @@ async function initializeAuth() {
       console.error("[MCP] Scopes: " + authenticatedScopes.join(", "));
       if (authenticatedExpiresAt) {
         const expiresMs = new Date(authenticatedExpiresAt).getTime();
-        const daysLeft = Math.ceil((expiresMs - Date.now()) / (1e3 * 60 * 60 * 24));
+        const daysLeft = Math.ceil(
+          (expiresMs - Date.now()) / (1e3 * 60 * 60 * 24)
+        );
         console.error("[MCP] Key expires: " + authenticatedExpiresAt);
         if (daysLeft <= 7) {
           console.error(
@@ -467,8 +471,12 @@ async function initializeAuth() {
     console.error(
       "[MCP] \u26A0 DEPRECATED: Service role keys grant full admin access to your database."
     );
-    console.error("[MCP]   Migrate to API key auth: npx @socialneuron/mcp-server setup");
-    console.error("[MCP]   Then remove SOCIALNEURON_SERVICE_KEY from your environment.");
+    console.error(
+      "[MCP]   Migrate to API key auth: npx @socialneuron/mcp-server setup"
+    );
+    console.error(
+      "[MCP]   Then remove SOCIALNEURON_SERVICE_KEY from your environment."
+    );
     if (!process.env.SOCIALNEURON_USER_ID) {
       console.error(
         "[MCP] Warning: SOCIALNEURON_USER_ID not set. Tools requiring a user will fail."
@@ -2947,7 +2955,9 @@ __export(setup_exports, {
   runSetup: () => runSetup
 });
 import { createHash as createHash4, randomBytes, randomUUID as randomUUID3 } from "node:crypto";
-import { createServer } from "node:http";
+import {
+  createServer
+} from "node:http";
 import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
 import { homedir as homedir3, platform as platform2 } from "node:os";
 import { join as join3 } from "node:path";
@@ -2962,7 +2972,7 @@ function generatePKCE() {
   return { codeVerifier, codeChallenge };
 }
 function getAppBaseUrl() {
-  return process.env.SOCIALNEURON_APP_URL || "https://app.socialneuron.com";
+  return process.env.SOCIALNEURON_APP_URL || "https://www.socialneuron.com";
 }
 function getDefaultSupabaseUrl() {
   return process.env.SOCIALNEURON_SUPABASE_URL || process.env.SUPABASE_URL || CLOUD_SUPABASE_URL;
@@ -3033,11 +3043,14 @@ function readBody(req) {
 async function completePkceExchange(codeVerifier, state) {
   const supabaseUrl = getDefaultSupabaseUrl();
   try {
-    const response = await fetch(`${supabaseUrl}/functions/v1/mcp-auth?action=exchange-key`, {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ code_verifier: codeVerifier, state })
-    });
+    const response = await fetch(
+      `${supabaseUrl}/functions/v1/mcp-auth?action=exchange-key`,
+      {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ code_verifier: codeVerifier, state })
+      }
+    );
     if (!response.ok) {
       const text = await response.text();
       console.error(`  PKCE exchange failed: ${text}`);
@@ -3046,7 +3059,9 @@ async function completePkceExchange(codeVerifier, state) {
     const data = await response.json();
     return data.success === true;
   } catch (err) {
-    console.error(`  PKCE exchange error: ${err instanceof Error ? err.message : String(err)}`);
+    console.error(
+      `  PKCE exchange error: ${err instanceof Error ? err.message : String(err)}`
+    );
     return false;
   }
 }
@@ -3057,9 +3072,13 @@ async function runSetup() {
   console.error("");
   console.error("  Privacy Notice:");
   console.error("  - Your API key is stored locally in your OS keychain");
-  console.error("  - Tool invocations are logged for usage metering (no content stored)");
+  console.error(
+    "  - Tool invocations are logged for usage metering (no content stored)"
+  );
   console.error("  - Set DO_NOT_TRACK=1 to disable telemetry");
-  console.error("  - Data export/delete: https://app.socialneuron.com/settings");
+  console.error(
+    "  - Data export/delete: https://www.socialneuron.com/settings"
+  );
   console.error("");
   const { codeVerifier, codeChallenge } = generatePKCE();
   const state = randomUUID3();
@@ -3092,49 +3111,54 @@ async function runSetup() {
     console.error("");
     console.error("  Waiting for authorization (timeout: 120s)...");
   }
-  const result = await new Promise((resolve3) => {
-    const timeout = setTimeout(() => {
-      server2.close();
-      resolve3({ error: "Authorization timed out after 120 seconds." });
-    }, 12e4);
-    server2.on("request", async (req, res) => {
-      res.setHeader("Access-Control-Allow-Origin", "*");
-      res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
-      res.setHeader("Access-Control-Allow-Headers", "Content-Type");
-      if (req.method === "OPTIONS") {
-        res.writeHead(204);
-        res.end();
-        return;
-      }
-      if (req.method === "POST" && req.url === "/callback") {
-        try {
-          const body = await readBody(req);
-          const data = JSON.parse(body);
-          if (data.state !== state) {
-            res.writeHead(400, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: "State mismatch" }));
+  const result = await new Promise(
+    (resolve3) => {
+      const timeout = setTimeout(() => {
+        server2.close();
+        resolve3({ error: "Authorization timed out after 120 seconds." });
+      }, 12e4);
+      server2.on(
+        "request",
+        async (req, res) => {
+          res.setHeader("Access-Control-Allow-Origin", "*");
+          res.setHeader("Access-Control-Allow-Methods", "POST, OPTIONS");
+          res.setHeader("Access-Control-Allow-Headers", "Content-Type");
+          if (req.method === "OPTIONS") {
+            res.writeHead(204);
+            res.end();
             return;
           }
-          if (!data.api_key) {
-            res.writeHead(400, { "Content-Type": "application/json" });
-            res.end(JSON.stringify({ error: "Missing api_key" }));
+          if (req.method === "POST" && req.url === "/callback") {
+            try {
+              const body = await readBody(req);
+              const data = JSON.parse(body);
+              if (data.state !== state) {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "State mismatch" }));
+                return;
+              }
+              if (!data.api_key) {
+                res.writeHead(400, { "Content-Type": "application/json" });
+                res.end(JSON.stringify({ error: "Missing api_key" }));
+                return;
+              }
+              res.writeHead(200, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ success: true }));
+              clearTimeout(timeout);
+              server2.close();
+              resolve3({ apiKey: data.api_key });
+            } catch {
+              res.writeHead(400, { "Content-Type": "application/json" });
+              res.end(JSON.stringify({ error: "Invalid request" }));
+            }
             return;
           }
-          res.writeHead(200, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ success: true }));
-          clearTimeout(timeout);
-          server2.close();
-          resolve3({ apiKey: data.api_key });
-        } catch {
-          res.writeHead(400, { "Content-Type": "application/json" });
-          res.end(JSON.stringify({ error: "Invalid request" }));
+          res.writeHead(404);
+          res.end("Not found");
         }
-        return;
-      }
-      res.writeHead(404);
-      res.end("Not found");
-    });
-  });
+      );
+    }
+  );
   if ("error" in result) {
     console.error("");
     console.error(`  Error: ${result.error}`);
@@ -3146,7 +3170,9 @@ async function runSetup() {
   const exchangeSuccess = await completePkceExchange(codeVerifier, state);
   if (!exchangeSuccess) {
     console.error("  Warning: PKCE exchange failed. Key may not be activated.");
-    console.error("  The key will still work if the server was in legacy mode.");
+    console.error(
+      "  The key will still work if the server was in legacy mode."
+    );
   } else {
     console.error("  PKCE verification complete.");
   }
@@ -3167,7 +3193,9 @@ async function runSetup() {
   }
   if (!configured) {
     console.error("");
-    console.error("  No MCP client config found. Add this to your MCP config manually:");
+    console.error(
+      "  No MCP client config found. Add this to your MCP config manually:"
+    );
     console.error("");
     console.error('    "socialneuron": {');
     console.error('      "command": "npx",');
@@ -3305,17 +3333,13 @@ async function runLoginDevice() {
       if (pollResponse.status === 200) {
         const pollData = await pollResponse.json();
         if (pollData.api_key) {
-          const validation = await validateApiKey(pollData.api_key);
-          if (validation.valid) {
-            await saveApiKey(pollData.api_key);
-            await saveSupabaseUrl(supabaseUrl);
-            console.error("");
-            console.error("  Authorized!");
-            console.error(`  User: ${validation.email || "unknown"}`);
-            console.error(`  Key prefix: ${pollData.api_key.substring(0, 12)}...`);
-            console.error("");
-            return;
-          }
+          await saveApiKey(pollData.api_key);
+          await saveSupabaseUrl(supabaseUrl);
+          console.error("");
+          console.error("  Authorized!");
+          console.error(`  Key prefix: ${pollData.api_key.substring(0, 12)}...`);
+          console.error("");
+          return;
         }
       }
       if (pollResponse.status === 410) {
@@ -3874,10 +3898,10 @@ init_supabase();
 function registerIdeationTools(server2) {
   server2.tool(
     "generate_content",
-    "Generate AI-powered content (scripts, captions, hooks, blog posts) using Google Gemini or Anthropic Claude. Provide a detailed prompt describing what you need, choose the content type, and optionally specify a target platform and brand voice guidelines.",
+    "Create a script, caption, hook, or blog post tailored to a specific platform. Pass project_id to auto-load brand profile and performance context, or call get_ideation_context first for full context. Output is draft text ready for quality_check then schedule_post.",
     {
       prompt: z.string().max(1e4).describe(
-        "Detailed prompt describing the content to generate. Include context like topic, angle, audience, and any specific requirements."
+        'Detailed content prompt. Include topic, angle, audience, and requirements. Example: "LinkedIn post about AI productivity for CTOs, 300 words, include 3 actionable tips, conversational tone." Richer prompts produce better results.'
       ),
       content_type: z.enum(["script", "caption", "blog", "hook"]).describe(
         'Type of content to generate. "script" for video scripts, "caption" for social media captions, "blog" for blog posts, "hook" for attention-grabbing hooks.'
@@ -3895,7 +3919,7 @@ function registerIdeationTools(server2) {
         "Target social media platform. Helps tailor tone, length, and format."
       ),
       brand_voice: z.string().max(500).optional().describe(
-        'Brand voice guidelines to follow (e.g. "professional and empathetic", "playful and Gen-Z"). Leave blank to use a neutral tone.'
+        'Tone directive (e.g. "direct, no jargon, second person" or "witty Gen-Z energy with emoji"). Leave blank to auto-load from project brand profile if project_id is set.'
       ),
       model: z.enum(["gemini-2.0-flash", "gemini-2.5-flash", "gemini-2.5-pro"]).optional().describe(
         "AI model to use. Defaults to gemini-2.5-flash. Use gemini-2.5-pro for highest quality."
@@ -4051,7 +4075,7 @@ Content Type: ${content_type}`;
   );
   server2.tool(
     "fetch_trends",
-    "Fetch current trending topics from YouTube, Google Trends, RSS feeds, or a custom URL. Results are cached for efficiency. Use this to discover what is popular right now for content ideation.",
+    'Get current trending topics for content inspiration. Source "youtube" returns trending videos with view counts, "google_trends" returns rising search terms, "rss"/"url" extracts topics from any feed or page. Results cached 1 hour \u2014 set force_refresh=true for real-time. Feed results into generate_content or plan_content_week.',
     {
       source: z.enum(["youtube", "google_trends", "rss", "url"]).describe(
         'Data source. "youtube" fetches trending videos, "google_trends" fetches daily search trends, "rss" fetches from a custom RSS feed URL, "url" extracts trend data from a web page.'
@@ -4137,7 +4161,7 @@ Content Type: ${content_type}`;
   );
   server2.tool(
     "adapt_content",
-    "Adapt existing content for a different social media platform. Rewrites content to match the target platform's norms including character limits, hashtag style, tone, and CTA conventions.",
+    "Rewrite existing content for a different platform \u2014 adjusts character limits, hashtag style, tone, and CTA format automatically. Use after generate_content when you need the same message across multiple platforms. Pass project_id to apply platform-specific voice overrides from your brand profile.",
     {
       content: z.string().max(5e3).describe(
         "The content to adapt. Can be a caption, script, blog excerpt, or any text."
@@ -4435,10 +4459,10 @@ function checkAssetBudget() {
 function registerContentTools(server2) {
   server2.tool(
     "generate_video",
-    "Start an AI video generation job. This is an async operation -- it returns a job_id immediately. Use check_status to poll for completion. Supports Veo 3, Runway, Sora 2, Kling 2.6, and Kling 3.0 models via the Kie.ai API.",
+    "Start an async AI video generation job \u2014 returns a job_id immediately. Poll with check_status every 10-30s until complete. Cost varies by model: veo3-fast (~15 credits/5s), kling-3 (~30 credits/5s), sora2-pro (~60 credits/10s). Check get_credit_balance first for expensive generations.",
     {
       prompt: z2.string().max(2500).describe(
-        "Text prompt describing the video to generate. Be specific about visual style, camera angles, movement, lighting, and mood."
+        'Video prompt \u2014 be specific about visual style, camera movement, lighting, and mood. Example: "Aerial drone shot of coastal cliffs at golden hour, slow dolly forward, cinematic 24fps, warm color grading." Vague prompts produce generic results.'
       ),
       model: z2.enum([
         "veo3-fast",
@@ -4450,13 +4474,13 @@ function registerContentTools(server2) {
         "kling-3",
         "kling-3-pro"
       ]).describe(
-        "Video generation model. veo3-fast is fastest (~60s), veo3-quality is highest quality (~120s). sora2-pro is OpenAI Sora premium tier. kling-3 is Kling 3.0 standard (4K, 15s, audio). kling-3-pro is Kling 3.0 pro (higher quality)."
+        "Video model. veo3-fast: fastest (~15 credits/5s, ~60s render). veo3-quality: highest quality (~20 credits/5s, ~120s). sora2-pro: OpenAI premium (~60 credits/10s). kling-3: 4K with audio (~30 credits/5s). kling-3-pro: best Kling quality (~40 credits/5s)."
       ),
       duration: z2.number().min(3).max(30).optional().describe(
         "Video duration in seconds. kling: 5-30s, kling-3/kling-3-pro: 3-15s, sora2: 10-15s. Defaults to 5 seconds."
       ),
       aspect_ratio: z2.enum(["16:9", "9:16", "1:1"]).optional().describe(
-        "Aspect ratio. 16:9 for landscape/YouTube, 9:16 for vertical/Reels/TikTok, 1:1 for square. Defaults to 16:9."
+        "Video aspect ratio. 16:9 for YouTube/landscape, 9:16 for TikTok/Reels/Shorts, 1:1 for Instagram feed/square. Defaults to 16:9."
       ),
       enable_audio: z2.boolean().optional().describe(
         "Enable native audio generation. Kling 2.6: doubles cost. Kling 3.0: 50% more (std 30/sec, pro 40/sec). 5+ languages."
@@ -4643,7 +4667,7 @@ function registerContentTools(server2) {
   );
   server2.tool(
     "generate_image",
-    "Start an AI image generation job. This is an async operation -- it returns a job_id immediately. Use check_status to poll for completion. Supports Midjourney, Imagen 4, Flux, GPT-4o Image, and Seedream models.",
+    "Start an async AI image generation job \u2014 returns a job_id immediately. Poll with check_status every 5-15s until complete. Costs 2-10 credits depending on model. Use for social media posts, carousel slides, or as input to generate_video (image-to-video).",
     {
       prompt: z2.string().max(2e3).describe(
         "Text prompt describing the image to generate. Be specific about style, composition, colors, lighting, and subject matter."
@@ -4823,7 +4847,7 @@ function registerContentTools(server2) {
   );
   server2.tool(
     "check_status",
-    "Check the status of an async generation job (video or image). Returns the current status, progress percentage, and result URL when complete. Call this tool periodically after generate_video or generate_image.",
+    'Poll an async job started by generate_video or generate_image. Returns status (queued/processing/completed/failed), progress %, and result URL on completion. Poll every 10-30s for video, 5-15s for images. On "failed" status, the error field explains why \u2014 check credits or try a different model.',
     {
       job_id: z2.string().describe(
         "The job ID returned by generate_video or generate_image. This is the asyncJobId or taskId value."
@@ -4999,7 +5023,7 @@ function registerContentTools(server2) {
   );
   server2.tool(
     "create_storyboard",
-    "Generate a structured scene-by-scene storyboard for video production. Returns an array of StoryboardFrames with prompts, durations, captions, and voiceover text. Use the output to drive image/video generation.",
+    "Plan a multi-scene video storyboard with AI-generated prompts, durations, captions, and voiceover text per frame. Use before generate_video or generate_image to create cohesive multi-shot content. Include brand_context from get_brand_profile for consistent visual branding across frames.",
     {
       concept: z2.string().max(2e3).describe(
         'The video concept/idea. Include: hook, key messages, target audience, and desired outcome (e.g., "TikTok ad for VPN app targeting privacy-conscious millennials, hook with shocking stat about data leaks").'
@@ -5186,7 +5210,7 @@ Return ONLY valid JSON in this exact format:
   );
   server2.tool(
     "generate_voiceover",
-    "Generate a professional voiceover audio file using ElevenLabs TTS. Returns an audio URL stored in R2. Use this for narration in video production.",
+    "Generate a voiceover audio file for video narration. Returns an R2-hosted audio URL. Use after create_storyboard to add narration to each scene, or standalone for podcast intros and ad reads. Costs ~2 credits per generation.",
     {
       text: z2.string().max(5e3).describe("The script/text to convert to speech."),
       voice: z2.enum([
@@ -5337,10 +5361,10 @@ Return ONLY valid JSON in this exact format:
   );
   server2.tool(
     "generate_carousel",
-    "Generate an Instagram carousel with AI-powered slide content. Supports multiple templates including Hormozi-style authority carousels. Returns slide data (headlines, body text, emphasis words). Use schedule_post with media_urls to publish the carousel to Instagram.",
+    "Generate carousel slide content (headlines, body text, emphasis words per slide). Supports Hormozi-style authority format and educational templates. Returns structured slide data \u2014 render visually then publish via schedule_post with media_type=CAROUSEL_ALBUM and 2-10 media_urls on Instagram.",
     {
       topic: z2.string().max(200).describe(
-        'The carousel topic/subject. Be specific about the angle or hook. Example: "5 reasons your startup will fail in 2026"'
+        'Carousel hook/angle \u2014 specific beats general. Example: "5 pricing mistakes that kill SaaS startups" beats "SaaS tips". Include a curiosity gap or strong opinion for better Hook Strength scores.'
       ),
       template_id: z2.enum([
         "educational-series",
@@ -5547,14 +5571,12 @@ function asEnvelope2(data) {
 function registerDistributionTools(server2) {
   server2.tool(
     "schedule_post",
-    "Schedule or immediately publish a post to one or more social media platforms. Requires the target platforms to have active OAuth connections configured in Social Neuron Settings. Supports YouTube, TikTok, Instagram, Facebook, LinkedIn, Twitter, Threads, and Bluesky. For Instagram carousels, provide media_urls (2-10 image URLs) and set media_type to CAROUSEL_ALBUM.",
+    'Publish or schedule a post to connected social platforms. Check list_connected_accounts first to verify active OAuth for each target platform. For Instagram carousels: use media_type=CAROUSEL_ALBUM with 2-10 media_urls. For YouTube: title is required. schedule_at uses ISO 8601 (e.g. "2026-03-20T14:00:00Z") \u2014 omit to post immediately.',
     {
       media_url: z3.string().optional().describe(
         "Optional URL of the media file (video or image) to post. This should be a publicly accessible URL or a Cloudflare R2 signed URL from a previous generation. Required for platforms that enforce media uploads. Not needed if media_urls is provided."
       ),
-      media_urls: z3.array(z3.string()).optional().describe(
-        "Array of image URLs for Instagram carousel posts (2-10 images). Each URL should be publicly accessible or a Cloudflare R2 URL. When provided with media_type=CAROUSEL_ALBUM, creates an Instagram carousel."
-      ),
+      media_urls: z3.array(z3.string()).optional().describe("Array of 2-10 image URLs for Instagram carousel posts. Each URL must be publicly accessible or a Cloudflare R2 signed URL. Use with media_type=CAROUSEL_ALBUM."),
       media_type: z3.enum(["IMAGE", "VIDEO", "CAROUSEL_ALBUM"]).optional().describe(
         "Media type. Set to CAROUSEL_ALBUM with media_urls for Instagram carousels. Default: auto-detected from media_url."
       ),
@@ -5570,16 +5592,10 @@ function registerDistributionTools(server2) {
           "threads",
           "bluesky"
         ])
-      ).min(1).describe(
-        "Target platforms to post to. Each must have an active OAuth connection."
-      ),
+      ).min(1).describe("Target platforms (array). Each must have active OAuth \u2014 check list_connected_accounts first. Values: youtube, tiktok, instagram, twitter, linkedin, facebook, threads, bluesky."),
       title: z3.string().optional().describe("Post title (used by YouTube and some other platforms)."),
-      hashtags: z3.array(z3.string()).optional().describe(
-        'Hashtags to append to the caption. Include or omit the "#" prefix.'
-      ),
-      schedule_at: z3.string().optional().describe(
-        'ISO 8601 datetime for scheduled posting (e.g. "2026-03-15T14:00:00Z"). Omit for immediate posting.'
-      ),
+      hashtags: z3.array(z3.string()).optional().describe('Hashtags to append to caption. Include or omit the "#" prefix \u2014 both work. Example: ["ai", "contentcreator"] or ["#ai", "#contentcreator"].'),
+      schedule_at: z3.string().optional().describe('ISO 8601 UTC datetime for scheduled posting (e.g. "2026-03-20T14:00:00Z"). Omit to post immediately. Must be in the future.'),
       project_id: z3.string().optional().describe("Social Neuron project ID to associate this post with."),
       response_format: z3.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text."),
       attribution: z3.boolean().optional().describe(
@@ -5733,7 +5749,7 @@ Created with Social Neuron`;
   );
   server2.tool(
     "list_connected_accounts",
-    "List all social media accounts connected to Social Neuron via OAuth. Shows which platforms are available for posting.",
+    "Check which social platforms have active OAuth connections for posting. Call this before schedule_post to verify credentials. If a platform is missing or expired, the user needs to reconnect at socialneuron.com/settings/connections.",
     {
       response_format: z3.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
@@ -5798,7 +5814,7 @@ Created with Social Neuron`;
   );
   server2.tool(
     "list_recent_posts",
-    "List recent posts from Social Neuron. Shows status, platform, title, and timestamps. Useful for checking what has been published or scheduled recently.",
+    "List recent published and scheduled posts with status, platform, title, and timestamps. Use to check what has been posted before planning new content, or to find post IDs for fetch_analytics. Filter by platform or status to narrow results.",
     {
       platform: z3.enum([
         "youtube",
@@ -6639,7 +6655,7 @@ function registerAnalyticsTools(server2) {
         "threads",
         "bluesky"
       ]).optional().describe("Filter analytics to a specific platform."),
-      days: z4.number().min(1).max(365).optional().describe("Number of days to look back. Defaults to 30. Max 365."),
+      days: z4.number().min(1).max(365).optional().describe("Lookback window in days (1-365). Default 30. Use 7 for weekly review, 30 for monthly summary, 90 for quarterly trends."),
       content_id: z4.string().uuid().optional().describe(
         "Filter to a specific content_history ID to see performance of one piece of content."
       ),
@@ -6819,7 +6835,7 @@ function registerAnalyticsTools(server2) {
   );
   server2.tool(
     "refresh_platform_analytics",
-    "Trigger an analytics refresh for all recently posted content across all connected platforms. Queues analytics fetch jobs for posts from the last 7 days.",
+    "Queue analytics refresh jobs for all posts from the last 7 days across connected platforms. Call this before fetch_analytics if you need fresh data. Returns immediately \u2014 data updates asynchronously over the next 1-5 minutes.",
     {
       response_format: z4.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
@@ -8755,13 +8771,11 @@ function asEnvelope6(data) {
 function registerCommentsTools(server2) {
   server2.tool(
     "list_comments",
-    "List YouTube comments. Without a video_id, returns recent comments across all channel videos. With a video_id, returns comments for that specific video.",
+    'List YouTube comments \u2014 pass video_id (11-char string, e.g. "dQw4w9WgXcQ") for a specific video, or omit for recent comments across all channel videos. Returns comment text, author, like count, and reply count. Use page_token from previous response for pagination.',
     {
-      video_id: z10.string().optional().describe(
-        "YouTube video ID. If omitted, returns comments across all channel videos."
-      ),
+      video_id: z10.string().optional().describe('YouTube video ID \u2014 the 11-character string from the URL (e.g. "dQw4w9WgXcQ" from youtube.com/watch?v=dQw4w9WgXcQ). Omit to get recent comments across all channel videos.'),
       max_results: z10.number().min(1).max(100).optional().describe("Maximum number of comments to return. Defaults to 50."),
-      page_token: z10.string().optional().describe("Pagination token from a previous list_comments call."),
+      page_token: z10.string().optional().describe("Pagination cursor from previous list_comments response nextPageToken field. Omit for first page of results."),
       response_format: z10.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
     async ({ video_id, max_results, page_token, response_format }) => {
@@ -8826,7 +8840,7 @@ function registerCommentsTools(server2) {
   );
   server2.tool(
     "reply_to_comment",
-    "Reply to a YouTube comment. Requires the parent comment ID and reply text.",
+    "Reply to a YouTube comment. Get the parent_id from list_comments results. Reply appears as the authenticated channel. Use for community engagement after checking list_comments for questions or feedback.",
     {
       parent_id: z10.string().describe(
         "The ID of the parent comment to reply to (from list_comments)."
@@ -9359,7 +9373,7 @@ function asEnvelope8(data) {
 function registerCreditsTools(server2) {
   server2.tool(
     "get_credit_balance",
-    "Get current subscription credit balance and plan.",
+    "Check remaining credits, monthly limit, spending cap, and plan tier. Call this before expensive operations \u2014 generate_video costs 15-80 credits, generate_image costs 2-10. Returns current balance, monthly allocation, and spending cap (2.5x allocation).",
     {
       response_format: z12.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
@@ -9412,7 +9426,7 @@ Monthly used: ${payload.monthlyUsed}` + (payload.monthlyLimit ? ` / ${payload.mo
   );
   server2.tool(
     "get_budget_status",
-    "Get current MCP run budget consumption for credits/assets.",
+    "Check how much of the per-session budget has been consumed. Tracks credits spent and assets created in this MCP session against configured limits. Use to avoid hitting budget caps mid-workflow.",
     {
       response_format: z12.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
@@ -9658,7 +9672,7 @@ function asEnvelope11(data) {
 function registerAutopilotTools(server2) {
   server2.tool(
     "list_autopilot_configs",
-    "List all autopilot configurations for your account. Shows active schedules, associated recipes, credit budgets, and last run times.",
+    "List autopilot configurations showing schedules, credit budgets, last run times, and active/inactive status. Use to check what is automated before creating new configs, or to find config_id for update_autopilot_config.",
     {
       active_only: z15.boolean().optional().describe("If true, only return active configs. Defaults to false (show all)."),
       response_format: z15.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
@@ -9804,7 +9818,7 @@ Schedule: ${JSON.stringify(updated.schedule_config)}`
   );
   server2.tool(
     "get_autopilot_status",
-    "Get the current status of your autopilot system, including active configs, recent runs, and next scheduled execution.",
+    "Get autopilot system overview: active config count, recent execution results, credits consumed, and next scheduled run time. Use as a dashboard check before modifying autopilot settings.",
     {
       response_format: z15.enum(["text", "json"]).optional().describe("Optional response format. Defaults to text.")
     },
@@ -9923,7 +9937,7 @@ ${content.suggested_hooks.map((h) => `  - ${h}`).join("\n")}`
 function registerExtractionTools(server2) {
   server2.tool(
     "extract_url_content",
-    "Extract content from a URL (YouTube video transcript, article text, product page). Routes to scrape-youtube for YouTube URLs or fetch-url-content for other URLs.",
+    "Extract text content from any URL \u2014 YouTube video transcripts, article text, or product page features/benefits/USP. YouTube URLs auto-route to transcript extraction with optional comments. Use before generate_content to repurpose existing content, or before plan_content_week to base a content plan on a source URL.",
     {
       url: z16.string().url().describe("URL to extract content from"),
       extract_type: z16.enum(["auto", "transcript", "article", "product"]).default("auto").describe("Type of extraction"),
@@ -10123,9 +10137,9 @@ function asEnvelope13(data) {
 function registerQualityTools(server2) {
   server2.tool(
     "quality_check",
-    "Score a single post's content quality across 7 categories (Hook Strength, Message Clarity, Platform Fit, Brand Alignment, Novelty, CTA Strength, Safety/Claims). Returns pass/fail with per-category scores.",
+    "Score post quality across 7 categories: Hook Strength, Message Clarity, Platform Fit, Brand Alignment, Novelty, CTA Strength, and Safety/Claims. Each scored 0-5, total 35. Default pass threshold is 26 (~75%). Run after generate_content and before schedule_post. Include hashtags in caption if they will be published \u2014 they affect Platform Fit and Safety scores.",
     {
-      caption: z17.string().describe("Post caption/body text"),
+      caption: z17.string().describe("The post text to score. Include hashtags if they will be published \u2014 they affect Platform Fit and Safety/Claims scores."),
       title: z17.string().optional().describe("Post title (important for YouTube)"),
       platforms: z17.array(
         z17.enum([
@@ -10139,7 +10153,7 @@ function registerQualityTools(server2) {
           "bluesky"
         ])
       ).min(1).describe("Target platforms"),
-      threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass"),
+      threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass (max 35, scored across 7 categories at 0-5 each). Default 26 (~75%). Use 20 for rough drafts, 28+ for final posts going to large audiences."),
       brand_keyword: z17.string().optional().describe("Brand keyword for alignment check"),
       brand_avoid_patterns: z17.array(z17.string()).optional(),
       custom_banned_terms: z17.array(z17.string()).optional(),
@@ -10210,7 +10224,7 @@ function registerQualityTools(server2) {
   );
   server2.tool(
     "quality_check_plan",
-    "Run quality checks on all posts in a content plan. Returns per-post scores and aggregate summary.",
+    "Batch quality check all posts in a content plan. Returns per-post scores and aggregate pass/fail summary. Use after plan_content_week and before schedule_content_plan to catch low-quality posts before publishing.",
     {
       plan: z17.object({
         posts: z17.array(
@@ -10222,7 +10236,7 @@ function registerQualityTools(server2) {
           })
         )
       }).passthrough().describe("Content plan with posts array"),
-      threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass"),
+      threshold: z17.number().min(0).max(35).default(26).describe("Minimum total score to pass (max 35, scored across 7 categories at 0-5 each). Default 26 (~75%). Use 20 for rough drafts, 28+ for final posts going to large audiences."),
       response_format: z17.enum(["text", "json"]).default("text")
     },
     async ({ plan, threshold, response_format }) => {
@@ -10405,7 +10419,7 @@ function formatPlanAsText(plan) {
 function registerPlanningTools(server2) {
   server2.tool(
     "plan_content_week",
-    "Generate a full week's content plan with platform-specific drafts. Takes a topic or source URL, loads brand context and performance insights, and returns structured posts with hooks, angles, captions, and suggested schedule times.",
+    "Generate a full content plan with platform-specific drafts, hooks, angles, and optimal schedule times. Pass a topic or source_url \u2014 brand context and performance insights auto-load via project_id. Output feeds directly into quality_check_plan then schedule_content_plan. Costs ~5-15 credits depending on post count.",
     {
       topic: z18.string().describe("Main topic or content theme"),
       source_url: z18.string().optional().describe("URL to extract content from (YouTube, article)"),
@@ -10741,7 +10755,7 @@ ${rawText.slice(0, 1e3)}`
   );
   server2.tool(
     "save_content_plan",
-    "Persist a content plan payload for later review, approvals, and scheduling.",
+    "Save a content plan to the database for team review, approval workflows, and scheduled publishing. Creates a plan_id you can reference in get_content_plan, update_content_plan, and schedule_content_plan.",
     {
       plan: z18.object({
         topic: z18.string(),
@@ -11406,7 +11420,7 @@ import { z as z20 } from "zod";
 function registerDiscoveryTools(server2) {
   server2.tool(
     "search_tools",
-    'Search and discover available MCP tools. Use detail level to control token usage: "name" (~50 tokens), "summary" (~500 tokens), "full" (complete schemas).',
+    'Search available tools by name, description, module, or scope. Use "name" detail (~50 tokens) for quick lookup, "summary" (~500 tokens) for descriptions, "full" for complete input schemas. Start here if unsure which tool to call \u2014 filter by module (e.g. "planning", "content", "analytics") to narrow results.',
     {
       query: z20.string().optional().describe("Search query to filter tools by name or description"),
       module: z20.string().optional().describe('Filter by module name (e.g. "planning", "content", "analytics")'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@socialneuron/mcp-server",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "MCP server for Social Neuron - AI content creation platform",
   "type": "module",
   "main": "dist/index.js",
@@ -61,10 +61,10 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "@supabase/supabase-js": "2.98.0",
+    "@supabase/supabase-js": "2.99.2",
     "express": "^5.1.0",
     "jose": "^6.2.1",
-    "open": "10.0.0",
+    "open": "11.0.0",
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
@@ -75,7 +75,7 @@
     "@types/node": "^25.3.5",
     "esbuild": "^0.27.3",
     "typescript": "^5.9.3",
-    "vitest": "^3.0.0"
+    "vitest": "^4.1.0"
   },
   "engines": {
     "node": ">=20.0.0 <21.0.0 || >=22.0.0"