@todoist/comms-mcp 0.0.1 → 11.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Doist
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,45 +1,209 @@
-# @todoist/comms-mcp
+# Comms MCP & AI Tools
+
+MCP server and importable AI tools for the Todoist Comms API. Use the
+tools through an MCP server, or import them directly to plug Comms into
+your own AI conversational interface.
+
+## Using the tools
+
+### 1. Install
+
+```sh
+npm install @todoist/comms-mcp
+```
+
+This package was previously published as `@doist/comms-mcp`.
+
+### 2. Plug them into an AI
+
+Example with [Vercel's AI SDK](https://ai-sdk.dev/docs/ai-sdk-core/generating-text#streamtext):
+
+```js
+import { fetchInbox, reply, markDone } from '@todoist/comms-mcp'
+import { streamText } from 'ai'
+
+const result = streamText({
+    model: yourModel,
+    system: 'You are a helpful Comms assistant',
+    tools: {
+        fetchInbox,
+        reply,
+        markDone,
+    },
+})
+```
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+## Using as an MCP server
+
+### Quick start
+
+```bash
+npx @todoist/comms-mcp
+```
+
+### Setup
+
+#### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+    "mcpServers": {
+        "comms": {
+            "command": "npx",
+            "args": ["-y", "@todoist/comms-mcp"],
+            "env": {
+                "COMMS_API_KEY": "your-comms-api-key-here"
+            }
+        }
+    }
+}
+```
+
+#### Cursor
+
+`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):
+
+```json
+{
+    "mcpServers": {
+        "comms": {
+            "command": "npx",
+            "args": ["-y", "@todoist/comms-mcp"],
+            "env": {
+                "COMMS_API_KEY": "your-comms-api-key-here"
+            }
+        }
+    }
+}
+```
+
+#### Claude Code (CLI)
+
+```bash
+claude mcp add comms npx @todoist/comms-mcp
+export COMMS_API_KEY=your-comms-api-key-here
+```
+
+#### Visual Studio Code
+
+1. Command Palette → MCP: Add Server
+2. Configure:
+
+```json
+{
+    "servers": {
+        "comms": {
+            "command": "npx",
+            "args": ["-y", "@todoist/comms-mcp"],
+            "env": {
+                "COMMS_API_KEY": "your-comms-api-key-here"
+            }
+        }
+    }
+}
+```
+
+### Targeting a non-production deployment
+
+By default the server talks to `https://comms.todoist.com`. To point at
+staging or a custom deployment, also set `COMMS_BASE_URL`:
+
+```json
+"env": {
+    "COMMS_API_KEY": "your-comms-api-key-here",
+    "COMMS_BASE_URL": "https://comms.staging.todoist.com"
+}
+```
+
+### Getting a Comms API key
+
+Comms accepts your Todoist API token. In Todoist, open **Settings →
+Integrations → Developer** and copy the API token, then export it as
+`COMMS_API_KEY` (or paste it into the MCP client config above). It has
+full access to your account, so keep it secret.
+
+## Features
+
+The tools are intentionally workflow-shaped rather than 1:1 wrappers
+around API endpoints, so an LLM can complete a useful action with a
+small number of calls.
+
+### Available tools
+
+- **userInfo** — Information about the current user, including their status
+- **updateUserInfo** — Change the user's name, timezone, language or status. The status is shared with Todoist (message, emoji, end, paused notifications or Karma). Over an OAuth connection this needs the `user:write` scope
+- **fetchInbox** — Threads and conversations from the inbox
+- **loadThread** — Load a thread with its comments
+- **loadConversation** — Load a conversation with its messages
+- **searchContent** — Search a workspace for threads, comments, and messages
+- **getMentions** — Threads, comments, and messages mentioning the current user
+- **create-channel** / **update-channel** — Create or update workspace channels through MCP
+- **createThread** — Start a new channel thread. Accepts an optional `displayInInbox` boolean (default `false`). When `true`, the thread is unarchived after creation so it appears in the author's Inbox. See also [COMMS_CREATE_THREAD_DISPLAY_IN_INBOX](#environment-variables).
+- **updateObject** / **deleteObject** — Edit or remove a thread, comment, or message
+- **reply** — Reply to a thread or conversation
+- **react** — Add a reaction to a thread, comment, conversation, or message
+- **markDone** — Mark threads or conversations as read and/or archived
+- **markRead** — Mark threads and/or conversations as read without archiving them (specific IDs, or everything unread in a workspace)
+- **buildLink** — Build URLs to Comms resources
+- **listChannels** / **getGroups** / **getUsers** / **getWorkspaces** — Discovery helpers
+
+For details, see [src/tools](src/tools).
+
+## Environment Variables
+
+| Variable                               | Default      | Description                                                                                                                                                                                                                                                                                                                  |
+| -------------------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `COMMS_API_KEY`                        | _(required)_ | Your Comms API key.                                                                                                                                                                                                                                                                                                          |
+| `COMMS_CREATE_THREAD_DISPLAY_IN_INBOX` | `false`      | Set to `true` to unarchive every newly-created thread so it appears in the author's Inbox, without needing to pass `displayInInbox: true` on each call. **Only takes effect when running the MCP locally.** The remote/hosted MCP does not have this variable set and will use the per-call `displayInInbox` parameter only. |
+
+## Dependencies
+
+- MCP server uses the official [@modelcontextprotocol/server](https://github.com/modelcontextprotocol/typescript-sdk)
+- Comms TypeScript SDK [@doist/comms-sdk](https://github.com/Doist/comms-sdk-typescript)
+
+## Local development
+
+### Prerequisites
+
+- Node.js 20.18.1+
+- npm
+- A Comms API token
+
+### Setup
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+```bash
+git clone https://github.com/todoist/comms-mcp.git
+cd comms-mcp
+npm install
+cp .env.example .env  # then add your COMMS_API_KEY
+npm run build
+```
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+### Commands
 
-## Purpose
+- `npm start` — Build and run the MCP inspector
+- `npm run dev` — Watch mode with auto-restart
+- `npm test` — Vitest
+- `npm run type-check` — TypeScript
+- `npm run format:check` / `npm run format:fix` — oxlint + oxfmt
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@todoist/comms-mcp`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+### Running a single tool directly
 
-## What is OIDC Trusted Publishing?
+```bash
+npx tsx scripts/run-tool.ts user-info '{}'
+npx tsx scripts/run-tool.ts --list
+```
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+## Contributing
 
-## Setup Instructions
+1. Tests pass (`npm test`)
+2. Types pass (`npm run type-check`)
+3. Lint & format pass (`npm run format:check`)
 
-To properly configure OIDC trusted publishing for this package:
+Use [Conventional Commits](https://www.conventionalcommits.org/) — `feat:`, `fix:`, `docs:`, `test:`, `chore:`.
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+## License
 
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+MIT

package/dist/comms-tool.d.ts

@@ -0,0 +1,14 @@
+import type { CommsApi } from '@doist/comms-sdk';
+import type { AnyMcpTool, McpTool } from '@todoist/mcp-core';
+import type { z } from 'zod';
+/**
+ * A Comms tool that can be used in an MCP server or other conversational AI interfaces: an
+ * `McpTool` from `@todoist/mcp-core` whose `execute` receives the Comms API client.
+ *
+ * `execute` returns `{ textContent, structuredContent }`; registration shapes that into the MCP
+ * result, so a tool never builds one itself.
+ */
+type CommsTool<Params extends z.ZodRawShape, Output extends z.ZodRawShape = Record<string, never>> = McpTool<Params, Output, CommsApi>;
+/** A Comms tool of any parameter and output shape, for collections that hold tools of mixed shapes. */
+type AnyCommsTool = AnyMcpTool<CommsApi>;
+export type { AnyCommsTool, CommsTool };

package/dist/comms-tool.js

@@ -0,0 +1 @@
+export {};