update_doc
Update an existing document by modifying its title, text, or folder. Validates references and sends only changed fields.
Instructions
Update an existing document (title, text, or folder). Validates references and only sends changed fields.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| doc_id | Yes | Document doc_id to update | |
| updates | Yes | Fields to update |
Implementation Reference
- src/tools/update_doc.ts:37-220 (handler)Main handler for the update_doc tool. Validates inputs (doc_id, updates, folder reference), resolves folder names to IDs, calls DartClient.updateDoc(), and returns the updated document with a deep link URL.
export async function handleUpdateDoc(input: UpdateDocInput): Promise<UpdateDocOutput> { const DART_TOKEN = process.env.DART_TOKEN; if (!DART_TOKEN) { throw new DartAPIError( 'DART_TOKEN environment variable is required. Get your token from: https://app.dartai.com/?settings=account', 401 ); } // ============================================================================ // Step 1: Validate input and doc_id // ============================================================================ if (!input || typeof input !== 'object') { throw new DartAPIError( 'input is required and must be an object', 400 ); } if (!input.doc_id || typeof input.doc_id !== 'string' || input.doc_id.trim() === '') { throw new DartAPIError( 'doc_id is required and must be a non-empty string', 400 ); } // ============================================================================ // Step 2: Validate updates object // ============================================================================ if (!input.updates || typeof input.updates !== 'object') { throw new ValidationError( 'updates is required and must be an object', 'updates' ); } const updateKeys = Object.keys(input.updates); if (updateKeys.length === 0) { throw new ValidationError( 'updates must contain at least one field to update', 'updates' ); } // ============================================================================ // Step 3: Validate folder reference (if updating folder) // ============================================================================ let resolvedFolder: string | undefined; if (input.updates.folder !== undefined) { if (input.updates.folder === null || input.updates.folder === '') { // Allow clearing folder resolvedFolder = input.updates.folder as string | undefined; } else if (typeof input.updates.folder === 'string') { // Validate folder exists let config: DartConfig; try { config = await handleGetConfig({ cache_bust: false }); } catch (error) { if (error instanceof DartAPIError) { throw new DartAPIError( `Failed to retrieve workspace config for folder validation: ${error.message}`, error.statusCode, error.response ); } throw error; } if (!config.folders || config.folders.length === 0) { throw new ValidationError( 'No folders found in workspace configuration. Create a folder first in Dart AI.', 'folder' ); } const folder = findFolder(config.folders, input.updates.folder); if (!folder) { const folderNames = getFolderNames(config.folders); const availableFolders = folderNames.join(', '); throw new ValidationError( `Invalid folder: "${input.updates.folder}" not found in workspace. Available folders: ${availableFolders}`, 'folder', folderNames ); } resolvedFolder = folder.dart_id; } else { // Invalid type for folder throw new ValidationError( `folder must be a string or null (received: ${typeof input.updates.folder})`, 'folder' ); } } // ============================================================================ // Step 4: Validate title and text (if provided) // ============================================================================ if (input.updates.title !== undefined) { if (typeof input.updates.title !== 'string' || input.updates.title.trim() === '') { throw new ValidationError( 'title must be a non-empty string', 'title' ); } } if (input.updates.text !== undefined) { if (typeof input.updates.text !== 'string') { throw new ValidationError( 'text must be a string', 'text' ); } } // ============================================================================ // Step 5: Build updates object with resolved references // ============================================================================ const resolvedUpdates: { title?: string; text?: string; folder?: string } = {}; const updatedFields: string[] = []; if (input.updates.title !== undefined) { resolvedUpdates.title = input.updates.title; updatedFields.push('title'); } if (input.updates.text !== undefined) { resolvedUpdates.text = input.updates.text; updatedFields.push('text'); } if (input.updates.folder !== undefined) { resolvedUpdates.folder = resolvedFolder; updatedFields.push('folder'); } // ============================================================================ // Step 6: Call DartClient.updateDoc() // ============================================================================ const client = new DartClient({ token: DART_TOKEN }); let updatedDoc; try { updatedDoc = await client.updateDoc({ doc_id: input.doc_id, updates: resolvedUpdates, }); } catch (error) { // Handle 404 errors specifically if (error instanceof DartAPIError && error.statusCode === 404) { throw new DartAPIError( `Document not found: No document with doc_id "${input.doc_id}" exists in workspace`, 404, error.response ); } // Re-throw other errors with enhanced context if (error instanceof DartAPIError) { throw new DartAPIError( `Failed to update document: ${error.message}`, error.statusCode, error.response ); } throw error; } // ============================================================================ // Step 7: Generate deep link URL and return output // ============================================================================ const deepLinkUrl = `https://app.dartai.com/doc/${updatedDoc.doc_id}`; return { doc_id: updatedDoc.doc_id, updated_fields: updatedFields, doc: updatedDoc, url: deepLinkUrl, }; } - src/types/index.ts:565-572 (schema)Input type definition for update_doc tool: requires doc_id string and an updates object with optional title, text, and folder fields.
export interface UpdateDocInput { doc_id: string; updates: { title?: string; text?: string; folder?: string; }; } - src/types/index.ts:574-579 (schema)Output type definition: returns doc_id, list of updated_fields, the full DartDoc object, and a deep link URL to the document.
export interface UpdateDocOutput { doc_id: string; updated_fields: string[]; doc: DartDoc; url: string; } - src/index.ts:730-759 (registration)Tool registration in the MCP server's tool list with name 'update_doc', description, and JSON Schema input definition.
name: 'update_doc', description: 'Update an existing document (title, text, or folder). Validates references and only sends changed fields.', inputSchema: { type: 'object', properties: { doc_id: { type: 'string', description: 'Document doc_id to update', }, updates: { type: 'object', description: 'Fields to update', properties: { title: { type: 'string', description: 'Document title', }, text: { type: 'string', description: 'Document text (markdown supported)', }, folder: { type: 'string', description: 'Folder dart_id or name', }, }, }, }, required: ['doc_id', 'updates'], }, - src/index.ts:1148-1158 (registration)Case statement in the request handler that dispatches 'update_doc' calls to handleUpdateDoc and formats the output as JSON text.
case 'update_doc': { const result = await handleUpdateDoc((args || {}) as any); return { content: [ { type: 'text', text: JSON.stringify(result, null, 2), }, ], }; }