MCP server reference

list_projects

List all projects you have access to. Returns id, title, category, priority, and note/task/idea counts. Use this to discover project IDs before calling other tools.

get_project

Read full project metadata: vision, goal, description, tech_stack, target_audience, success_metrics, constraints, completion_percentage. Use this when you need to inspect or update specific project fields. For AI-optimized context with notes and tasks, use get_context_pack instead.

• project_id integer required
  Project ID, from list_projects

get_project_context

Read project metadata + 5 latest notes + 5 latest changes in one call. Lightweight alternative to get_context_pack when you don't need profile-based ranking. Prefer get_context_pack(profile=...) for curated, role-specific context.

• project_id integer required
  Project ID, from list_projects

get_context_pack

Get AI-optimized context pack with notes and tasks ranked by relevance to a role profile. Profiles: 'coding' (architecture, APIs, bugs), 'founder' (vision, priorities, market), 'product' (UX, roadmap, feedback), 'marketing' (positioning, messaging), 'fundraising' (traction, metrics), 'support' (recent issues). Returns structured data + pre-rendered exports (markdown, llm_document, compact_summary).

• project_id integer required
  Project ID, from list_projects
• profile string
  Role profile to rank notes/tasks by relevance
• notes_limit integer
  How many notes to include (default 6)
• tasks_limit integer
  How many tasks to include (default 6)
• changes_limit integer
  How many changes to include (default 6)

get_note

Read a single note's full content by note_id. Use when you need the complete text of a specific note. To browse notes hierarchically, use get_note_tree. To search by keyword, use search_notes.

• note_id integer required
  Note ID, from get_note_tree or search_notes

search_notes

Full-text search across note titles and content. Returns matching notes with snippets. Use get_note_tree for hierarchical browsing instead, or get_context_pack for curated AI context.

• query string required
  Search keyword to match in titles and content
• project_id integer
  Optional: limit search to one project
• limit integer
  Maximum items to return (default 10)

get_note_tree

Get hierarchical note tree (parent-child structure) for a project. Shows note titles, types, tags, and nesting. Use this to understand how notes are organized or to find parent_note_id for creating child notes. Use search_notes to find notes by keyword instead.

• project_id integer required
  Project ID, from list_projects
• max_depth integer
  How deep to traverse the tree (default 5)

get_recent_changes

Read project change log: who changed what, when, and from which source (user, AI, system). Use this to see recent activity and audit trail.

• project_id integer required
  Project ID, from list_projects
• limit integer
  Maximum items to return (default 10)

get_changes_since

Get all changes to a project since a timestamp. Returns change log entries, modified notes, modified tasks, and counts. Use this for incremental sync: pass the last_synced_at from .nibvine.json to see what changed remotely.

• project_id integer required
  Project ID, from list_projects
• since string required
  ISO 8601 timestamp, e.g. 2026-04-01T12:00:00Z

get_sync_status

Compare local sync state with remote to detect drift. Pass local_context_version and local_updated_at from .nibvine.json. Returns whether sync is needed, how many versions behind, active project members, and task/note counts. Use this before syncing to decide what to do.

• project_id integer required
  Project ID, from list_projects
• local_context_version integer
  context_version from .nibvine.json (0 if first sync)
• local_updated_at string
  updated_at from .nibvine.json (empty if first sync)

list_tasks

List project tasks, optionally filtered by status. Returns title, description, status, priority, due_date. Use get_task(task_id) to read a single task in detail.

• project_id integer required
  Project ID, from list_projects
• status string
  Filter by status (omit to list all)
• limit integer
  Maximum tasks to return (default 20)

get_task

Read a single task's full details by task_id. Use list_tasks(project_id) first to find task IDs.

• task_id integer required
  Task ID, from list_tasks

get_claude_instructions

START HERE: Get complete workflow guide for this Nibvine project. Returns current project state, available tools, data types, best practices, and step-by-step instructions. Call this first in every new session.

• project_id integer required
  Project ID, from list_projects

