CivNode MCP Server

MCP server for CivNode — the AI-powered creative writing platform where every human gets exactly one page (a Monument) displayed at random. No algorithm, no likes, no followers.

263 tools for writing, world-building (characters, locations, creatures, plots, family trees), entity exploration, books, collections, showcase, research, marketplace, library, forums, competitions, collaboration, passage comments, civic room, file management, and platform administration.

Quick Start

npx @civnode/mcp

No installation required. The server runs via npx and communicates over stdio using the Model Context Protocol.

Configuration

Claude Desktop

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "civnode": {
      "command": "npx",
      "args": ["-y", "@civnode/mcp"],
      "env": {
        "CIVNODE_SESSION_TOKEN": "your-session-token"
      }
    }
  }
}

Claude Code

Add to .claude/settings.json or ~/.claude/settings.json:

{
  "mcpServers": {
    "civnode": {
      "command": "npx",
      "args": ["-y", "@civnode/mcp"],
      "env": {
        "CIVNODE_SESSION_TOKEN": "your-session-token"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | CIVNODE_SESSION_TOKEN | For authenticated tools | Your CivNode session token | | CIVNODE_API_URL | No | API base URL (default: https://civnode.com) |

Authentication

Tools fall into three categories:

• Public — No token needed. Browse monuments, read works, search users.
• Authenticated — Requires CIVNODE_SESSION_TOKEN. Publishing, messaging, managing your compendium.
• Admin — Requires a token with admin role. System management, moderation, bot simulation. These tools only appear when a token is configured.

To get a session token, log in to CivNode and go to Settings → API Token.

---

Tool Reference

Monuments

Every user has exactly one Monument — their single page on the platform, displayed at random to visitors.

| Tool | Auth | Description | |------|------|-------------| | get_random_monument | No | Get a random Monument. Optionally filter by mood tags. | | get_monument | No | Read a specific Monument by UUID. | | get_monument_by_alias | No | Read a user's Monument by their alias. | | publish_monument | Yes | Publish or update your Monument. Accepts title, body (Markdown), sources, identity mode. | | resonate | Yes | Leave quiet appreciation on a Monument or work (CivNode's alternative to likes). | | user_update_working_on | Yes | Set or clear the "currently working on" status shown on your profile (max 100 chars, optional work link). |

Letters

Anonymous letters sent to Monument authors, plus direct personal letters between users.

| Tool | Auth | Description | |------|------|-------------| | send_letter | Yes | Send an anonymous letter to a Monument author (max 500 words). | | get_public_letters | No | Get publicly displayed letters on a user's Monument. | | personal_letter_inbox | Yes | Get your personal letter inbox. | | personal_letter_sent | Yes | Get your sent personal letters. | | send_personal_letter | Yes | Send a direct, non-anonymous letter to another user. | | read_personal_letter | Yes | Read a specific personal letter (marks as read). |

Writing

Create, publish, and manage creative writing — poems, short stories, essays, novellas, and more.

| Tool | Auth | Description | |------|------|-------------| | browse_writing | No | Browse published works. Filter by literary form or mood. | | get_work | No | Read a specific work by UUID. | | search_writing | No | Full-text search across published works. | | publish_work | Yes | Publish a new work with title, content (Markdown), form, mood tags, and visibility. | | list_my_works | Yes | List your own works (drafts and published). | | update_work | Yes | Update a work's content, title, mood tags, or visibility. | | delete_work | Yes | Delete a work permanently. | | export_work | Yes | Export a work's content. | | get_series | No | Get a writing series with all its works in reading order. | | create_series | Yes | Create a new writing series. | | list_my_series | Yes | List your writing series. | | add_work_to_series | Yes | Add a work to a series. |

Characters

Full character management with AI generation, portraits, and marketplace publishing.

| Tool | Auth | Description | |------|------|-------------| | list_characters | Yes | List your characters. | | get_character | Yes | Get a character's full profile. | | create_character | Yes | Create a character (only name required, fill rest later or use AI). | | update_character | Yes | Update character fields (pass only fields to change). | | delete_character | Yes | Delete a character permanently. | | ai_generate_character | Yes | Generate a complete character using AI. Accepts role, genre, setting hints. | | character_portrait_generate | Yes | Generate an AI portrait. Requires an image provider. | | character_suggestions | Yes | Get AI suggestions for a specific field (appearance, personality, backstory, etc.). | | character_publish | Yes | Publish to the marketplace. | | character_unpublish | Yes | Remove from the marketplace. | | character_relationships | Yes | Get all relationships for a character. | | entity_explorer_chat_character | Yes | Interview a character via the Entity Explorer. Chat in character, grounded in your story data. Requires BYOK AI provider. |

Locations

World-building locations with areas, blueprints, and AI-powered generation.

| Tool | Auth | Description | |------|------|-------------| | list_locations | Yes | List your locations. | | get_location | Yes | Get full location details. | | create_location | Yes | Create a location (name required). Fields: description, atmosphere, sensory details, inhabitants, secrets, etc. | | update_location | Yes | Update location fields. | | delete_location | Yes | Delete a location permanently. | | location_ai_fill | Yes | AI fills in missing details based on name and existing fields. | | location_ai_image | Yes | Generate an AI image. Requires an image provider. | | location_publish | Yes | Publish to the marketplace. | | location_unpublish | Yes | Remove from the marketplace. | | get_location_blueprint | Yes | Get the visual blueprint/map. | | entity_explorer_chat_location | Yes | Explore a location via the Entity Explorer. Analyze ripple effects of changes. Requires BYOK AI provider. |

Creatures

Creatures and fantastical beings with full AI support.

| Tool | Auth | Description | |------|------|-------------| | list_creatures | Yes | List your creatures. | | get_creature | Yes | Get full creature profile. | | create_creature | Yes | Create a creature (name and species_type required). | | update_creature | Yes | Update creature fields. | | delete_creature | Yes | Delete a creature permanently. | | ai_generate_creature | Yes | Generate a creature using AI. Accepts species_type, habitat_type, era. | | creature_ai_image | Yes | Generate an AI image. | | creature_portrait_generate | Yes | Generate an AI portrait. | | creature_publish | Yes | Publish to the marketplace. | | creature_unpublish | Yes | Remove from the marketplace. | | creature_suggestions | Yes | Get AI suggestions for a field. | | entity_explorer_chat_creature | Yes | Interview a creature via the Entity Explorer. Chat in character, grounded in your story data. Requires BYOK AI provider. |

Plots

Structured plot outlines with acts, scenes, beats, and AI generation.

| Tool | Auth | Description | |------|------|-------------| | list_plots | Yes | List your plots. | | get_plot | Yes | Get full plot with acts, scenes, and beats. | | create_plot | Yes | Create a plot (title required). Fields: genre, tone, central_conflict, etc. | | update_plot | Yes | Update plot fields. | | delete_plot | Yes | Delete a plot permanently. | | plot_add_act | Yes | Add an act (title, summary, purpose, notes). | | plot_ai_acts | Yes | Generate acts using AI. | | plot_add_scene | Yes | Add a scene to an act. | | update_plot_scene | Yes | Update a scene's text fields (title, summary, purpose, style_hint, pov_character, notes), location bindings (region_id, area_id, spot_id — pass null to clear), or move it between acts in the same plot by passing act_id (optionally with sort_order to position it in the new act). | | plot_ai_scenes | Yes | Generate scenes for an act using AI. | | plot_ai_image | Yes | Generate an AI image for the plot. | | plot_publish | Yes | Publish to the marketplace. | | plot_unpublish | Yes | Remove from the marketplace. | | entity_explorer_chat_plot | Yes | Explore a plot via the Entity Explorer. Analyze branching possibilities and tension points. Requires BYOK AI provider. |

Plot Designer (Book-level)

Tools for the dedicated Plot Designer screen at /books/{bookId}/plot.

| Tool | Auth | Description | |------|------|-------------| | list_plot_templates | No | List available plot structure templates (Three-Act, Hero's Journey, etc.). | | get_plot_template | Yes | Get a single plot template with full beat details (acts → beats → name + hint). | | get_book_plot | Yes | Get the plot linked to a book with all acts, scenes, and beats. | | create_book_plot_from_template | Yes | Create a plot from a template and link to a book. | | get_plot_synopsis | Yes | Read the cached AI synopsis for a book's plot. Does not trigger regeneration. Returns {synopsis, hash, generated_at} or null fields if none has been generated. | | regenerate_plot_synopsis | Yes | Force regeneration of the AI synopsis. Cache-aware: returns the cached value if the plot content hasn't drifted. Requires BYOK. | | delete_book_plot | Yes | Delete the plot linked to a book. | | create_plot_beat | Yes | Create a beat under a scene. sort_order auto-assigned. | | update_plot_beat | Yes | Update fields on a plot beat. Pass only the fields to change. | | delete_plot_beat | Yes | Delete a plot beat by UUID. | | reorder_plot_beats | Yes | Reorder beats within a scene via {id, sort_order} list. | | get_beat_suggestions | Yes | Get story evidence suggestions for a beat (analysis, text stats, semantic). | | auto_map_plot | Yes | Batch-map story content to all empty beats using analysis + AI. |

Family Trees

Visual family trees linking characters and creatures with relationship tracking.

| Tool | Auth | Description | |------|------|-------------| | list_trees | Yes | List your family trees. | | get_tree_members | Yes | Get all members in a tree. | | create_tree | Yes | Create a family tree (name required). | | update_tree | Yes | Update tree name or description. | | delete_tree | Yes | Delete a tree permanently. | | tree_add_member | Yes | Add a character or creature to a tree. | | tree_generate | Yes | Generate family members using AI. | | tree_publish | Yes | Publish to the marketplace. | | tree_unpublish | Yes | Remove from the marketplace. |

Books

Full book management — create books with chapters, link compendium entities, export.

| Tool | Auth | Description | |------|------|-------------| | list_books | Yes | List your books. | | list_my_stories | Yes | List the user's books that have a plot. Subset of list_books. Useful for "what stories am I working on?" | | search_my_stories | Yes | Full-text search over your Stories including character names. Returns books ranked by relevance. | | get_book | Yes | Get book details and linked entities. | | create_book | Yes | Create a book (title and book_type required). Types: novel, poetry_collection, essay_collection, screenplay. For screenplays, also pass screenplay_format. | | update_book | Yes | Update book metadata (title, subtitle, blurb, genre, etc.). Set published: true/false to publish or unpublish a book to the marketplace. Screenplays support screenplay_format, screenplay_font, screenplay_title_page. | | delete_book | Yes | Delete a book and all chapters. | | list_chapters | Yes | List chapters in a book. | | get_chapter | Yes | Get a chapter's content and metadata. | | create_chapter | Yes | Create a chapter (title and chapter_type required). Types: chapter, prologue, epilogue, interlude, appendix. Optional plot_scene_id links the new chapter to a plot scene you own (silently skipped if the scene isn't on one of your plots) — powers the Plot Canvas drawer's "Create chapter from this scene" button. | | update_chapter | Yes | Update chapter content or metadata. | | delete_chapter | Yes | Delete a chapter. | | reorder_chapters | Yes | Reorder chapters (pass chapter IDs in desired order). | | book_link_entity | Yes | Link a compendium entity to a book (characters, creatures, locations, plots, trees). | | book_unlink_entity | Yes | Remove a linked entity from a book. | | export_book | Yes | Export a book's content in various formats (json, markdown, html, epub, pdf, fdx, fountain). | | import_fountain | Yes | Import a Fountain screenplay as a new book. | | book_entities | Yes | Get all entity types linked to a book in one call (characters, creatures, locations, plots, trees). | | compendium_unassigned | Yes | Get entities not linked to any book or work. | | get_public_book | No | Get a published book's public info. |

Collections

Group books and works into ordered collections.

| Tool | Auth | Description | |------|------|-------------| | create_collection | Yes | Create a new collection (title required, optional description). | | list_collections | Yes | List all your collections. | | get_collection | Yes | Get a collection with its ordered items (books and works). | | update_collection | Yes | Update a collection's title or description. | | delete_collection | Yes | Delete a collection (items are unlinked, not deleted). | | collection_add_item | Yes | Add a book or work to a collection. | | collection_remove_item | Yes | Remove an item from a collection. | | collection_reorder | Yes | Reorder items in a collection by passing ordered item IDs. |

Showcase

Your showcase is your public gallery — the books, works, and collections you have chosen to share with visitors.

| Tool | Auth | Description | |------|------|-------------| | showcase_list | No | Get a user's public showcase items. Supports search, type filtering, and pagination. | | showcase_count | No | Get the number of items in a user's showcase. | | showcase_add | Yes | Add a book, work, or collection to your showcase. Provide exactly one ID. | | showcase_mine | Yes | List your own showcase items. | | showcase_update_note | Yes | Update the author note on a showcase item (max 280 chars). | | showcase_remove | Yes | Retract an item from your showcase. It stays in My Writing but becomes private. | | showcase_reorder | Yes | Set display order by providing item IDs in the desired order. |

Canvases

Collaborative drawing and brainstorming boards within groups.

| Tool | Auth | Description | |------|------|-------------| | list_canvases | Yes | List your canvases. | | get_canvas | Yes | Get a canvas with nodes and metadata. | | create_canvas | Yes | Create a canvas in a group. | | update_canvas | Yes | Update canvas name. | | delete_canvas | Yes | Delete a canvas permanently. |

Passage Comments

Contextual feedback anchored to specific text passages in works and monuments.

| Tool | Auth | Description | |------|------|-------------| | passage_comments_inbox | Yes | Get passage comments others left on your works. | | passage_comments_mine | Yes | Get passage comments you wrote on other works. | | passage_comments_create | Yes | Create a passage comment anchored to a text selection. | | passage_comments_list | Yes | List passage comments for a specific work or monument. | | passage_comments_reply | Yes | Reply to a passage comment. | | passage_comments_delete | Yes | Delete a passage comment. | | passage_comments_resonate | Yes | Leave quiet appreciation on a passage comment. | | passage_comments_escalate | Yes | Escalate a passage comment for moderation review. | | passage_comments_mark_read | Yes | Mark a passage comment as read. | | passage_comments_dismiss | Yes | Dismiss a passage comment from your inbox. |

Research & Observatory

Semantic search, tiered chapter analysis, writing insights, and AI-powered questions about your work.

| Tool | Auth | Description | |------|------|-------------| | research_search | Yes | Semantic search across research notes and analyzed content. | | research_analyze_chapter | Yes | Trigger tiered chapter analysis. Core (Tier 1): characters, themes, arcs, interactions. Deep (Tier 2): voice, foreshadowing, craft metrics. Requires AI provider. | | research_intelligence | Yes | Get aggregated intelligence: character appearances, themes, timeline. | | research_character_graph | Yes | Get a character's relationship graph and arc. | | observatory_insights | Yes | Get writing insights and patterns. | | observatory_stats | Yes | Get writing statistics: word counts, streaks, productivity. | | observatory_moments | Yes | Get notable moments: breakthroughs, milestones, patterns. | | observatory_ask | Yes | Ask AI about your writing patterns and story structure. | | observatory_summary | Yes | Get an AI summary of your writing journey. | | book_character_evolution | Yes | Get character evolution data for a book — emotional state, driving forces, chapter timeline, and ghost characters. |

Marketplace

Browse and fork community-published characters, creatures, locations, plots, families, and books.

| Tool | Auth | Description | |------|------|-------------| | marketplace_browse | No | Browse marketplace by entity type (characters, creatures, locations, plots, families, books). | | marketplace_get | No | Get detailed view of a marketplace item. | | marketplace_fork | Yes | Fork (copy) a marketplace item into your compendium. | | marketplace_book_showcase | No | Get a published book's full showcase with author info and all entities. | | marketplace_fork_book | Yes | Fork a published marketplace book and all its entities into your collection. |

Library

Curated showcase books that demonstrate CivNode's world-building capabilities.

| Tool | Auth | Description | |------|------|-------------| | library_books | No | List the 4 showcase books in the CivNode library. | | library_fork_book | Yes | Fork a library book and all its entities into your collection. |

Site Forum

The CivNode community forum at /forum, open to all users.

| Tool | Auth | Description | |------|------|-------------| | forum_site_categories | No | List the six categories in the site-wide forum (Announcements, Writing Craft, Writing Groups, Competitions, Feedback & Ideas, Introductions). | | forum_site_threads | No | List threads in the site-wide forum. Accepts optional category_id to filter by category and cursor for pagination. | | forum_site_create_thread | Yes | Create a new thread in the site-wide forum. Requires title and body_markdown; optionally provide category_id. |

Personal Forum

Every user on CivNode also has their own personal forum on their profile.

| Tool | Auth | Description | |------|------|-------------| | forum_list_threads | No | List threads in a user's forum. | | forum_read_thread | No | Read a thread with all posts. | | forum_search | No | Search threads by keyword. | | forum_post | Yes | Create a new thread or reply. Provide thread_id for replies, or forum_alias + title for new threads. |

Competitions

Community writing competitions with signup, submission, and voting phases.

| Tool | Auth | Description | |------|------|-------------| | list_competitions | No | List competitions. Filter by phase: signup, writing, voting, completed. | | get_competition | Yes | Get competition details. | | create_competition | Yes | Create a competition (requires supporter status). | | competition_signup | Yes | Sign up for a competition. | | competition_submit_entry | Yes | Submit your entry (writing phase only). | | competition_vote | Yes | Vote for top 3 entries (voting phase only). | | competition_entries | No | Get blind entries (voting/completed phase). | | competition_results | No | Get ranked results (completed phase). |

Collaboration

Real-time co-writing and draft sharing.

| Tool | Auth | Description | |------|------|-------------| | create_share_link | Yes | Generate a shareable link for a work. | | list_share_links | Yes | List share links for a work. | | get_shared_work | No | Read a shared work by its token. | | delete_share_link | Yes | Delete a share link. | | list_collaborators | Yes | List collaborators on a work. | | invite_collaborator | Yes | Invite a user as coauthor or editor. | | accept_collaboration | Yes | Accept a collaboration invitation. | | remove_collaborator | Yes | Remove a collaborator. |

Groups, Topics & Community

| Tool | Auth | Description | |------|------|-------------| | list_groups | Yes | List groups you belong to. | | create_group | Yes | Create a new writing group. Types: critique, accountability, workshop, co_writing, sprint. Caller becomes owner. | | get_group | Yes | Get group details. | | group_update | Yes | Update a group's name and description (owner/leader only). | | delete_group | Yes | Delete a group permanently (owner only). Removes all cycles, submissions, and rooms. | | group_settings_get | Yes | Get feature settings for a group (caller must be a member). Returns submissions_enabled, reciprocity_mode, cycles_enabled, etc. | | group_settings_update | Yes | Update feature settings for a group (owner/leader only). Pass any subset of: submissions_enabled, reciprocity_mode, silent_period_enabled, cycles_enabled, critique_templates_enabled, goals_enabled, sprints_enabled, challenges_enabled, project_tracking_enabled, directory_listed, member_cap. | | group_add_member | Yes | Add a user to a group by user_id (owner/leader only). | | group_remove_member | Yes | Remove a member from a group. Owner/leaders can remove anyone; members can remove themselves. | | group_list_members | Yes | List all group members with roles (owner, leader, moderator, member). | | group_promote_member | Yes | Promote or demote a member to a new role (leader, moderator, member). Owner can set any role; leaders can promote to moderator only. | | group_transfer_ownership | Yes | Transfer ownership to another member (owner only). Former owner becomes leader. | | group_warn_member | Yes | Issue a warning to a member with a required reason. Returns the warning and strike number. Moderators, leaders, and owner can warn. | | group_list_warnings | Yes | List warnings issued to a specific member. Accessible by moderators, leaders, owner, or the member themselves. | | group_ban_member | Yes | Ban a member from the group (leaders and owner only). Requires a reason. Member is removed immediately. | | group_unban_member | Yes | Remove a ban on a user (owner only). | | group_list_bans | Yes | List all currently banned members (owner and leaders only). | | group_report | Yes | Report a group or specific member for a rules violation. Any group member can report. | | list_topics | No | List topic communities. | | join_topic | Yes | Join a topic. | | leave_topic | Yes | Leave a topic. | | get_encounter | Yes | Get today's encounter (daily anonymous pairing). | | get_presence | No | See how many people are online (ambient count, no identities). |

Messaging

| Tool | Auth | Description | |------|------|-------------| | send_message | Yes | Send a message in a conversation. | | list_conversations | Yes | List your conversations. | | read_conversation | Yes | Read messages in a conversation. |

Platform

| Tool | Auth | Description | |------|------|-------------| | get_profile | No | Get a user's public profile. | | update_tagline | Yes | Update your profile tagline (max 200 chars). | | get_social_links | No | Get a user's social links. | | update_social_links | Yes | Update your social links (replaces all). | | update_avatar_source | Yes | Set avatar source (goavatar, gravatar, custom). | | search_users | No | Search users by alias or name. | | search_content | No | Search across all public content. | | list_notifications | Yes | List your notifications. | | mark_notifications_read | Yes | Mark all notifications as read. | | list_bookmarks | Yes | List your bookmarks. | | toggle_bookmark | Yes | Toggle a bookmark on content. | | list_highlights | Yes | List your text highlights. | | create_highlight | Yes | Highlight text on a monument or work. | | delete_highlight | Yes | Delete a highlight. | | get_notepad | Yes | Get your private notepad. | | update_notepad | Yes | Update your notepad content. | | get_supporter_status | Yes | Check supporter status. | | supporter_checkout | Yes | Start Stripe checkout for supporter ($5/month). | | supporter_cancel | Yes | Cancel supporter subscription. | | purchase_checkout | Yes | Create Stripe checkout to purchase a book or work. | | check_purchase | Yes | Check if current user has purchased a specific item. | | list_my_purchases | Yes | List all purchases by current user. | | get_author_balance | Yes | Get author earnings balance and lifetime totals. | | list_author_sales | Yes | List all sales for current user as author. | | ai_usage_log_local | Yes | Log local AI usage (Ollama, ComfyUI) from the browser. | | link_preview | No | Get a rich preview for an internal CivNode URL. Returns title, author, image, and meta for published content. |

Speech Writing

Deterministic speech metrics and chapter revision history for writers working on speeches. Every metric is computed from LanguageTool plus rule-based Go packages — no LLM calls anywhere in these tools.

| Tool | Auth | Description | |------|------|-------------| | speech_analysis | Yes | Return speech metrics for a chapter: delivery time, word/syllable/sentence counts, LIX, Flesch-Kincaid, breath-test violations, filler words, passive voice, rhetorical devices, per-sentence timings. Results cached per content hash. | | convert_to_speech | Yes | Flip a book's type to speech, enable speech_mode on every chapter, and trigger a first analysis pass. Reversible. | | convert_from_speech | Yes | Revert a speech book back to story (or another target type) and clear speech_mode on every chapter. | | list_revisions | Yes | List revision history for a chapter, newest first. | | fetch_revision | Yes | Fetch a single revision's full body (ProseMirror JSON + plain text). | | restore_revision | Yes | Restore a chapter to a previous revision. Snapshots current body first so nothing is lost. | | list_speaker_notes | Yes | List anchored speaker notes on a chapter, sorted by anchor position. | | create_speaker_note | Yes | Create a speaker note anchored to a chapter text range. |

Example — run a full speech analysis on a chapter and print the delivery time:

mcp__civnode__speech_analysis({
  chapter_id: "8f3a...",
  audience_preset: "formal"
})

Example — convert an existing story book into a speech:

mcp__civnode__convert_to_speech({ book_id: "a1b2..." })

---

Admin Tools

Admin tools require a session token with admin role. They only appear when a token is configured.

| Tool | Description | |------|-------------| | admin_health | System health: app status, migration version, DB/Redis connectivity. | | admin_stats | System-wide statistics: users, works, monuments, forums, moderation. | | admin_users | List all users with details and status. | | admin_user_ban | Ban a user. | | admin_user_unban | Unban a user. | | admin_toggle_strategist | Toggle strategist role for a user (grants Civic Room access). | | admin_moderation_queue | View flagged content awaiting review. | | admin_ai_providers | List configured AI text providers. | | admin_ai_provider_keys | List AI providers with partial API keys visible. | | admin_image_providers | List image generation providers. | | admin_embedding_providers | List embedding providers. | | admin_ai_usage | AI token usage statistics. | | ai_usage_log | Detailed AI usage log with filtering (date range, provider, action, local/cloud, success) and pagination. | | ai_usage_export | Export AI usage data as CSV with the same filters. | | ai_pricing_list | List AI pricing rules (per-model token and image prices). | | ai_pricing_upsert | Create or update an AI pricing rule for a provider+model. | | ai_pricing_delete | Delete an AI pricing rule by ID. | | admin_test_ai_chat | Test AI chat pipeline with a prompt. | | admin_test_embedding | Test embedding pipeline. | | admin_test_ollama | Test local Ollama connectivity from the server. | | admin_backups | List database backups. | | admin_trigger_backup | Trigger an immediate backup. | | admin_feedback | List user feedback and bug reports. | | admin_site_settings | View site-wide settings. | | admin_update_site_settings | Update site settings (registration, maintenance mode). | | admin_research_stats | Research system statistics. | | admin_botsim_state | Bot simulation state. | | admin_botsim_bots | List simulated bots. | | admin_botsim_tick | Trigger one simulation tick. | | admin_images | List AI-generated images with moderation status. | | admin_block_image | Block an AI-generated image. | | admin_campaigns | List marketing campaigns. | | admin_ornaments | List monument ornaments. | | admin_captcha_stats | Captcha analytics: challenges, solve rates, country breakdown. | | admin_captcha_recent_failures | Recent captcha failures with IP and country. | | admin_takedown | Execute a takedown from a content report (delete file, log event, optionally ban hash). |

File Manager

Tools for inspecting file storage. Require a session token.

| Tool | Auth | Description | |------|------|-------------| | list_drawers | Yes | List all drawers owned by the authenticated user. Returns name, kind (user/book/work/collection/character/canvas), file count, and total size in bytes. | | file_stats | Yes | Get storage quota summary: quota_bytes, used_bytes, plan (free/paid/grace), grace_until, upgrade_url, and a human-readable "X MB of Y MB used" string. |

Civic Room (Admin / Strategist)

The Civic Room is a private workspace for platform strategists and admins to manage social media presence and coordinate.

| Tool | Description | |------|-------------| | civic_room_get_notes | Get your private Civic Room notes. | | civic_room_save_notes | Save your private Civic Room notes. | | civic_room_overview | Get overview: recent posts, threads, canvases. | | civic_room_threads | List civic threads. | | civic_room_canvases | List civic canvases. | | civic_room_list_channels | List social media channels. | | civic_room_create_channel | Create a social media channel. | | civic_room_update_channel | Update a social media channel. | | civic_room_delete_channel | Delete a social media channel. | | civic_room_list_posts | List social media posts. Filter by state and channel. | | civic_room_create_post | Create a social media post targeting multiple channels. | | civic_room_update_post | Update a draft/queued post. | | civic_room_delete_post | Delete a draft/queued post. | | civic_room_publish_post | Publish a post immediately to its platform. |

---

Examples

Create a Screenplay

create_book({
  title: "The Last Lighthouse",
  book_type: "screenplay",
  screenplay_format: "feature_film"
})

Export a Screenplay as Final Draft (FDX)

export_book({
  id: "book-uuid-here",
  format: "fdx"
})

Export a Screenplay as Fountain

export_book({
  id: "book-uuid-here",
  format: "fountain"
})

Import a Fountain Screenplay

import_fountain({
  text: "Title: The Last Lighthouse\nCredit: Written by\nAuthor: Jane Doe\n\nINT. LIGHTHOUSE - NIGHT\n\nA lone KEEPER tends the light."
})

Get a Link Preview

link_preview({
  url: "/books/abc-123/read"
})

Browse the Library

library_books()

Fork a Library Book

library_fork_book({
  book_id: "book-uuid-here"
})

Create a Chapter Linked to a Plot Scene

create_chapter({
  book_id: "book-uuid-here",
  title: "The Crossing",
  chapter_type: "chapter",
  plot_scene_id: "scene-uuid-here"
})

Move a Plot Scene Between Acts

update_plot_scene({
  plot_id: "plot-uuid-here",
  scene_id: "scene-uuid-here",
  act_id: "target-act-uuid",
  sort_order: 2
})

Edit a Plot Scene's Summary

update_plot_scene({
  plot_id: "plot-uuid-here",
  scene_id: "scene-uuid-here",
  summary: "Elena arrives at the lighthouse"
})

Create a Beat Under a Scene

create_plot_beat({
  plot_id: "plot-uuid-here",
  scene_id: "scene-uuid-here",
  title: "Elena spots the keeper's lantern",
  description: "First glimpse of another soul on the island.",
  beat_type: "reveal"
})

Reorder Beats Within a Scene

reorder_plot_beats({
  plot_id: "plot-uuid-here",
  scene_id: "scene-uuid-here",
  items: [
    { id: "beat-uuid-a", sort_order: 1 },
    { id: "beat-uuid-b", sort_order: 2 },
    { id: "beat-uuid-c", sort_order: 3 }
  ]
})

---

Local Development

To run against a local CivNode instance:

CIVNODE_API_URL=http://localhost:9080 CIVNODE_SESSION_TOKEN=your-token npx @civnode/mcp

Or in your MCP client config:

{
  "mcpServers": {
    "civnode-local": {
      "command": "npx",
      "args": ["-y", "@civnode/mcp"],
      "env": {
        "CIVNODE_API_URL": "http://localhost:9080",
        "CIVNODE_SESSION_TOKEN": "your-local-token"
      }
    }
  }
}

Troubleshooting

"Authentication required" — Set the CIVNODE_SESSION_TOKEN environment variable. Get a token from Settings → API Token on CivNode.

"Forbidden" — Your token doesn't have permission for that action. Admin tools require admin role.

"Rate limit exceeded" — Wait a moment and retry. CivNode rate-limits API calls per user.

"API error: 404" — The resource doesn't exist or you don't have access. Check the UUID.

Admin tools not showing — Admin tools only appear when CIVNODE_SESSION_TOKEN is set. They also require server-side admin role.

Wrong API URL — By default the server connects to https://civnode.com. Set CIVNODE_API_URL for local development.

Contributing

Adding a New Tool

1. Add a tool object to the tools array in index.js (or the admin section for admin tools):

{
  name: "tool_name",
  description: "What it does. Mention auth requirement.",
  inputSchema: {
    type: "object",
    properties: {
      id: { type: "string", description: "Resource UUID" },
    },
    required: ["id"],
  },
  handler: (args) => fetchAPI(`/api/endpoint/${args.id}`),
},

1. Use the existing HTTP helpers: fetchAPI (GET), postAPI (POST), putAPI (PUT), patchAPI (PATCH), deleteAPI (DELETE).

1. Update the tool count in the header comment and package.json.

1. Test locally: CIVNODE_API_URL=http://localhost:9080 node index.js

1. Bump version in package.json and push to main — CI auto-publishes to npm.

License

MIT