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: OAuth and mcp
Nikolai Giman3403e1a71d3a
diff --git a/api/src/tv-modules/oauth/OAuthController.ts b/api/src/tv-modules/oauth/OAuthController.tsindex cb4104d..3c53df4 100644--- a/api/src/tv-modules/oauth/OAuthController.ts+++ b/api/src/tv-modules/oauth/OAuthController.ts@@ -183,7 +183,7 @@ export class OAuthController {if (rejected) {return res.status(400).json({error: 'invalid_redirect_uri',- error_description: `redirect_uri must be https or loopback http: ${rejected}`,+ error_description: `redirect_uri must be https, loopback http, or an app scheme, and carry no fragment: ${rejected}`,})}@@ -200,7 +200,12 @@ export class OAuthController {return res.status(201).json({client_id: result.value.clientId,- ...(result.value.clientSecret ? { client_secret: result.value.clientSecret } : {}),+ // RFC 7591 §3.2.1: client_secret_expires_at is REQUIRED whenever a+ // secret is issued. 0 means it does not expire.+ ...(result.value.clientSecret+ ? { client_secret: result.value.clientSecret, client_secret_expires_at: 0 }+ : {}),+ client_id_issued_at: Math.floor(Date.now() / 1000),client_name: name,redirect_uris: data.redirect_uris,token_endpoint_auth_method: isPublic ? 'none' : 'client_secret_post',diff --git a/api/src/tv-modules/oauth/__tests__/OAuth.integration.spec.ts b/api/src/tv-modules/oauth/__tests__/OAuth.integration.spec.tsindex 965d6ff..8f7ae13 100644--- a/api/src/tv-modules/oauth/__tests__/OAuth.integration.spec.ts+++ b/api/src/tv-modules/oauth/__tests__/OAuth.integration.spec.ts@@ -193,6 +193,30 @@ describe('OAuth 2.1 authorization server', () => {expect(response.data.token_endpoint_auth_method).toBe('none');});+ it('reports when the client_id was issued (RFC 7591)', async () => {+ const before = Math.floor(Date.now() / 1000);+ const response = await registerClient();++ expect(response.status).toBe(201);+ expect(response.data.client_id_issued_at).toBeGreaterThanOrEqual(before - 5);+ expect(response.data.client_id_issued_at).toBeLessThanOrEqual(Math.floor(Date.now() / 1000) + 5);+ });++ it('omits client_secret_expires_at when no secret is issued', async () => {+ const response = await registerClient();++ expect(response.data.client_secret).toBeUndefined();+ expect(response.data.client_secret_expires_at).toBeUndefined();+ });++ it('states that an issued secret does not expire', async () => {+ const response = await registerClient({ token_endpoint_auth_method: 'client_secret_post' });++ expect(response.status).toBe(201);+ expect(response.data.client_secret).toBeTruthy();+ expect(response.data.client_secret_expires_at).toBe(0);+ });+it('refuses a non-https redirect_uri', async () => {const response = await registerClient({ redirect_uris: ['http://evil.example.com/cb'] });@@ -200,6 +224,23 @@ describe('OAuth 2.1 authorization server', () => {expect(response.data.error).toBe('invalid_redirect_uri');});+ it('registers a native app returning through its own scheme', async () => {+ const response = await registerClient({+ client_name: 'Native client',+ redirect_uris: ['com.example.app://oauth/callback'],+ });++ expect(response.status).toBe(201);+ expect(response.data.client_id).toBeTruthy();+ });++ it('refuses a scheme where redirecting would execute code', async () => {+ const response = await registerClient({ redirect_uris: ['javascript:alert(1)'] });++ expect(response.status).toBe(400);+ expect(response.data.error).toBe('invalid_redirect_uri');+ });+it('refuses a redirect_uri carrying a fragment', async () => {const response = await registerClient({ redirect_uris: ['https://client.test/cb#x'] });diff --git a/api/src/tv-modules/oauth/__tests__/oauth.utils.test.ts b/api/src/tv-modules/oauth/__tests__/oauth.utils.test.tsindex 21c4702..b9970ba 100644--- a/api/src/tv-modules/oauth/__tests__/oauth.utils.test.ts+++ b/api/src/tv-modules/oauth/__tests__/oauth.utils.test.ts@@ -98,8 +98,30 @@ describe('isAcceptableRedirectUri', () => {expect(isAcceptableRedirectUri('https://example.com/cb#token')).toBe(false)})- it('rejects a non-http scheme', () => {+ it('accepts a private-use scheme, which is how native apps come back (RFC 8252)', () => {+ expect(isAcceptableRedirectUri('com.example.app://oauth/callback')).toBe(true)+ expect(isAcceptableRedirectUri('myapp://callback')).toBe(true)+ })++ it('rejects schemes where redirecting would execute something', () => {expect(isAcceptableRedirectUri('javascript:alert(1)')).toBe(false)+ expect(isAcceptableRedirectUri('data:text/html,<script>alert(1)</script>')).toBe(false)+ expect(isAcceptableRedirectUri('vbscript:msgbox(1)')).toBe(false)+ expect(isAcceptableRedirectUri('file:///etc/passwd')).toBe(false)+ expect(isAcceptableRedirectUri('blob:https://example.com/x')).toBe(false)+ expect(isAcceptableRedirectUri('about:blank')).toBe(false)+ })++ it('still refuses plaintext http off loopback', () => {+ expect(isAcceptableRedirectUri('http://evil.example.com/cb')).toBe(false)+ })++ it('still refuses a fragment on any scheme', () => {+ expect(isAcceptableRedirectUri('com.example.app://cb#token')).toBe(false)+ })++ it('rejects a string that is not a URL at all', () => {+ expect(isAcceptableRedirectUri('not a url')).toBe(false)})})diff --git a/api/src/tv-modules/oauth/oauth.utils.ts b/api/src/tv-modules/oauth/oauth.utils.tsindex 01c4fc5..598f565 100644--- a/api/src/tv-modules/oauth/oauth.utils.ts+++ b/api/src/tv-modules/oauth/oauth.utils.ts@@ -70,6 +70,16 @@ export function matchesRegisteredRedirectUri(args: MatchRedirectUriArgs): boolea})}+/**+ * Schemes where "redirecting" means executing something rather than handing+ * control to an application. Everything else is allowed: RFC 8252 §7.1 has+ * native apps return through a private-use scheme (com.example.app://), and+ * refusing those locks every mobile client out of the flow. Interception of a+ * private-use scheme by another app on the device is what PKCE — mandatory here,+ * S256 only — exists to make useless.+ */+const DANGEROUS_REDIRECT_SCHEMES = ['javascript:', 'data:', 'vbscript:', 'file:', 'blob:', 'about:']+export function isAcceptableRedirectUri(raw: string): boolean {let parsed: URLtry {@@ -78,12 +88,13 @@ export function isAcceptableRedirectUri(raw: string): boolean {return false}if (parsed.hash) return false+ if (DANGEROUS_REDIRECT_SCHEMES.includes(parsed.protocol)) return falseif (parsed.protocol === 'https:') return true- // http is allowed only on loopback. There is deliberately no NODE_ENV escape- // hatch: an install running without NODE_ENV=production would otherwise let- // any client register a plaintext redirect to a host it does not control.+ // http stays loopback-only. There is deliberately no NODE_ENV escape hatch:+ // an install running without NODE_ENV=production would otherwise let any+ // client register a plaintext redirect to a host it does not control.if (parsed.protocol === 'http:') return isLoopbackUrl(parsed)- return false+ return true}export function buildRedirectUrl(args: BuildRedirectUrlArgs): string {diff --git a/docs/3.integrations/2.mcp.md b/docs/3.integrations/2.mcp.mdindex 7335f2a..f23a0ed 100644--- a/docs/3.integrations/2.mcp.md+++ b/docs/3.integrations/2.mcp.md@@ -1,6 +1,6 @@---title: MCP Server-description: Connect AI assistants like Claude Code and Claude Desktop to TaskView via the Model Context Protocol (MCP). Manage projects and tasks with a scoped API token.+description: Connect AI assistants like Claude Code, claude.ai and ChatGPT to TaskView via the Model Context Protocol (MCP). Authenticate with a scoped API token or over OAuth.navigation:icon: i-lucide-bot---@@ -15,7 +15,7 @@ Shared (HTTP): AI client ──HTTPS──▶ taskview-mcp container ──```- **Local (stdio)** — each user runs the server on their machine via `npx`; the token lives in the client config.-- **Shared (HTTP)** — one server container runs next to your TaskView instance; every user connects to its URL and authenticates with their own API token per request.+- **Shared (HTTP)** — one server container runs next to your TaskView instance; every user connects to its URL and authenticates with their own API token per request, or over [OAuth](#oauth-cloud-clients) for clients that cannot send a token header.## Prerequisites@@ -56,7 +56,8 @@ The `gimanhead/taskview-ce-mcp` image serves MCP over HTTP (Streamable HTTP tranrestart: unless-stoppedenvironment:# Where this MCP server forwards requests; the docker-network address- # of your API service works best+ # of your API service works best. For OAuth it must be the public API+ # URL instead — see below.TASKVIEW_URL: "http://taskview-api-server:1401"ports:- "3100:3100"@@ -88,10 +89,43 @@ or in `.mcp.json` (Claude Code, Cursor, VS Code):Put the port behind your reverse proxy with HTTPS for anything beyond local use.-::callout{icon="i-lucide-info" color="neutral"}-The claude.ai and Claude Desktop **custom connectors** UI supports only OAuth-based servers and has no field for a token header — it cannot connect to this endpoint yet. Claude Desktop users should use the local stdio configuration above instead.-::+## OAuth (cloud clients)++Cloud assistants have no field for a pasted token: claude.ai and Claude Desktop **custom connectors**, ChatGPT connectors and similar clients authorize over OAuth 2.1 instead. The shared HTTP server supports this with nothing extra to run. The MCP server presents itself as the protected resource and names your TaskView API as the authorization server; the API handles client registration, the consent screen and tokens.++What happens when a client connects:++1. The client calls `/mcp` without a token and gets `401` with a `WWW-Authenticate` header pointing at the resource metadata.+2. It reads `/.well-known/oauth-protected-resource` on the MCP server, then `/.well-known/oauth-authorization-server` on the API.+3. It registers itself (dynamic client registration, RFC 7591) and opens the TaskView consent screen in your browser.+4. You sign in and tick the permissions and projects the app may use. Ticking nothing grants your full access; your RBAC role is the ceiling either way.+5. The client receives a `tvo_` access token (valid 1 hour) and a refresh token (valid 30 days), and sends the access token to `/mcp` like any other bearer token.++To connect, paste the MCP URL (`https://mcp.your-domain.com/mcp`) into the client's custom connector form. When it asks you to authorize, the TaskView consent screen opens. Claude Code can use OAuth too: add the server without the `--header` flag and run `/mcp` to authenticate.++### Configuration for OAuth++- `MCP_PUBLIC_URL` on the MCP server — the public URL of the server exactly as clients reach it. This is the OAuth resource identifier. When unset it is derived from the request's `Host` and `X-Forwarded-Proto` headers.+- `TASKVIEW_URL` on the MCP server — advertised to clients as the authorization server, so for OAuth it must be the **public** API URL (`https://api.your-domain.com`), not the docker-network address from the example above.+- `API_PUBLIC_URL` and `APP_URL` on the API — the first names the authorization server in its metadata, the second is where the consent screen lives. See [environment variables](/docs/configuration/environment-variables#application).+- `OAUTH_DYNAMIC_REGISTRATION=false` on the API — stops new clients from registering themselves, which closes OAuth for new connections on a locked-down instance. Existing connected apps keep working.++**Mounted under a path.** When the MCP server sits behind a reverse proxy at `https://api.your-domain.com/mcp` rather than on its own host, put the full path into `MCP_PUBLIC_URL`. The resource metadata then also lives at `/.well-known/oauth-protected-resource/mcp` (RFC 9728), which is where a client that computes the address from the spec will look. The server publishes it at both that address and the root one, but the proxy has to route the path-inserted address to the MCP server too:++```nginx+location = /.well-known/oauth-protected-resource/mcp {+ proxy_pass http://127.0.0.1:3100/.well-known/oauth-protected-resource/mcp;+ proxy_set_header Host $host;+ proxy_set_header X-Forwarded-Proto $scheme;+}+```++### Managing connected apps++Every app you authorized is listed in your account settings under **Connected apps**, with the permissions and projects you granted and when it was last used. Revoking one cuts off its access immediately. OAuth tokens do not appear in the API tokens list and cannot be deleted from there.++Manually issued `tvk_` tokens keep working exactly as before. OAuth is an additional way in, not a replacement: use `tvk_` for stdio, CLIs and CI, where there is no browser to complete an authorization flow.## Permissions-The assistant can only do what the API token allows. Token permissions are scoped to selected projects and intersected with your RBAC role, so an AI client never exceeds your own access. Grant the minimum scope needed.+The assistant can only do what its credential allows. API token permissions are scoped to selected projects; an OAuth grant carries the permissions and projects you ticked on the consent screen. Both are intersected with your RBAC role, so an AI client never exceeds your own access. Grant the minimum scope needed.diff --git a/docs/4.configuration/1.environment-variables.md b/docs/4.configuration/1.environment-variables.mdindex e9c2db0..d4d8c7e 100644--- a/docs/4.configuration/1.environment-variables.md+++ b/docs/4.configuration/1.environment-variables.md@@ -51,6 +51,7 @@ Unlike everything else on this page, this variable is set on the **web app conta| `AUTH_LOGIN_METHODS` | No | all enabled | Comma-separated list of login methods to offer: `magic-link`, `password`, `sso`, `social`. Disabled methods disappear from the login page and their API endpoints return 403. The API refuses to start if the list contains a typo or disables every method. || `PASSWORD_CHANGE_CONFIRMATION` | No | `email` | How account password changes are confirmed: `email` — a confirmation code is sent to the user's email (requires SMTP); `password` — the user confirms with their current password (works without SMTP, recommended for installs without a mail server). || `ALLOW_PUBLIC_REGISTRATION` | No | `true` | Set to `false` to close the instance: strangers can no longer create accounts — the registration endpoint returns 403, and magic-link / social sign-in stop auto-creating users. Emails invited to an organization or project can still sign in and get their account created on first login. |+| `OAUTH_DYNAMIC_REGISTRATION` | No | `true` | Whether AI clients may register themselves as OAuth clients (RFC 7591) when connecting to the [MCP server](/docs/integrations/mcp#oauth-cloud-clients). Set to `false` on a locked-down instance: the registration endpoint returns 403 and no new OAuth connection can be started; apps already connected keep working. || `SSO_TRUSTED_DOMAINS` | No | empty | Comma-separated email domains that skip DNS/HTTP ownership checks for SSO (air-gapped / closed-network installs). Example: `company.com,corp.local`. On a public instance leave this unset so every org must prove it owns the domain. |::callout{icon="i-lucide-shield" color="warning"}diff --git a/taskview-packages/taskview-api/src/api/__tests__/start.test.ts b/taskview-packages/taskview-api/src/api/__tests__/start.test.tsnew file mode 100644index 0000000..9ade617--- /dev/null+++ b/taskview-packages/taskview-api/src/api/__tests__/start.test.ts@@ -0,0 +1,89 @@+import { TvApi } from '@/tv';+import {+ describe,+ it,+ expect,+ beforeAll,+ afterAll,+} from 'vitest';+import { initApi } from './init-api';+import { ymd } from './test-helpers';++/**+ * The main screen endpoint. It answers "what do I have today" in one request and+ * splits the day server-side in the caller's timezone — the reason a client must+ * not fetch every project and compare deadlines itself.+ */+describe('Start screen state', () => {+ let $api: TvApi;+ let goalId: number;++ beforeAll(async () => {+ const { $tvApi } = await initApi();+ $api = $tvApi;++ const goal = await $api.goals.createGoal({ name: `Agenda test-${Date.now()}` });+ goalId = goal!.id!;+ });++ afterAll(async () => {+ await $api.goals.deleteGoal(goalId).catch(() => {});+ });++ it('returns every bucket the main screen shows', async () => {+ const state = await $api.start.fetchAllState({ tz: 'UTC' });++ expect(state).toBeDefined();+ expect(Array.isArray(state!.tasksToday)).toBe(true);+ expect(Array.isArray(state!.tasksUpcoming)).toBe(true);+ expect(Array.isArray(state!.tasksLastCompleted)).toBe(true);+ expect(Array.isArray(state!.tasks)).toBe(true);+ });++ it('puts a task due today into tasksToday', async () => {+ const task = await $api.tasks.createTask({+ goalId,+ description: `Due today-${Date.now()}`,+ });+ await $api.tasks.updateTask({ id: task!.id, endDate: ymd(0) });++ const state = await $api.start.fetchAllState({ tz: 'UTC' });++ expect(state!.tasksToday.some((t) => t.id === task!.id)).toBe(true);+ expect(state!.tasksUpcoming.some((t) => t.id === task!.id)).toBe(false);+ });++ it('puts a task due later into tasksUpcoming', async () => {+ const task = await $api.tasks.createTask({+ goalId,+ description: `Due later-${Date.now()}`,+ });+ await $api.tasks.updateTask({ id: task!.id, endDate: ymd(7) });++ const state = await $api.start.fetchAllState({ tz: 'UTC' });++ expect(state!.tasksUpcoming.some((t) => t.id === task!.id)).toBe(true);+ expect(state!.tasksToday.some((t) => t.id === task!.id)).toBe(false);+ });++ it('keeps a task with no deadline out of both dated buckets', async () => {+ const task = await $api.tasks.createTask({+ goalId,+ description: `No deadline-${Date.now()}`,+ });++ const state = await $api.start.fetchAllState({ tz: 'UTC' });++ expect(state!.tasksToday.some((t) => t.id === task!.id)).toBe(false);+ expect(state!.tasksUpcoming.some((t) => t.id === task!.id)).toBe(false);+ });++ it('requires a timezone — the split is meaningless without one', async () => {+ const status = await $api.start+ .fetchAllState({ tz: '' })+ .then(() => 200)+ .catch((err) => err.status ?? err.response?.status);++ expect(status).toBe(400);+ });+});diff --git a/taskview-packages/taskview-api/src/api/start.ts b/taskview-packages/taskview-api/src/api/start.tsnew file mode 100644index 0000000..559e7dd--- /dev/null+++ b/taskview-packages/taskview-api/src/api/start.ts@@ -0,0 +1,29 @@+import TvApiBase from './base';+import type { AppResponse } from '@/api/base.types';+import type { StartScreenState, StartStateArgs } from './start.types';++/**+ * The main screen module. Its routes sit under /module/about for historical+ * reasons, while the backend module itself is called `start`.+ */+export default class TvStartApi extends TvApiBase {+ protected moduleUrl = '/module/about';++ /**+ * One request for what the main screen shows: today, upcoming and recently+ * completed tasks across every project the caller can see. The split happens+ * on the server in `tz`, so it matches the app — a client that fetches every+ * project and compares deadlines itself gets a different answer for anyone+ * outside UTC.+ */+ public async fetchAllState(args: StartStateArgs) {+ const params = new URLSearchParams({ tz: args.tz });+ if (args.organizationId) {+ params.set('organizationId', String(args.organizationId));+ }++ return this.request(+ this.$axios.get<AppResponse<StartScreenState>>(`${this.moduleUrl}/fetchallstate?${params.toString()}`)+ );+ }+}diff --git a/taskview-packages/taskview-api/src/api/start.types.ts b/taskview-packages/taskview-api/src/api/start.types.tsnew file mode 100644index 0000000..e35fd34--- /dev/null+++ b/taskview-packages/taskview-api/src/api/start.types.ts@@ -0,0 +1,30 @@+import type { Task } from './tasks.api.types';++export type StartScreenUsers = {+ id: number;+ name: string;+ users: { id: number; email: string }[];+}[];++export type StartScreenAssignees = {+ taskId: Task['id'];+ collabUserId: number;+ email: string;+}[];++/** Everything the main screen shows, split server-side in the caller's timezone. */+export type StartScreenState = {+ tasks: Task[];+ tasksToday: Task[];+ tasksUpcoming: Task[];+ tasksLastCompleted: Task[];+ users: StartScreenUsers;+ assignees: StartScreenAssignees;+ listToGoal: Record<number, number>;+};++export type StartStateArgs = {+ /** IANA timezone, e.g. "Europe/Belgrade". The API rejects the request without it. */+ tz: string;+ organizationId?: number;+};diff --git a/taskview-packages/taskview-api/src/index.ts b/taskview-packages/taskview-api/src/index.tsindex 1db36d0..7df96ac 100644--- a/taskview-packages/taskview-api/src/index.ts+++ b/taskview-packages/taskview-api/src/index.ts@@ -15,6 +15,7 @@ export * from '@/api/webhooks.types';export * from '@/api/messaging.types';export * from '@/api/api-tokens.types';export * from '@/api/oauth.types';+export * from '@/api/start.types';export * from '@/api/sessions.types';export * from '@/api/organizations.types';export * from '@/api/sso.types';diff --git a/taskview-packages/taskview-api/src/tv.ts b/taskview-packages/taskview-api/src/tv.tsindex a09fea9..cac7335 100644--- a/taskview-packages/taskview-api/src/tv.ts+++ b/taskview-packages/taskview-api/src/tv.ts@@ -12,6 +12,7 @@ import TvWebhooks from "./api/webhooks";import TvMessagingApi from "./api/messaging";import TvApiTokens from "./api/api-tokens";import TvOAuth from "./api/oauth";+import TvStartApi from "./api/start";import TvSessions from "./api/sessions";import TvOrganizationsApi from "./api/organizations";import TvSsoApi from "./api/sso";@@ -49,6 +50,7 @@ export class TvApi {public apiTokens: TvApiTokens;public oauth: TvOAuth;+ public start: TvStartApi;public sessions: TvSessions;@@ -93,6 +95,7 @@ export class TvApi {this.apiTokens = new TvApiTokens(this.$axios);this.oauth = new TvOAuth(this.$axios);+ this.start = new TvStartApi(this.$axios);this.sessions = new TvSessions(this.$axios);diff --git a/taskview-packages/taskview-mcp/README.md b/taskview-packages/taskview-mcp/README.mdindex 7c3ec2e..478e3b2 100644--- a/taskview-packages/taskview-mcp/README.md+++ b/taskview-packages/taskview-mcp/README.md@@ -73,7 +73,7 @@ Then use `"command": "taskview-mcp"` (no `args` needed).| `TASKVIEW_URL` | yes | TaskView API server URL (e.g. `https://api.taskview.tech`) || `TASKVIEW_TOKEN` | yes (stdio mode) | API token with `tvk_` prefix. Not used in HTTP mode — each caller sends their own token || `MCP_HTTP_PORT` | no (HTTP mode) | Port for the HTTP server, default `3100` |-| `MCP_PUBLIC_URL` | no (HTTP mode) | Public URL of this server as clients reach it. Used as the OAuth resource identifier; derived from the request host when unset |+| `MCP_PUBLIC_URL` | no (HTTP mode) | Public URL of this server as clients reach it — the OAuth resource identifier. Include the path when the server is mounted under one (`https://api.example.com/mcp`); derived from the request host when unset || `MCP_ALLOWED_ORIGINS` | no (HTTP mode) | Comma-separated browser origins allowed to call `/mcp`. Unset means no browser origin is allowed; non-browser clients send no `Origin` and are unaffected |## HTTP server (remote / self-hosted)@@ -133,6 +133,22 @@ which is the authorization server.Set `MCP_PUBLIC_URL` to the externally reachable URL of this server so theadvertised resource identifier matches what clients actually request.+**Mounted under a path.** When the server sits behind a reverse proxy at+`https://api.example.com/mcp` rather than on its own host, put the full path in+`MCP_PUBLIC_URL`. RFC 9728 then places the metadata at+`/.well-known/oauth-protected-resource/mcp`, which is where a client that+computes the address from the spec — instead of trusting the `WWW-Authenticate`+header — will look. The server publishes it at both that address and the root+one, but the proxy has to route the path-inserted address here too:++```nginx+location = /.well-known/oauth-protected-resource/mcp {+ proxy_pass http://127.0.0.1:3100/.well-known/oauth-protected-resource/mcp;+ proxy_set_header Host $host;+ proxy_set_header X-Forwarded-Proto $scheme;+}+```+Manually issued `tvk_` tokens keep working exactly as before — OAuth is anadditional way in, not a replacement. Use `tvk_` for stdio, CLIs and CI, wherethere is no browser to complete an authorization flow.@@ -147,6 +163,8 @@ there is no browser to complete an authorization flow.**Tasks** — `list_tasks`, `get_task`, `create_task`, `update_task`, `delete_task`, `toggle_task_assignees`, `get_task_history`, `restore_task_from_history`+**Agenda** — `get_agenda` (today, upcoming and recently completed across all projects in one call)+**Tags** — `list_tags`, `create_tag`, `update_tag`, `delete_tag`, `toggle_task_tag`**Kanban** — `list_kanban_columns`, `create_kanban_column`, `update_kanban_column`, `delete_kanban_column`diff --git a/taskview-packages/taskview-mcp/src/__tests__/annotations.test.ts b/taskview-packages/taskview-mcp/src/__tests__/annotations.test.tsnew file mode 100644index 0000000..df55955--- /dev/null+++ b/taskview-packages/taskview-mcp/src/__tests__/annotations.test.ts@@ -0,0 +1,96 @@+import { describe, it, expect } from 'vitest'+import { registerGoalsTools } from '../tools/goals.js'+import { registerTasksTools } from '../tools/tasks.js'+import { registerListsTools } from '../tools/lists.js'+import { registerTagsTools } from '../tools/tags.js'+import { registerKanbanTools } from '../tools/kanban.js'+import { registerCollaborationTools } from '../tools/collaboration.js'+import { registerGraphTools } from '../tools/graph.js'+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 { mockServer, mockApi, findTool } from './setup.js'++const REQUIRED_HINTS = ['readOnlyHint', 'destructiveHint', 'openWorldHint'] as const++function registerEverything() {+ const { server, tools } = mockServer()+ const api = mockApi()+ registerGoalsTools(server, api)+ registerTasksTools(server, api)+ registerListsTools(server, api)+ registerTagsTools(server, api)+ registerKanbanTools(server, api)+ registerCollaborationTools(server, api)+ registerGraphTools(server, api)+ registerNotificationsTools(server, api)+ registerStartTools(server, api)+ registerOrganizationsTools(server, api)+ registerTimeTrackingTools(server, api)+ return tools+}++describe('tool annotations', () => {+ const tools = registerEverything()++ it('gives every tool a human-readable title', () => {+ // The Claude Connectors Directory flags any tool without a title and+ // will not accept the submission until every one has it.+ for (const tool of tools) {+ expect(typeof tool.config.title, tool.name).toBe('string')+ expect(tool.config.title?.trim().length, tool.name).toBeGreaterThan(0)+ }+ })++ it('keeps every tool name within the 64-character directory limit', () => {+ for (const tool of tools) {+ expect(tool.name.length, tool.name).toBeLessThanOrEqual(64)+ }+ })++ it('sets every safety hint explicitly on every tool', () => {+ // ChatGPT refuses to list an app whose tools leave any hint unset, and the+ // protocol defaults differ between clients — so nothing may rely on them.+ for (const tool of tools) {+ for (const hint of REQUIRED_HINTS) {+ expect(typeof tool.config.annotations?.[hint], `${tool.name}.${hint}`).toBe('boolean')+ }+ }+ })++ it('marks every list and get tool as read-only', () => {+ const readers = tools.filter((t) => /^(list|get)_/.test(t.name))+ expect(readers.length).toBeGreaterThan(0)+ for (const tool of readers) {+ expect(tool.config.annotations?.readOnlyHint, tool.name).toBe(true)+ expect(tool.config.annotations?.destructiveHint, tool.name).toBe(false)+ }+ })++ it('never marks a writing tool as read-only', () => {+ const writers = tools.filter((t) => !/^(list|get)_/.test(t.name))+ for (const tool of writers) {+ expect(tool.config.annotations?.readOnlyHint, tool.name).toBe(false)+ }+ })++ it('marks deletion and removal as destructive', () => {+ const removers = tools.filter((t) => /^(delete|remove)_/.test(t.name))+ expect(removers.length).toBeGreaterThan(0)+ for (const tool of removers) {+ expect(tool.config.annotations?.destructiveHint, tool.name).toBe(true)+ }+ })++ it('marks restoring a task from history as destructive, since it overwrites the current state', () => {+ expect(findTool(tools, 'restore_task_from_history').config.annotations?.destructiveHint).toBe(true)+ })++ it('keeps every tool inside the user\'s own instance except the invitation email', () => {+ for (const tool of tools) {+ const expected = tool.name === 'invite_collaborator'+ expect(tool.config.annotations?.openWorldHint, tool.name).toBe(expected)+ }+ })+})diff --git a/taskview-packages/taskview-mcp/src/__tests__/integration/http-oauth-discovery.integration.test.ts b/taskview-packages/taskview-mcp/src/__tests__/integration/http-oauth-discovery.integration.test.tsindex d46b3c4..176b620 100644--- a/taskview-packages/taskview-mcp/src/__tests__/integration/http-oauth-discovery.integration.test.ts+++ b/taskview-packages/taskview-mcp/src/__tests__/integration/http-oauth-discovery.integration.test.ts@@ -60,7 +60,7 @@ describe('MCP HTTP transport — OAuth discovery', () => {it('publishes protected resource metadata naming the TaskView API as the authorization server', async () => {const response = await fetch(`${PUBLIC_URL}/.well-known/oauth-protected-resource`)- const body = await response.json()+ const body = await response.json() as Record<string, any>expect(response.status).toBe(200)expect(body.resource).toBe(PUBLIC_URL)@@ -72,7 +72,7 @@ describe('MCP HTTP transport — OAuth discovery', () => {const response = await fetch(`${PUBLIC_URL}/.well-known/oauth-protected-resource`, {headers: { Host: 'internal-name:9999' },})- const body = await response.json()+ const body = await response.json() as Record<string, any>expect(body.resource).toBe(PUBLIC_URL)})@@ -81,7 +81,7 @@ describe('MCP HTTP transport — OAuth discovery', () => {const response = await fetch(`${PUBLIC_URL}/health`)expect(response.status).toBe(200)- expect((await response.json()).status).toBe('ok')+ expect(((await response.json()) as { status: string }).status).toBe('ok')})it('does not allow an unlisted browser origin', async () => {@@ -93,6 +93,71 @@ describe('MCP HTTP transport — OAuth discovery', () => {expect(response.headers.get('access-control-allow-origin')).toBeNull()})+ describe('mounted under a path', () => {+ const PATH_PORT = PORT + 2+ const PATH_PUBLIC_URL = `http://127.0.0.1:${PATH_PORT}/mcp`+ let pathServer: ChildProcess++ beforeAll(async () => {+ pathServer = spawn('node', [join(__dirname, '../../../dist/http.js')], {+ env: {+ ...process.env,+ TASKVIEW_URL,+ MCP_PUBLIC_URL: PATH_PUBLIC_URL,+ MCP_HTTP_PORT: String(PATH_PORT),+ },+ stdio: 'ignore',+ })+ for (let i = 0; i < 40; i++) {+ try {+ if ((await fetch(`http://127.0.0.1:${PATH_PORT}/health`)).ok) return+ } catch {+ // not listening yet+ }+ await new Promise((resolve) => setTimeout(resolve, 250))+ }+ throw new Error('path-mounted MCP server did not start')+ })++ afterAll(() => {+ pathServer?.kill()+ })++ it('points the 401 at the path-inserted metadata address', async () => {+ const response = await fetch(`http://127.0.0.1:${PATH_PORT}/mcp`, {+ method: 'POST',+ headers: { 'Content-Type': 'application/json' },+ body: '{}',+ })++ expect(response.status).toBe(401)+ expect(response.headers.get('www-authenticate')).toBe(+ `Bearer resource_metadata="http://127.0.0.1:${PATH_PORT}/.well-known/oauth-protected-resource/mcp"`,+ )+ })++ it('serves the document where RFC 9728 says it lives', async () => {+ const response = await fetch(+ `http://127.0.0.1:${PATH_PORT}/.well-known/oauth-protected-resource/mcp`,+ )+ const body = await response.json() as Record<string, any>++ expect(response.status).toBe(200)+ // The identifier now matches the URL the client actually connected to.+ expect(body.resource).toBe(PATH_PUBLIC_URL)+ })++ it('keeps serving the root address for clients that only follow the header', async () => {+ const response = await fetch(+ `http://127.0.0.1:${PATH_PORT}/.well-known/oauth-protected-resource`,+ )+ const body = await response.json() as Record<string, any>++ expect(response.status).toBe(200)+ expect(body.resource).toBe(PATH_PUBLIC_URL)+ })+ })+it('allows an origin listed in MCP_ALLOWED_ORIGINS', async () => {const allowed = spawn('node', [join(__dirname, '../../../dist/http.js')], {env: {diff --git a/taskview-packages/taskview-mcp/src/__tests__/setup.ts b/taskview-packages/taskview-mcp/src/__tests__/setup.tsindex d83b092..a4ad0f3 100644--- a/taskview-packages/taskview-mcp/src/__tests__/setup.ts+++ b/taskview-packages/taskview-mcp/src/__tests__/setup.ts@@ -26,6 +26,7 @@ export function mockApi(overrides: Record<string, Record<string, unknown>> = {})},graph: { fetchAllEdges: noop, addEdge: noop, deleteEdge: noop },notifications: { fetch: noop, markRead: noop, markAllRead: noop },+ start: { fetchAllState: noop },timeTracking: {start: noop, stop: noop, getActive: noop, createManual: noop, update: noop, delete: noop,fetchEntries: noop, summaryByTask: noop, summaryByGoal: noop,@@ -52,7 +53,7 @@ export function apiThrow(message: string) {type ToolEntry = {name: string- config: { description?: string; inputSchema?: Record<string, unknown> }+ config: { title?: string; description?: string; inputSchema?: Record<string, unknown>; annotations?: Record<string, unknown> }cb: (args: Record<string, unknown>) => Promise<{ content: { type: string; text: string }[]; isError?: boolean }>}diff --git a/taskview-packages/taskview-mcp/src/__tests__/start.test.ts b/taskview-packages/taskview-mcp/src/__tests__/start.test.tsnew file mode 100644index 0000000..0301a86--- /dev/null+++ b/taskview-packages/taskview-mcp/src/__tests__/start.test.ts@@ -0,0 +1,68 @@+import { describe, it, expect } from 'vitest'+import { registerStartTools } from '../tools/start.js'+import { mockServer, mockApi, apiReturn, apiThrow, findTool, ts } from './setup.js'++describe('start tools', () => {+ it('registers the agenda tool', () => {+ const { server, tools } = mockServer()+ registerStartTools(server, mockApi())++ expect(tools.map((t) => t.name)).toEqual(['get_agenda'])+ })++ it('returns today, upcoming and recently completed in one call', async () => {+ const { server, tools } = mockServer()+ const data = {+ tasks: [],+ tasksToday: [{ id: 1, description: `Today ${ts()}` }],+ tasksUpcoming: [{ id: 2, description: `Later ${ts()}` }],+ tasksLastCompleted: [{ id: 3, description: `Done ${ts()}` }],+ users: [],+ assignees: [],+ listToGoal: {},+ }+ registerStartTools(server, mockApi({ start: { fetchAllState: apiReturn(data) } }))++ const result = await findTool(tools, 'get_agenda').cb({})+ expect(result.content[0].text).toContain(data.tasksToday[0].description)+ expect(result.content[0].text).toContain(data.tasksUpcoming[0].description)+ expect(result.content[0].text).toContain(data.tasksLastCompleted[0].description)+ })++ it('passes the timezone through, since the server splits the day by it', async () => {+ const { server, tools } = mockServer()+ let captured: unknown+ const fetchAllState = (args: unknown) => {+ captured = args+ return Promise.resolve({ response: {}, rid: `rid-${ts()}` })+ }+ registerStartTools(server, mockApi({ start: { fetchAllState } }))++ await findTool(tools, 'get_agenda').cb({ timezone: 'Europe/Belgrade', organizationId: 7 })++ expect(captured).toEqual({ tz: 'Europe/Belgrade', organizationId: 7 })+ })++ it('falls back to UTC when the caller does not know the timezone', async () => {+ const { server, tools } = mockServer()+ let captured: any+ const fetchAllState = (args: unknown) => {+ captured = args+ return Promise.resolve({ response: {}, rid: `rid-${ts()}` })+ }+ registerStartTools(server, mockApi({ start: { fetchAllState } }))++ await findTool(tools, 'get_agenda').cb({})++ // The API rejects a request without tz, so the tool must always send one.+ expect(captured.tz).toBe('UTC')+ })++ it('reports an API failure instead of throwing', async () => {+ const { server, tools } = mockServer()+ registerStartTools(server, mockApi({ start: { fetchAllState: apiThrow('boom') } }))++ const result = await findTool(tools, 'get_agenda').cb({})+ expect(result.isError).toBe(true)+ })+})diff --git a/taskview-packages/taskview-mcp/src/http.ts b/taskview-packages/taskview-mcp/src/http.tsindex 20338e6..b8c7dcf 100644--- a/taskview-packages/taskview-mcp/src/http.ts+++ b/taskview-packages/taskview-mcp/src/http.ts@@ -8,9 +8,11 @@ import type { CorsHeadersArgs, HandleMcpRequestArgs, UnauthorizedArgs } from './const TASKVIEW_URL = process.env.TASKVIEW_URLconst PORT = Number(process.env.MCP_HTTP_PORT || 3100)-// Public URL of THIS server, as clients reach it. It is the OAuth "resource"-// identifier, so it must match what the client puts in the resource parameter.+// Public URL of THIS server, as clients reach it — the OAuth resource+// identifier. It may carry a path when the server is mounted under one+// (https://api.example.com/mcp), which changes where the metadata lives.const MCP_PUBLIC_URL = process.env.MCP_PUBLIC_URL?.replace(/\/+$/, '')+const METADATA_PREFIX = '/.well-known/oauth-protected-resource'// Browser origins allowed to call /mcp. Unset means no browser origin is// allowed — non-browser clients (ChatGPT, Claude, CLIs) send no Origin and are// unaffected. Guards against DNS rebinding, which the MCP spec calls out.@@ -42,13 +44,36 @@ function resourceUrl(req: IncomingMessage): string {if (MCP_PUBLIC_URL) return MCP_PUBLIC_URLconst host = req.headers.host ?? `localhost:${PORT}`const proto = (req.headers['x-forwarded-proto'] as string | undefined)?.split(',')[0]?.trim()- return `${proto || 'http'}://${host}`+ return `${proto || 'http'}://${host}/mcp`}/**- * RFC 9728. Discovery starts here: the 401 below points at this document, and- * this document points at the TaskView API that issues the tokens.+ * RFC 9728 §3.1: for a resource identified by a URL with a path, the metadata+ * lives at the well-known prefix followed by that path — not at the origin root.+ * A client that computes the address from the spec instead of trusting the+ * WWW-Authenticate header looks exactly there, so this is what makes a server+ * mounted under /mcp discoverable.*/+function metadataPathsFor(resource: string): string[] {+ let path = ''+ try {+ path = new URL(resource).pathname.replace(/\/+$/, '')+ } catch {+ path = ''+ }+ // The root form stays served for clients that only follow the 401 header.+ return path ? [`${METADATA_PREFIX}${path}`, METADATA_PREFIX] : [METADATA_PREFIX]+}++function metadataUrlFor(resource: string): string {+ const [preferred] = metadataPathsFor(resource)+ try {+ return `${new URL(resource).origin}${preferred}`+ } catch {+ return `${resource}${METADATA_PREFIX}`+ }+}+function protectedResourceMetadata(req: IncomingMessage) {return {resource: resourceUrl(req),@@ -58,7 +83,7 @@ function protectedResourceMetadata(req: IncomingMessage) {}function sendUnauthorized({ req, res, message }: UnauthorizedArgs) {- const metadataUrl = `${resourceUrl(req)}/.well-known/oauth-protected-resource`+ const metadataUrl = metadataUrlFor(resourceUrl(req))res.writeHead(401, {'Content-Type': 'application/json','WWW-Authenticate': `Bearer resource_metadata="${metadataUrl}"`,@@ -118,7 +143,7 @@ const httpServer = createServer(async (req, res) => {return}- if (path === '/.well-known/oauth-protected-resource') {+ if (metadataPathsFor(resourceUrl(req)).includes(path)) {res.writeHead(200, { 'Content-Type': 'application/json' }).end(JSON.stringify(protectedResourceMetadata(req)),)diff --git a/taskview-packages/taskview-mcp/src/server.ts b/taskview-packages/taskview-mcp/src/server.tsindex 967afe3..906db37 100644--- a/taskview-packages/taskview-mcp/src/server.ts+++ b/taskview-packages/taskview-mcp/src/server.ts@@ -8,6 +8,7 @@ import { registerKanbanTools } from './tools/kanban.js'import { registerCollaborationTools } from './tools/collaboration.js'import { registerGraphTools } from './tools/graph.js'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'@@ -23,7 +24,9 @@ DATA MODEL (top to bottom):WORKFLOW: all IDs are numeric and must be resolved first — never guess them. Map a name to its id with the matching list_* tool (project → list_goals, list → list_lists, members → list_collaborators_for_goal, kanban columns → list_kanban_columns, tags → list_tags), then pass that id to the create/update/delete tools.-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.`+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.`export function createMcpServer(api: TvApi) {const server = new McpServer(@@ -42,6 +45,7 @@ export function createMcpServer(api: TvApi) {registerCollaborationTools(server, api)registerGraphTools(server, api)registerNotificationsTools(server, api)+ registerStartTools(server, api)registerOrganizationsTools(server, api)registerTimeTrackingTools(server, api)diff --git a/taskview-packages/taskview-mcp/src/tools/collaboration.ts b/taskview-packages/taskview-mcp/src/tools/collaboration.tsindex 7c5a500..689dfe7 100644--- a/taskview-packages/taskview-mcp/src/tools/collaboration.ts+++ b/taskview-packages/taskview-mcp/src/tools/collaboration.ts@@ -1,12 +1,14 @@import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'import type { TvApi } from 'taskview-api'import { z } from 'zod'-import { ok, err } from './helpers.js'+import { ok, err, toolAnnotations } from './helpers.js'export function registerCollaborationTools(server: McpServer, api: TvApi) {server.registerTool('list_collaborators',{+ title: 'List collaborators',+ annotations: toolAnnotations.readOnly,description: 'List all collaborators across all projects',},async () => {@@ -20,6 +22,8 @@ export function registerCollaborationTools(server: McpServer, api: TvApi) {server.registerTool('list_collaborators_for_goal',{+ title: 'List project collaborators',+ annotations: toolAnnotations.readOnly,description: 'List collaborators for a specific project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -36,6 +40,8 @@ export function registerCollaborationTools(server: McpServer, api: TvApi) {server.registerTool('invite_collaborator',{+ title: 'Invite collaborator',+ annotations: toolAnnotations.writeExternal,description: 'Invite a user to a project by email',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -54,6 +60,8 @@ export function registerCollaborationTools(server: McpServer, api: TvApi) {server.registerTool('remove_collaborator',{+ title: 'Remove collaborator',+ annotations: toolAnnotations.destructive,description: 'Remove a user from a project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -71,6 +79,8 @@ export function registerCollaborationTools(server: McpServer, api: TvApi) {server.registerTool('toggle_collaborator_roles',{+ title: 'Toggle collaborator roles',+ annotations: toolAnnotations.write,description: 'Update roles for a collaborator in a project',inputSchema: {userId: z.coerce.number().describe('User ID'),@@ -89,6 +99,8 @@ export function registerCollaborationTools(server: McpServer, api: TvApi) {server.registerTool('list_roles',{+ title: 'List roles',+ annotations: toolAnnotations.readOnly,description: 'List all roles for a project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -105,6 +117,8 @@ export function registerCollaborationTools(server: McpServer, api: TvApi) {server.registerTool('create_role',{+ title: 'Create role',+ annotations: toolAnnotations.write,description: 'Create a new role for a project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -123,6 +137,8 @@ export function registerCollaborationTools(server: McpServer, api: TvApi) {server.registerTool('delete_role',{+ title: 'Delete role',+ annotations: toolAnnotations.destructive,description: 'Delete a role from a project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -140,6 +156,8 @@ export function registerCollaborationTools(server: McpServer, api: TvApi) {server.registerTool('list_role_permissions_for_goal',{+ title: 'List role permissions for project',+ annotations: toolAnnotations.readOnly,description: 'Get role-to-permission mappings for a project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -156,6 +174,8 @@ export function registerCollaborationTools(server: McpServer, api: TvApi) {server.registerTool('list_permissions',{+ title: 'List permissions',+ annotations: toolAnnotations.readOnly,description: 'List all available permissions',},async () => {@@ -169,6 +189,8 @@ export function registerCollaborationTools(server: McpServer, api: TvApi) {server.registerTool('toggle_role_permission',{+ title: 'Toggle role permission',+ annotations: toolAnnotations.write,description: 'Add or remove a permission from a role',inputSchema: {roleId: z.coerce.number().describe('Role ID'),diff --git a/taskview-packages/taskview-mcp/src/tools/goals.ts b/taskview-packages/taskview-mcp/src/tools/goals.tsindex aa4b750..836c6c8 100644--- a/taskview-packages/taskview-mcp/src/tools/goals.ts+++ b/taskview-packages/taskview-mcp/src/tools/goals.ts@@ -1,12 +1,14 @@import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'import type { TvApi } from 'taskview-api'import { z } from 'zod'-import { ok, err } from './helpers.js'+import { ok, err, toolAnnotations } from './helpers.js'export function registerGoalsTools(server: McpServer, api: TvApi) {server.registerTool('list_goals',{+ title: 'List projects',+ annotations: toolAnnotations.readOnly,description: 'List all projects (goals) accessible to the current user. Optionally filter by organization.',inputSchema: {organizationId: z.coerce.number().optional().describe('Filter by organization ID'),@@ -23,6 +25,8 @@ export function registerGoalsTools(server: McpServer, api: TvApi) {server.registerTool('create_goal',{+ title: 'Create project',+ annotations: toolAnnotations.write,description: 'Create a new project (goal). If organizationId is provided, creates within that organization.',inputSchema: {name: z.string().describe('Project name'),@@ -43,6 +47,8 @@ export function registerGoalsTools(server: McpServer, api: TvApi) {server.registerTool('update_goal',{+ title: 'Update project',+ annotations: toolAnnotations.write,description: 'Update a project (goal) — name, description, color',inputSchema: {id: z.coerce.number().describe('Project (goal) ID'),@@ -64,6 +70,8 @@ export function registerGoalsTools(server: McpServer, api: TvApi) {server.registerTool('delete_goal',{+ title: 'Delete project',+ annotations: toolAnnotations.destructive,description: 'Delete a project (goal)',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID to delete'),diff --git a/taskview-packages/taskview-mcp/src/tools/graph.ts b/taskview-packages/taskview-mcp/src/tools/graph.tsindex 2dcf22e..591e2a6 100644--- a/taskview-packages/taskview-mcp/src/tools/graph.ts+++ b/taskview-packages/taskview-mcp/src/tools/graph.ts@@ -1,12 +1,14 @@import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'import type { TvApi } from 'taskview-api'import { z } from 'zod'-import { ok, err } from './helpers.js'+import { ok, err, toolAnnotations } from './helpers.js'export function registerGraphTools(server: McpServer, api: TvApi) {server.registerTool('list_task_dependencies',{+ title: 'List task dependencies',+ annotations: toolAnnotations.readOnly,description: 'List all task dependency edges in a project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -23,6 +25,8 @@ export function registerGraphTools(server: McpServer, api: TvApi) {server.registerTool('add_task_dependency',{+ title: 'Add task dependency',+ annotations: toolAnnotations.write,description: 'Create a dependency between two tasks',inputSchema: {source: z.coerce.number().describe('Source task ID'),@@ -40,6 +44,8 @@ export function registerGraphTools(server: McpServer, api: TvApi) {server.registerTool('delete_task_dependency',{+ title: 'Delete task dependency',+ annotations: toolAnnotations.destructive,description: 'Delete a task dependency edge',inputSchema: {id: z.coerce.number().describe('Dependency edge ID'),diff --git a/taskview-packages/taskview-mcp/src/tools/helpers.ts b/taskview-packages/taskview-mcp/src/tools/helpers.tsindex 71121be..cde21af 100644--- a/taskview-packages/taskview-mcp/src/tools/helpers.ts+++ b/taskview-packages/taskview-mcp/src/tools/helpers.ts@@ -1,3 +1,19 @@+import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js'++/**+ * Every tool declares all three hints explicitly. ChatGPT refuses to list an+ * app whose tools leave any of them unset, and other clients use them to decide+ * what needs confirmation. openWorldHint is false throughout: a tool only ever+ * touches the user's own TaskView instance — the one exception reaches out to+ * an email address that may belong to someone outside it.+ */+export const toolAnnotations = {+ readOnly: { readOnlyHint: true, destructiveHint: false, openWorldHint: false },+ write: { readOnlyHint: false, destructiveHint: false, openWorldHint: false },+ destructive: { readOnlyHint: false, destructiveHint: true, openWorldHint: false },+ writeExternal: { readOnlyHint: false, destructiveHint: false, openWorldHint: true },+} as const satisfies Record<string, ToolAnnotations>+export function ok(data: unknown) {return { content: [{ type: 'text' as const, text: JSON.stringify(data, null, 2) }] }}diff --git a/taskview-packages/taskview-mcp/src/tools/kanban.ts b/taskview-packages/taskview-mcp/src/tools/kanban.tsindex 54cd3f8..458ddff 100644--- a/taskview-packages/taskview-mcp/src/tools/kanban.ts+++ b/taskview-packages/taskview-mcp/src/tools/kanban.ts@@ -1,12 +1,14 @@import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'import type { TvApi } from 'taskview-api'import { z } from 'zod'-import { ok, err } from './helpers.js'+import { ok, err, toolAnnotations } from './helpers.js'export function registerKanbanTools(server: McpServer, api: TvApi) {server.registerTool('list_kanban_columns',{+ title: 'List kanban columns',+ annotations: toolAnnotations.readOnly,description: 'Get all kanban columns for a project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -23,6 +25,8 @@ export function registerKanbanTools(server: McpServer, api: TvApi) {server.registerTool('create_kanban_column',{+ title: 'Create kanban column',+ annotations: toolAnnotations.write,description: 'Create a new kanban column in a project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -40,6 +44,8 @@ export function registerKanbanTools(server: McpServer, api: TvApi) {server.registerTool('update_kanban_column',{+ title: 'Update kanban column',+ annotations: toolAnnotations.write,description: 'Update a kanban column',inputSchema: {id: z.coerce.number().describe('Column ID'),@@ -58,6 +64,8 @@ export function registerKanbanTools(server: McpServer, api: TvApi) {server.registerTool('delete_kanban_column',{+ title: 'Delete kanban column',+ annotations: toolAnnotations.destructive,description: 'Delete a kanban column',inputSchema: {id: z.coerce.number().describe('Column ID to delete'),diff --git a/taskview-packages/taskview-mcp/src/tools/lists.ts b/taskview-packages/taskview-mcp/src/tools/lists.tsindex 2b89543..53514de 100644--- a/taskview-packages/taskview-mcp/src/tools/lists.ts+++ b/taskview-packages/taskview-mcp/src/tools/lists.ts@@ -1,12 +1,14 @@import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'import type { TvApi } from 'taskview-api'import { z } from 'zod'-import { ok, err } from './helpers.js'+import { ok, err, toolAnnotations } from './helpers.js'export function registerListsTools(server: McpServer, api: TvApi) {server.registerTool('list_lists',{+ title: 'List lists in project',+ annotations: toolAnnotations.readOnly,description: 'Get all task lists within a project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -23,6 +25,8 @@ export function registerListsTools(server: McpServer, api: TvApi) {server.registerTool('create_list',{+ title: 'Create list',+ annotations: toolAnnotations.write,description: 'Create a new task list within a project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -41,6 +45,8 @@ export function registerListsTools(server: McpServer, api: TvApi) {server.registerTool('update_list',{+ title: 'Update list',+ annotations: toolAnnotations.write,description: 'Update a task list',inputSchema: {id: z.coerce.number().describe('List ID'),@@ -60,6 +66,8 @@ export function registerListsTools(server: McpServer, api: TvApi) {server.registerTool('delete_list',{+ title: 'Delete list',+ annotations: toolAnnotations.destructive,description: 'Delete a task list',inputSchema: {id: z.coerce.number().describe('List ID to delete'),diff --git a/taskview-packages/taskview-mcp/src/tools/notifications.ts b/taskview-packages/taskview-mcp/src/tools/notifications.tsindex 88effc6..f832639 100644--- a/taskview-packages/taskview-mcp/src/tools/notifications.ts+++ b/taskview-packages/taskview-mcp/src/tools/notifications.ts@@ -1,12 +1,14 @@import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'import type { TvApi } from 'taskview-api'import { z } from 'zod'-import { ok, err } from './helpers.js'+import { ok, err, toolAnnotations } from './helpers.js'export function registerNotificationsTools(server: McpServer, api: TvApi) {server.registerTool('list_notifications',{+ title: 'List notifications',+ annotations: toolAnnotations.readOnly,description: 'Get user notifications',inputSchema: {cursor: z.coerce.number().optional().describe('Pagination cursor'),@@ -23,6 +25,8 @@ export function registerNotificationsTools(server: McpServer, api: TvApi) {server.registerTool('mark_notification_read',{+ title: 'Mark notification as read',+ annotations: toolAnnotations.write,description: 'Mark a notification as read',inputSchema: {notificationId: z.coerce.number().describe('Notification ID'),@@ -39,6 +43,8 @@ export function registerNotificationsTools(server: McpServer, api: TvApi) {server.registerTool('mark_all_notifications_read',{+ title: 'Mark all notifications as read',+ annotations: toolAnnotations.write,description: 'Mark all notifications as read',},async () => {diff --git a/taskview-packages/taskview-mcp/src/tools/organizations.ts b/taskview-packages/taskview-mcp/src/tools/organizations.tsindex 94492a1..adc44f9 100644--- a/taskview-packages/taskview-mcp/src/tools/organizations.ts+++ b/taskview-packages/taskview-mcp/src/tools/organizations.ts@@ -1,12 +1,14 @@import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'import type { TvApi } from 'taskview-api'import { z } from 'zod'-import { ok, err } from './helpers.js'+import { ok, err, toolAnnotations } from './helpers.js'export function registerOrganizationsTools(server: McpServer, api: TvApi) {server.registerTool('list_organizations',{+ title: 'List organizations',+ annotations: toolAnnotations.readOnly,description: 'List all organizations the current user belongs to',},async () => {@@ -20,6 +22,8 @@ export function registerOrganizationsTools(server: McpServer, api: TvApi) {server.registerTool('get_organization',{+ title: 'Get organization',+ annotations: toolAnnotations.readOnly,description: 'Get organization details by ID',inputSchema: {organizationId: z.coerce.number().describe('Organization ID'),@@ -36,6 +40,8 @@ export function registerOrganizationsTools(server: McpServer, api: TvApi) {server.registerTool('create_organization',{+ title: 'Create organization',+ annotations: toolAnnotations.write,description: 'Create a new organization. The creator becomes the owner.',inputSchema: {name: z.string().describe('Organization name'),@@ -55,6 +61,8 @@ export function registerOrganizationsTools(server: McpServer, api: TvApi) {server.registerTool('update_organization',{+ title: 'Update organization',+ annotations: toolAnnotations.write,description: 'Update organization name, slug, or logo. Requires admin or owner role.',inputSchema: {organizationId: z.coerce.number().describe('Organization ID'),@@ -75,6 +83,8 @@ export function registerOrganizationsTools(server: McpServer, api: TvApi) {server.registerTool('delete_organization',{+ title: 'Delete organization',+ annotations: toolAnnotations.destructive,description: 'Delete an organization. Only the owner can delete. Personal workspaces cannot be deleted.',inputSchema: {organizationId: z.coerce.number().describe('Organization ID to delete'),@@ -91,6 +101,8 @@ export function registerOrganizationsTools(server: McpServer, api: TvApi) {server.registerTool('list_organization_members',{+ title: 'List organization members',+ annotations: toolAnnotations.readOnly,description: 'List all members of an organization',inputSchema: {organizationId: z.coerce.number().describe('Organization ID'),@@ -107,6 +119,8 @@ export function registerOrganizationsTools(server: McpServer, api: TvApi) {server.registerTool('add_organization_member',{+ title: 'Add organization member',+ annotations: toolAnnotations.write,description: 'Add a member to an organization by email. Requires admin or owner role. NOTE: organization membership alone does NOT grant access to any project — the user will not see a project until they are also added to it via invite_collaborator. After adding the member, invite them to the relevant project(s).',inputSchema: {organizationId: z.coerce.number().describe('Organization ID'),@@ -126,6 +140,8 @@ export function registerOrganizationsTools(server: McpServer, api: TvApi) {server.registerTool('update_organization_member_role',{+ title: 'Change organization member role',+ annotations: toolAnnotations.write,description: 'Change a member role in an organization. Cannot change the owner role.',inputSchema: {organizationId: z.coerce.number().describe('Organization ID'),@@ -145,6 +161,8 @@ export function registerOrganizationsTools(server: McpServer, api: TvApi) {server.registerTool('remove_organization_member',{+ title: 'Remove organization member',+ annotations: toolAnnotations.destructive,description: 'Remove a member from an organization. Cannot remove the owner.',inputSchema: {organizationId: z.coerce.number().describe('Organization ID'),diff --git a/taskview-packages/taskview-mcp/src/tools/start.ts b/taskview-packages/taskview-mcp/src/tools/start.tsnew file mode 100644index 0000000..9142a5e--- /dev/null+++ b/taskview-packages/taskview-mcp/src/tools/start.ts@@ -0,0 +1,44 @@+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'++export function registerStartTools(server: McpServer, api: TvApi) {+ server.registerTool(+ 'get_agenda',+ {+ title: 'Get agenda',+ annotations: toolAnnotations.readOnly,+ description:+ 'Get the user\'s agenda across every project in one call: tasks due today, '+ + 'upcoming tasks, recently completed ones, and tasks with no deadline. '+ + 'Use this for questions like "what do I have today", "what is coming up" or '+ + '"what did I finish recently" instead of listing projects and their tasks one '+ + 'by one — this is the same data the app\'s main screen shows, and the split '+ + 'into today/upcoming is computed on the server in the given timezone.',+ inputSchema: {+ timezone: z+ .string()+ .optional()+ .describe(+ 'IANA timezone deciding where "today" ends, e.g. "Europe/Belgrade". '+ + 'Defaults to UTC; pass the user\'s zone when it is known, otherwise the '+ + 'day boundary may be off by a few hours.',+ ),+ organizationId: z.coerce+ .number()+ .optional()+ .describe('Limit to one organization; omit for every organization the user belongs to'),+ },+ },+ async ({ timezone, organizationId }) => {+ try {+ const result = await api.start.fetchAllState({+ tz: timezone || 'UTC',+ organizationId,+ })+ return ok(result)+ } catch (e) { return err(e) }+ },+ )+}diff --git a/taskview-packages/taskview-mcp/src/tools/tags.ts b/taskview-packages/taskview-mcp/src/tools/tags.tsindex 79458e6..44649aa 100644--- a/taskview-packages/taskview-mcp/src/tools/tags.ts+++ b/taskview-packages/taskview-mcp/src/tools/tags.ts@@ -1,12 +1,14 @@import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'import type { TvApi } from 'taskview-api'import { z } from 'zod'-import { ok, err } from './helpers.js'+import { ok, err, toolAnnotations } from './helpers.js'export function registerTagsTools(server: McpServer, api: TvApi) {server.registerTool('list_tags',{+ title: 'List tags',+ annotations: toolAnnotations.readOnly,description: 'List all tags accessible to the current user',},async () => {@@ -20,6 +22,8 @@ export function registerTagsTools(server: McpServer, api: TvApi) {server.registerTool('create_tag',{+ title: 'Create tag',+ annotations: toolAnnotations.write,description: 'Create a new tag',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -38,6 +42,8 @@ export function registerTagsTools(server: McpServer, api: TvApi) {server.registerTool('update_tag',{+ title: 'Update tag',+ annotations: toolAnnotations.write,description: 'Update a tag',inputSchema: {id: z.coerce.number().describe('Tag ID'),@@ -57,6 +63,8 @@ export function registerTagsTools(server: McpServer, api: TvApi) {server.registerTool('delete_tag',{+ title: 'Delete tag',+ annotations: toolAnnotations.destructive,description: 'Delete a tag',inputSchema: {tagId: z.coerce.number().describe('Tag ID to delete'),@@ -73,6 +81,8 @@ export function registerTagsTools(server: McpServer, api: TvApi) {server.registerTool('toggle_task_tag',{+ title: 'Toggle tag on task',+ annotations: toolAnnotations.write,description: 'Add or remove a tag from a task',inputSchema: {tagId: z.coerce.number().describe('Tag ID'),diff --git a/taskview-packages/taskview-mcp/src/tools/tasks.ts b/taskview-packages/taskview-mcp/src/tools/tasks.tsindex b245346..363b1eb 100644--- a/taskview-packages/taskview-mcp/src/tools/tasks.ts+++ b/taskview-packages/taskview-mcp/src/tools/tasks.ts@@ -1,12 +1,14 @@import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'import { type TvApi, ALL_TASKS_LIST_ID } from 'taskview-api'import { z } from 'zod'-import { ok, err } from './helpers.js'+import { ok, err, toolAnnotations } from './helpers.js'export function registerTasksTools(server: McpServer, api: TvApi) {server.registerTool('list_tasks',{+ title: 'List tasks',+ annotations: toolAnnotations.readOnly,description: 'List tasks for a specific project (goal). Returns paginated results.',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -39,6 +41,8 @@ export function registerTasksTools(server: McpServer, api: TvApi) {server.registerTool('get_task',{+ title: 'Get task',+ annotations: toolAnnotations.readOnly,description: 'Get a single task by its ID with full details',inputSchema: {taskId: z.coerce.number().describe('Task ID'),@@ -56,6 +60,8 @@ export function registerTasksTools(server: McpServer, api: TvApi) {server.registerTool('create_task',{+ title: 'Create task',+ annotations: toolAnnotations.write,description: 'Create a new task in a project',inputSchema: {goalId: z.coerce.number().describe('Project (goal) ID'),@@ -81,6 +87,8 @@ export function registerTasksTools(server: McpServer, api: TvApi) {server.registerTool('update_task',{+ title: 'Update task',+ annotations: toolAnnotations.write,description: 'Update an existing task (description, status, priority, dates, cost, etc.)',inputSchema: {id: z.coerce.number().describe('Task ID to update'),@@ -111,6 +119,8 @@ export function registerTasksTools(server: McpServer, api: TvApi) {server.registerTool('delete_task',{+ title: 'Delete task',+ annotations: toolAnnotations.destructive,description: 'Delete a task',inputSchema: {taskId: z.coerce.number().describe('Task ID to delete'),@@ -127,6 +137,8 @@ export function registerTasksTools(server: McpServer, api: TvApi) {server.registerTool('toggle_task_assignees',{+ title: 'Toggle task assignees',+ annotations: toolAnnotations.write,description: 'Assign or unassign users to/from a task',inputSchema: {taskId: z.coerce.number().describe('Task ID'),@@ -144,6 +156,8 @@ export function registerTasksTools(server: McpServer, api: TvApi) {server.registerTool('get_task_history',{+ title: 'Get task history',+ annotations: toolAnnotations.readOnly,description: 'Get the change history of a task',inputSchema: {taskId: z.coerce.number().describe('Task ID'),@@ -160,6 +174,8 @@ export function registerTasksTools(server: McpServer, api: TvApi) {server.registerTool('restore_task_from_history',{+ title: 'Restore task from history',+ annotations: toolAnnotations.destructive,description: 'Restore a task to a previous state from its history',inputSchema: {taskId: z.coerce.number().describe('Task ID'),diff --git a/taskview-packages/taskview-mcp/src/tools/time-tracking.ts b/taskview-packages/taskview-mcp/src/tools/time-tracking.tsindex e0eceaa..7a67046 100644--- a/taskview-packages/taskview-mcp/src/tools/time-tracking.ts+++ b/taskview-packages/taskview-mcp/src/tools/time-tracking.ts@@ -1,12 +1,14 @@import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'import type { TvApi } from 'taskview-api'import { z } from 'zod'-import { ok, err } from './helpers.js'+import { ok, err, toolAnnotations } from './helpers.js'export function registerTimeTrackingTools(server: McpServer, api: TvApi) {server.registerTool('start_timer',{+ title: 'Start timer',+ annotations: toolAnnotations.write,description: 'Start a timer for the given task. Returns {entry, autoStoppedEntry} — autoStoppedEntry is the previous active timer that was stopped (null if there was no active timer).',inputSchema: {taskId: z.coerce.number().describe('Task ID to track time for'),@@ -27,6 +29,8 @@ export function registerTimeTrackingTools(server: McpServer, api: TvApi) {server.registerTool('stop_timer',{+ title: 'Stop timer',+ annotations: toolAnnotations.write,description: 'Stop the active timer (or specific entry by id) and return the closed entry.',inputSchema: {entryId: z.coerce.number().optional().describe('Specific entry ID; if omitted, stops the user\'s active timer'),@@ -43,6 +47,8 @@ export function registerTimeTrackingTools(server: McpServer, api: TvApi) {server.registerTool('get_active_timer',{+ title: 'Get active timer',+ annotations: toolAnnotations.readOnly,description: 'Get the user\'s currently running timer (if any).',},async () => {@@ -56,6 +62,8 @@ export function registerTimeTrackingTools(server: McpServer, api: TvApi) {server.registerTool('log_time',{+ title: 'Log time',+ annotations: toolAnnotations.write,description: 'Log a manual time entry retroactively (no time-period restrictions).',inputSchema: {taskId: z.coerce.number().describe('Task ID'),@@ -82,6 +90,8 @@ export function registerTimeTrackingTools(server: McpServer, api: TvApi) {server.registerTool('list_time_entries',{+ title: 'List time entries',+ annotations: toolAnnotations.readOnly,description: 'List time entries with optional filters (goalId, taskId, userId, date range).',inputSchema: {goalId: z.coerce.number().optional().describe('Filter by project'),@@ -104,6 +114,8 @@ export function registerTimeTrackingTools(server: McpServer, api: TvApi) {server.registerTool('get_time_summary',{+ title: 'Get time summary',+ annotations: toolAnnotations.readOnly,description: 'Get aggregated time summary for a task or a project (goal).',inputSchema: {scope: z.enum(['task', 'goal']).describe('Aggregation scope'),@@ -124,6 +136,8 @@ export function registerTimeTrackingTools(server: McpServer, api: TvApi) {server.registerTool('update_time_entry',{+ title: 'Update time entry',+ annotations: toolAnnotations.write,description: 'Update fields of an existing time entry (cannot edit started/ended of a running timer).',inputSchema: {id: z.coerce.number().describe('Time entry ID'),@@ -144,6 +158,8 @@ export function registerTimeTrackingTools(server: McpServer, api: TvApi) {server.registerTool('get_time_report',{+ title: 'Get time report',+ annotations: toolAnnotations.readOnly,description:'Aggregated time report. Choose scope: by-day (daily totals), by-user (per member), by-task (per task), summary (totals + billable). Filter by org, optional projects, optional user, date range.',inputSchema: {@@ -181,6 +197,8 @@ export function registerTimeTrackingTools(server: McpServer, api: TvApi) {server.registerTool('get_time_contributors',{+ title: 'Get time contributors',+ annotations: toolAnnotations.readOnly,description:'List users who logged time in the given projects and date range, with total seconds and entry counts. Useful for "who worked on this project last month".',inputSchema: {@@ -208,6 +226,8 @@ export function registerTimeTrackingTools(server: McpServer, api: TvApi) {server.registerTool('delete_time_entry',{+ title: 'Delete time entry',+ annotations: toolAnnotations.destructive,description: 'Delete a time entry (writes a record to history.time_entries before deletion).',inputSchema: {id: z.coerce.number().describe('Time entry ID'),