@socialneuron/mcp-server 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -2,6 +2,47 @@
 
 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
+
+- **README**: Removed phantom "MCP API $19/mo" plan — pricing now matches actual tiers (Trial/Starter/Pro/Team)
+- **README**: Rewrote scopes section with tool-to-scope mapping
+- **README**: Security section now shows trust signals instead of implementation internals
+- **README**: Added telemetry section with opt-out instructions (`DO_NOT_TRACK=1`)
+- **README**: Added MCP vs CLI distinction, npx usage note, fixed tool count to 51
+- **Device auth**: Removed decorative PKCE from device code flow (code_challenge was sent but never verified on exchange)
+- **Logout**: Message now honestly says "removed from this device" with link to server-side revocation
+- **LICENSE**: Added trade name "(trading as Social Neuron)" to copyright holder
+- **SECURITY.md**: Removed phantom 1.1.x from supported versions (never published to npm)
+- **CONTRIBUTING.md**: Added Developer Certificate of Origin (DCO) section
+
 ## [1.2.0] - 2026-03-10
 
 ### Added

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Cosmocodex Ltd
+Copyright (c) 2026 Cosmocodex Ltd (trading as Social Neuron)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,6 +1,6 @@
 # @socialneuron/mcp-server
 
-> 50+ 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 paid Social Neuron plan (MCP API $19/mo or higher).
+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,9 @@ 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.
 
 ### Content Lifecycle
 
@@ -126,6 +128,7 @@ Ask Claude things like:
 | 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
 
@@ -139,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
 
@@ -161,31 +164,38 @@ Keys are stored in your OS keychain (macOS Keychain, Linux secret-tool) or file
 
 ## Pricing
 
-MCP access requires a paid Social Neuron plan:
+MCP access requires a paid plan:
 
-| Plan    | Price   | MCP Scopes               | Credits |
-| ------- | ------- | ------------------------ | ------- |
-| MCP API | $19/mo  | Full access              | 400     |
-| Starter | $29/mo  | Read + Analytics         | 800     |
-| Pro     | $79/mo  | Full access              | 2,000   |
-| Team    | $199/mo | Full access + Multi-user | 6,500   |
+| Plan | Price | Credits/mo | MCP Access |
+|------|-------|-----------|------------|
+| 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 |
 
-**No free tier for MCP.** Sign up at [socialneuron.com/pricing](https://socialneuron.com/pricing).
+Sign up at [socialneuron.com/pricing](https://socialneuron.com/pricing).
 
 ## Scopes
 
-| Scope            | Access                                 |
-| ---------------- | -------------------------------------- |
-| `mcp:full`       | All operations                         |
-| `mcp:read`       | Read-only (analytics, insights, lists) |
-| `mcp:write`      | Content generation                     |
-| `mcp:distribute` | Publishing and scheduling              |
-| `mcp:analytics`  | Performance data                       |
-| `mcp:comments`   | Social engagement                      |
-| `mcp:autopilot`  | Automated scheduling                   |
+Each API key inherits scopes from your plan. Tools require specific scopes to execute.
+
+| Scope | What you can do |
+|-------|----------------|
+| `mcp:read` | Analytics, insights, brand profiles, content plans, quality checks, screenshots, usage stats, credit balance |
+| `mcp:write` | Generate content (video, image, voiceover, carousel), create storyboards, save brand profiles, plan content |
+| `mcp:distribute` | Schedule posts, publish content plans |
+| `mcp:analytics` | Refresh analytics, YouTube deep analytics |
+| `mcp:comments` | List, reply, post, moderate, delete comments |
+| `mcp:autopilot` | Configure and monitor automated scheduling |
+| `mcp:full` | All of the above |
 
 ## CLI Reference
 
+These commands run directly in your terminal — no AI agent needed. Useful for scripts, CI/CD, and quick checks.
+
+> After global install (`npm i -g @socialneuron/mcp-server`), use `socialneuron-mcp` directly.
+> Otherwise, prefix with `npx @socialneuron/mcp-server`.
+
 ```bash
 # Auth
 socialneuron-mcp login [--device|--paste]
@@ -205,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
 ```
 
@@ -226,13 +245,22 @@ Each iteration produces smarter content as performance data feeds back into the
 
 ## Security
 
-- API keys are SHA-256 hashed with random salt before storage
-- PKCE (S256) challenge verification for browser auth
-- Timing-safe hash comparison prevents side-channel attacks
-- SSRF protection on all URL parameters
-- Rate limiting: 100 req/min per user, per-tool limits for expensive operations
-- Agent loop detection (>5 identical calls in 30s)
-- Credentials stored in OS keychain (macOS/Linux) or env var. On Windows, use `SOCIALNEURON_API_KEY` env var for secure storage
+- All API keys are hashed before storage — we never store plaintext keys
+- Credentials stored in your OS keychain (macOS Keychain, Linux secret-tool) or environment variable
+- SSRF protection on all URL parameters with DNS rebinding prevention
+- Rate limiting per user with per-tool limits for expensive operations
+- Agent loop detection prevents runaway automation
+- Set `DO_NOT_TRACK=1` to disable anonymous usage telemetry
+
+See [SECURITY.md](./SECURITY.md) for our vulnerability disclosure policy and credential safety details.
+
+## Telemetry
+
+This package collects anonymous usage metrics (tool name, duration, success/failure) to improve the product. Your user ID is hashed before transmission.
+
+**To disable**: Set `DO_NOT_TRACK=1` or `SOCIALNEURON_NO_TELEMETRY=1` in your environment.
+
+No personal content, API keys, or request payloads are ever collected.
 
 ## Examples
 

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.0";
+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