@socialneuron/mcp-server 1.7.2 → 1.7.4

package/CHANGELOG.md

@@ -2,34 +2,140 @@
 
 All notable changes to `@socialneuron/mcp-server` will be documented in this file.
 
+## [1.7.3] - 2026-04-04
+
+### Security
+- **Full error sanitization**: `sanitizeError()` applied across all 15 catch blocks in 9 tool files + `http.ts` global error handler. No internal paths, table names, or stack traces leak to clients.
+- **R2 key masking**: R2 storage keys are masked in all text output to prevent path disclosure.
+
+### Added
+- **`upload_media` tool**: Upload local files or URLs to R2 storage for use in posts.
+- **`get_media_url` tool**: Generate signed URLs for R2-stored media.
+- **`schedule_post` enhancements**: Now accepts `r2_key`/`r2_keys`, `job_id`/`job_ids`, and typed `platform_metadata` — enables seamless generate-upload-post pipeline.
+- **`check_status` enhancements**: Returns `all_urls` for multi-output jobs, presigned PUT URL support.
+- **Brand consistency scoring**: New `brandScoring.ts` + `brandRuntime.ts` modules with multi-dimensional brand alignment scoring.
+
+### Fixed
+- Duplicate `sanitizeError` import removed.
+
+### Changed
+- `MCP_VERSION` bumped to `1.7.3`.
+- Removed `api/` directory (OpenAPI spec, router, tool-executor) — REST convenience routes consolidated into `http.ts`.
+- Removed `cli/sn/completions.ts`, `cli/sn/generate.ts`, `cli/sn/parse.ts` — CLI streamlined.
+- Removed `lib/tool-errors.ts` — error handling consolidated into `sanitizeError`.
+
 ## [1.7.0] - 2026-04-03
 
 ### Added
+- 12 new tools (52 → 64): brandRuntime (3), pipeline (4), suggest (1), digest (2), remotion (+1), autopilot (+1)
+- `/.well-known/mcp/server-card.json` endpoint for Smithery marketplace discovery
+- `/config` endpoint for cloud-mode connection info (replaces hardcoded credentials)
+- MCP tool safety annotations for Anthropic Connectors Directory
+- Response truncation (100K char limit)
+
+### Security
+- Cloud config fetched at startup from `/config` endpoint (rotatable without npm republish)
+- Supabase anon key (public, RLS-gated) restored with documentation — service role key remains env-only
+
+### Dependencies
+- `@modelcontextprotocol/sdk` 1.27 → 1.29
+- `@supabase/supabase-js` 2.99 → 2.101
+- `jose` 6.2.1 → 6.2.2
 
-- **`/config` endpoint**: Returns server configuration (tools count, version, capabilities) without authentication
-- **Rate limit exemptions**: `/config`, `/health`, and `/.well-known/` paths bypass rate limiting
-- **All tools migrated to gateway**: 13 tool files moved from `getSupabaseClient()` to `callEdgeFunction('mcp-data', ...)` — tools now work in cloud mode (API key users)
-- **REST API layer**: Universal tool proxy (`POST /v1/tools/:name`), 15 convenience endpoints, OpenAPI 3.1 spec
-- **64 tools** (was 52): distribution, media, and configuration tools added
-- **mcp-data gateway**: 17 new actions added for cloud-mode tool execution
+## [1.6.1] - 2026-03-22
+
+### Security
+- **Explicit body size limit**: `express.json({ limit: '50kb' })` prevents DoS via oversized payloads.
+- **Error message sanitization**: MCP POST catch block now uses `sanitizeError()` — no more internal paths or table names in error responses.
+- **PII removal**: Removed `email` from API key validation chain (7 files). Key validation no longer exposes user email addresses.
+- **Generation rate limiting**: Added explicit `generation` category at 20 req/min (previously fell back to `read` at 60/min).
+- **npm provenance**: Added `--provenance` flag and `id-token: write` permission to release workflow for supply chain verification.
+- **Security comment**: Documented that Edge Functions must not trust `x-internal-worker-call` header without Bearer token verification.
 
 ### Fixed
