@todoist/comms-mcp 0.0.1 → 11.0.0

package/dist/utils/tool-names.js

@@ -0,0 +1,25 @@
+export const ToolNames = {
+    USER_INFO: 'user-info',
+    UPDATE_USER_INFO: 'update-user-info',
+    FETCH_INBOX: 'fetch-inbox',
+    LOAD_THREAD: 'load-thread',
+    LOAD_CONVERSATION: 'load-conversation',
+    SEARCH_CONTENT: 'search-content',
+    GET_MENTIONS: 'get-mentions',
+    CREATE_CHANNEL: 'create-channel',
+    UPDATE_CHANNEL: 'update-channel',
+    CREATE_THREAD: 'create-thread',
+    CREATE_CONVERSATION: 'create-conversation',
+    UPDATE_OBJECT: 'update-object',
+    DELETE_OBJECT: 'delete-object',
+    REPLY: 'reply',
+    REACT: 'react',
+    MARK_DONE: 'mark-done',
+    MARK_READ: 'mark-read',
+    BUILD_LINK: 'build-link',
+    GET_WORKSPACES: 'get-workspaces',
+    GET_USERS: 'get-users',
+    GET_GROUPS: 'get-groups',
+    LIST_CHANNELS: 'list-channels',
+    LIST_CONVERSATIONS: 'list-conversations',
+};

package/dist/utils/url-helpers.d.ts

@@ -0,0 +1,3 @@
+export declare function getWorkspaceUrl(workspaceId: number): string;
+export declare function getChannelUrl(workspaceId: number, channelId: string): string;
+export declare function getConversationUrl(workspaceId: number, conversationId: string): string;

package/dist/utils/url-helpers.js

@@ -0,0 +1,10 @@
+import { getFullCommsURL } from '@doist/comms-sdk';
+export function getWorkspaceUrl(workspaceId) {
+    return getFullCommsURL({ workspaceId });
+}
+export function getChannelUrl(workspaceId, channelId) {
+    return getFullCommsURL({ workspaceId, channelId });
+}
+export function getConversationUrl(workspaceId, conversationId) {
+    return getFullCommsURL({ workspaceId, conversationId });
+}

package/dist/utils/user-status.d.ts

@@ -0,0 +1,8 @@
+import type { UserStatus } from '@doist/comms-sdk';
+import type { UserInfoOutput } from './output-schemas.js';
+type StatusOutput = NonNullable<UserInfoOutput['status']>;
+declare function normaliseActiveUntil(activeUntil: string): string;
+declare function toStatusOutput(status: UserStatus): StatusOutput;
+/** The status lines of a user-info text, in the same `**Label:** value` form as the rest. */
+declare function describeStatus(status: StatusOutput | undefined): string[];
+export { describeStatus, normaliseActiveUntil, toStatusOutput };

package/dist/utils/user-status.js

@@ -0,0 +1,33 @@
+// Comms sends RFC 3339, but an end that fails to parse is still worth showing, so it is reported as
+// sent. A set never gets this far with one: it fails the comparison with the end it asked for.
+function normaliseActiveUntil(activeUntil) {
+    const parsed = new Date(activeUntil);
+    return Number.isNaN(parsed.getTime()) ? activeUntil : parsed.toISOString();
+}
+function toStatusOutput(status) {
+    const activeUntil = status.activeUntil ? normaliseActiveUntil(status.activeUntil) : undefined;
+    return {
+        message: status.message,
+        ...(status.emoji ? { emoji: status.emoji } : {}),
+        ...(activeUntil ? { activeUntil } : {}),
+        pauseNotifications: Boolean(status.effects?.pauseNotifications),
+        pauseActivity: Boolean(status.effects?.pauseActivity),
+    };
+}
+/** The status lines of a user-info text, in the same `**Label:** value` form as the rest. */
+function describeStatus(status) {
+    if (!status) {
+        return ['**Status:** none'];
+    }
+    const lines = [`**Status:** ${status.emoji ? `${status.emoji} ` : ''}${status.message}`];
+    lines.push(`**Status Until:** ${status.activeUntil ?? 'no end'}`);
+    const effects = [
+        status.pauseNotifications ? 'Comms notifications paused' : undefined,
+        status.pauseActivity ? 'Karma and streaks paused' : undefined,
+    ].filter((effect) => effect !== undefined);
+    if (effects.length > 0) {
+        lines.push(`**Status Effects:** ${effects.join(', ')}`);
+    }
+    return lines;
+}
+export { describeStatus, normaliseActiveUntil, toStatusOutput };

package/dist/utils/validate-comms-token.d.ts