get_public_settings

Read the public sharing settings for a project: is_public toggle, which content is shared (notes, tasks, ideas, analyses), published note branches, and the public URL. Use before updating sharing settings.

• project_id integer required
  Project ID, from list_projects

update_public_settings

Update public sharing settings for a project. Toggle is_public to enable/disable the public page. Choose what to share: notes, tasks, ideas, analyses. Set published_note_ids to select which root-level note branches appear on the public page. Set regenerate_token=true to invalidate old share links. Changes apply immediately (no preview/commit needed).

• project_id integer required
  Project ID, from list_projects
• is_public boolean
  Enable or disable the public share page
• share_notes boolean
  Show published note branches on public page
• share_tasks boolean
  Show tasks on public page
• share_ideas boolean
  Show ideas on public page
• share_analyses boolean
  Show AI analyses on public page
• published_note_ids array
  IDs of root-level notes to publish. Use get_note_tree to find IDs.
• regenerate_token boolean
  Generate a new public URL token (invalidates old links)

list_notes_by_tag

List notes in a project that contain a given tag. Returns note summaries.

• project_id integer required
  Project ID, from list_projects
• tag string required
  Tag to filter by (case-insensitive substring match)

batch_tag_notes

Add or remove tags from multiple notes at once. Provide note_ids and at least one of add_tags or remove_tags.

• note_ids array required
  List of note IDs to update
• add_tags array
  Tags to add
• remove_tags array
  Tags to remove

list_ideas

List a project's ideas (the lightweight idea inbox that sits next to notes and tasks). Optionally filter by implementation state or a text query. Use get_idea(idea_id) for the full body.

• project_id integer required
  Project to read ideas from
• is_implemented boolean
  Filter: true = only implemented ideas, false = only open ideas
• query string
  Optional keyword matched against idea title and content
• limit integer
  Maximum ideas to return (default 20)

get_idea

Read a single idea in full by idea_id. Call list_ideas(project_id) first to discover idea IDs.

• idea_id integer required
  ID returned by list_ideas

list_comments

List the project's unified comment stream (human messages, AI assistant replies, and system events), newest first. Filter by note_id to read one note's discussion, by role, or set root_only=true to skip replies.

• project_id integer required
  Project whose comments to read
• note_id integer
  Only comments attached to this note
• role string
  Only comments written with this role
• root_only boolean
  true = only thread starters, skipping replies
• limit integer
  Maximum comments to return (default 20)

get_comment_thread

Read one full comment thread: walks up to the root comment and returns it with all nested replies. Pass any comment_id in the thread.

• comment_id integer required
  Any comment in the thread (from list_comments)

list_quick_notes

List your quick notes — free-form captures waiting for AI placement in the note tree (draft, analyzing, ready_for_review, confirmed, saved, cancelled). Project-scoped tokens only ever see quick notes tied to their project.

• project_id integer
  Only quick notes suggested or confirmed for this project
• status string
  Filter by pipeline stage
• limit integer
  Maximum quick notes to return (default 20)

get_quick_note

Read one quick note with its full AI placement analysis: general summary, branch analysis, detailed analysis, placement strategy, and confidence score.

• quick_note_id integer required
  ID returned by list_quick_notes

list_project_members

List everyone with access to a project: the owner plus each membership, with username, role, active flag, and join date. Use before removing a member or issuing an invite link.

• project_id integer required
  Project whose members to list

list_invite_links

List the project's one-time invite links with their tokens, paths, and consumption state. Owner-only. Use preview_create_invite_link to mint a new one.

• project_id integer required
  Project whose invite links to list

list_tags

List every tag used on a project's notes with how many notes carry it, ordered by frequency. Use this to discover the project's tag vocabulary before tagging or calling list_notes_by_tag.

• project_id integer required
  Project whose note tags to aggregate

get_note_path

Get the breadcrumb from the project root down to a note: every ancestor in order plus a human-readable 'A / B / C' string. Use it to explain where a note lives before moving or updating it.

