# MCP Tools Reference — Dock Editor

38 tools for document manipulation via MCP protocol.

## Tools

### list_documents
List the user's documents, newest first.

- `limit` (optional, 1-100, default 50)
- `offset` (optional, default 0)
- Returns: array of `{ id, title, status, createdAt, updatedAt, isPublished, publicSlug }`

### read_document
Read a document's content.

- `id` (required) — document UUID
- `format` (optional) — `"markdown"` (default), `"json"` (structured JSON), or `"nodes"` (per-node breakdown)
- Returns: document with content in the requested format. Markdown format includes the title as the first H1 line (`# Title\n\n{body}`).

When `format=nodes`, the response contains a flat array of block-level nodes, each with:
- `index` — zero-based position in the document
- `attrs.nodeId` — unique identifier for targeting edits. New documents have stable ids; older documents get stable ids after their next save (a missing id is assigned in the response only)
- All other node data (type, content, etc.)

This is useful for targeting specific sections when the same text appears multiple times.

### create_document
Create a new blank document.

- `title` (optional) — document title (if omitted, stored empty; the editor shows "Untitled" as a placeholder)
- Returns: `{ id, title, createdAt, url }`

### write_document
Update a document's content. A version snapshot is created automatically before
the write, so the previous version is always recoverable.

- `id` (required) — document UUID
- `content` (optional) — document content as markdown (or structured JSON if format="json"). Omit to update only the title (the body is left untouched).
- `title` (optional) — update the document title
- `format` (optional) — `"markdown"` (default) or `"json"`
- Provide `content`, `title`, or both.
- Returns: `{ id, title, updatedAt, url, publishedUrl }`

### delete_document
Permanently delete a document.

- `id` (required) — document UUID
- Returns: `{ success: true, id }`

### duplicate_document
Create a copy of an existing document. The copy starts as a draft with "(Copy)"
appended to the title.

- `id` (required) — document UUID to duplicate
- Returns: `{ document: { id, title, status, createdAt, url } }`

### publish_document
Publish a document to a public URL.

- Requires a non-empty document title. Publishing an untitled document returns an error ("Add a title before publishing"). Set the title first via write_document (markdown starting with `# Title`) or update_document.
- `id` (required) — document UUID
- `slug` (optional) — custom URL slug (auto-generated from title if omitted)
- `seoTitle` (optional) — SEO title override
- `seoDescription` (optional) — SEO description
- `isListed` (optional, boolean, default true) — whether the document appears in public listings
- Returns: `{ success: true, slug, url }`

Publishing an already-published document re-publishes it — regenerates the
public page with current content while keeping the same URL slug. You do not
need a separate "update published page" command.

The published page is accessible at `agentdock.ai/p/{slug}`.

### unpublish_document
Revert a published document back to draft status.

- `id` (required) — document UUID
- Returns: `{ success: true }`

### list_folders
List all document folders for the authenticated user.

- No inputs required
- Returns: array of `{ id, name, parentId }`

### create_folder
Create a new document folder.

- `name` (required) — folder name
- `parentId` (optional) — parent folder UUID (omit for root level)
- Returns: `{ folder: { id, name, parentId } }`

### update_folder
Rename or move a folder.

- `folderId` (required) — folder UUID to update
- `name` (optional) — new folder name
- `parentId` (optional) — new parent folder UUID (null to move to root)
- Returns: `{ folder: { id, name, parentId } }`

### delete_folder
Delete a folder. Child folders are deleted recursively. Documents in deleted
folders are moved to root.

- `folderId` (required) — folder UUID to delete
- Returns: `{ success: true }`

### suggest_edits
Propose a specific text change. The document owner sees the change as
tracked edits (red deletion, green insertion) and can accept or reject.

- `id` (required) — document UUID
- `find` (required) — the exact text to find in the document
- `replace` (required) — the replacement text (empty string to suggest deletion)
- `authorName` (optional) — your display name (default: "AI Agent")
- `reason` (optional) — why you're suggesting this change
- `nodeId` (optional) — target a specific node by its ID from `format=nodes` (new documents have stable ids; older ones become stable after their next save)
- `nodeIndex` (optional) — target a specific node by its zero-based index
- Returns: `{ suggestionsCount: 1, suggestions: [...] }`

Example: To change "dramatically outpace" to "significantly outperform":
```
suggest_edits(id: "abc-123", find: "dramatically outpace", replace: "significantly outperform", reason: "more precise language")
```

### import_web_page
Import a web page URL as a new editable document. Uses server-side content
extraction for clean, readable results.

- `url` (required) — URL of the web page to import
- `title` (optional) — custom title (defaults to page title)
- Returns: `{ id, title, source }`
- Note: Document-scoped tokens (ak_doc_) cannot use this tool

### move_document
Move a document to a different folder, or to the root (no folder).

- `id` (required) — document UUID
- `folderId` (required) — target folder UUID, or `null` for root
- Returns: `{ id, folderId, moved: true }`

### update_document_settings
Update per-document preferences. Currently supports citation style. Read
settings via `read_document` with `format=json`.

- `id` (required) — document UUID
- `citationStyle` (required) — one of: APA, MLA, Chicago, Harvard, IEEE, AMA, Vancouver
- Returns: `{ id, citationStyle }`

