io.github.bitsandtea/postking-mcp

Generates a side page for a brand's landing page, optionally linked to an SEO cluster (`clusterId`). When linked, the side page surfaces in cluster-context queries and inherits the cluster's keyword targeting — strengthening topical authority that feeds GEO citation patterns. Two body modes: • freeform: pass `key` + `prompt` (+ optional `keywords`, `selectedSections`, `voiceProfileId`, `sidePageType`). • brief: pass `key` + `brief` (structured outline) + optional `briefId` and `roadmapItemId`. Typically takes ~2–5 min. Async — returns `{ success, operationId, operationRowId, pollUrl, sidePageId }`. Poll `get_job` with the operationId until `state` is `completed` (or `failed`/`partially_failed`/`cancelled` on error); comparison-type briefs run synchronously and return `sidePageId` directly. `slug` is the PARENT landing page slug under which the side page is created.

Fetch a single SeoBrief by id, including its briefData outline, status, roadmap item, and cluster. Returns full detail by default (complete brief incl briefData). Use detail="medium" for {id, type, status, title, clusterName, briefSummary, sidePageUrl} or detail="short" for {id, type, status}. Use to inspect a brief before refining it with seo_edit_brief or approving it with seo_approve_briefs.

Returns ALL briefs across EVERY status by default — do NOT add a status filter unless the user explicitly asks. `statusBreakdown` gives the per-status counts (match these to the dashboard's brief count). NOTE: briefs whose generation is still in-flight may not appear here yet — check `list_operations` / `get_job` for in-progress generation. Returns short detail by default: {id, type, status, title} per brief. Use detail="medium" for compact summary (clusterId, clusterName, briefSummary, sidePageUrl, generationError, blogArticleId, generatedAt, approvedAt) or detail="full" for raw briefs including briefData outline. To inspect a single brief's full outline, call seo_get_brief with detail="full". Filters: status (CSV — e.g. 'pending_review,approved'), type (CSV — e.g. 'blog,comparison,landing'), clusterId, roadmapItemId, q (cluster-name fuzzy match), limit (default 50, max 200), cursor. Response shape: { count, total, nextCursor, statusBreakdown, detail, briefs: [...] }.

Step 5. List clusters so the agent can pick one (or several) to approve before brief and roadmap generation. Returns short detail by default: {id, name, status} per cluster. Use detail="medium" for the full compact summary (pillarKeyword, briefGenerationStatus, briefCount, keywordCount, topKeywords, firstBriefId, description) or detail="full" for raw cluster objects. Full keyword detail (keywordsMeta, contentMix, briefAssignments) is intentionally omitted at short/medium to keep context small — use cluster IDs with approve/reject tools directly.

List generated keywords for the brand. Useful for auditing between steps. Returns short detail by default: {id, keyword, intent} per keyword. Use detail="medium" for the full compact summary (priority, searchVolume, difficulty, excludedFromClustering, userTags) or detail="full" for raw keyword objects.

List the 'Generated Results' (blog articles + side pages + comparisons) the SEO/GEO pipeline has produced — mirrors the dashboard Results tab. Includes BOTH draft and published items. Use kind to filter. This is the canonical 'what content has been generated' list — prefer it over reconstructing results from briefs.

List roadmap items (blog topics queued for writing). Returns short detail by default: {id, title, status} per item. Use detail="medium" for the compact summary (priority, primaryKeywords, clusterId) or detail="full" for raw objects. Call seo_roadmap_get with detail="full" for a single item's complete detail.

Step 10. Publish or schedule a roadmap-generated article to a publication. Free-tier choke point — may return FREE_CAP_REACHED with a checkoutUrl.

Re-runs L3 brief generation for a single brief (scoped to its cluster). Typically takes ~2–5 min. Async — returns `{operationId, status}`. Poll `get_job` with the operationId until `state` is `completed` (or `failed`/`partially_failed`/`cancelled` on error), then re-fetch with seo_get_brief to see the refreshed briefData. Use when the existing brief's outline is unusable and a structured seo_edit_brief won't recover it.

Reject a single cluster — marks it rejected and detaches its scored keywords. Use when a generated cluster isn't relevant.

Restore a rejected cluster back to pending_review so it can be approved again.

Permanently delete a roadmap item. Pass confirm: true to proceed — this is irreversible.

Edit a roadmap item — update its title, status (suggested|in_progress|completed|ignored), or priority.

View a single roadmap item by ID. Returns full detail by default (raw object). Use detail="medium" for {id, title, status, primaryKeywords, clusterId} or detail="short" for {id, title, status}.

Progress stats for the content roadmap (completed, in-progress, suggested counts).

Revert an approved cluster back to pending_review. Fails if briefs have already been generated for this cluster (cannot be reverted once briefs exist).

ALTERNATIVE write path — only call this when a brief was NOT approved via seo_approve_briefs (which already auto-generates). If the brief status is `writing`, generation is already in progress — poll the existing operationId with get_job until state is `completed` rather than calling this again. Step 7 (manual path). Draft a full blog article for a roadmap item. Uses credits. Typically takes ~3–8 min per article. Precondition: the brief for this roadmap item must be in status `approved`. If the brief is still `drafted` or `pending_review`, review with `seo_list_briefs` / `seo_get_brief`, refine with `seo_edit_brief`, then approve with `seo_approve_briefs` (which will auto-generate). Returns an articleId that can be reviewed, edited, or published.

Set the active brand for this session. All subsequent tools will use this brand by default.

STEP 2 of brand onboarding. Saves the list of platforms the brand publishes on. Call this immediately after `create_brand` or `onboard_brand` and the user has picked platforms. After this, call `get_onboarding_status` every ~15 seconds until it reports `done`.

Overwrite the content and/or metadata of a landing page. Pass content as a string (HTML or markdown). Pass metadata as a JSON object. Returns a versionId — all writes are versioned.

Bulk-replace all carousel cards for a post. Provide a full array of card objects with title, body, and optional number.

Update the content of a specific section within a side page.

Publish or unpublish a side page. Set published=true to make it live, false to pull it back to draft.

Update a brand's social media content rules for ONE platform. By default this MERGES your provided fields into the existing rules (send only what you want to change — other fields are preserved; arrays you provide replace the old array). Set replace=true to overwrite the entire platform ruleset. Valid platforms: linkedin, x/twitter, facebook, instagram, threads, general. Tip: call get_social_media_rules first to see current values.

Create or replace the weekly content schedule for the active brand. dayConfigs: array of { dayOfWeek (0=Sun…6=Sat), mediums: [{ medium, postsPerDay }] }. Mediums: x/twitter | linkedin | instagram | facebook | threads | blog. After setting, call enable_weekly_schedule to activate it.

Add a new line item (deliverable) to a storyline's strategy. Specify the channel, type, title, description, and a config map (pass {} if no extra config).

Run the intake/clarification step for a storyline. The API returns follow-up questions or a readiness signal; call iteratively until the system has enough context. After clarification is complete, call storyline_generate_brief.

Confirm (lock) the brief for a storyline, advancing it to the strategy phase. After confirmation, call storyline_generate_strategy.

Create a new storyline (marketing plan) for the brand. Pass a prompt describing the campaign goal; optionally provide a title. After creation, call storyline_clarify to gather context, then storyline_generate_brief.

Archive (soft-delete) a storyline. Pass confirm: true to proceed. Use storyline_restore to reverse this.

Permanently remove a line item from a storyline's strategy. Pass confirm: true to proceed.

Apply an AI-driven edit to the current brief using a natural-language instruction. Examples: 'Make the tone more casual', 'Add a proof point about our 99% uptime SLA'. Optionally pass expectedVersion for optimistic concurrency.

Apply an AI-driven edit to the current strategy using a natural-language instruction. Examples: 'Add a LinkedIn video post for launch week', 'Remove the influencer outreach line items'.

Read-only dry-run. Estimate the credits required to execute the storyline without actually running it. Use before storyline_execute to surface the cost to the user for approval. Returns { estimatedCredits, lineItemBreakdown } or similar.

Async. Execute a storyline — generates content drafts for all selected line items. Returns { operationId, status } — poll get_job with the operationId until state=completed. Typically takes ~3–8 min. Call storyline_estimate first to surface the credit cost before execution.

Async. Generate the marketing brief for a storyline (positioning, key messages, audience, timing, tone notes). Returns { operationId, status } — poll get_job with the operationId until state=completed. Typically takes ~1–3 min. After completion, review the brief with storyline_get, then call storyline_confirm_brief to advance to strategy.

Async. Generate the strategy and line-items for a storyline based on its confirmed brief. Returns { operationId, status } — poll get_job with the operationId until state=completed. Typically takes ~2–5 min. After completion, review with storyline_get_strategy, then optionally edit with storyline_edit_strategy or add/remove line items.

Fetch a single storyline by ID with its full state (brief, strategy, line items, status). Returns full detail by default. Use detail="medium" for a compact summary or detail="short" for {id,title,status}.

Fetch the strategy and line items for a storyline. Returns full detail by default (raw strategy + all line items). Use detail="medium" for a compact summary or detail="short" for {id,status} + line-item count.

List the brand's storylines (marketing plans). short detail {id,title,status}; medium adds isLive, dates, promptSummary; full = raw.

Async. Re-generate a single line item's content draft. Returns { operationId, status } — poll get_job with the operationId until state=completed. Typically takes ~1–3 min.

Restore an archived storyline back to active state.

Manually set (replace) the full brief for a storyline. Use to provide a human-authored brief or to push back an edited version retrieved via storyline_get. Pass the complete brief object and the current expectedVersion (use 0 when setting from scratch). After setting, call storyline_confirm_brief to advance to strategy generation.

Update metadata on a storyline: title, live status, or start/end/launch dates. Pass at least one field to change.

Update a line item on a storyline — select/deselect, retitle, change description, targetDate, or config. Pass only the fields to change.

Get AI-suggested assets from the brand library that match a given post context or topic.

Add or remove tags on an asset. Provide addTags and/or removeTags as arrays.

Create one or more content templates for the brand. Pass a single template object, or pass the 'templates' array param for bulk creation. If both are supplied, 'templates' (bulk) takes precedence. Returns the created template record(s).

Permanently delete a content template from the brand. This action is irreversible.

AI extracts a reusable content template from a pasted post text. Synchronous (seconds) — no polling needed. Pass save=true to also persist the template to the brand's library. Returns the extracted template object; if saved, includes the new template id.