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.
TypeScript graphviewkanban-boardnodejsproductivityproject-managementself-hostedtasktask-managementtask-managertodoapp
wip: mcp
Nikolai Giman796b3dc6000f
diff --git a/taskview-packages/taskview-api/src/tv.ts b/taskview-packages/taskview-api/src/tv.tsindex 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.mdindex 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 worksThe 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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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. Mlist_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.tsnew file mode 100644index 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.tsindex 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'),