@socialneuron/mcp-server 1.7.3 → 1.7.5

package/CHANGELOG.md

@@ -2,34 +2,170 @@
 
 All notable changes to `@socialneuron/mcp-server` will be documented in this file.
 
-## [1.7.0] - 2026-04-03
+## [1.7.5] - 2026-04-22
 
 ### Added
+- **`upload_media` base64 path**: new optional `file_data` + `file_name` params let Claude Desktop, Claude Web, and other remote agents upload bytes directly without a filesystem path. Content-type is validated against an allowlist, base64 charset is checked, and decoded size is capped at 10MB before the Edge Function call. `file_name` is `basename()`-sanitized.
+- **`schedule_post` auto-rehost**: any `media_url` / `media_urls` / `job_id` result URL that is not already R2-signed is automatically persisted into R2 via `upload-to-r2` before posting. Keeps scheduled posts alive past ephemeral-URL expiry (Replicate, OpenAI, DALL-E, kie.ai) and feeds byte-upload platforms (X, LinkedIn, YouTube, Bluesky). New optional `auto_rehost` parameter (default: true) opts out.
+- **`create_carousel` meta-tool** (from v1.7.4): Brand-aware carousel generation that composes `generate_image` with brand color/tone constraints and auto-exports to R2. Catalog now at **73 tools**.
+- **Brand runtime scoring**: `brandScoring.ts` + `colorAudit.ts` modules power multi-dimensional brand alignment checks used by the carousel meta-tool.
+
+### Security
+- **npm Trusted Publishing (OIDC)**: Release workflow publishes to npm via OIDC — no long-lived `NPM_TOKEN` secret. Package ships with SLSA provenance.
+- **Production environment gate**: Release workflow requires manual approval of the `production` environment before publishing.
+- **Perimeter hardening (Sprint 1)**: Repo-level `.npmrc` pins registry, disables funding/audit noise in CI, and enforces `save-exact`. `CODEOWNERS` locks security-sensitive paths (workflows, `.npmrc`, `package.json`, `src/auth/`) to `@socialneuron/sn-maintainers`.
+- **Pre-push identity hook**: Blocks pushes from unexpected git identities; ships with a local allowlist.
+- **Lockfile-lint + dependency cooldown**: CI validates `package-lock.json` integrity. Release enforces a 14-day cooldown on new dependency versions (temporarily warn-only for this release during OIDC validation — re-enforced in 1.7.6).
+- **Sealed tools manifest (CVE-2025-6514 mitigation)**: `tools.lock.json` records a sha256 hash of every tool's `name`/`description`/`module`/`scope`. CI `lint:tools` blocks drift between source and manifest. Mitigates tool-poisoning attacks on MCP clients.
+- **SSRF guard on caller URLs**: every URL passed to auto-rehost is validated by `quickSSRFCheck` — rejects localhost, RFC1918 private ranges, link-local, cloud metadata endpoints (AWS/GCP/Azure), embedded credentials, and non-HTTP(S) protocols.
+- **Hono patched**: `hono` override bumped 4.12.12 → 4.12.14 to resolve GHSA-458j-xx4x-4375 (JSX attribute HTML injection, moderate).
+- Covers **11 Dependabot alerts** pinned via npm `overrides` (security patches for transitive deps).
 
-- **`/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
+### Changed
+- `MCP_VERSION` bumped to `1.7.5`.
+- Tool descriptions updated on `upload_media` and `schedule_post.media_url` to tell agents ephemeral URLs are safe to pass directly.
+- CI runners upgraded: `actions/checkout@v6`, `actions/setup-node@v6`.
+- Dependencies: `@supabase/supabase-js` 2.101 → 2.103, `posthog-node` 5.28 → 5.29.2, `hono` → 4.12.14, `@types/node` → 25.6, `typescript` → 6.0, `trufflehog` action → 3.94.2.
 
 ### Fixed
+- Missing `sanitizeError` import on the presigned-PUT error branch of `upload_media`.
+- Release workflow: removed stale `registry-url` directive that blocked OIDC Trusted Publishing.
+- Release workflow: removed broken typecheck gate that blocked publish.
 
-- **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
+## [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.
 
-- 50kb body limit on all endpoints
-- `sanitizeError` on /mcp catch path
-- Email removed from auth chain
-- Generation rate limit 20/min
+### 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.
 
-### Internal
+### 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
+
+## [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.
+
+### 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.
+
+## [1.6.0] - 2026-03-21
 
-- 64 tools, 900+ tests, ~375KB build
-- OpenAPI 3.1 spec auto-generated from tool schemas
+### 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.
+
+### 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).
+
+### 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.
+> 73 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 73 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,11 @@ 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 (73 tools)
+
+> Full machine-readable listing in [`tools.lock.json`](tools.lock.json) (sealed manifest, verified in CI).
 
-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 +263,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 73 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 +297,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 disable**: Set `DO_NOT_TRACK=1` or `SOCIALNEURON_NO_TELEMETRY=1` in your environment.
+**To enable**: Set `SOCIALNEURON_TELEMETRY=1` in your environment.
 
-No personal content, API keys, or request payloads are ever collected.
+**To disable**: `DO_NOT_TRACK=1` or `SOCIALNEURON_NO_TELEMETRY=1` always disables telemetry, even if `SOCIALNEURON_TELEMETRY=1` is set.
+
+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