### list_versions
List version history for a document. Returns metadata without content (version
number, reason, word count, timestamp). Each `write_document` call creates a
version snapshot automatically.

- `id` (required) — document UUID
- Returns: `{ versions: [{ id, versionNumber, reason, wordCount, createdAt }] }`

### read_version
Read a specific version's full content. Use `list_versions` first to find
version IDs.

- `id` (required) — document UUID
- `versionId` (required) — version UUID from `list_versions`
- Returns: `{ version: { id, versionNumber, content, createdAt } }`

### list_suggestions
List pending suggestions on a document.

- `id` (required) — document UUID
- Returns: array of `{ id, type, from, to, content, authorName, reason, createdAt }`

### accept_suggestion
Accept a specific suggestion (applies the change).

- `id` (required) — document UUID
- `suggestionId` (required) — suggestion UUID
- Returns: `{ success: true }`

### reject_suggestion
Reject a specific suggestion (discards it).

- `id` (required) — document UUID
- `suggestionId` (required) — suggestion UUID
- Returns: `{ success: true }`


## Prompts

### list_user_prompts
List the user's personal prompts and system-provided prompts.

- `includeSystem` (optional, boolean, default true) — include system-provided prompts
- `limit` (optional, 1-200, default 100)
- Returns: `{ prompts: [...], count }`

### get_user_prompt
Read a specific prompt by ID. Returns the full prompt text and metadata.

- `promptId` (required) — prompt UUID
- Returns: `{ prompt: { id, title, text, ... } }`

## In-Document Citations

### add_citation
Add a citation to an existing document. The citation is placed inline at the
end of the specified paragraph.

- `id` (required) — document UUID
- `identifier` (required) — DOI, URL, "pmid:12345", or "arxiv:2301.07041"
- `paragraphIndex` (optional) — which paragraph to cite (0-based). Default: last paragraph.
- `style` (optional) — citation style (apa, mla, chicago, harvard, ieee, ama, vancouver)
- `format` (optional) — `"parenthetical"` = (Smith, 2024), `"narrative"` = Smith (2024)
- `saveToLibrary` (optional, boolean, default false) — also save to personal library
- Returns: `{ citation: { id, formattedText, title, authors, year, doi, savedToLibrary } }`

### search_citations
Search for papers to cite. Returns verified sources from real databases.

- `query` (required) — search text (3-500 chars)
- `limit` (optional, 1-10, default 5)
- `yearFrom` / `yearTo` (optional) — publication year range
- Returns: array of citation candidates with DOI, title, authors, year, journal

### list_citations
List all citations currently in a document.

- `id` (required) — document UUID
- Returns: array of `{ id, title, authors, year, doi, formattedText }`

### remove_citation
Remove a citation from a document.

- `id` (required) — document UUID
- `citationId` (required) — citation ID (from list_citations)
- Returns: `{ success: true }`

## Citation Library

### citation_library_list
List citations from your personal library.

- `limit` (optional, 1-100, default 50)
- `sortBy` (optional) — `"recent"` (default), `"usage"`, or `"title"`
- Returns: `{ citations: [...], count }`

### citation_library_save
Save a citation to your personal library. Automatically formats in all 7 citation styles.

- `title` (required) — citation title
- `authors` (required) — array of `{ firstName, lastName }`
- `year` (optional) — publication year
- `citationType` (optional) — CSL type (default: article-journal)
- `metadata` (optional) — additional fields (doi, journal, volume, etc.)
- Returns: `{ citation: { id, title, formattedApa } }`

### citation_library_get
Read a single citation from your library by ID.

- `citationId` (required) — citation UUID
- Returns: `{ citation: { ... } }`

### citation_library_search
Search your personal citation library using full-text search.

- `query` (required) — search text
- `limit` (optional, 1-50, default 20)
- Returns: `{ citations: [...], count }`

### citation_library_delete
Delete a citation from your personal library.

- `citationId` (required) — citation UUID to delete
- Returns: `{ success: true }`

### citation_format
Format a citation in a specific style without saving to your library.

- `title` (required) — citation title
- `authors` (required) — array of `{ firstName, lastName }`
- `year` (optional) — publication year
- `style` (required) — apa, mla, chicago, harvard, ieee, ama, or vancouver
- `format` (optional) — `"parenthetical"` (default) or `"narrative"`
- `doi` (optional) — DOI
- `journal` (optional) — journal name
- Returns: `{ formattedText, style }`

## Citation Collections

### citation_collection_list
List your citation collections.

- `counts` (optional, boolean) — include citation counts per collection
- Returns: `{ collections: [...] }`

### citation_collection_create
Create a new collection.

- `name` (required) — collection name
- `description` (optional) — collection description
- `parentId` (optional) — parent collection UUID (for nested collections)
- Returns: `{ collection: { id, name } }`

### citation_collection_add
Add a citation from your library to a collection.

- `citationId` (required) — citation UUID
- `collectionId` (required) — collection UUID
- Returns: `{ success: true }`

### citation_collection_remove
Remove a citation from a collection. The citation remains in your library.

- `collectionId` (required) — collection UUID
- `citationId` (required) — citation UUID to remove
- Returns: `{ success: true }`

### citation_collection_delete
Delete a collection. Child collections are deleted recursively. Citations
in the collection are not deleted from your library.

- `collectionId` (required) — collection UUID to delete
- Returns: `{ success: true }`