+- **hono prototype pollution**: Updated transitive dependency to fix GHSA-v8w9-8mx6-g223.
+- `npm audit` now reports 0 vulnerabilities.
 
-- **Smithery OAuth**: `/register` now allows all HTTPS redirect URIs per MCP spec (was Claude-only)
-- **Zod 4 compatibility**: Upgraded zod 3→4 for SDK v1.27 compatibility
-- **Express middleware**: Added express-rate-limit + cors as direct dependencies
+### Added
+- 18 examples (8 REST curl, 5 TypeScript SDK, 4 CLI, 1 MCP prompts).
+- TypeScript SDK package (`packages/sdk/`) with 9 resource classes.
+- CLI tab completion and content generation commands.
+- SDK documentation and release workflow.
 
-### Security
+## [1.6.0] - 2026-03-21
 
-- 50kb body limit on all endpoints
-- `sanitizeError` on /mcp catch path
-- Email removed from auth chain
-- Generation rate limit 20/min
+### Added
+- **REST API layer**: Universal tool proxy at `POST /v1/tools/:name` — call any of the 52 MCP tools via standard HTTP REST. No MCP client required.
+- **OpenAPI 3.1 spec**: Auto-generated from TOOL_CATALOG at `/openapi.json` — always in sync with tools.
+- **15 convenience endpoints**: Resource-oriented routes for common operations (`/v1/credits`, `/v1/content/generate`, `/v1/posts`, etc.).
+- **Express HTTP transport**: New `dist/http.js` entry point for running as a standalone REST API server.
+- **MCP Registry metadata**: `server.json` with mcpName, endpoints, env, and auth configuration for registry discovery.
+- **Cursor Directory manifest**: Plugin manifest for Cursor IDE integration.
 
-### Internal
+### Fixed
+- **TS2345**: Cast Express route param to string for strict TypeScript compatibility.
+- **npm publish 404**: Removed `--provenance` flag from release workflow (incompatible with scoped packages on granular tokens).
 
-- 64 tools, 900+ tests, ~375KB build
-- OpenAPI 3.1 spec auto-generated from tool schemas
+### Changed
+- Dual transport support: MCP (stdio) and HTTP (Express) from a single codebase.
+- SECURITY.md updated with v1.6.x in supported versions.
+- `docs/auth.md` domain reference corrected (`www.socialneuron.com` → `socialneuron.com`).
+
+## [1.5.2] - 2026-03-20
+
+### Added
+- **Error recovery hints**: All 47 error paths now include actionable recovery guidance — agents know what to call next when something fails (e.g., "Call get_credit_balance to check remaining credits" or "Verify platform OAuth with list_connected_accounts").
+- Central `formatToolError()` helper with 9 error categories: rate limits, credits, OAuth, generation, not-found, access, SSRF, scheduling, and plan validation.
+- 18 new tests for error recovery formatting.
+
+## [1.5.1] - 2026-03-20
+
+### Added
+- **MCP tool annotations**: All 52 tools now declare `readOnlyHint`, `destructiveHint`, `idempotentHint`, and `openWorldHint` per MCP spec. Agents can now determine which tools are safe to call without confirmation.
+- **Complete parameter descriptions**: Added `.describe()` to all remaining parameters (248 total). Every parameter now has format examples, constraints, and usage guidance.
+
+### Changed
+- Updated test setup to support 5-argument `server.tool()` signature with annotations.
+
+## [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
+- **Telemetry is now opt-IN**: No data is sent unless `SOCIALNEURON_TELEMETRY=1` is explicitly set. Previously telemetry was opt-out.
+- **PostHog moved to optionalDependencies**: `posthog-node` is no longer a required runtime dependency. The package works fully without it installed. This reduces supply chain surface and resolves socket.dev security flags.
+- **Dynamic import**: PostHog is loaded via `import()` at runtime, silently skipped if unavailable.
+- `DO_NOT_TRACK=1` continues to override and disable telemetry in all cases.
+
+## [1.3.2] - 2026-03-13
+
+### Fixed
+- **TypeScript strict mode**: Added `@types/express`, fixed `AuthenticatedRequest` type to extend express `Request`, corrected `StreamableHTTPServerTransport` constructor usage
+- **Optional dependency stubs**: Added ambient declarations for `playwright`, `@remotion/bundler`, `@remotion/renderer` (dynamically imported, not required at runtime)
+- **Removed unused directive**: Cleaned up stale `@ts-expect-error` in REPL module
+- **Release CI**: Typecheck now passes in GitHub Actions release workflow
+
+## [1.3.1] - 2026-03-13
+
+### Fixed
+- **zod v4 compatibility**: Updated `zod` dependency from v3 to v4 to match `@modelcontextprotocol/sdk` peer requirement, fixing `ERR_PACKAGE_PATH_NOT_EXPORTED` crash on `npx` install
+- **Test domain**: Fixed test fixtures using deprecated `socialneuron.ai` domain (now `socialneuron.com`)
+- **CLI E2E timeout**: Increased envelope test timeout to avoid false failures
 
 ## [1.3.0] - 2026-03-13
 

