@shortcut/mcp 0.18.0 → 0.20.0

package/README.md

@@ -14,12 +14,70 @@ The MCP server for [Shortcut](https://shortcut.com).
 
 ## Usage
 
+The only required input is your Shortcut API token. You can find it in your [Shortcut account settings](https://app.shortcut.com/settings/account/api-tokens).
+
+Once you have a valid token, you can pass it to the MCP server as an environement variable or a CLI argument.
+
+Examples:
+
+```json
+"shortcut": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "@shortcut/mcp@latest"
+  ],
+  "env": {
+    "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
+  }
+}
+```
+
+```json
+"shortcut": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "@shortcut/mcp@latest",
+    "SHORTCUT_API_TOKEN=<YOUR_SHORTCUT_API_TOKEN>"
+  ]
+}
+```
+
+Due to an issue in `gemini-cli` that redacts environment variables that contain the word "token", you can also use the alternative name `SHORTCUT_API_TKN` instead of `SHORTCUT_API_TOKEN`. This works for both the environment variable and the CLI argument:
+
+```json
+"shortcut": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "@shortcut/mcp@latest"
+  ],
+  "env": {
+    "SHORTCUT_API_TKN": "<YOUR_SHORTCUT_API_TOKEN>"
+  }
+}
+```
+
+```json
+"shortcut": {
+  "command": "npx",
+  "args": [
+    "-y",
+    "@shortcut/mcp@latest",
+    "SHORTCUT_API_TKN=<YOUR_SHORTCUT_API_TOKEN>"
+  ]
+}
+```
+
+For more information on how to setup the MCP for your tool of choice, see below.
+
 ### Windsurf
 
 See the [official Windsurf docs](https://docs.windsurf.com/windsurf/cascade/mcp) for more information.
 
-1. Open the `Windsurf MCP Configuration Panel`
-2. Click `Add custom server`.
+1. Open the MCP configuration by clicking the `MCPs` icon in the Cascade panel, or navigate to `Windsurf Settings` > `Cascade` > `MCP Servers`.
+2. Click `Add Custom Server` to edit the raw `mcp_config.json` file (located at `~/.codeium/windsurf/mcp_config.json`).
 3. Add the following details and save the file:
 
 ```json
@@ -66,35 +124,27 @@ See the [official Cursor docs](https://docs.cursor.com/context/model-context-pro
 
 ### Claude Code
 
-See the [official Claude Code docs](https://docs.anthropic.com/en/docs/agents-and-tools/claude-code/tutorials#set-up-model-context-protocol-mcp) for more information.
-
-_You can add a new MCP server from the Claude Code CLI. But modifying the json file directly is simpler!_
+See the [official Claude Code docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more information.
 
-You can either add a new MCP server from the command line:
+Add the MCP server from the command line:
 
 ```shell
-# Grab your Shortcut token here: https://app.shortcut.com/settings/account/api-tokens
-claude mcp add shortcut --transport=stdio -e SHORTCUT_API_TOKEN=$SHORTCUT_API_TOKEN -- npx -y @shortcut/mcp@latest
+claude mcp add shortcut --transport stdio -e SHORTCUT_API_TOKEN=$SHORTCUT_API_TOKEN -- npx -y @shortcut/mcp@latest
 ```
 
-Or you can edit the local JSON file directly:
-
-1. Open the Claude Code configuration file (it should be in `~/.claude.json`).
-2. Find the `projects` > `mcpServers` section and add the following details and save the file:
+Or you can create a `.mcp.json` file in your project root to share with your team:
 
 ```json
 {
-  "projects": {
-    "mcpServers": {
-      "shortcut": {
-        "command": "npx",
-        "args": [
-          "-y",
-          "@shortcut/mcp@latest"
-        ],
-        "env": {
-          "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
-        }
+  "mcpServers": {
+    "shortcut": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@shortcut/mcp@latest"
+      ],
+      "env": {
+        "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
       }
     }
   }
@@ -102,26 +152,72 @@ Or you can edit the local JSON file directly:
 ```
 
 ### Zed
-[Zed MCP Documentation](https://zed.dev/docs/ai/mcp)
-1. Open your `settings.json` file. Instructions [here](https://zed.dev/docs/configuring-zed#settings-files)
-2. Add the following details and save the file:
+
+See the [official Zed MCP docs](https://zed.dev/docs/ai/mcp) for more information.
+
+1. Open your `settings.json` file. Instructions [here](https://zed.dev/docs/configuring-zed#settings-files).
+2. Add the following to the `context_servers` section and save the file:
 
 ```json
+{
   "context_servers": {
     "shortcut": {
-      "settings":{},
-      "command": {
-        "path": "<PATH/TO/NPX>",
-        "args": [
-          "-y",
-          "@shortcut/mcp@latest"
-        ],
-        "env": {
-          "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
-        }
+      "command": "npx",
+      "args": [
+        "-y",
+        "@shortcut/mcp@latest"
+      ],
+      "env": {
+        "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+### VS Code
+
+See the [official VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more information.
+
+1. Create (or open) the `.vscode/mcp.json` file in your workspace.
+2. Add the following details and save the file:
+
+```json
+{
+  "servers": {
+    "shortcut": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@shortcut/mcp@latest"
+      ],
+      "env": {
+        "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
+      }
+    }
+  }
+}
+```
+
+### OpenCode
+
+See the [official OpenCode MCP docs](https://opencode.ai/docs/mcp-servers/) for more information.
+
+Add the following to your `opencode.json` configuration file:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "shortcut": {
+      "type": "local",
+      "command": ["npx", "-y", "@shortcut/mcp@latest"],
+      "environment": {
+        "SHORTCUT_API_TOKEN": "<YOUR_SHORTCUT_API_TOKEN>"
       }
     }
   }
+}
 ```
 
 ## Available Tools
@@ -191,7 +287,8 @@ Or you can edit the local JSON file directly:
 
 ### Documents
 
-- **documents-create** - Create a new document in Shortcut with HTML content
+- **documents-create** - Create a new document in Shortcut with Markdown content
+- **documents-update** - Update content of an existing document by its ID
 - **documents-list** - List all documents in Shortcut
 - **documents-search** - Search for documents
 - **documents-get-by-id** - Retrieve a specific document in markdown format by its ID
@@ -203,7 +300,8 @@ You can limit the tools available to the LLM by setting the `SHORTCUT_TOOLS` env
 - Tools can be limited by entity type by just adding the entity, eg `stories` or `epics`.
 - Individual tools can also be limitied by their full name, eg `stories-get-by-id` or `epics-search`.
 
-By default, all tools are enabled.
+> [!NOTE]
+> By default, all tools are enabled.
 
 Example:
 
@@ -241,6 +339,9 @@ The following values are accepted in addition to the full tool names listed abov
 
 You can run the MCP server in read-only mode by setting the `SHORTCUT_READONLY` environment variable to `true`. This will disable all tools that modify data in Shortcut.
 
+> [!TIP]
+> Shortcut supports **read-only API tokens**, which you can use to ensure that the MCP server is limited to read-only operations at the API level. This provides an additional layer of security since the restriction is enforced by the Shortcut API itself, not just the MCP server. You can create a read-only token from your [Shortcut API tokens settings](https://app.shortcut.com/settings/account/api-tokens).
+
 Example:
 
 ```json
@@ -263,7 +364,8 @@ Example:
 
 ## Issues and Troubleshooting
 
-Before doing anything else, please make sure you are running the latest version!
+> [!IMPORTANT]
+> Before doing anything else, please make sure you are running the latest version!
 
 If you run into problems using this MCP server, you have a couple of options:
 
@@ -274,6 +376,10 @@ You can also check the list of [common issues](#common-issues) below to see if t
 
 ### Common Issues and Solutions
 
+#### MCP fails on startup in Gemini CLI
+
+If you are using the Gemini CLI and the MCP fails with the following error: `✕ Error during discovery for MCP server 'shortcut': MCP error -32000: Connection closed`, it might be due to an issue in Gemini where it redacts environment variables that contain the word `token`. You can either pass the Shortcut token as a CLI argument, or use the alternative name `SHORTCUT_API_TKN` instead of `SHORTCUT_API_TOKEN`. See the [Usage section](#usage) for more information.
+
 #### NPX command not working when using MISE for version management
 
 If you are using MISE for managing Node and NPM versions, you may encounter a "Client closed" error when trying to run the MCP server. Installing this extension into your IDE might help: https://github.com/hverlin/mise-vscode/.

package/dist/{index.js → index.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { BaseTools, CustomMcpServer, DocumentTools, EpicTools, IterationTools, ObjectiveTools, ShortcutClientWrapper, StoryTools, TeamTools, UserTools, WorkflowTools } from "./workflows-Dko3ibgz.js";
+import { a as ObjectiveTools, c as DocumentTools, d as ShortcutClientWrapper, i as StoryTools, l as BaseTools, n as UserTools, o as IterationTools, r as TeamTools, s as EpicTools, t as WorkflowTools, u as CustomMcpServer } from "./workflows-GwezThPA.mjs";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { ShortcutClient } from "@shortcut/client";
 import { z } from "zod";
@@ -9,10 +9,10 @@ import { z } from "zod";
 * Tools for managing Shortcut labels.
 */
 var LabelTools = class LabelTools extends BaseTools {
-	static create(client$1, server$1) {
-		const tools = new LabelTools(client$1);
-		server$1.addToolWithReadAccess("labels-list", "List all labels in the Shortcut workspace.", { includeArchived: z.boolean().optional().describe("Whether to include archived labels in the list.").default(false) }, async (params) => await tools.listLabels(params));
-		server$1.addToolWithWriteAccess("labels-create", "Create a new label in Shortcut.", {
+	static create(client, server) {
+		const tools = new LabelTools(client);
+		server.addToolWithReadAccess("labels-list", "List all labels in the Shortcut workspace.", { includeArchived: z.boolean().optional().describe("Whether to include archived labels in the list.").default(false) }, async (params) => await tools.listLabels(params));
+		server.addToolWithWriteAccess("labels-create", "Create a new label in Shortcut.", {
 			name: z.string().min(1).max(128).describe("The name of the new label. Required."),
 			color: z.string().regex(/^#[a-fA-F0-9]{6}$/).optional().describe("The hex color to be displayed with the label (e.g., \"#ff0000\")."),
 			description: z.string().max(1024).optional().describe("A description of the label.")
@@ -47,16 +47,17 @@ var LabelTools = class LabelTools extends BaseTools {
 
 //#endregion
 //#region src/server.ts
-let apiToken = process.env.SHORTCUT_API_TOKEN;
+let apiToken = process.env.SHORTCUT_API_TKN || process.env.SHORTCUT_API_TOKEN;
 let isReadonly = process.env.SHORTCUT_READONLY === "true";
 let enabledTools = (process.env.SHORTCUT_TOOLS || "").split(",").map((tool) => tool.trim()).filter(Boolean);
 if (process.argv.length >= 3) process.argv.slice(2).map((arg) => arg.split("=")).forEach(([name, value]) => {
+	if (name === "SHORTCUT_API_TKN") apiToken = value;
 	if (name === "SHORTCUT_API_TOKEN") apiToken = value;
 	if (name === "SHORTCUT_READONLY") isReadonly = value === "true";
 	if (name === "SHORTCUT_TOOLS") enabledTools = value.split(",").map((tool) => tool.trim()).filter(Boolean);
 });
 if (!apiToken) {
-	console.error("SHORTCUT_API_TOKEN is required");
+	console.error("A Shortcut api token is required.");
 	process.exit(1);
 }
 const server = new CustomMcpServer({
@@ -84,4 +85,5 @@ async function startServer() {
 }
 startServer();
 
-//#endregion
+//#endregion
+export {  };

package/dist/{server-http.js → server-http.mjs}

@@ -1,4 +1,4 @@
-import { CustomMcpServer, DocumentTools, EpicTools, IterationTools, ObjectiveTools, ShortcutClientWrapper, StoryTools, TeamTools, UserTools, WorkflowTools } from "./workflows-Dko3ibgz.js";
+import { a as ObjectiveTools, c as DocumentTools, d as ShortcutClientWrapper, i as StoryTools, n as UserTools, o as IterationTools, r as TeamTools, s as EpicTools, t as WorkflowTools, u as CustomMcpServer } from "./workflows-GwezThPA.mjs";
 import { ShortcutClient } from "@shortcut/client";
 import { randomUUID } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -52,15 +52,18 @@ const logger = pino({
 function loadConfig() {
 	let isReadonly = process.env.SHORTCUT_READONLY !== "false";
 	let enabledTools = parseToolsList(process.env.SHORTCUT_TOOLS || "");
+	let httpDebug = process.env.SHORTCUT_HTTP_DEBUG === "true";
 	if (process.argv.length >= 3) process.argv.slice(2).map((arg) => arg.split("=")).forEach(([name, value]) => {
 		if (name === "SHORTCUT_READONLY") isReadonly = value !== "false";
 		if (name === "SHORTCUT_TOOLS") enabledTools = parseToolsList(value);
+		if (name === "SHORTCUT_HTTP_DEBUG") httpDebug = value === "true";
 	});
 	return {
 		port: Number.parseInt(process.env.PORT || String(DEFAULT_PORT), 10),
 		isReadonly,
 		enabledTools,
-		sessionTimeoutMs: SESSION_TIMEOUT_MS
+		sessionTimeoutMs: SESSION_TIMEOUT_MS,
+		httpDebug
 	};
 }
 function parseToolsList(toolsStr) {
@@ -91,8 +94,7 @@ var SessionManager = class {
 		logger.info({ sessionId }, "Session initialized");
 	}
 	remove(sessionId) {
-		const session = this.sessions.get(sessionId);
-		if (session) {
+		if (this.sessions.get(sessionId)) {
 			this.sessions.delete(sessionId);
 			logger.info({ sessionId }, "Session removed");
 		}
@@ -105,10 +107,7 @@ var SessionManager = class {
 	cleanupStaleSessions() {
 		const now = Date.now();
 		const staleSessionIds = [];
-		for (const [sessionId, session] of this.sessions.entries()) {
-			const timeSinceLastAccess = now - session.lastAccessedAt.getTime();
-			if (timeSinceLastAccess > this.timeoutMs) staleSessionIds.push(sessionId);
-		}
+		for (const [sessionId, session] of this.sessions.entries()) if (now - session.lastAccessedAt.getTime() > this.timeoutMs) staleSessionIds.push(sessionId);
 		if (staleSessionIds.length > 0) {
 			logger.info({ count: staleSessionIds.length }, "Cleaning up stale sessions");
 			for (const sessionId of staleSessionIds) {
@@ -156,8 +155,7 @@ function extractApiToken(req) {
 */
 async function validateApiToken(token) {
 	try {
-		const client = new ShortcutClient(token);
-		await client.getCurrentMemberInfo();
+		await new ShortcutClient(token).getCurrentMemberInfo();
 		return true;
 	} catch (error) {
 		logger.debug({ error: error instanceof Error ? error.message : error }, "API token validation failed");
@@ -242,8 +240,7 @@ async function createTransport(apiToken, config, sessionManager) {
 			if (sid && sessionManager.has(sid)) sessionManager.remove(sid);
 		}
 	};
-	const server = createServerInstance(apiToken, config);
-	await server.connect(transport);
+	await createServerInstance(apiToken, config).connect(transport);
 	return transport;
 }
 async function handleMcpPost(req, res, sessionManager, config) {
@@ -266,8 +263,7 @@ async function handleMcpPost(req, res, sessionManager, config) {
 				sendUnauthorizedError(res, "API token does not match the session");
 				return;
 			}
-			const session = sessionManager.get(sessionId);
-			await session.transport.handleRequest(req, res, req.body);
+			await sessionManager.get(sessionId).transport.handleRequest(req, res, req.body);
 			return;
 		}
 		if (isInitializeRequest(req.body)) {
@@ -276,15 +272,13 @@ async function handleMcpPost(req, res, sessionManager, config) {
 				return;
 			}
 			reqLogger.info("Validating API token");
-			const isValid = await validateApiToken(apiToken);
-			if (!isValid) {
+			if (!await validateApiToken(apiToken)) {
 				reqLogger.warn("API token validation failed");
 				sendInvalidTokenError(res, requestId);
 				return;
 			}
 			reqLogger.info("API token validated, creating session");
-			const transport = await createTransport(apiToken, config, sessionManager);
-			await transport.handleRequest(req, res, req.body);
+			await (await createTransport(apiToken, config, sessionManager)).handleRequest(req, res, req.body);
 			return;
 		}
 		if (sessionId && !sessionManager.has(sessionId)) {
@@ -321,8 +315,7 @@ async function handleMcpGet(req, res, sessionManager) {
 	if (lastEventId) reqLogger.info({ lastEventId }, "Client reconnecting with Last-Event-ID");
 	else reqLogger.info("Establishing SSE stream");
 	try {
-		const session = sessionManager.get(sessionId);
-		await session.transport.handleRequest(req, res);
+		await sessionManager.get(sessionId).transport.handleRequest(req, res);
 	} catch (error) {
 		reqLogger.error({ error }, "Error handling MCP GET request");
 		if (!res.headersSent) res.status(500).send("Internal server error");
@@ -350,8 +343,7 @@ async function handleMcpDelete(req, res, sessionManager) {
 	}
 	reqLogger.info("Terminating session");
 	try {
-		const session = sessionManager.get(sessionId);
-		await session.transport.handleRequest(req, res);
+		await sessionManager.get(sessionId).transport.handleRequest(req, res);
 	} catch (error) {
 		reqLogger.error({ error }, "Error handling session termination");
 		if (!res.headersSent) res.status(500).send("Error processing session termination");
@@ -382,13 +374,43 @@ function loggingMiddleware(req, _res, next) {
 	}, "Incoming request");
 	next();
 }
+function httpDebugRequestMiddleware(req, _res, next) {
+	const headers = { ...req.headers };
+	delete headers[HEADERS.AUTHORIZATION];
+	delete headers[HEADERS.X_SHORTCUT_API_TOKEN];
+	delete headers.cookie;
+	logger.info(JSON.stringify({
+		event: "http_request",
+		method: req.method,
+		path: req.path,
+		url: req.originalUrl,
+		query: req.query,
+		headers,
+		body: req.body
+	}));
+	next();
+}
 async function startServer() {
 	const config = loadConfig();
 	const sessionManager = new SessionManager(config.sessionTimeoutMs);
 	const app = express();
 	app.use(express.json());
+	if (config.httpDebug) app.use(httpDebugRequestMiddleware);
 	app.use(corsMiddleware);
 	app.use(loggingMiddleware);
+	app.use((req, res, next) => {
+		const start = Date.now();
+		res.on("finish", () => {
+			if (res.statusCode >= 400) logger.info(JSON.stringify({
+				event: "http_request_failed",
+				method: req.method,
+				path: req.path,
+				status: res.statusCode,
+				ms: Date.now() - start
+			}));
+		});
+		next();
+	});
 	app.get("/health", (_req, res) => {
 		res.json({
 			status: "ok",
@@ -427,4 +449,5 @@ startServer().catch((error) => {
 	process.exit(1);
 });
 
-//#endregion
+//#endregion
+export {  };