• note_id integer required
  Note to trace back to the root

get_note_children

List the direct children of a note in sibling order, with each child's own children count. Cheaper than get_note_tree when you only need to walk one level at a time.

• note_id integer required
  Parent note whose direct children to list

list_ai_analyses

List stored AI analyses for a project (presentation, audience, strategy) with token usage and cost. Set include_content=true to get the full analysis body and prompt instead of a 500-character preview.

• project_id integer required
  Project whose analyses to list
• type string
  Filter by analysis type
• include_content boolean
  Return the full analysis body and prompt (default false)
• limit integer
  Maximum analyses to return (default 10)

get_project_stats

Get counts and health metrics for a project in one call: notes by type/relation/depth, tasks by status and priority, ideas, comments, analyses, members, change count, and last activity timestamps. Use it to report progress without pulling content.

• project_id integer required
  Project to summarize

export_project

Export the whole project as one JSON document: metadata, flat notes, the note tree, tasks, ideas, comments, AI analyses, public settings, and change log. Sections your token cannot read are skipped and named in omitted_sections. Use for backups, migrations, or loading everything into another tool.

• project_id integer required
  Project to export
• include_changes boolean
  Include the change log section (default true)
• changes_limit integer
  How many change-log entries to include (default 50)

whoami

Report the identity behind this connection: the Nibvine user, whether the credential is a scoped external token or a user token, its scopes, its project binding (if any), the accessible project IDs, and exactly which tools your scopes allow or block. Call this when a tool fails with a scope error.

preview_create_project

Preview creating a new Nibvine project. Returns a write_action_id — review the preview, then call commit_write_action to execute. Preview expires in 30 minutes.

• title string required
  Project name (required)
• description string
  Short description of what the project is
• goal string
  What the project aims to achieve
• vision string
  Long-term direction and spirit of the project
• unique_task string
  What makes this project different
• target_audience string
  Who the project is for
• success_metrics string
  How success will be measured
• tech_stack array
  Technologies, e.g. ['Python', 'Django', 'React']
• constraints string
  Budget, timeline, or resource limits
• category string
  Project category (default 'web')
• priority string
  Project priority (default 'medium')

preview_update_project

Preview updating project metadata. Pass only the fields you want to change. Returns a write_action_id — review, then commit. Preview expires in 30 minutes. Call get_project first to see current values.

• project_id integer required
  Project ID, from list_projects
• title string
  New project name
• description string
  New description
• goal string
  New goal
• vision string
  New long-term vision
• unique_task string
  What makes this project different
• target_audience string
  Who the project is for
• success_metrics string
  How success is measured
• tech_stack array
  Technologies, e.g. ['Python', 'Django', 'React']
• constraints string
  Budget, timeline, or resource limits
• category string
  Project category
• priority string
  Project priority
• completion_percentage integer
  Progress estimate from 0 to 100
• is_draft boolean
  Keep the project in draft state
• is_archived boolean
  Archive or unarchive the project
• formatted_idea string
  Full idea write-up for copying between chats
• ai_context object
  Structured JSON context stored for the LLM
• insights array
  Accumulated insights about the project
• suggested_goals array
  AI-suggested goals
• suggested_tasks array
  AI-suggested tasks

preview_create_note

Preview creating a new note. Set parent_note_id to nest under an existing note (use get_note_tree to find IDs). Returns write_action_id — review, then commit. Preview expires in 30 minutes.

• project_id integer required
  Project ID, from list_projects
• parent_note_id integer
  ID of parent note to nest under (omit for root-level)
• title string
  Note title (defaults to the first 80 characters of content)
• content string required
  Note body — required, markdown supported
• type string
  Block type, default 'text'
• relation_type string
  branch=major topic, dependency=depends on parent, reference=reference material, what_if=hypothesis, related=general
• tags array
  Tags for cross-cutting search, e.g. ['api', 'urgent']

preview_update_note

Preview updating an existing note. Pass only the fields you want to change. Call get_note(note_id) first to see current content. Returns write_action_id — review, then commit. Preview expires in 30 minutes.

