Skip to content

TaskView is a self-hosted project and task management platform focused on clarity, ownership, and control. TaskView is built for teams that want a transparent, self-hosted alternative to SaaS task managers.

wip: mcp

Nikolai Giman796b3dc6000f
diff --git a/taskview-packages/taskview-api/src/tv.ts b/taskview-packages/taskview-api/src/tv.ts
index abeafb1..bbc4528 100644
--- a/taskview-packages/taskview-api/src/tv.ts
+++ b/taskview-packages/taskview-api/src/tv.ts
@@ -127,6 +127,10 @@ export class TvApi {
this.files = new TvFilesApi(this.$axios);
}
+ public get baseUrl(): string | undefined {
+ return this.$axios.defaults.baseURL;
+ }
+
public setBaseUrl(baseUrl: string) {
this.$axios.defaults.baseURL = baseUrl;
}
diff --git a/taskview-packages/taskview-mcp/README.md b/taskview-packages/taskview-mcp/README.md
index 478e3b2..ae75459 100644
--- a/taskview-packages/taskview-mcp/README.md
+++ b/taskview-packages/taskview-mcp/README.md
@@ -155,7 +155,7 @@ there is no browser to complete an authorization flow.
## Available tools
-61 tools covering the full TaskView surface.
+68 tools covering the full TaskView surface.
**Projects (Goals)** — `list_goals`, `create_goal`, `update_goal`, `delete_goal`
@@ -179,6 +179,8 @@ there is no browser to complete an authorization flow.
**Time tracking** — `start_timer`, `stop_timer`, `get_active_timer`, `log_time`, `list_time_entries`, `update_time_entry`, `delete_time_entry`, `get_time_summary`, `get_time_report`, `get_time_contributors`
+**Files** — `list_files`, `get_file`, `get_file_download_url`, `attach_files_to_task`, `detach_file_from_task`, `rename_file`, `delete_file` (metadata and short-lived download links for existing attachments; uploading goes through the app)
+
## How it works
The MCP server uses the `taskview-api` client under the hood. Every tool call goes through the full API stack — authentication, permission checks, and validation. The MCP process itself is stateless; your token never leaves your machine except in `Authorization: Bearer ...` headers to your TaskView API server.
diff --git a/taskview-packages/taskview-mcp/src/__tests__/annotations.test.ts b/taskview-packages/taskview-mcp/src/__tests__/annotations.test.ts
index df55955..9b42061 100644
--- a/taskview-packages/taskview-mcp/src/__tests__/annotations.test.ts
+++ b/taskview-packages/taskview-mcp/src/__tests__/annotations.test.ts
@@ -10,6 +10,7 @@ import { registerNotificationsTools } from '../tools/notifications.js'
import { registerStartTools } from '../tools/start.js'
import { registerOrganizationsTools } from '../tools/organizations.js'
import { registerTimeTrackingTools } from '../tools/time-tracking.js'
+import { registerFilesTools } from '../tools/files.js'
import { mockServer, mockApi, findTool } from './setup.js'
const REQUIRED_HINTS = ['readOnlyHint', 'destructiveHint', 'openWorldHint'] as const
@@ -28,6 +29,7 @@ function registerEverything() {
registerStartTools(server, api)
registerOrganizationsTools(server, api)
registerTimeTrackingTools(server, api)
+ registerFilesTools(server, api)
return tools
}
diff --git a/taskview-packages/taskview-mcp/src/__tests__/files.test.ts b/taskview-packages/taskview-mcp/src/__tests__/files.test.ts
new file mode 100644
index 0000000..dd1fa51
--- /dev/null
+++ b/taskview-packages/taskview-mcp/src/__tests__/files.test.ts
@@ -0,0 +1,112 @@
+import { describe, it, expect } from 'vitest'
+import { registerFilesTools } from '../tools/files.js'
+import { mockServer, mockApi, apiReturn, apiThrow, findTool, ts } from './setup.js'
+
+const FILE_ID = '4eddd060-ed84-4cfd-b2e3-2256bdd47ddb'
+
+function withBaseUrl(api: ReturnType<typeof mockApi>, baseUrl: string | undefined) {
+ Object.defineProperty(api, 'baseUrl', { value: baseUrl })
+ return api
+}
+
+describe('files tools', () => {
+ it('registers all file tools', () => {
+ const { server, tools } = mockServer()
+ registerFilesTools(server, mockApi())
+
+ expect(tools.map((t) => t.name)).toEqual([
+ 'list_files', 'get_file', 'get_file_download_url', 'attach_files_to_task',
+ 'detach_file_from_task', 'rename_file', 'delete_file',
+ ])
+ })
+
+ it('list_files lists project files when no taskId is given', async () => {
+ const { server, tools } = mockServer()
+ const name = `spec-${ts()}.pdf`
+ const listForGoal = apiReturn({ items: [{ id: FILE_ID, name, linkedTaskIds: [] }], nextCursor: null })
+ const listForTask = apiThrow('must not be called')
+ registerFilesTools(server, mockApi({ files: { listForGoal, listForTask } }))
+
+ const result = await findTool(tools, 'list_files').cb({ goalId: 1, search: 'spec', type: 'document' })
+ expect(result.isError).toBeUndefined()
+ expect(result.content[0].text).toContain(name)
+ })
+
+ it('list_files lists task files when taskId is given', async () => {
+ const { server, tools } = mockServer()
+ const name = `task-${ts()}.png`
+ registerFilesTools(server, mockApi({
+ files: { listForTask: apiReturn([{ id: FILE_ID, name, linkedTaskIds: [10] }]), listForGoal: apiThrow('must not be called') },
+ }))
+
+ const result = await findTool(tools, 'list_files').cb({ goalId: 1, taskId: 10 })
+ expect(result.content[0].text).toContain(name)
+ })
+
+ it('get_file returns the file', async () => {
+ const { server, tools } = mockServer()
+ const name = `one-${ts()}.txt`
+ registerFilesTools(server, mockApi({ files: { getById: apiReturn({ id: FILE_ID, name }) } }))
+
+ const result = await findTool(tools, 'get_file').cb({ fileId: FILE_ID })
+ expect(result.content[0].text).toContain(name)
+ })
+
+ it('get_file_download_url makes the link absolute against the API base URL', async () => {
+ const { server, tools } = mockServer()
+ const api = withBaseUrl(mockApi({
+ files: { downloadUrl: apiReturn({ url: '/module/files/content/tok.sig', expiresAt: '2026-10-04T10:00:00.000Z' }) },
+ }), 'https://api.example.com')
+ registerFilesTools(server, api)
+
+ const result = await findTool(tools, 'get_file_download_url').cb({ fileId: FILE_ID, inline: true })
+ const parsed = JSON.parse(result.content[0].text)
+ expect(parsed.url).toBe('https://api.example.com/module/files/content/tok.sig')
+ expect(parsed.expiresAt).toBe('2026-10-04T10:00:00.000Z')
+ })
+
+ it('get_file_download_url keeps the relative link when no base URL is known', async () => {
+ const { server, tools } = mockServer()
+ const api = withBaseUrl(mockApi({
+ files: { downloadUrl: apiReturn({ url: '/module/files/content/tok.sig', expiresAt: 'x' }) },
+ }), undefined)
+ registerFilesTools(server, api)
+
+ const result = await findTool(tools, 'get_file_download_url').cb({ fileId: FILE_ID })
+ expect(JSON.parse(result.content[0].text).url).toBe('/module/files/content/tok.sig')
+ })
+
+ it('attach_files_to_task returns the attached files', async () => {
+ const { server, tools } = mockServer()
+ registerFilesTools(server, mockApi({ files: { link: apiReturn([{ id: FILE_ID, linkedTaskIds: [7] }]) } }))
+
+ const result = await findTool(tools, 'attach_files_to_task').cb({ taskId: 7, fileIds: [FILE_ID] })
+ expect(result.content[0].text).toContain(FILE_ID)
+ })
+
+ it('detach_file_from_task and delete_file report success', async () => {
+ const { server, tools } = mockServer()
+ registerFilesTools(server, mockApi({ files: { unlink: apiReturn(null), deleteForever: apiReturn(null) } }))
+
+ expect((await findTool(tools, 'detach_file_from_task').cb({ taskId: 7, fileId: FILE_ID })).content[0].text).toContain('true')
+ expect((await findTool(tools, 'delete_file').cb({ fileId: FILE_ID })).content[0].text).toContain('true')
+ })
+
+ it('rename_file returns the renamed file', async () => {
+ const { server, tools } = mockServer()
+ const name = `renamed-${ts()}.txt`
+ registerFilesTools(server, mockApi({ files: { rename: apiReturn({ id: FILE_ID, name }) } }))
+
+ const result = await findTool(tools, 'rename_file').cb({ fileId: FILE_ID, name })
+ expect(result.content[0].text).toContain(name)
+ })
+
+ it('surfaces API errors, e.g. storage not configured', async () => {
+ const { server, tools } = mockServer()
+ registerFilesTools(server, mockApi({ files: { downloadUrl: apiThrow('File storage is not configured on this server') } }))
+
+ const result = await findTool(tools, 'get_file_download_url').cb({ fileId: FILE_ID })
+ expect(result.isError).toBe(true)
+ expect(result.content[0].text).toContain('not configured')
+ })
+})
diff --git a/taskview-packages/taskview-mcp/src/__tests__/integration/files.integration.test.ts b/taskview-packages/taskview-mcp/src/__tests__/integration/files.integration.test.ts
new file mode 100644
index 0000000..85413c3
--- /dev/null
+++ b/taskview-packages/taskview-mcp/src/__tests__/integration/files.integration.test.ts
@@ -0,0 +1,112 @@
+import axios from 'axios'
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import { registerGoalsTools } from '../../tools/goals.js'
+import { registerTasksTools } from '../../tools/tasks.js'
+import { registerFilesTools } from '../../tools/files.js'
+import { api, captureServer, call, parse, ts } from './setup.js'
+
+const { server, tools } = captureServer()
+registerGoalsTools(server, api)
+registerTasksTools(server, api)
+registerFilesTools(server, api)
+
+const content = `mcp files integration ${ts()}`
+let goalId: number
+let taskId: number
+let fileId: string
+
+beforeAll(async () => {
+ const goal = await call(tools, 'create_goal', { name: `Files MCP Test ${ts()}` })
+ goalId = parse(goal).id
+ const task = await call(tools, 'create_task', { goalId, description: `task with files ${ts()}` })
+ taskId = parse(task).id
+
+ // Uploading is deliberately not an MCP tool, so the fixture file goes in through the API client.
+ const uploaded = await api.files.upload({
+ goalId,
+ taskId: null,
+ file: new Blob([content], { type: 'text/plain' }),
+ fileName: `notes-${ts()}.txt`,
+ })
+ fileId = uploaded.id
+})
+
+afterAll(async () => {
+ await call(tools, 'delete_file', { fileId }).catch(() => {})
+ await call(tools, 'delete_goal', { goalId }).catch(() => {})
+})
+
+describe('files integration', () => {
+ it('lists the uploaded file among the project files and finds it by search', async () => {
+ const all = parse(await call(tools, 'list_files', { goalId }))
+ expect(all.items.map((f: { id: string }) => f.id)).toContain(fileId)
+
+ const found = parse(await call(tools, 'list_files', { goalId, search: 'notes-', type: 'document' }))
+ expect(found.items.map((f: { id: string }) => f.id)).toContain(fileId)
+
+ const none = parse(await call(tools, 'list_files', { goalId, type: 'image' }))
+ expect(none.items.map((f: { id: string }) => f.id)).not.toContain(fileId)
+ })
+
+ it('gets the file with its metadata', async () => {
+ const file = parse(await call(tools, 'get_file', { fileId }))
+ expect(file.id).toBe(fileId)
+ expect(file.goalId).toBe(goalId)
+ expect(file.mimeType).toBe('text/plain')
+ expect(file.sizeBytes).toBe(Buffer.byteLength(content))
+ expect(file.linkedTaskIds).toEqual([])
+ })
+
+ it('attaches the file to a task and lists it under the task', async () => {
+ const attached = parse(await call(tools, 'attach_files_to_task', { taskId, fileIds: [fileId] }))
+ expect(attached[0].linkedTaskIds).toContain(taskId)
+
+ const taskFiles = parse(await call(tools, 'list_files', { goalId, taskId }))
+ expect(taskFiles.map((f: { id: string }) => f.id)).toEqual([fileId])
+ })
+
+ it('issues a download link that serves the bytes without authentication', async () => {
+ const link = parse(await call(tools, 'get_file_download_url', { fileId }))
+ expect(link.url).toMatch(/^https?:\/\/.+\/module\/files\/content\//)
+ expect(new Date(link.expiresAt).getTime()).toBeGreaterThan(Date.now())
+
+ const response = await axios.get(link.url, { responseType: 'text', validateStatus: () => true })
+ expect(response.status).toBe(200)
+ expect(response.data).toBe(content)
+ expect(response.headers['content-disposition']).toContain('attachment')
+ })
+
+ it('renames the file and keeps the extension', async () => {
+ const renamed = parse(await call(tools, 'rename_file', { fileId, name: 'renamed-by-mcp' }))
+ expect(renamed.name).toBe('renamed-by-mcp.txt')
+ })
+
+ it('detaches the file from the task but keeps it in the project', async () => {
+ expect(parse(await call(tools, 'detach_file_from_task', { taskId, fileId })).success).toBe(true)
+
+ const taskFiles = parse(await call(tools, 'list_files', { goalId, taskId }))
+ expect(taskFiles).toEqual([])
+ const file = parse(await call(tools, 'get_file', { fileId }))
+ expect(file.linkedTaskIds).toEqual([])
+ })
+
+ it('refuses to attach a file to a task of another project', async () => {
+ const other = parse(await call(tools, 'create_goal', { name: `Files MCP Other ${ts()}` }))
+ try {
+ const foreignTask = parse(await call(tools, 'create_task', { goalId: other.id, description: 'foreign' }))
+ const result = await call(tools, 'attach_files_to_task', { taskId: foreignTask.id, fileIds: [fileId] })
+ expect(result.isError).toBe(true)
+ } finally {
+ await call(tools, 'delete_goal', { goalId: other.id }).catch(() => {})
+ }
+ })
+
+ it('deletes the file forever', async () => {
+ expect(parse(await call(tools, 'delete_file', { fileId })).success).toBe(true)
+
+ const gone = await call(tools, 'get_file', { fileId })
+ expect(gone.isError).toBe(true)
+ const all = parse(await call(tools, 'list_files', { goalId }))
+ expect(all.items.map((f: { id: string }) => f.id)).not.toContain(fileId)
+ })
+})
diff --git a/taskview-packages/taskview-mcp/src/__tests__/setup.ts b/taskview-packages/taskview-mcp/src/__tests__/setup.ts
index a4ad0f3..734df94 100644
--- a/taskview-packages/taskview-mcp/src/__tests__/setup.ts
+++ b/taskview-packages/taskview-mcp/src/__tests__/setup.ts
@@ -33,6 +33,10 @@ export function mockApi(overrides: Record<string, Record<string, unknown>> = {})
reportByDay: noop, reportByUser: noop, reportByTask: noop, reportSummary: noop,
reportContributors: noop,
},
+ files: {
+ listForGoal: noop, listForTask: noop, getById: noop, downloadUrl: noop,
+ link: noop, unlink: noop, rename: noop, deleteForever: noop,
+ },
}
for (const [ns, methods] of Object.entries(overrides)) {
diff --git a/taskview-packages/taskview-mcp/src/server.ts b/taskview-packages/taskview-mcp/src/server.ts
index 906db37..2c98171 100644
--- a/taskview-packages/taskview-mcp/src/server.ts
+++ b/taskview-packages/taskview-mcp/src/server.ts
@@ -11,6 +11,7 @@ import { registerNotificationsTools } from './tools/notifications.js'
import { registerStartTools } from './tools/start.js'
import { registerOrganizationsTools } from './tools/organizations.js'
import { registerTimeTrackingTools } from './tools/time-tracking.js'
+import { registerFilesTools } from './tools/files.js'
const INSTRUCTIONS = `TaskView is a project and task management platform.
@@ -26,7 +27,11 @@ WORKFLOW: all IDs are numeric and must be resolved first — never guess them. M
list_tasks is paginated: page is 0-based, ~30 tasks per page — request the next page until one returns fewer than 30. Completed tasks are hidden unless showCompleted is set. Use sortBy ("date" or "priority") with descending to control ordering.
-AGENDA: for "what do I have today", "what is coming up" or "what did I finish recently", call get_agenda. It returns today, upcoming, recently completed and undated tasks across every project in a single request, with the day boundary computed on the server. Do NOT answer those questions by listing projects and walking their tasks — that is many times slower and gets the day wrong for anyone outside UTC. Pass the user's IANA timezone when you know it.`
+AGENDA: for "what do I have today", "what is coming up" or "what did I finish recently", call get_agenda. It returns today, upcoming, recently completed and undated tasks across every project in a single request, with the day boundary computed on the server. Do NOT answer those questions by listing projects and walking their tasks — that is many times slower and gets the day wrong for anyone outside UTC. Pass the user's IANA timezone when you know it.
+
+TASK FIELDS: "description" is the task title (short, one line). "note" is the task body, stored as HTML - send <p>, <ul>, <ol>, <b> markup, never plain newlines. update_task replaces the note entirely, so to append read it with get_task first and send the merged HTML.
+
+FILES: tasks and projects can have file attachments, identified by a uuid fileId. list_files shows them (pass taskId for one task, omit it for the whole project), get_file_download_url gives a 5-minute link to the bytes, attach_files_to_task / detach_file_from_task move existing files between tasks. Uploading new files is not available over MCP — ask the user to upload in the app, then attach.`
export function createMcpServer(api: TvApi) {
const server = new McpServer(
@@ -48,6 +53,7 @@ export function createMcpServer(api: TvApi) {
registerStartTools(server, api)
registerOrganizationsTools(server, api)
registerTimeTrackingTools(server, api)
+ registerFilesTools(server, api)
return server
}
diff --git a/taskview-packages/taskview-mcp/src/tools/files.ts b/taskview-packages/taskview-mcp/src/tools/files.ts
new file mode 100644
index 0000000..49841d0
--- /dev/null
+++ b/taskview-packages/taskview-mcp/src/tools/files.ts
@@ -0,0 +1,143 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import type { TvApi } from 'taskview-api'
+import { z } from 'zod'
+import { ok, err, toolAnnotations } from './helpers.js'
+
+const fileId = z.string().uuid().describe('File ID (uuid)')
+
+export function registerFilesTools(server: McpServer, api: TvApi) {
+ server.registerTool(
+ 'list_files',
+ {
+ title: 'List files',
+ annotations: toolAnnotations.readOnly,
+ description:
+ 'List files attached to a project or to one task. With taskId returns the files of that task; '
+ + 'without it returns the project files page by page (nextCursor → cursor). '
+ + 'Each file carries linkedTaskIds — the tasks it is attached to.',
+ inputSchema: {
+ goalId: z.coerce.number().describe('Project (goal) ID'),
+ taskId: z.coerce.number().optional().describe('Task ID — list only the files attached to this task'),
+ search: z.string().optional().describe('Filter project files by name (ignored with taskId)'),
+ type: z.enum(['image', 'document', 'all']).optional().describe('Filter project files by kind (ignored with taskId)'),
+ cursor: z.string().optional().describe('nextCursor from the previous page (ignored with taskId)'),
+ limit: z.coerce.number().optional().describe('Page size, up to 200 (ignored with taskId)'),
+ },
+ },
+ async ({ goalId, taskId, search, type, cursor, limit }) => {
+ try {
+ if (taskId !== undefined) return ok(await api.files.listForTask(taskId))
+ return ok(await api.files.listForGoal({ goalId, search, type, cursor, limit }))
+ } catch (e) { return err(e) }
+ },
+ )
+
+ server.registerTool(
+ 'get_file',
+ {
+ title: 'Get file',
+ annotations: toolAnnotations.readOnly,
+ description: 'Get one file by ID: name, mime type, size, uploader, creation date and the tasks it is attached to',
+ inputSchema: { fileId },
+ },
+ async ({ fileId }) => {
+ try {
+ return ok(await api.files.getById(fileId))
+ } catch (e) { return err(e) }
+ },
+ )
+
+ server.registerTool(
+ 'get_file_download_url',
+ {
+ title: 'Get file download URL',
+ annotations: toolAnnotations.readOnly,
+ description:
+ 'Issue a short-lived (5 minutes) download link for a file. No authentication is needed to open it. '
+ + 'Fails when file storage is not configured on the server.',
+ inputSchema: {
+ fileId,
+ inline: z.boolean().optional().describe('true to open in the browser instead of downloading'),
+ },
+ },
+ async ({ fileId, inline }) => {
+ try {
+ const issued = await api.files.downloadUrl({ fileId, inline: inline ?? false })
+ const base = api.baseUrl
+ const url = base ? new URL(issued.url, base.endsWith('/') ? base : `${base}/`).toString() : issued.url
+ return ok({ url, expiresAt: issued.expiresAt })
+ } catch (e) { return err(e) }
+ },
+ )
+
+ server.registerTool(
+ 'attach_files_to_task',
+ {
+ title: 'Attach files to task',
+ annotations: toolAnnotations.write,
+ description: 'Attach existing project files to a task. The files must belong to the same project as the task',
+ inputSchema: {
+ taskId: z.coerce.number().describe('Task ID'),
+ fileIds: z.array(z.string().uuid()).min(1).describe('File IDs to attach'),
+ },
+ },
+ async ({ taskId, fileIds }) => {
+ try {
+ return ok(await api.files.link({ taskId, fileIds }))
+ } catch (e) { return err(e) }
+ },
+ )
+
+ server.registerTool(
+ 'detach_file_from_task',
+ {
+ title: 'Detach file from task',
+ annotations: toolAnnotations.write,
+ description: 'Remove a file from a task. The file itself stays in the project',
+ inputSchema: {
+ taskId: z.coerce.number().describe('Task ID'),
+ fileId,
+ },
+ },
+ async ({ taskId, fileId }) => {
+ try {
+ await api.files.unlink({ taskId, fileId })
+ return ok({ success: true })
+ } catch (e) { return err(e) }
+ },
+ )
+
+ server.registerTool(
+ 'rename_file',
+ {
+ title: 'Rename file',
+ annotations: toolAnnotations.write,
+ description: 'Rename a file. The original extension is kept',
+ inputSchema: {
+ fileId,
+ name: z.string().min(1).describe('New file name'),
+ },
+ },
+ async ({ fileId, name }) => {
+ try {
+ return ok(await api.files.rename({ fileId, name }))
+ } catch (e) { return err(e) }
+ },
+ )
+
+ server.registerTool(
+ 'delete_file',
+ {
+ title: 'Delete file',
+ annotations: toolAnnotations.destructive,
+ description: 'Delete a file forever from the project and from every task it is attached to',
+ inputSchema: { fileId },
+ },
+ async ({ fileId }) => {
+ try {
+ await api.files.deleteForever(fileId)
+ return ok({ success: true })
+ } catch (e) { return err(e) }
+ },
+ )
+}
diff --git a/taskview-packages/taskview-mcp/src/tools/tasks.ts b/taskview-packages/taskview-mcp/src/tools/tasks.ts
index 363b1eb..a029634 100644
--- a/taskview-packages/taskview-mcp/src/tools/tasks.ts
+++ b/taskview-packages/taskview-mcp/src/tools/tasks.ts
@@ -67,7 +67,7 @@ export function registerTasksTools(server: McpServer, api: TvApi) {
goalId: z.coerce.number().describe('Project (goal) ID'),
description: z.string().describe('Task title/description'),
goalListId: z.coerce.number().optional().nullable().describe('List ID within the project'),
- note: z.string().optional().nullable().describe('Additional notes'),
+ note: z.string().optional().nullable().describe('Task note, separate from the description (the title). Stored and rendered as HTML: wrap paragraphs in <p>, lists in <ul>/<ol>; plain newlines collapse'),
priorityId: z.union([z.literal(1), z.literal(2), z.literal(3)]).optional()
.describe('Priority: 1=low, 2=medium, 3=high'),
startDate: z.string().optional().nullable().describe('Start date (ISO format)'),
@@ -94,7 +94,7 @@ export function registerTasksTools(server: McpServer, api: TvApi) {
id: z.coerce.number().describe('Task ID to update'),
description: z.string().optional().describe('New task description'),
complete: z.boolean().optional().describe('Mark task as complete/incomplete'),
- note: z.string().optional().describe('Task notes'),
+ note: z.string().optional().describe('Task note, separate from the description (the title). Stored and rendered as HTML: wrap paragraphs in <p>, lists in <ul>/<ol>; plain newlines collapse. Replaces the whole note - read the current one with get_task first when appending'),
priorityId: z.union([z.literal(1), z.literal(2), z.literal(3)]).optional()
.describe('Priority: 1=low, 2=medium, 3=high'),
goalListId: z.coerce.number().optional().nullable().describe('Move to a different list'),