@@ -0,0 +1,13 @@
+import { type TokenValidationResult } from '@todoist/mcp-core/host';
+/**
+ * Validates a Comms API token with a status-only call to the session-user endpoint.
+ *
+ * Resolves `'valid'`, `'invalid'` (401) or `'forbidden'` (403), so a host can answer a
+ * scope-deficient token with an RFC 6750 `insufficient_scope` challenge rather than a blanket
+ * 401. The request carries the usage-tracking headers, as the tool `auth:validate-token`.
+ *
+ * @throws {TokenValidationError} (from `@todoist/mcp-core/host`) for any other status, such as a
+ * 5xx or a 404 from a misconfigured base URL, carrying it as `httpStatusCode`. Network and
+ * timeout errors propagate unchanged.
+ */
+export declare function validateCommsToken(token: string, baseUrl?: string): Promise<TokenValidationResult>;

package/dist/utils/validate-comms-token.js

@@ -0,0 +1,22 @@
+import { validateBearerToken } from '@todoist/mcp-core/host';
+import { buildUsageTrackingHeaders } from '../usage-tracking.js';
+/** Production Comms API base URL, used when no explicit base is given. */
+const DEFAULT_BASE_URL = 'https://comms.todoist.com';
+/**
+ * Validates a Comms API token with a status-only call to the session-user endpoint.
+ *
+ * Resolves `'valid'`, `'invalid'` (401) or `'forbidden'` (403), so a host can answer a
+ * scope-deficient token with an RFC 6750 `insufficient_scope` challenge rather than a blanket
+ * 401. The request carries the usage-tracking headers, as the tool `auth:validate-token`.
+ *
+ * @throws {TokenValidationError} (from `@todoist/mcp-core/host`) for any other status, such as a
+ * 5xx or a 404 from a misconfigured base URL, carrying it as `httpStatusCode`. Network and
+ * timeout errors propagate unchanged.
+ */
+export function validateCommsToken(token, baseUrl = DEFAULT_BASE_URL) {
+    return validateBearerToken({
+        url: `${baseUrl}/api/v1/users/get_session_user`,
+        token,
+        headers: buildUsageTrackingHeaders('auth:validate-token'),
+    });
+}

package/package.json

@@ -1,10 +1,87 @@
 {
-  "name": "@todoist/comms-mcp",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @todoist/comms-mcp",
-  "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
+    "name": "@todoist/comms-mcp",
+    "version": "11.0.0",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "mcpName": "com.doist/comms-mcp",
+    "bin": {
+        "comms-mcp": "dist/main.js"
+    },
+    "files": [
+        "dist",
+        "package.json",
+        "LICENSE",
+        "README.md"
+    ],
+    "license": "MIT",
+    "description": "MCP server and importable AI tools for the Doist Comms API",
+    "author": "Doist",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/todoist/comms-mcp.git"
+    },
+    "keywords": [
+        "comms",
+        "doist",
+        "ai",
+        "mcp",
+        "collaboration",
+        "model-context-protocol"
+    ],
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "engines": {
+        "node": ">=24",
+        "npm": ">=11"
+    },
+    "scripts": {
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:coverage": "vitest run --coverage",
+        "build": "rimraf dist && npx tsc --project tsconfig.json",
+        "postbuild": "chmod +x dist/main.js",
+        "start": "npm run build && npx @modelcontextprotocol/inspector node dist/main.js",
+        "dev": "concurrently \"npx tsc --watch\" \"npx @modelcontextprotocol/inspector npx nodemon --quiet --watch dist --ext js --exec node dist/main.js\"",
+        "type-check": "npx tsc --noEmit && npx tsc --noEmit -p .agents/scripts",
+        "format:check": "oxlint src scripts .agents/scripts *.config.js *.config.ts && oxfmt --check",
+        "format:fix": "oxlint src scripts .agents/scripts *.config.js *.config.ts --fix && oxfmt",
+        "prepublishOnly": "npm run build && npm test",
+        "prepare": "lefthook install --reset-hooks-path",
+        "verify": "node .agents/scripts/verify.ts",
+        "tool": "tsx scripts/run-tool.ts",
+        "tool:list": "tsx scripts/run-tool.ts --list",
+        "review:worktree": "node .agents/scripts/review-worktree.ts"
+    },
+    "dependencies": {
+        "@doist/comms-sdk": "3.12.0",
+        "@todoist/mcp-core": "1.0.0",
+        "dotenv": "17.4.2",
+        "p-limit": "6.2.0",
+        "zod": "4.6.7"
+    },
+    "peerDependencies": {
+        "@modelcontextprotocol/server": "^2.2.0"
+    },
+    "devDependencies": {
+        "@modelcontextprotocol/client": "2.3.0",
+        "@semantic-release/changelog": "6.0.3",
+        "@semantic-release/git": "10.0.1",
+        "@types/node": "22.19.17",
+        "@vitest/coverage-v8": "4.1.12",
+        "concurrently": "10.0.6",
+        "conventional-changelog-conventionalcommits": "9.3.1",
+        "gpt-tokenizer": "3.4.0",
+        "lefthook": "2.2.2",
+        "nodemon": "3.1.14",
+        "oxfmt": "0.72.0",
+        "oxlint": "1.63.0",
+        "rimraf": "6.1.3",
+        "semantic-release": "25.0.3",
+        "tsx": "4.22.4",
+        "typescript": "6.0.3",
+        "vitest": "4.1.12"
+    }
 }