• note_id integer required
  Note to update, from get_note_tree or search_notes
• project_id integer
  Optional: the note's project, inferred when omitted
• title string
  New title
• content string
  New body — replaces the current content
• type string
  New block type
• relation_type string
  New relation to the parent note
• tags array
  Replacement tag list (replaces all existing tags)

preview_create_task

Preview creating a new task. Returns write_action_id — review, then commit. Preview expires in 30 minutes.

• project_id integer required
  Project ID, from list_projects
• title string required
  Task title (required)
• description string
  What the task involves
• priority string
  Task priority, default 'medium'
• status string
  Default: todo
• is_completed boolean
  Must agree with status ('done' means completed)
• due_date string
  YYYY-MM-DD format

preview_update_task

Preview updating an existing task. Pass only changed fields. Call get_task(task_id) or list_tasks(project_id) to find task IDs. Returns write_action_id — review, then commit. Preview expires in 30 minutes.

• project_id integer
  Optional: the task's project, inferred when omitted
• task_id integer required
  Task to update, from list_tasks
• title string
  New title
• description string
  New description
• priority string
  New priority
• status string
  New status; setting 'done' also marks the task completed
• is_completed boolean
  Must agree with status ('done' means completed)
• due_date string
  YYYY-MM-DD format

preview_delete_note

Preview deleting a note. By default cascades (deletes children too). Set cascade=false to reparent children to the deleted note's parent. Returns write_action_id — review, then commit.

• note_id integer required
  Note to delete, from get_note_tree or search_notes
• cascade boolean
  Delete children too (default true). False = reparent children to the deleted note's parent.

preview_delete_task

Preview deleting a task. Returns a write_action_id — review the preview, then call commit_write_action. Deletion is permanent; prefer preview_update_task(status='done') to close work you want to keep. Preview expires in 30 minutes.

• task_id integer required
  Task to delete (from list_tasks)
• project_id integer
  Optional: the task's project, inferred when omitted

preview_delete_project

Preview deleting an entire project with all of its notes, tasks, ideas, comments, analyses, and history. Owner-only and irreversible: confirm_title must exactly match the project's current title. Returns a write_action_id — review the counts in the preview, then call commit_write_action.

• project_id integer required
  Project to delete
• confirm_title string required
  Must equal the project's exact title, as a typo-guard

preview_move_note

Preview re-parenting a note (with its whole subtree) and/or repositioning it among its siblings. Pass new_parent_note_id=null to move it to the project root; omit it to keep the current parent and only change position. position is the zero-based index among the target siblings; omit to append last. Depth and order of every descendant are recomputed on commit.

• note_id integer required
  Note to move
• new_parent_note_id ['integer', 'null']
  New parent note ID, or null for the project root. Omit to keep the current parent.
• position integer
  Zero-based index among the target siblings (omit to append)
• project_id integer
  Optional: the note's project, inferred when omitted

preview_reorder_notes

