tododdle-mcp 3.8.0 → 3.9.1

package/dist/server.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { readFileSync } from 'node:fs';
 import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { z } from 'zod';
+import { ToDoddleApiError } from './api-client.js';
 import { prepareUploadSource } from './upload-source.js';
 import { TODODDLE_WORKFLOW_GUIDANCE } from './workflow-guidance.js';
 const packageVersion = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'));
@@ -229,6 +230,85 @@ const assessmentEvidenceSchema = z
         });
     }
 });
+/**
+ * Turns a ToDoddle API failure into a tool error the agent can act on. The SDK
+ * default keeps only the message, which dropped the scope an owner must grant.
+ */
+export function apiErrorResult(error) {
+    const missing = error.scopes?.missingScopes ?? [];
+    const hint = error.code === 'scope_required' && missing.length
+        ? `Ask a workspace owner or admin to enable ${missing.join(', ')} for this Agent Connection in Workspace Settings > Agent Connections, then retry.`
+        : error.code === 'scope_required'
+            ? 'Ask a workspace owner or admin to check the scopes on this Agent Connection in Workspace Settings > Agent Connections.'
+            : runEnvelopeRequired(error.details)
+                ? 'This ticket has an active Agent Run for this connection. Pass the runId and projectId of that run with this call, then retry.'
+                : undefined;
+    const body = {
+        error: error.code,
+        status: error.status,
+        message: error.message,
+        ...(missing.length ? { missingScopes: missing } : {}),
+        ...(error.scopes?.requiredScopes ? { requiredScopes: error.scopes.requiredScopes } : {}),
+        ...(hint ? { hint } : {}),
+        ...(error.details !== undefined ? { details: error.details } : {}),
+    };
+    return { isError: true, content: [{ type: 'text', text: JSON.stringify(body) }] };
+}
+function runEnvelopeRequired(details) {
+    return (typeof details === 'object' &&
+        details !== null &&
+        details.reason === 'RUN_ENVELOPE_REQUIRED');
+}
+const LINK_KEYS = new Set(['uiUrl', 'href']);
+/**
+ * The API returns web links as paths such as /dashboard/project/x. Left
+ * relative, a client guesses the host and often picks www.tododdle.com, which
+ * is the marketing site. Turn them into absolute links on the app origin.
+ * In-app embed paths (/api/documents/...) are left alone.
+ */
+export function absolutizeLinks(value, appOrigin) {
+    if (Array.isArray(value))
+        return value.map((item) => absolutizeLinks(item, appOrigin));
+    if (!value || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+        key,
+        LINK_KEYS.has(key) &&
+            typeof item === 'string' &&
+            item.startsWith('/') &&
+            !item.startsWith('//')
+            ? new URL(item, appOrigin).toString()
+            : absolutizeLinks(item, appOrigin),
+    ]));
+}
+function withAbsoluteLinks(result, appOrigin) {
+    const typed = result;
+    if (!appOrigin || !typed?.structuredContent)
+        return result;
+    const structuredContent = absolutizeLinks(typed.structuredContent, appOrigin);
+    return {
+        ...typed,
+        structuredContent,
+        content: [{ type: 'text', text: JSON.stringify(structuredContent) }],
+    };
+}
+/**
+ * Wraps every tool so API failures keep their code, scopes, and hint, and
+ * web links in results are absolute.
+ */
+function withApiErrorResults(server, appOrigin) {
+    const register = server.registerTool.bind(server);
+    server.registerTool = (name, config, callback) => register(name, config, (async (...args) => {
+        try {
+            return withAbsoluteLinks(await callback(...args), appOrigin);
+        }
+        catch (error) {
+            if (error instanceof ToDoddleApiError)
+                return apiErrorResult(error);
+            throw error;
+        }
+    }));
+}
 function toolResult(value) {
     return {
         // Keep text content for clients that do not consume structuredContent, but
@@ -338,8 +418,35 @@ const completeUploadInputSchema = z.object({
     error: z.string().max(1000).optional(),
     idempotencyKey: z.string().min(8),
 });
+const EMBEDDABLE_IMAGE_TYPES = new Set(['image/png', 'image/jpeg', 'image/gif', 'image/webp']);
+/** Escapes a file name for use as Markdown image alt text. */
+function markdownAlt(value) {
+    return value.replace(/[\\[\]]/g, '\\$&');
+}
+/**
+ * Adds what an agent needs next: `embedMarkdown` to show an image inline in a
+ * Note or Context, and a `notice` when the stored type differs. ToDoddle stores
+ * SVG, HTML, and other active content as an opaque file so it never runs in a
+ * browser; an SVG previews and embeds through a PNG rendering instead.
+ */
+function withUploadHints(result, requestedType, fileName) {
+    const entity = asRecord(result.entity);
+    const storedType = entity?.mimeType;
+    const id = typeof entity?.id === 'string' ? entity.id : undefined;
+    const isSvg = /\.svg$/i.test(fileName);
+    const hints = {};
+    if (id && typeof storedType === 'string' && (EMBEDDABLE_IMAGE_TYPES.has(storedType) || isSvg)) {
+        hints.embedMarkdown = `![${markdownAlt(fileName)}](/api/documents/${id}/${isSvg ? 'thumbnail' : 'embed'})`;
+    }
+    if (typeof storedType === 'string' && storedType !== requestedType) {
+        hints.notice = isSvg
+            ? `Stored as ${storedType}: ToDoddle keeps SVG files as opaque downloads for safety. Previews and embeds use a PNG rendering of it, so embedMarkdown still shows the image.`
+            : `Stored as ${storedType}, not ${requestedType}. ToDoddle stores HTML and other active content as an opaque file for safety. It downloads normally but does not preview inline.`;
+    }
+    return { ...result, ...hints };
+}
 async function uploadDocument(api, options, input) {
-    const prepared = await prepareUploadSource(input, options.uploadRoots, options.maxUploadBytes, options.managedUploadRoot);
+    const prepared = await prepareUploadSource(input, options.maxUploadBytes, options.managedUploadRoot);
     let session = null;
     let bytesUploaded = false;
     let uploadConfirmed = false;
@@ -357,7 +464,7 @@ async function uploadDocument(api, options, input) {
         bytesUploaded = true;
         const result = await api.post(`/api/external/projects/${input.projectId}/documents/${session.documentId}/finalize`, { success: true, taskId: input.taskId }, `${idempotencyKey}-finalize`);
         uploadConfirmed = true;
-        return result;
+        return withUploadHints(result, prepared.contentType, prepared.fileName);
     }
     catch (error) {
         if (session && !bytesUploaded) {
@@ -426,11 +533,12 @@ const securityEventTypes = [
 ];
 export function createToDoddleMcpServer(api, serverOptions = {}) {
     const options = {
-        uploadRoots: serverOptions.uploadRoots ?? [],
         managedUploadRoot: serverOptions.managedUploadRoot,
+        appOrigin: serverOptions.appOrigin,
         maxUploadBytes: serverOptions.maxUploadBytes ?? 1024 * 1024 * 1024,
     };
     const server = new McpServer({ name: 'tododdle', version: packageVersion.version }, { instructions: TODODDLE_WORKFLOW_GUIDANCE });
+    withApiErrorResults(server, options.appOrigin);
     server.registerTool('list_projects', {
         description: 'List projects accessible through this Agent Connection.',
         inputSchema: z.object({
@@ -735,7 +843,7 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
         }, async ({ projectId, planId, sectionId, expectedUpdatedAt }) => toolResult(await api.put(`/api/external/projects/${projectId}/plans/${planId}/sections/${sectionId}`, { archived, expectedUpdatedAt })));
     }
     server.registerTool('list_releases', {
-        description: 'List bounded release summaries in one project. Filter by status or a version and title search. Needs the `releases:read` scope.',
+        description: 'List bounded release summaries in one project. Filter by status or a version and title search. The result has total (releases that match) and archivedHidden (archived releases left out; set includeArchived to see them), so an empty list is not ambiguous. Needs the `releases:read` scope.',
         inputSchema: z.object({
             projectId: z.string().min(1),
             search: z.string().trim().max(100).optional(),
@@ -765,8 +873,18 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
             openWorldHint: false,
         },
     }, async ({ projectId, releaseId, taskId, runId }) => toolResult(await api.get(`/api/external/projects/${projectId}/releases/${releaseId}`, undefined, projectRunContext(runId, projectId, taskId, 'READ_PROJECT_DATA'))));
+    server.registerTool('get_release_metadata_templates', {
+        description: 'Get the release metadata templates (App Store, Google Play). Each field has the key to use in release metadata, the store character limit (maxLength), the format (text or url), and a hint. Needs the `releases:read` scope.',
+        inputSchema: z.object({}),
+        annotations: {
+            readOnlyHint: true,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async () => toolResult(await api.get('/api/external/release-metadata-templates')));
     server.registerTool('create_release', {
-        description: 'Create a PENDING release in one project. Needs the `releases:write` scope and project owner or admin access. Publishing or abandoning a release needs request_release_status_change and human approval.',
+        description: 'Create a PENDING release in one project. Needs the `releases:write` scope and project owner or admin access. For store metadata, use the field keys from get_release_metadata_templates (for example "What\'s New" or "Promotional text"). The response has warnings when a value is over a store limit or a URL field is not a link; the release still saves. Publishing or abandoning a release needs request_release_status_change and human approval.',
         inputSchema: z.object({
             projectId: z.string().min(1),
             version: z.string().trim().min(1).max(100),
@@ -782,7 +900,7 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
         },
     }, async ({ projectId, idempotencyKey, taskId, runId, ...body }) => toolResult(await api.post(`/api/external/projects/${projectId}/releases`, body, idempotencyKey, projectRunContext(runId, projectId, taskId, 'UPDATE_INTERNAL_WORKFLOW'))));
     server.registerTool('update_release', {
-        description: 'Update release details using expectedRevision from the latest read. This tool cannot change status or archive state; use request_release_status_change for those. Archived releases cannot be edited.',
+        description: 'Update release details using expectedRevision from the latest read. The response has warnings when a metadata value breaks a store limit from get_release_metadata_templates. This tool cannot change status or archive state; use request_release_status_change for those. Archived releases cannot be edited.',
         inputSchema: z.object({
             projectId: z.string().min(1),
             releaseId: releaseIdSchema,
@@ -1177,7 +1295,7 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
         },
     }, async ({ projectId, noteId }) => toolResult(await api.get(`/api/external/notes/${noteId}`, { projectId })));
     server.registerTool('create_note', {
-        description: 'Create a workspace or project Note. Supply projectId for a project Note.',
+        description: 'Create a workspace or project Note. Supply projectId for a project Note. To show an uploaded image inline, paste the embedMarkdown returned by upload_project_document or complete_upload, for example ![Map](/api/documents/<documentId>/embed); it shows only to people who can open that document.',
         inputSchema: z.object({
             projectId: z.string().min(1).optional(),
             title: z.string().min(1).max(500),
@@ -1193,7 +1311,7 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
         },
     }, async ({ idempotencyKey, ...body }) => toolResult(await api.post('/api/external/notes', body, idempotencyKey)));
     server.registerTool('update_note', {
-        description: 'Update a workspace or project Note using optimistic concurrency.',
+        description: 'Update a workspace or project Note using optimistic concurrency. To show an uploaded image inline, paste the embedMarkdown returned by upload_project_document or complete_upload, for example ![Map](/api/documents/<documentId>/embed); it shows only to people who can open that document.',
         inputSchema: z.object({
             projectId: z.string().min(1).optional(),
             noteId: z.string().min(1),
@@ -1263,9 +1381,16 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ projectId, documentId, idempotencyKey, ...body }) => toolResult(await api.post(`/api/external/projects/${projectId}/documents/${documentId}/finalize`, body, idempotencyKey)));
+    }, async ({ projectId, documentId, idempotencyKey, ...body }) => {
+        const result = await api.post(`/api/external/projects/${projectId}/documents/${documentId}/finalize`, body, idempotencyKey);
+        // The remote client sent the bytes, so the stored type is the only type to compare.
+        const entity = asRecord(result.entity);
+        const fileName = typeof entity?.fileName === 'string' ? entity.fileName : '';
+        const storedType = typeof entity?.mimeType === 'string' ? entity.mimeType : '';
+        return toolResult(body.success === false ? result : withUploadHints(result, storedType, fileName));
+    });
     server.registerTool('upload_project_document', {
-        description: 'Upload an approved local file or HTTPS URL to a project document library. Local paths must be regular files in the system temporary directory (or an optional approved upload root) and owned by the current user.',
+        description: 'Upload an approved local file or HTTPS URL to a project document library. Local paths must be regular files in the system temporary directory, owned by the current user; copy a file there first if needed. SVG and HTML are stored as opaque files that download but do not preview.',
         inputSchema: uploadInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -1275,7 +1400,7 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
         },
     }, async (input) => toolResult(await uploadDocument(api, options, input)));
     server.registerTool('attach_file_to_ticket', {
-        description: 'Upload a local file or HTTPS URL and attach it to a ticket in the same project. Local paths must be regular files in the system temporary directory (or an optional approved upload root) and owned by the current user.',
+        description: 'Upload a local file or HTTPS URL and attach it to a ticket in the same project. Local paths must be regular files in the system temporary directory, owned by the current user; copy a file there first if needed. SVG and HTML are stored as opaque files that download but do not preview.',
         inputSchema: taskUploadInputSchema,
         annotations: {
             readOnlyHint: false,
@@ -1394,14 +1519,14 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
         },
     }, async ({ taskId }) => toolResult(await api.delete(`/api/external/focus/${taskId}`, {})));
     server.registerTool('search_project', {
-        description: 'Find compact ticket, board, lane, Note, Context, and document matches within one known project. Use this for discovery before narrow get tools instead of scanning every board or lane.',
+        description: 'Find compact ticket, board, lane, Note, Context, document, and release matches within one known project. Release matches need the `releases:read` scope and match the version, title, or build. Use this for discovery before narrow get tools instead of scanning every board or lane. Each result has relevance (0 to 1; 0.8 or more is an exact or phrase title match) and matchedTerms. Matching uses titles only; an empty result means no title matched well.',
         inputSchema: z.object({
             projectId: z.string().min(1),
             query: z.string().trim().min(2).max(200),
             types: z
-                .array(z.enum(['TICKET', 'BOARD', 'LANE', 'NOTE', 'CONTEXT', 'DOCUMENT']))
+                .array(z.enum(['TICKET', 'BOARD', 'LANE', 'NOTE', 'CONTEXT', 'DOCUMENT', 'RELEASE']))
                 .min(1)
-                .max(6)
+                .max(7)
                 .optional(),
             limit: z.number().int().min(1).max(50).default(20),
         }),
@@ -1756,6 +1881,49 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
             openWorldHint: false,
         },
     }, async ({ taskId, runId, projectId, ...body }) => toolResult(await api.post(`/api/external/tasks/${taskId}/agent-runs/${runId}`, body, undefined, runContext(runId, projectId, taskId, 'RECORD_EVIDENCE'))));
+    server.registerTool('log_completed_work', {
+        description: 'Record finished ad-hoc work in one call, for quick requests done in conversation without claiming a ticket first. ' +
+            'Pass taskId for an existing ticket, or ticket (planId, sectionId, title) to create one. ToDoddle claims it, sets the status, and records a finished Agent Run with your outcome and evidence (commits, tests, files, links), so it shows in run history like claimed work. ' +
+            'status defaults to COMPLETE. A ticket another person created goes to REVIEW instead; the response warns you, and you should then call create_review_request. ' +
+            'Use claim_ticket and finish_agent_run for planned work. Reuse the same idempotencyKey to retry safely.',
+        inputSchema: z.object({
+            projectId: z.string().min(1),
+            taskId: z.string().min(1).optional(),
+            ticket: z
+                .object({
+                planId: z.string().min(1),
+                sectionId: z.string().min(1),
+                title: z.string().trim().min(1).max(500),
+                description: z.string().trim().max(50_000).optional(),
+                kind: taskKindSchema.optional(),
+                priority: prioritySchema.optional(),
+            })
+                .optional(),
+            runId: z.string().min(1).max(200).optional(),
+            outcome: z.string().trim().min(1).max(2000),
+            evidence: z
+                .array(z.object({
+                type: agentRunEvidenceTypeSchema,
+                reference: z.string().trim().min(1).max(2000),
+                label: z.string().trim().min(1).max(200).optional(),
+            }))
+                .max(25)
+                .default([]),
+            status: z.enum(['COMPLETE', 'REVIEW']).default('COMPLETE'),
+            idempotencyKey: z.string().trim().min(8).max(180),
+        }),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: false,
+            idempotentHint: true,
+            openWorldHint: false,
+        },
+    }, async ({ projectId, ...body }) => {
+        if (Boolean(body.taskId) === Boolean(body.ticket)) {
+            throw new Error('Send taskId for an existing ticket or ticket to create one, not both.');
+        }
+        return toolResult(await api.post(`/api/external/projects/${projectId}/completed-work`, body));
+    });
     server.registerTool('get_supervisor_state', {
         description: 'Get compact, permission-filtered task state for an external decision or supervision provider. The response contains evidence and policy hints, but grants no authority to change work state.',
         inputSchema: z.object({
@@ -2228,7 +2396,10 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
         },
     }, async ({ projectId, artifactId, idempotencyKey, ...body }) => toolResult(await api.post(`/api/external/projects/${projectId}/artifacts/${artifactId}/relations`, body, idempotencyKey)));
     server.registerTool('update_project_artifact', {
-        description: 'Update artifact Markdown, its current short summary, or metadata using optimistic concurrency. Editing approved content returns it to draft.',
+        description: 'Update artifact Markdown, its current short summary, or metadata using optimistic concurrency. Editing approved content returns it to draft. ' +
+            'To change part of a long document, send contentEdits instead of content: replace_section (by heading path, e.g. "Release Plan" or "Plan > Risks"; replaces the text under that heading and keeps its subsections), append_section (optionally inside a parent heading), or find_replace (exact text; expectedCount defaults to 1). ' +
+            'Pass baseVersion (the version you read) so an edit still applies when someone else changed a different section; the server rejects it if your section changed. ' +
+            'The response is a slim summary (id, version, updatedAt, changedFields) unless verbose is true. Embed an uploaded image with the embedMarkdown returned by the upload tools.',
         inputSchema: z.object({
             projectId: z.string().min(1),
             artifactId: z.string().min(1),
@@ -2236,10 +2407,36 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
             title: z.string().min(1).optional(),
             summary: z.string().trim().max(500).nullable().optional(),
             content: z.string().optional(),
+            contentEdits: z
+                .array(z.discriminatedUnion('op', [
+                z.object({
+                    op: z.literal('replace_section'),
+                    heading: z.string().min(1).max(500),
+                    content: z.string(),
+                }),
+                z.object({
+                    op: z.literal('append_section'),
+                    heading: z.string().min(1).max(200),
+                    content: z.string(),
+                    parent: z.string().min(1).max(500).optional(),
+                    level: z.number().int().min(1).max(6).optional(),
+                }),
+                z.object({
+                    op: z.literal('find_replace'),
+                    find: z.string().min(1),
+                    replace: z.string(),
+                    expectedCount: z.number().int().min(1).max(1000).optional(),
+                }),
+            ]))
+                .min(1)
+                .max(20)
+                .optional(),
+            baseVersion: z.number().int().min(1).optional(),
             parentArtifactId: z.string().min(1).nullable().optional(),
             ownerId: z.string().optional(),
             metadata: z.record(z.unknown()).optional(),
             changeNote: z.string().optional(),
+            verbose: z.boolean().default(false),
         }),
         annotations: {
             readOnlyHint: false,
@@ -2247,7 +2444,15 @@ export function createToDoddleMcpServer(api, serverOptions = {}) {
             idempotentHint: true,
             openWorldHint: false,
         },
-    }, async ({ projectId, artifactId, ...body }) => toolResult(await api.patch(`/api/external/projects/${projectId}/artifacts/${artifactId}`, body)));
+    }, async ({ projectId, artifactId, verbose, ...body }) => {
+        const result = await api.patch(`/api/external/projects/${projectId}/artifacts/${artifactId}${verbose ? '' : '?detail=summary'}`, body);
+        // An older ToDoddle server strips contentEdits it does not know and reports success.
+        const changedFields = result.changedFields;
+        if (body.contentEdits && Array.isArray(changedFields) && !changedFields.includes('content')) {
+            throw new Error('This ToDoddle server does not support contentEdits yet. Send the full content instead.');
+        }
+        return toolResult(result);
+    });
     server.registerTool('transition_project_artifact', {
         description: 'Submit, approve, supersede, archive, or return a project artifact to draft.',
         inputSchema: z.object({