@socialneuron/mcp-server 1.2.1 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,32 @@
 
 All notable changes to `@socialneuron/mcp-server` will be documented in this file.
 
+## [1.3.0] - 2026-03-13
+
+### Added
+
+- **Tool discovery**: `sn tools` command lists all 52 MCP tools, filterable by `--module` and `--scope`
+- **Introspection**: `sn info` shows version, tool count, auth status, and credit balance (works offline)
+- **Content plan CLI**: `sn plan list|view|approve` wrappers for content plan management
+- **Presets**: `sn preset list|show|save|delete` with 6 built-in platform presets (instagram-reel, tiktok, youtube-short, etc.)
+- **Interactive REPL**: `socialneuron-mcp repl` with tab completion and persistent auth
+- **Progressive disclosure**: New `search_tools` MCP tool reduces agent token usage from 55K to ~500 tokens
+- **Unified JSON envelope**: All CLI JSON output includes `schema_version: "1"`, `ok`, `command`, typed errors with `errorType` + `retryable` + `hint`
+- **`--json` everywhere**: `--version --json`, `--help --json` now return structured JSON
+
+### Fixed
+
+- Error handler (`withSnErrorHandling`) now wraps all dispatcher handler calls — consistent error formatting
+- Flag validation runs before auth — missing flags show VALIDATION error, not AUTH error
+- Deduplicated platform normalization in publish handler
+- `schema_version: "1"` added to whoami, health, logout JSON output
+
+### Internal
+
+- 52 tools (was 51), 759 tests (was 698), 374.7KB build
+- New files: tool-catalog.ts, discovery.ts (CLI + MCP), planning.ts, presets.ts, repl.ts
+- CLI E2E test suite (23 tests), MCP E2E test suite (13 tests)
+
 ## [1.2.1] - 2026-03-11
 
 ### Fixed

package/README.md

@@ -1,6 +1,6 @@
 # @socialneuron/mcp-server
 