Preview reordering a sibling group. note_ids is the new front-to-back order and must contain direct children of parent_note_id (omit parent_note_id to reorder the project's root notes). Siblings you leave out keep their relative order after the listed ones. Returns a write_action_id — review, then commit.

• project_id integer required
  Project that owns the notes
• parent_note_id ['integer', 'null']
  Parent whose children are being reordered; omit or null for root notes
• note_ids array required
  Note IDs in their new order, first to last

preview_create_idea

Preview adding an idea to a project's idea list. Ideas are flat, lightweight sparks — use notes for structured knowledge and tasks for work items. Returns a write_action_id — review, then commit. Preview expires in 30 minutes.

• project_id integer required
  Project to add the idea to
• title string
  Short label (defaults to the first 80 characters of content)
• content string required
  The idea itself
• is_implemented boolean
  Mark as already implemented (default false)

preview_update_idea

Preview updating an idea. Pass only the fields you want to change — typically is_implemented=true once the idea ships. Returns a write_action_id — review, then commit.

• idea_id integer required
  Idea to update (from list_ideas)
• project_id integer
  Optional: the idea's project, inferred when omitted
• title string
  New title
• content string
  New content
• is_implemented boolean
  New implementation state

preview_delete_idea

Preview deleting an idea permanently. Returns a write_action_id — review, then commit. Consider preview_update_idea(is_implemented=true) instead when the idea was simply completed.

• idea_id integer required
  Idea to delete (from list_ideas)
• project_id integer
  Optional: the idea's project, inferred when omitted

preview_create_comment

Preview posting a comment into the project's chat stream. Attach it to a note with note_id, or reply inside a thread with parent_comment_id. role defaults to 'assistant' — the correct role for messages an AI agent writes; use 'user' only when relaying something the human said. Returns a write_action_id — review, then commit.

• project_id integer required
  Project to comment on
• content string required
  Comment body (markdown is rendered in the web UI)
• role string
  Author role, default 'assistant'
• note_id integer
  Attach the comment to this note instead of the project as a whole
• parent_comment_id integer
  Reply inside this thread (from list_comments / get_comment_thread)
• metadata object
  Optional JSON metadata stored alongside the comment

preview_create_quick_note

Preview capturing a quick note — free-form text parked for later placement in the note tree, exactly like the web quick-capture box. Optionally suggest a parent note. Use this when you have a thought worth keeping but no clear home yet; use preview_create_note when you know where it belongs. Returns a write_action_id — review, then commit.

• project_id integer required
  Project the quick note belongs to
• content string required
  Raw captured text
• status string
  Pipeline stage to start in (default 'draft')
• suggested_parent_note_id integer
  Note this capture probably belongs under

preview_import_notes

Preview importing a whole note subtree in one call. notes is a nested array where each node may carry its own children array, so a full branch (parents and descendants) is created by a single commit. Attach it under parent_note_id or omit that for new root branches. Limits: 200 notes and 10 levels per import. Returns a write_action_id whose preview contains the outline — review, then commit.

• project_id integer required
  Project to import into
• parent_note_id ['integer', 'null']
  Existing note to hang the imported tree under; omit or null for root-level branches
• notes array required
  Top-level nodes to create, in order

preview_batch_create_notes

Preview creating up to 100 notes in one write action. Each entry is flat and may name an existing parent_note_id; parents created in the same batch are NOT addressable — use preview_import_notes for a new hierarchy. Returns a write_action_id — review, then commit.

• project_id integer required
  Project to create the notes in
• notes array required
  Notes to create, in order

preview_create_invite_link

Preview minting a new one-time invite link that lets another person join the project as a member. Owner-only. The committed result contains the token and the shareable URL. Returns a write_action_id — review, then commit.

• project_id integer required
  Project to invite someone to

preview_remove_member

Preview revoking a member's access to a project by deactivating their membership. Owner-only; the owner cannot be removed. Identify the member by username or user_id from list_project_members. Returns a write_action_id — review, then commit.

• project_id integer required
  Project to remove the member from
• username string
  Member's username (from list_project_members)
• user_id integer
  Member's user ID, as an alternative to username

list_write_actions

List write actions created with this token — by default the pending previews that are still waiting for commit_write_action. Pass status='all' to include committed, expired, and canceled ones. Use it to recover a write_action_id you lost.

• project_id integer
  Only actions targeting this project
• status string
  Status filter (default 'preview')
• limit integer
  Maximum actions to return (default 20)

cancel_write_action

Discard a pending write action so it can never be committed. Use it when the preview is wrong or the user declines. Already-committed actions cannot be canceled; expired previews simply become uncommittable on their own.

• write_action_id string required
  UUID returned by any preview_* tool

commit_write_action

Execute a previously previewed write action. Call this after reviewing the preview from any preview_* tool. The write_action_id comes from the preview response. Previews expire after 30 minutes — if expired, create a new preview.

• write_action_id string required
  UUID returned by any preview_* tool