@shortcut/mcp 0.15.1 → 0.16.0

package/dist/server-http.js

@@ -0,0 +1,430 @@
+import { CustomMcpServer, DocumentTools, EpicTools, IterationTools, ObjectiveTools, ShortcutClientWrapper, StoryTools, TeamTools, UserTools, WorkflowTools } from "./workflows-ChA_XcfF.js";
+import { ShortcutClient } from "@shortcut/client";
+import { randomUUID } from "node:crypto";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import express from "express";
+import pino from "pino";
+
+//#region src/server-http.ts
+const DEFAULT_PORT = 9292;
+const BEARER_PREFIX = "Bearer ";
+const SESSION_TIMEOUT_MS = 1800 * 1e3;
+const HEADERS = {
+	AUTHORIZATION: "authorization",
+	X_SHORTCUT_API_TOKEN: "x-shortcut-api-token",
+	MCP_SESSION_ID: "mcp-session-id",
+	LAST_EVENT_ID: "last-event-id"
+};
+const JSON_RPC_ERRORS = {
+	UNAUTHORIZED: {
+		code: -32e3,
+		message: "Unauthorized"
+	},
+	BAD_REQUEST: {
+		code: -32e3,
+		message: "Bad Request"
+	},
+	SESSION_NOT_FOUND: {
+		code: -32001,
+		message: "Session not found"
+	},
+	INVALID_TOKEN: {
+		code: -32002,
+		message: "Invalid API token"
+	},
+	INTERNAL_ERROR: {
+		code: -32603,
+		message: "Internal server error"
+	}
+};
+const logger = pino({
+	level: process.env.LOG_LEVEL || "info",
+	transport: process.env.NODE_ENV !== "production" ? {
+		target: "pino-pretty",
+		options: {
+			colorize: true,
+			translateTime: "HH:MM:ss",
+			ignore: "pid,hostname"
+		}
+	} : void 0
+});
+function loadConfig() {
+	let isReadonly = process.env.SHORTCUT_READONLY !== "false";
+	let enabledTools = parseToolsList(process.env.SHORTCUT_TOOLS || "");
+	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);
+	});
+	return {
+		port: Number.parseInt(process.env.PORT || String(DEFAULT_PORT), 10),
+		isReadonly,
+		enabledTools,
+		sessionTimeoutMs: SESSION_TIMEOUT_MS
+	};
+}
+function parseToolsList(toolsStr) {
+	return toolsStr.split(",").map((tool) => tool.trim()).filter(Boolean);
+}
+var SessionManager = class {
+	sessions = /* @__PURE__ */ new Map();
+	cleanupInterval = null;
+	constructor(timeoutMs) {
+		this.timeoutMs = timeoutMs;
+		this.cleanupInterval = setInterval(() => this.cleanupStaleSessions(), 6e4);
+	}
+	has(sessionId) {
+		return this.sessions.has(sessionId);
+	}
+	get(sessionId) {
+		const session = this.sessions.get(sessionId);
+		if (session) session.lastAccessedAt = /* @__PURE__ */ new Date();
+		return session;
+	}
+	add(sessionId, transport, apiToken) {
+		this.sessions.set(sessionId, {
+			transport,
+			apiToken,
+			createdAt: /* @__PURE__ */ new Date(),
+			lastAccessedAt: /* @__PURE__ */ new Date()
+		});
+		logger.info({ sessionId }, "Session initialized");
+	}
+	remove(sessionId) {
+		const session = this.sessions.get(sessionId);
+		if (session) {
+			this.sessions.delete(sessionId);
+			logger.info({ sessionId }, "Session removed");
+		}
+	}
+	validateToken(sessionId, providedToken) {
+		const session = this.sessions.get(sessionId);
+		if (!session) return false;
+		return session.apiToken === providedToken;
+	}
+	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);
+		}
+		if (staleSessionIds.length > 0) {
+			logger.info({ count: staleSessionIds.length }, "Cleaning up stale sessions");
+			for (const sessionId of staleSessionIds) {
+				const session = this.sessions.get(sessionId);
+				if (session) {
+					session.transport.close().catch((error) => {
+						logger.error({
+							sessionId,
+							error
+						}, "Error closing stale transport");
+					});
+					this.remove(sessionId);
+				}
+			}
+		}
+	}
+	async closeAll() {
+		logger.info("Shutting down server...");
+		if (this.cleanupInterval) clearInterval(this.cleanupInterval);
+		const closePromises = [];
+		for (const [sessionId, session] of this.sessions.entries()) {
+			logger.debug({ sessionId }, "Closing session");
+			closePromises.push(session.transport.close().catch((error) => {
+				logger.error({
+					sessionId,
+					error
+				}, "Error closing transport");
+			}));
+			this.remove(sessionId);
+		}
+		await Promise.all(closePromises);
+		logger.info("Server shutdown complete");
+	}
+};
+function extractApiToken(req) {
+	const authHeader = req.headers[HEADERS.AUTHORIZATION];
+	if (authHeader?.startsWith(BEARER_PREFIX)) return authHeader.slice(7);
+	const customHeader = req.headers[HEADERS.X_SHORTCUT_API_TOKEN];
+	if (typeof customHeader === "string") return customHeader;
+	return null;
+}
+/**
+* Validates the API token by attempting to fetch current user info.
+* This ensures the token is valid before creating a session.
+*/
+async function validateApiToken(token) {
+	try {
+		const client = new ShortcutClient(token);
+		await client.getCurrentMemberInfo();
+		return true;
+	} catch (error) {
+		logger.debug({ error: error instanceof Error ? error.message : error }, "API token validation failed");
+		return false;
+	}
+}
+function sendUnauthorizedError(res, message) {
+	res.status(401).json({
+		jsonrpc: "2.0",
+		error: {
+			...JSON_RPC_ERRORS.UNAUTHORIZED,
+			message: message || "API token required. Provide via Authorization: Bearer <token> or X-Shortcut-API-Token: <token>"
+		},
+		id: null
+	});
+}
+function sendInvalidTokenError(res, requestId) {
+	res.status(401).json({
+		jsonrpc: "2.0",
+		error: {
+			...JSON_RPC_ERRORS.INVALID_TOKEN,
+			message: "Invalid or expired API token. Please check your credentials."
+		},
+		id: requestId || null
+	});
+}
+function sendSessionNotFoundError(res, sessionId, requestId) {
+	logger.warn({ sessionId }, "Session not found - may have expired or server restarted");
+	res.status(404).json({
+		jsonrpc: "2.0",
+		error: {
+			...JSON_RPC_ERRORS.SESSION_NOT_FOUND,
+			message: "Session not found or expired. Please re-initialize the connection."
+		},
+		id: requestId || null
+	});
+}
+function sendBadRequestError(res, message, requestId) {
+	res.status(400).json({
+		jsonrpc: "2.0",
+		error: {
+			...JSON_RPC_ERRORS.BAD_REQUEST,
+			message
+		},
+		id: requestId || null
+	});
+}
+function sendInternalError(res, requestId) {
+	if (!res.headersSent) res.status(500).json({
+		jsonrpc: "2.0",
+		error: JSON_RPC_ERRORS.INTERNAL_ERROR,
+		id: requestId || null
+	});
+}
+function createServerInstance(apiToken, config) {
+	const server = new CustomMcpServer({
+		readonly: config.isReadonly,
+		tools: config.enabledTools
+	});
+	const client = new ShortcutClientWrapper(new ShortcutClient(apiToken));
+	UserTools.create(client, server);
+	StoryTools.create(client, server);
+	IterationTools.create(client, server);
+	EpicTools.create(client, server);
+	ObjectiveTools.create(client, server);
+	TeamTools.create(client, server);
+	WorkflowTools.create(client, server);
+	DocumentTools.create(client, server);
+	return server;
+}
+async function createTransport(apiToken, config, sessionManager) {
+	let transport = null;
+	transport = new StreamableHTTPServerTransport({
+		sessionIdGenerator: () => randomUUID(),
+		onsessioninitialized: (sid) => {
+			if (transport) sessionManager.add(sid, transport, apiToken);
+		}
+	});
+	transport.onclose = () => {
+		if (transport) {
+			const sid = transport.sessionId;
+			if (sid && sessionManager.has(sid)) sessionManager.remove(sid);
+		}
+	};
+	const server = createServerInstance(apiToken, config);
+	await server.connect(transport);
+	return transport;
+}
+async function handleMcpPost(req, res, sessionManager, config) {
+	const sessionId = req.headers[HEADERS.MCP_SESSION_ID];
+	const apiToken = extractApiToken(req);
+	const requestId = req.body?.id;
+	const reqLogger = logger.child({
+		sessionId: sessionId || "new",
+		method: "POST"
+	});
+	reqLogger.debug({ hasToken: !!apiToken }, "Received POST request");
+	try {
+		if (sessionId && sessionManager.has(sessionId)) {
+			if (!apiToken) {
+				sendUnauthorizedError(res);
+				return;
+			}
+			if (!sessionManager.validateToken(sessionId, apiToken)) {
+				reqLogger.warn("Token mismatch for session");
+				sendUnauthorizedError(res, "API token does not match the session");
+				return;
+			}
+			const session = sessionManager.get(sessionId);
+			await session.transport.handleRequest(req, res, req.body);
+			return;
+		}
+		if (isInitializeRequest(req.body)) {
+			if (!apiToken) {
+				sendUnauthorizedError(res);
+				return;
+			}
+			reqLogger.info("Validating API token");
+			const isValid = await validateApiToken(apiToken);
+			if (!isValid) {
+				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);
+			return;
+		}
+		if (sessionId && !sessionManager.has(sessionId)) {
+			sendSessionNotFoundError(res, sessionId, requestId);
+			return;
+		}
+		sendBadRequestError(res, "No session ID provided for non-initialization request", requestId);
+	} catch (error) {
+		reqLogger.error({ error }, "Error handling MCP POST request");
+		sendInternalError(res, requestId);
+	}
+}
+async function handleMcpGet(req, res, sessionManager) {
+	const sessionId = req.headers[HEADERS.MCP_SESSION_ID];
+	const apiToken = extractApiToken(req);
+	const reqLogger = logger.child({
+		sessionId,
+		method: "GET"
+	});
+	if (!sessionId || !sessionManager.has(sessionId)) {
+		res.status(400).send("Invalid or missing session ID");
+		return;
+	}
+	if (!apiToken) {
+		sendUnauthorizedError(res);
+		return;
+	}
+	if (!sessionManager.validateToken(sessionId, apiToken)) {
+		reqLogger.warn("Token mismatch for GET request");
+		sendUnauthorizedError(res, "API token does not match the session");
+		return;
+	}
+	const lastEventId = req.headers[HEADERS.LAST_EVENT_ID];
+	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);
+	} catch (error) {
+		reqLogger.error({ error }, "Error handling MCP GET request");
+		if (!res.headersSent) res.status(500).send("Internal server error");
+	}
+}
+async function handleMcpDelete(req, res, sessionManager) {
+	const sessionId = req.headers[HEADERS.MCP_SESSION_ID];
+	const apiToken = extractApiToken(req);
+	const reqLogger = logger.child({
+		sessionId,
+		method: "DELETE"
+	});
+	if (!sessionId || !sessionManager.has(sessionId)) {
+		res.status(400).send("Invalid or missing session ID");
+		return;
+	}
+	if (!apiToken) {
+		sendUnauthorizedError(res);
+		return;
+	}
+	if (!sessionManager.validateToken(sessionId, apiToken)) {
+		reqLogger.warn("Token mismatch for DELETE request");
+		sendUnauthorizedError(res, "API token does not match the session");
+		return;
+	}
+	reqLogger.info("Terminating session");
+	try {
+		const session = sessionManager.get(sessionId);
+		await session.transport.handleRequest(req, res);
+	} catch (error) {
+		reqLogger.error({ error }, "Error handling session termination");
+		if (!res.headersSent) res.status(500).send("Error processing session termination");
+	}
+}
+function corsMiddleware(req, res, next) {
+	res.header("Access-Control-Allow-Origin", "*");
+	res.header("Access-Control-Allow-Methods", "GET, POST, DELETE, OPTIONS");
+	res.header("Access-Control-Allow-Headers", "Content-Type, Authorization, X-Shortcut-API-Token, Mcp-Session-Id, Last-Event-Id");
+	res.header("Access-Control-Expose-Headers", "Mcp-Session-Id");
+	if (req.method === "OPTIONS") {
+		res.sendStatus(204);
+		return;
+	}
+	next();
+}
+/**
+* Request logging middleware for debugging and audit purposes
+*/
+function loggingMiddleware(req, _res, next) {
+	const sessionId = req.headers[HEADERS.MCP_SESSION_ID];
+	const hasToken = !!extractApiToken(req);
+	logger.debug({
+		method: req.method,
+		path: req.path,
+		sessionId: sessionId || "none",
+		hasToken
+	}, "Incoming request");
+	next();
+}
+async function startServer() {
+	const config = loadConfig();
+	const sessionManager = new SessionManager(config.sessionTimeoutMs);
+	const app = express();
+	app.use(express.json());
+	app.use(corsMiddleware);
+	app.use(loggingMiddleware);
+	app.get("/health", (_req, res) => {
+		res.json({
+			status: "ok",
+			service: "shortcut-mcp-server",
+			transport: "streamable-http",
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			version: "2025-06-18"
+		});
+	});
+	app.post("/mcp", (req, res) => handleMcpPost(req, res, sessionManager, config));
+	app.get("/mcp", (req, res) => handleMcpGet(req, res, sessionManager));
+	app.delete("/mcp", (req, res) => handleMcpDelete(req, res, sessionManager));
+	app.listen(config.port, () => {
+		logger.info({
+			port: config.port,
+			readonly: config.isReadonly,
+			sessionTTL: `${config.sessionTimeoutMs / 1e3 / 60}m`,
+			enabledTools: config.enabledTools.length > 0 ? config.enabledTools : "all",
+			mcpSpec: "2025-06-18"
+		}, "Shortcut MCP Server (Streamable HTTP) started");
+		logger.info(`Server URL: http://localhost:${config.port}`);
+		logger.info(`Health check: http://localhost:${config.port}/health`);
+		logger.info(`MCP endpoint: http://localhost:${config.port}/mcp`);
+	});
+	process.on("SIGINT", async () => {
+		await sessionManager.closeAll();
+		process.exit(0);
+	});
+	process.on("SIGTERM", async () => {
+		await sessionManager.closeAll();
+		process.exit(0);
+	});
+}
+startServer().catch((error) => {
+	logger.fatal({ error }, "Fatal error starting server");
+	process.exit(1);
+});
+
+//#endregion