-> 51 MCP tools for AI-powered social media management. Create content, schedule posts, track analytics, and optimize performance — all from Claude Code or any MCP client.
+> 52 MCP tools for AI-powered social media management. Create content, schedule posts, track analytics, and optimize performance — all from Claude Code or any MCP client.
 
 [![npm version](https://img.shields.io/npm/v/@socialneuron/mcp-server)](https://www.npmjs.com/package/@socialneuron/mcp-server)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -13,7 +13,7 @@
 npx -y @socialneuron/mcp-server login --device
 ```
 
-This opens your browser to authorize access. Requires a Social Neuron plan ([free trial available](https://socialneuron.com/pricing)).
+This opens your browser to authorize access. Requires a paid Social Neuron plan (Starter or above). See [pricing](https://socialneuron.com/pricing).
 
 ### 2. Add to Claude Code
 
@@ -92,7 +92,7 @@ Ask Claude things like:
 - "Check my analytics and suggest improvements"
 - "Set up autopilot to post 3 times per week"
 
-## Tool Categories (51 tools)
+## Tool Categories (52 tools)
 
 These tools are available to AI agents (Claude, Cursor, etc.) via the MCP protocol.
 
@@ -128,6 +128,7 @@ These tools are available to AI agents (Claude, Cursor, etc.) via the MCP protoc
 | Remotion | list_compositions, render_demo_video | Programmatic video rendering |
 | Usage | get_mcp_usage | API usage monitoring |
 | YouTube | fetch_youtube_analytics | YouTube-specific deep analytics |
+| Discovery | search_tools | Find tools by keyword with progressive detail levels (saves 98% tokens vs loading all tools) |
 
 ## Authentication
 
@@ -141,13 +142,13 @@ npx -y @socialneuron/mcp-server login --device
 
 Opens browser, you approve, CLI receives API key automatically.
 
-### PKCE Browser Flow
+### Browser Flow
 
 ```bash
 npx -y @socialneuron/mcp-server login
 ```
 
-Browser-based OAuth flow with PKCE challenge.
+Browser-based OAuth flow.
 
 ### API Key Paste
 
@@ -163,14 +164,16 @@ Keys are stored in your OS keychain (macOS Keychain, Linux secret-tool) or file
 
 ## Pricing
 
+MCP access requires a paid plan:
+
 | Plan | Price | Credits/mo | MCP Access |
 |------|-------|-----------|------------|
-| Trial | Free (7 days) | 500 | Read + Write + Analytics + Comments |
+| Free | $0 | 100 | — |
 | Starter | $29/mo | 800 | Read + Analytics |
 | Pro | $79/mo | 2,000 | Full access |
 | Team | $199/mo | 6,500 | Full access + Multi-user |
 
-Start with a [free trial](https://socialneuron.com/pricing) — no credit card required.
+Sign up at [socialneuron.com/pricing](https://socialneuron.com/pricing).
 
 ## Scopes
 
@@ -212,6 +215,15 @@ socialneuron-mcp sn usage
 socialneuron-mcp sn loop
 socialneuron-mcp sn credits
 
+# Agent-native CLI v2
+socialneuron-mcp sn tools [--module ideation] [--scope mcp:write]  # List/filter all 52 tools
+socialneuron-mcp sn info                                            # Version, auth, credits, tool count
+socialneuron-mcp sn plan list|view|approve                          # Content plan management
+socialneuron-mcp sn preset list|show|save|delete                    # Platform presets (6 built-in)
+
+# Interactive REPL
+socialneuron-mcp repl
+
 # Add --json to any command for machine-readable output
 ```
 

package/dist/http.js

@@ -618,7 +618,8 @@ var TOOL_SCOPES = {
   schedule_content_plan: "mcp:distribute",
   // mcp:read (usage is read-only)
   get_mcp_usage: "mcp:read",
-  list_plan_approvals: "mcp:read"
+  list_plan_approvals: "mcp:read",
+  search_tools: "mcp:read"
 };
 function hasScope(userScopes, required) {
   if (userScopes.includes(required)) return true;
@@ -1287,11 +1288,11 @@ function asEnvelope(data) {
   };
 }
 var VIDEO_CREDIT_ESTIMATES = {
-  "veo3-fast": 156,
-  "veo3-quality": 780,
-  "runway-aleph": 260,
-  sora2: 390,
-  "sora2-pro": 1170,
+  "veo3-fast": 200,
+  "veo3-quality": 1e3,
+  "runway-aleph": 340,
+  sora2: 500,
+  "sora2-pro": 1500,
   kling: 170,
   "kling-3": 100,
   "kling-3-pro": 135
@@ -6214,7 +6215,7 @@ init_supabase();
 import { z as z14 } from "zod";
 
 // src/lib/version.ts
-var MCP_VERSION = "1.2.1";
+var MCP_VERSION = "1.3.0";
 
 // src/tools/usage.ts
 function asEnvelope10(data) {
@@ -7883,6 +7884,408 @@ function registerPlanApprovalTools(server) {
   );
 }
 
+// src/tools/discovery.ts
+import { z as z20 } from "zod";
+
+// src/lib/tool-catalog.ts
+var TOOL_CATALOG = [
+  // ideation
+  {
+    name: "generate_content",
+    description: "Generate social media content ideas based on brand profile and trends",
+    module: "ideation",
+    scope: "mcp:write"
+  },
+  {
+    name: "fetch_trends",
+    description: "Fetch current trending topics for content ideation",
+    module: "ideation",
+    scope: "mcp:read"
+  },
+  // ideation-context
+  {
+    name: "get_ideation_context",
+    description: "Get full ideation context including brand, analytics, and trends",
+    module: "ideation-context",
+    scope: "mcp:read"
+  },
+  // content
+  {
+    name: "adapt_content",
+    description: "Adapt existing content for different platforms",
+    module: "content",
+    scope: "mcp:write"
+  },
+  {
+    name: "generate_video",
+    description: "Generate video content using AI",
+    module: "content",
+    scope: "mcp:write"
+  },
+  {
+    name: "generate_image",
+    description: "Generate images using AI",
+    module: "content",
+    scope: "mcp:write"
+  },
+  {
+    name: "check_status",
+    description: "Check status of async content generation job",
+    module: "content",
+    scope: "mcp:write"
+  },
+  {
+    name: "create_storyboard",
+    description: "Create a video storyboard with scenes and shots",
+    module: "content",
+    scope: "mcp:write"
+  },
+  {
+    name: "generate_voiceover",
+    description: "Generate AI voiceover audio",
+    module: "content",
+    scope: "mcp:write"
+  },
+  {
+    name: "generate_carousel",
+    description: "Generate carousel/slide content",
+    module: "content",
+    scope: "mcp:write"
+  },
+  // distribution
+  {
+    name: "schedule_post",
+    description: "Schedule content for publishing to social platforms",
+    module: "distribution",
+    scope: "mcp:distribute"
+  },
+  {
+    name: "list_recent_posts",
+    description: "List recently published or scheduled posts",
+    module: "distribution",
+    scope: "mcp:read"
+  },
+  {
+    name: "list_connected_accounts",
+    description: "List connected social media accounts",
+    module: "distribution",
+    scope: "mcp:read"
+  },
+  // analytics
+  {
+    name: "fetch_analytics",
+    description: "Fetch post performance analytics",
+    module: "analytics",
+    scope: "mcp:read"
+  },
+  {
+    name: "refresh_platform_analytics",
+    description: "Refresh analytics data from connected platforms",
+    module: "analytics",
+    scope: "mcp:analytics"
+  },
+  // insights
+  {
+    name: "get_performance_insights",
+    description: "Get AI-generated performance insights",
+    module: "insights",
+    scope: "mcp:read"
+  },
+  {
+    name: "get_best_posting_times",
+    description: "Get recommended posting times based on audience data",
+    module: "insights",
+    scope: "mcp:read"
+  },
+  // brand
+  {
+    name: "extract_brand",
+    description: "Extract brand identity from URL or text",
+    module: "brand",
+    scope: "mcp:read"
+  },
+  {
+    name: "get_brand_profile",
+    description: "Get the current brand profile",
+    module: "brand",
+    scope: "mcp:read"
+  },
+  {
+    name: "save_brand_profile",
+    description: "Save or update brand profile",
+    module: "brand",
+    scope: "mcp:write"
+  },
+  {
+    name: "update_platform_voice",
+    description: "Update platform-specific brand voice settings",
+    module: "brand",
+    scope: "mcp:write"
+  },
+  // screenshot
+  {
+    name: "capture_screenshot",
+    description: "Capture a screenshot of a URL",
+    module: "screenshot",
+    scope: "mcp:read"
+  },
+  {
+    name: "capture_app_page",
+    description: "Capture a screenshot of an app page",
+    module: "screenshot",
+    scope: "mcp:read"
+  },
+  // remotion
+  {
+    name: "render_demo_video",
+    description: "Render a demo video using Remotion",
+    module: "remotion",
+    scope: "mcp:write"
+  },
+  {
+    name: "list_compositions",
+    description: "List available Remotion video compositions",
+    module: "remotion",
+    scope: "mcp:read"
+  },
+  // youtube-analytics
+  {
+    name: "fetch_youtube_analytics",
+    description: "Fetch YouTube channel analytics data",
+    module: "youtube-analytics",
+    scope: "mcp:analytics"
+  },
+  // comments
+  {
+    name: "list_comments",
+    description: "List comments on published posts",
+    module: "comments",
+    scope: "mcp:comments"
+  },
+  {
+    name: "reply_to_comment",
+    description: "Reply to a comment on a post",
+    module: "comments",
+    scope: "mcp:comments"
+  },
+  {
+    name: "post_comment",
+    description: "Post a new comment",
+    module: "comments",
+    scope: "mcp:comments"
+  },
+  {
+    name: "moderate_comment",
+    description: "Moderate a comment (approve/hide/flag)",
+    module: "comments",
+    scope: "mcp:comments"
+  },
+  {
+    name: "delete_comment",
+    description: "Delete a comment",
+    module: "comments",
+    scope: "mcp:comments"
+  },
+  // planning
+  {
+    name: "plan_content_week",
+    description: "Generate a weekly content plan",
+    module: "planning",
+    scope: "mcp:write"
+  },
+  {
+    name: "save_content_plan",
+    description: "Save a content plan",
+    module: "planning",
+    scope: "mcp:write"
+  },
+  {
+    name: "get_content_plan",
+    description: "Get a specific content plan by ID",
+    module: "planning",
+    scope: "mcp:read"
+  },
+  {
+    name: "update_content_plan",
+    description: "Update an existing content plan",
+    module: "planning",
+    scope: "mcp:write"
+  },
+  {
+    name: "submit_content_plan_for_approval",
+    description: "Submit a content plan for team approval",
+    module: "planning",
+    scope: "mcp:write"
+  },
+  {
+    name: "schedule_content_plan",
+    description: "Schedule all posts in an approved content plan",
+    module: "planning",
+    scope: "mcp:distribute"
+  },
+  {
+    name: "find_next_slots",
+    description: "Find next available scheduling slots",
+    module: "planning",
+    scope: "mcp:read"
+  },
+  // plan-approvals
+  {
+    name: "create_plan_approvals",
+    description: "Create approval requests for a content plan",
+    module: "plan-approvals",
+    scope: "mcp:write"
+  },
+  {
+    name: "respond_plan_approval",
+    description: "Respond to a plan approval request",
+    module: "plan-approvals",
+    scope: "mcp:write"
+  },
+  {
+    name: "list_plan_approvals",
+    description: "List pending plan approval requests",
+    module: "plan-approvals",
+    scope: "mcp:read"
+  },
+  // quality
+  {
+    name: "quality_check",
+    description: "Run quality checks on content before publishing",
+    module: "quality",
+    scope: "mcp:read"
+  },
+  {
+    name: "quality_check_plan",
+    description: "Run quality checks on an entire content plan",
+    module: "quality",
+    scope: "mcp:read"
+  },
+  // credits
+  {
+    name: "get_credit_balance",
+    description: "Get current credit balance",
+    module: "credits",
+    scope: "mcp:read"
+  },
+  {
+    name: "get_budget_status",
+    description: "Get budget and spending status",
+    module: "credits",
+    scope: "mcp:read"
+  },
+  // autopilot
+  {
+    name: "list_autopilot_configs",
+    description: "List autopilot configurations",
+    module: "autopilot",
+    scope: "mcp:autopilot"
+  },
+  {
+    name: "update_autopilot_config",
+    description: "Update autopilot configuration",
+    module: "autopilot",
+    scope: "mcp:autopilot"
+  },
+  {
+    name: "get_autopilot_status",
+    description: "Get current autopilot status",
+    module: "autopilot",
+    scope: "mcp:autopilot"
+  },
+  // extraction
+  {
+    name: "extract_url_content",
+    description: "Extract content from a URL for repurposing",
+    module: "extraction",
+    scope: "mcp:read"
+  },
+  // loop-summary
+  {
+    name: "get_loop_summary",
+    description: "Get growth loop summary and recommendations",
+    module: "loop-summary",
+    scope: "mcp:read"
+  },
+  // usage
+  {
+    name: "get_mcp_usage",
+    description: "Get MCP usage statistics for the current billing period",
+    module: "usage",
+    scope: "mcp:read"
+  },
+  // discovery
+  {
+    name: "search_tools",
+    description: "Search and discover available MCP tools",
+    module: "discovery",
+    scope: "mcp:read"
+  }
+];
+function getToolsByModule(module) {
+  return TOOL_CATALOG.filter((t) => t.module === module);
+}
+function getToolsByScope(scope) {
+  return TOOL_CATALOG.filter((t) => t.scope === scope);
+}
+function searchTools(query) {
+  const q = query.toLowerCase();
+  return TOOL_CATALOG.filter(
+    (t) => t.name.toLowerCase().includes(q) || t.description.toLowerCase().includes(q)
+  );
+}
+
+// src/tools/discovery.ts
+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).',
+    {
+      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")'),
+      scope: z20.string().optional().describe('Filter by required scope (e.g. "mcp:read", "mcp:write")'),
+      detail: z20.enum(["name", "summary", "full"]).default("summary").describe(
+        'Detail level: "name" for just tool names, "summary" for names + descriptions, "full" for complete info including scope and module'
+      )
+    },
+    async ({ query, module, scope, detail }) => {
+      let results = [...TOOL_CATALOG];
+      if (query) {
+        results = searchTools(query);
+      }
+      if (module) {
+        const moduleTools = getToolsByModule(module);
+        results = results.filter((t) => moduleTools.some((mt) => mt.name === t.name));
+      }
+      if (scope) {
+        const scopeTools = getToolsByScope(scope);
+        results = results.filter((t) => scopeTools.some((st) => st.name === t.name));
+      }
+      let output;
+      switch (detail) {
+        case "name":
+          output = results.map((t) => t.name);
+          break;
+        case "summary":
+          output = results.map((t) => ({ name: t.name, description: t.description }));
+          break;
+        case "full":
+        default:
+          output = results;
+          break;
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify({ toolCount: results.length, tools: output }, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
 // src/lib/register-tools.ts
 function applyScopeEnforcement(server, scopeResolver) {
   const originalTool = server.tool.bind(server);
@@ -7946,6 +8349,7 @@ function registerAllTools(server, options) {
   registerQualityTools(server);
   registerPlanningTools(server);
   registerPlanApprovalTools(server);
+  registerDiscoveryTools(server);
 }
 
 // src/http.ts