package/README.md

@@ -1,13 +1,26 @@
 # @socialneuron/mcp-server
 
-> 63 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.
+> 64 tools for AI-powered social media management. MCP, REST API, CLI — create content, schedule posts, track analytics, and optimize performance.
 
 [![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)
 
+## Integration Methods
+
+| Method | Best For | Docs |
+|--------|----------|------|
+| **MCP** | AI agents (Claude, Cursor, VS Code) | [Setup](#quick-start) |
+| **REST API** | Any HTTP client, webhooks, Zapier | [Guide](docs/rest-api.md) |
+| **CLI** | Terminal, CI/CD pipelines | [Guide](docs/cli-guide.md) |
+| **SDK** | TypeScript/Node.js apps | Coming Q2 2026 |
+
+All methods share the same 64 tools, auth, scopes, and credit system. [Compare methods](docs/integration-methods.md).
+
 ## Quick Start
 
-### 1. Authenticate
+### MCP (AI Agents)
+
+#### 1. Authenticate
 
 ```bash
 npx -y @socialneuron/mcp-server login --device
@@ -15,7 +28,7 @@ npx -y @socialneuron/mcp-server login --device
 
 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
+#### 2. Add to Claude Code
 
 ```bash
 claude mcp add socialneuron -- npx -y @socialneuron/mcp-server
@@ -76,10 +89,42 @@ Add to `.cursor/mcp.json` in your workspace:
 ```
 </details>
 
-### 3. Start using
+#### 3. Start using
 
 Ask Claude: "What content should I post this week?" or "Schedule my latest video to YouTube and TikTok"
 
+### REST API (Any Language)
+
+```bash
+# Check credits
+curl -H "Authorization: Bearer snk_live_..." \
+  https://mcp.socialneuron.com/v1/credits
+
+# Generate content
+curl -X POST -H "Authorization: Bearer snk_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{"topic": "AI trends", "platforms": ["linkedin"]}' \
+  https://mcp.socialneuron.com/v1/content/generate
+
+# Execute any tool via proxy
+curl -X POST -H "Authorization: Bearer snk_live_..." \
+  -H "Content-Type: application/json" \
+  -d '{"response_format": "json"}' \
+  https://mcp.socialneuron.com/v1/tools/get_brand_profile
+```
+
+See [REST API docs](docs/rest-api.md) | [OpenAPI spec](https://mcp.socialneuron.com/v1/openapi.json) | [Examples](examples/rest/)
+
+### CLI (Terminal & CI/CD)
+
+```bash
+npx @socialneuron/mcp-server sn system credits --json
+npx @socialneuron/mcp-server sn analytics loop --json
+npx @socialneuron/mcp-server sn discovery tools --module content
+```
+
+See [CLI guide](docs/cli-guide.md) | [Examples](examples/cli/)
+
 ## What You Can Do
 
 Ask Claude things like:
@@ -92,9 +137,9 @@ Ask Claude things like:
 - "Check my analytics and suggest improvements"
 - "Set up autopilot to post 3 times per week"
 
-## Tool Categories (63 tools)
+## Tool Categories (64 tools)
 
-These tools are available to AI agents (Claude, Cursor, etc.) via the MCP protocol.
+All tools are accessible via MCP, REST API (`POST /v1/tools/{name}`), and CLI.
 
 ### Content Lifecycle
 
@@ -216,7 +261,7 @@ socialneuron-mcp sn loop
 socialneuron-mcp sn credits
 
 # Agent-native CLI v2
-socialneuron-mcp sn tools [--module ideation] [--scope mcp:write]  # List/filter all 63 tools
+socialneuron-mcp sn tools [--module ideation] [--scope mcp:write]  # List/filter all 64 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)
@@ -250,37 +295,50 @@ Each iteration produces smarter content as performance data feeds back into the
 - 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
+- Telemetry is off by default — opt in with `SOCIALNEURON_TELEMETRY=1`
 
 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.
+Telemetry is **off by default**. No data is collected unless you explicitly opt in.
+
+**To enable**: Set `SOCIALNEURON_TELEMETRY=1` in your environment.
 
-**To disable**: Set `DO_NOT_TRACK=1` or `SOCIALNEURON_NO_TELEMETRY=1` in your environment.
+**To disable**: `DO_NOT_TRACK=1` or `SOCIALNEURON_NO_TELEMETRY=1` always disables telemetry, even if `SOCIALNEURON_TELEMETRY=1` is set.
 
-No personal content, API keys, or request payloads are ever collected.
+When enabled, the following anonymous metrics are collected via PostHog:
+- Tool name invoked
+- Success or failure status
+- Invocation duration (ms)
+
+No personal content, API keys, or request payloads are ever collected. Your user ID is hashed (SHA-256) before transmission.
+
+`posthog-node` is an optional dependency — if it is not installed, telemetry is a silent no-op regardless of environment variables.
 
 ## Examples
 
-See the [examples repo](https://github.com/socialneuron/examples) for prompt-driven workflow templates:
+See the [`examples/`](examples/) directory:
 
-- Weekly content batch planning
-- Cross-platform content repurposing
+- [REST API examples](examples/rest/) — curl scripts for every endpoint
+- [CLI examples](examples/cli/) — automation workflows
+- [MCP prompts](examples/mcp/claude-prompts.md) — natural language examples
+- [External examples repo](https://github.com/socialneuron/examples) — prompt-driven workflow templates
 - Performance review and optimization loops
 - Brand-aligned content generation
 - Comment engagement automation
 
 ## Links
 
-- [Social Neuron](https://socialneuron.com)
-- [For Developers](https://socialneuron.com/for-developers)
+- [For Developers](https://socialneuron.com/for-developers) — Integration methods, tools, pricing
+- [REST API Docs](docs/rest-api.md) — Endpoint reference
+- [CLI Guide](docs/cli-guide.md) — Terminal commands
+- [Integration Methods](docs/integration-methods.md) — Compare MCP vs REST vs CLI
+- [OpenAPI Spec](https://mcp.socialneuron.com/v1/openapi.json) — Machine-readable API spec
+- [Developer Settings](https://socialneuron.com/settings/developer) — Generate API keys
 - [Documentation](https://socialneuron.com/docs)
-- [Examples](https://github.com/socialneuron/examples)
-- [Agent Protocol](https://socialneuron.com/system-prompt.txt)
-- [Developer Settings](https://socialneuron.com/settings/developer)
 - [Pricing](https://socialneuron.com/pricing)
+- [Agent Protocol](https://socialneuron.com/system-prompt.txt)
 
 ## License