@socialneuron/mcp-server 1.8.0 → 1.8.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +39 -0
- package/README.md +76 -47
- package/dist/apps/analytics-pulse/mcp-app.html +167 -0
- package/dist/apps/content-calendar/mcp-app.html +475 -0
- package/dist/http.js +2086 -480
- package/dist/index.js +1868 -373
- package/dist/sn.js +1893 -398
- package/package.json +15 -12
- package/tools.lock.json +116 -101
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,45 @@
|
|
|
2
2
|
|
|
3
3
|
All notable changes to `@socialneuron/mcp-server` will be documented in this file.
|
|
4
4
|
|
|
5
|
+
## [1.8.2] - 2026-07-14
|
|
6
|
+
|
|
7
|
+
### Added
|
|
8
|
+
|
|
9
|
+
- **Five project-scoped lifecycle tools.** `cancel_async_job`, `cancel_scheduled_post`, `delete_carousel`, `delete_content_plan`, and `delete_autopilot_config` require explicit confirmation, carry destructive annotations, and are exposed consistently through MCP, REST/OpenAPI, CLI discovery, and typed SDK helpers.
|
|
10
|
+
- **Analytics Pulse and corrected Content Calendar MCP Apps.** Both use scoped backing tools and conversational fallbacks; Calendar quick-create uses a stable idempotency key and rescheduling uses an optimistic concurrency precondition.
|
|
11
|
+
- **Structured async-job billing.** Status and carousel responses expose server-derived reserved, charged, and refunded amounts plus `billing_status` and a stable failure reason.
|
|
12
|
+
- **Living skill retrieval.** `list_skills` merges live guide rows with executable workflows, and `get_skill` returns the full current guide by slug without breaking the existing `run_skill` path.
|
|
13
|
+
|
|
14
|
+
### Security
|
|
15
|
+
|
|
16
|
+
- Failed-job refunds now require explicit debit authority, inspect returned ledger errors, and report `refund_pending` rather than inventing success. Provider/database error strings are removed from public polling responses.
|
|
17
|
+
- Hardened OAuth resource binding, CLI credential-file access, SDK endpoint validation, output scanning, strict base64 handling, publishing provenance/idempotency, and model-visible tool metadata sealing.
|
|
18
|
+
- The version-3 tool manifest now seals every exposure flag, including authenticated-hidden registration, so a tool cannot silently move onto a public surface.
|
|
19
|
+
- Added CodeQL, npm OIDC-only publication, and an exact-tag dependency cooldown exception for this audited release.
|
|
20
|
+
- Hardened hosted connector discovery for Claude/ChatGPT browser origins and both RFC 9728 protected-resource metadata paths. Session caps now reclaim only the least-recently-used idle session and never evict an active request or SSE stream.
|
|
21
|
+
|
|
22
|
+
### Changed
|
|
23
|
+
|
|
24
|
+
- Public transport count is 91 tools (104 sealed surfaces including internal, local-only, and App entries).
|
|
25
|
+
- Brand extraction rejects ambiguous handles instead of guessing DNS names; publishing enables native AI-content disclosures by default while preserving explicit false for verified non-AI media.
|
|
26
|
+
- `check_status` discloses requested-versus-delivered model fallback, and HyperFrames documents the exact `window.__hf` runtime contract.
|
|
27
|
+
- Analytics keeps the newest cumulative snapshot for each `(post_id, platform)` pair before aggregation.
|
|
28
|
+
- The release workflow creates a matching formal GitHub release after npm succeeds and verifies npm/GitHub latest-version consistency.
|
|
29
|
+
|
|
30
|
+
### Release acceptance
|
|
31
|
+
|
|
32
|
+
- Lifecycle deletion/cancellation and failed-job billing are not considered production-verified until the compatible private backend is deployed and the evidence matrix in [`docs/lifecycle-backend-smoke.md`](docs/lifecycle-backend-smoke.md) passes against the hosted authenticated service.
|
|
33
|
+
- Claude/Codex connector compatibility and session reclamation are not considered production-verified until private PR `#2223` is independently approved, deployed, and passes a greater-than-10-session live regression.
|
|
34
|
+
|
|
35
|
+
## [1.8.1] - 2026-07-14
|
|
36
|
+
|
|
37
|
+
### Fixed
|
|
38
|
+
|
|
39
|
+
- **`create_storyboard` empty responses.** The tool now accepts the AI service's canonical `text` response field as well as the legacy `content` field, and reports a real tool error when neither contains a storyboard.
|
|
40
|
+
- **Project isolation across the creative workflow.** `generate_image`, `create_storyboard`, `generate_voiceover`, and `render_hyperframes` now accept `project_id`. Analytics refresh, analytics reads, performance insights, and best-time recommendations are also project-scoped and default to the active project context.
|
|
41
|
+
- **Autopilot run visibility.** `get_autopilot_status` now returns recent runs supplied by the backend instead of replacing them with an empty array.
|
|
42
|
+
- **HyperFrames capability copy.** Removed the obsolete Phase-2/runtime-not-installed warning now that live HyperFrames renders complete successfully, and corrected image/storyboard/voiceover credit descriptions to match the client budget checks.
|
|
43
|
+
|
|
5
44
|
## [1.8.0] - 2026-07-14
|
|
6
45
|
|
|
7
46
|
### Changed
|
package/README.md
CHANGED
|
@@ -1,13 +1,27 @@
|
|
|
1
1
|
# @socialneuron/mcp-server
|
|
2
2
|
|
|
3
|
-
>
|
|
3
|
+
> 91 public 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.
|
|
4
4
|
|
|
5
5
|
[](https://www.npmjs.com/package/@socialneuron/mcp-server)
|
|
6
6
|
[](https://opensource.org/licenses/MIT)
|
|
7
7
|
|
|
8
8
|
## Quick Start
|
|
9
9
|
|
|
10
|
-
### 1.
|
|
10
|
+
### 1. Connect the hosted MCP
|
|
11
|
+
|
|
12
|
+
The hosted endpoint needs no local npm process:
|
|
13
|
+
|
|
14
|
+
```text
|
|
15
|
+
https://mcp.socialneuron.com/mcp
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
- **Claude Web:** open `claude.ai/customize/connectors`, choose **Add custom connector**, enter the URL above, then approve OAuth.
|
|
19
|
+
- **Claude Code:** `claude mcp add --transport http socialneuron https://mcp.socialneuron.com/mcp`
|
|
20
|
+
- **Codex Desktop/CLI:** `codex mcp add socialneuron --url https://mcp.socialneuron.com/mcp`, then `codex mcp login socialneuron` if prompted. Codex Desktop reads the same MCP configuration.
|
|
21
|
+
|
|
22
|
+
### 2. Or run locally over stdio
|
|
23
|
+
|
|
24
|
+
Authenticate first:
|
|
11
25
|
|
|
12
26
|
```bash
|
|
13
27
|
npx -y @socialneuron/mcp-server login --device
|
|
@@ -15,7 +29,7 @@ npx -y @socialneuron/mcp-server login --device
|
|
|
15
29
|
|
|
16
30
|
This opens your browser to authorize access. Requires a Social Neuron Pro plan or higher. See [pricing](https://socialneuron.com/pricing).
|
|
17
31
|
|
|
18
|
-
|
|
32
|
+
Then add the local process to Claude Code:
|
|
19
33
|
|
|
20
34
|
```bash
|
|
21
35
|
claude mcp add socialneuron -- npx -y @socialneuron/mcp-server
|
|
@@ -40,6 +54,7 @@ Add to your `claude_desktop_config.json`:
|
|
|
40
54
|
}
|
|
41
55
|
}
|
|
42
56
|
```
|
|
57
|
+
|
|
43
58
|
</details>
|
|
44
59
|
|
|
45
60
|
<details>
|
|
@@ -57,6 +72,7 @@ Add to `.vscode/mcp.json` in your workspace:
|
|
|
57
72
|
}
|
|
58
73
|
}
|
|
59
74
|
```
|
|
75
|
+
|
|
60
76
|
</details>
|
|
61
77
|
|
|
62
78
|
<details>
|
|
@@ -74,6 +90,7 @@ Add to `.cursor/mcp.json` in your workspace:
|
|
|
74
90
|
}
|
|
75
91
|
}
|
|
76
92
|
```
|
|
93
|
+
|
|
77
94
|
</details>
|
|
78
95
|
|
|
79
96
|
### 3. Start using
|
|
@@ -94,43 +111,55 @@ Ask Claude things like:
|
|
|
94
111
|
|
|
95
112
|
## Tool Categories
|
|
96
113
|
|
|
97
|
-
The hosted endpoint
|
|
114
|
+
The hosted endpoint and npm stdio server each expose **91 public tools**. Their surfaces differ intentionally: hosted HTTP includes the Content Calendar and Analytics Pulse MCP Apps, while stdio includes 2 local screen-capture tools instead. The live hosted count is published by the [server card](https://mcp.socialneuron.com/.well-known/mcp/server-card.json). A small set of internal service tools used by Social Neuron's own automation are registered but not part of the public surface.
|
|
115
|
+
|
|
116
|
+
MCP App support is host-dependent. Every App tool returns a normal structured/text fallback, so scheduling and analytics still work when a host does not render the interactive widget.
|
|
98
117
|
|
|
99
118
|
These tools are available to AI agents (Claude, Cursor, etc.) via the MCP protocol.
|
|
100
119
|
|
|
101
120
|
### Content Lifecycle
|
|
102
121
|
|
|
103
|
-
| Category
|
|
104
|
-
|
|
105
|
-
| Ideation
|
|
106
|
-
| Content
|
|
107
|
-
| Distribution | schedule_post, schedule_content_plan, find_next_slots, list_connected_accounts, list_recent_posts |
|
|
108
|
-
| Analytics
|
|
109
|
-
| Insights
|
|
122
|
+
| Category | Tools | What It Does |
|
|
123
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- |
|
|
124
|
+
| Ideation | generate_content, fetch_trends, adapt_content, get_ideation_context | AI-powered content ideas and trend research |
|
|
125
|
+
| Content | generate_video, generate_image, generate_voiceover, generate_carousel, check_status, create_storyboard | Video, image, voiceover, and carousel creation with 20+ AI models |
|
|
126
|
+
| Distribution | schedule_post, reschedule_post, schedule_content_plan, find_next_slots, list_connected_accounts, list_recent_posts | Project-scoped multi-platform publishing, scheduling, rescheduling, and slot optimization |
|
|
127
|
+
| Analytics | fetch_analytics, refresh_platform_analytics | Performance tracking across all platforms |
|
|
128
|
+
| Insights | get_performance_insights, get_best_posting_times | Data-driven content optimization |
|
|
110
129
|
|
|
111
130
|
### Management & Optimization
|
|
112
131
|
|
|
113
|
-
| Category
|
|
114
|
-
|
|
115
|
-
| Brand
|
|
116
|
-
| Comments
|
|
117
|
-
|
|
|
118
|
-
|
|
|
119
|
-
|
|
|
120
|
-
|
|
|
121
|
-
|
|
|
122
|
-
|
|
|
132
|
+
| Category | Tools | What It Does |
|
|
133
|
+
| -------------- | ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
|
|
134
|
+
| Brand | extract_brand, get_brand_profile, save_brand_profile, update_platform_voice | Brand identity and voice management |
|
|
135
|
+
| Comments | list_comments, reply_to_comment, post_comment, moderate_comment, delete_comment | Social engagement management |
|
|
136
|
+
| Lifecycle | cancel_async_job, cancel_scheduled_post, delete_carousel, delete_content_plan, delete_autopilot_config | Project-scoped cancellation and cleanup; release acceptance requires the [backend smoke evidence](docs/lifecycle-backend-smoke.md) |
|
|
137
|
+
| Planning | plan_content_week, save_content_plan, get_content_plan, update_content_plan, submit_content_plan_for_approval | Content calendar and approval workflows |
|
|
138
|
+
| Plan Approvals | create_plan_approvals, respond_plan_approval, list_plan_approvals | Review and approve content plans |
|
|
139
|
+
| Autopilot | list_autopilot_configs, get_autopilot_status, update_autopilot_config | Automated content scheduling |
|
|
140
|
+
| Quality | quality_check, quality_check_plan | Pre-publish content validation |
|
|
141
|
+
| Credits | get_credit_balance, get_budget_status | Usage and budget tracking |
|
|
142
|
+
| Loop | get_loop_summary | Closed-loop optimization feedback |
|
|
123
143
|
|
|
124
144
|
### Utilities
|
|
125
145
|
|
|
126
|
-
| Category
|
|
127
|
-
|
|
128
|
-
| Extraction
|
|
129
|
-
| Screenshots | capture_app_page, capture_screenshot | Visual documentation and monitoring
|
|
130
|
-
| Remotion
|
|
131
|
-
| Usage
|
|
132
|
-
| YouTube
|
|
133
|
-
| Discovery
|
|
146
|
+
| Category | Tools | What It Does |
|
|
147
|
+
| ----------- | ------------------------------------ | -------------------------------------------------------------------------------------------- |
|
|
148
|
+
| Extraction | extract_url_content | Extract content from URLs, YouTube, articles |
|
|
149
|
+
| Screenshots | capture_app_page, capture_screenshot | Visual documentation and monitoring |
|
|
150
|
+
| Remotion | list_compositions, render_demo_video | Programmatic video rendering |
|
|
151
|
+
| Usage | get_mcp_usage | API usage monitoring |
|
|
152
|
+
| YouTube | fetch_youtube_analytics | YouTube-specific deep analytics |
|
|
153
|
+
| Discovery | search_tools | Find tools by keyword with progressive detail levels (saves 98% tokens vs loading all tools) |
|
|
154
|
+
|
|
155
|
+
### Interactive MCP Apps (hosted HTTP)
|
|
156
|
+
|
|
157
|
+
| App | Open tool | Purpose |
|
|
158
|
+
| ---------------- | ----------------------- | -------------------------------------------------------------------- |
|
|
159
|
+
| Content Calendar | `open_content_calendar` | Project-scoped calendar, quick create, and drag-to-reschedule |
|
|
160
|
+
| Analytics Pulse | `open_analytics_pulse` | Project-scoped KPI, platform-mix, and top-post performance dashboard |
|
|
161
|
+
|
|
162
|
+
Apps render only in MCP hosts that support the MCP Apps extension. All underlying data and write operations remain ordinary scoped tools, so hosts without interactive UI can use the same workflows through text/tool calls.
|
|
134
163
|
|
|
135
164
|
## Authentication
|
|
136
165
|
|
|
@@ -160,7 +189,7 @@ npx -y @socialneuron/mcp-server login --paste
|
|
|
160
189
|
|
|
161
190
|
Generate a key at socialneuron.com/settings/developer, paste it in.
|
|
162
191
|
|
|
163
|
-
Keys are stored in your OS keychain (macOS Keychain, Linux secret-tool) or file fallback.
|
|
192
|
+
Keys are stored in your OS keychain (macOS Keychain, Linux secret-tool) or a file fallback created with owner-only permissions where the operating system supports them.
|
|
164
193
|
|
|
165
194
|
> **Windows users**: The file fallback (`~/.config/social-neuron/credentials.json`) does not have strong permission enforcement on NTFS. For production use on Windows, set the `SOCIALNEURON_API_KEY` environment variable instead.
|
|
166
195
|
|
|
@@ -168,13 +197,13 @@ Keys are stored in your OS keychain (macOS Keychain, Linux secret-tool) or file
|
|
|
168
197
|
|
|
169
198
|
MCP/API access requires a Pro plan or higher:
|
|
170
199
|
|
|
171
|
-
| Plan
|
|
172
|
-
|
|
173
|
-
| Free
|
|
174
|
-
| Starter | $19/mo
|
|
175
|
-
| Pro
|
|
176
|
-
| Team
|
|
177
|
-
| Agency
|
|
200
|
+
| Plan | Price | Credits/mo | MCP/API Access |
|
|
201
|
+
| ------- | ------- | ---------- | ---------------------------------------------- |
|
|
202
|
+
| Free | $0 | 50 | — |
|
|
203
|
+
| Starter | $19/mo | 500 | — |
|
|
204
|
+
| Pro | $49/mo | 1,500 | MCP/API: Read + Analytics + Write + Distribute |
|
|
205
|
+
| Team | $99/mo | 3,500 | Full MCP/API + 5 keys |
|
|
206
|
+
| Agency | $249/mo | 10,000 | Full MCP/API + 20 keys |
|
|
178
207
|
|
|
179
208
|
Sign up at [socialneuron.com/pricing](https://socialneuron.com/pricing).
|
|
180
209
|
|
|
@@ -182,15 +211,15 @@ Sign up at [socialneuron.com/pricing](https://socialneuron.com/pricing).
|
|
|
182
211
|
|
|
183
212
|
Each API key inherits scopes from your plan. Tools require specific scopes to execute.
|
|
184
213
|
|
|
185
|
-
| Scope
|
|
186
|
-
|
|
187
|
-
| `mcp:read`
|
|
188
|
-
| `mcp:write`
|
|
189
|
-
| `mcp:distribute` | Schedule posts, publish content plans
|
|
190
|
-
| `mcp:analytics`
|
|
191
|
-
| `mcp:comments`
|
|
192
|
-
| `mcp:autopilot`
|
|
193
|
-
| `mcp:full`
|
|
214
|
+
| Scope | What you can do |
|
|
215
|
+
| ---------------- | ------------------------------------------------------------------------------------------------------------ |
|
|
216
|
+
| `mcp:read` | Analytics, insights, brand profiles, content plans, quality checks, screenshots, usage stats, credit balance |
|
|
217
|
+
| `mcp:write` | Generate content (video, image, voiceover, carousel), create storyboards, save brand profiles, plan content |
|
|
218
|
+
| `mcp:distribute` | Schedule posts, publish content plans |
|
|
219
|
+
| `mcp:analytics` | Refresh analytics, YouTube deep analytics |
|
|
220
|
+
| `mcp:comments` | List, reply, post, moderate, delete comments |
|
|
221
|
+
| `mcp:autopilot` | Configure and monitor automated scheduling |
|
|
222
|
+
| `mcp:full` | All of the above |
|
|
194
223
|
|
|
195
224
|
## CLI Reference
|
|
196
225
|
|
|
@@ -259,7 +288,7 @@ See [SECURITY.md](./SECURITY.md) for our vulnerability disclosure policy and cre
|
|
|
259
288
|
|
|
260
289
|
## Telemetry
|
|
261
290
|
|
|
262
|
-
This package collects
|
|
291
|
+
This package collects operational usage metrics (tool name, duration, success/failure) to improve reliability. It does not send tool inputs, outputs, generated content, API keys, emails, or upstream error bodies. When a deployment configures `POSTHOG_PSEUDONYMIZATION_KEY`, the user identifier is HMAC-pseudonymized; otherwise an ephemeral per-process key prevents stable cross-session correlation.
|
|
263
292
|
|
|
264
293
|
**To disable**: Set `DO_NOT_TRACK=1` or `SOCIALNEURON_NO_TELEMETRY=1` in your environment.
|
|
265
294
|
|