Implement Cloudflare Worker for remote MCP access

.gitignore

@@ -32,3 +32,5 @@ report.[0-9]_.[0-9]_.[0-9]_.[0-9]_.json
 
 # Finder (MacOS) folder config
 .DS_Store
+
+**/.claude/settings.local.json

CLAUDE.md

@@ -0,0 +1,35 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+# Shortcut MCP Server Development Guide
+
+## Commands
+- **Build**: `bun run build` or `npm run build`
+- **Lint/Format**: `bun run lint` / `bun run format` (uses Biome)
+- **Type check**: `bun run ts`
+- **Run all tests**: `bun test` or `bun run test`
+- **Run single test**: `bun test -t "test name"` or `bun test path/to/specific.test.ts`
+
+## Code Style Guidelines
+- **Formatting**: 
+  - Tab indentation, 100 character line width, double quotes
+  - Organized imports (by type/path using Biome)
+- **TypeScript**: 
+  - Use strict typing with proper annotations
+  - Leverage Zod for schema validation
+  - Follow TypeScript best practices for null checking
+- **Naming**:
+  - PascalCase for classes
+  - camelCase for variables, functions, and methods
+  - Descriptive function names
+
+## Error Handling
+- Use explicit error throwing with descriptive messages
+- Follow proper async/await patterns
+- Perform null checking before operations
+
+## Testing
+- Test files co-located with implementation files (*.test.ts)
+- Use descriptive test organization with `describe` and `test` blocks
+- Implement mock functions and spies as needed

PROJECT_STRUCTURE.md

@@ -0,0 +1,122 @@
+# Shortcut MCP Project Structure
+
+This document provides an overview of the project structure for the Shortcut MCP implementation.
+
+## Project Components
+
+The project is now organized into three main components:
+
+1. **`shortcut-mcp-tools`**: A shared package containing all Shortcut-specific tools and client logic
+2. **`mcp-server-shortcut`**: The original stdio-based MCP server (CLI tool)
+3. **`shortcut-mcp-worker`**: A Cloudflare Worker implementation for remote MCP access
+
+## Shared Tools Package
+
+### Location
+`/shortcut-mcp-tools/`
+
+### Description
+This package contains all the Shortcut-specific tools and client logic that is shared between both the stdio-based and Cloudflare Worker implementations. This eliminates code duplication and ensures consistent behavior across different transports.
+
+### Key Files
+- `src/client/shortcut.ts`: Wrapper around the Shortcut API client
+- `src/client/cache.ts`: Simple caching implementation for API responses
+- `src/tools/*.ts`: Various tools for interacting with Shortcut (stories, epics, etc.)
+- `src/tools/utils/*.ts`: Utility functions for formatting, validation, etc.
+- `src/index.ts`: Exports all tools and utilities
+
+## Original MCP Server (stdio-based)
+
+### Location
+`/` (root directory)
+
+### Description
+The original implementation of the Shortcut MCP server that uses stdio for communication. This is designed to be run as a CLI tool and is compatible with Claude Code, Cursor, and Windsurf.
+
+### Key Files
+- `index.ts`: Entry point for the CLI tool
+- `src/server.ts`: MCP server setup with stdio transport
+- Other configuration files (biome.json, tsconfig.json, etc.)
+
+### Dependencies
+- Now depends on the shared tools package
+- Uses stdio transport from the MCP SDK
+
+## Cloudflare Worker Implementation
+
+### Location
+`/shortcut-mcp-worker/`
+
+### Description
+A new implementation of the Shortcut MCP server that runs on Cloudflare Workers. This allows for remote access to the MCP server without needing to run the CLI tool locally.
+
+### Key Files
+- `src/index.ts`: Main entry point for the Worker
+- `src/transport/http-sse.ts`: HTTP+SSE transport implementation for MCP
+- `src/auth.ts`: OAuth authentication implementation
+- `wrangler.toml`: Cloudflare Worker configuration
+
+### Dependencies
+- Depends on the shared tools package
+- Uses HTTP+SSE transport instead of stdio
+- Adds OAuth authentication via Cloudflare Workers OAuth provider
+
+## How to Use
+
+### Local Development
+
+1. **Install dependencies for all components**:
+   ```bash
+   # Install dependencies for the shared package
+   cd shortcut-mcp-tools
+   npm install
+
+   # Install dependencies for the original server
+   cd ..
+   npm install
+
+   # Install dependencies for the worker
+   cd shortcut-mcp-worker
+   npm install
+   ```
+
+2. **Build the shared package**:
+   ```bash
+   cd shortcut-mcp-tools
+   npm run build
+   ```
+
+3. **Run the original server**:
+   ```bash
+   cd ..
+   SHORTCUT_API_TOKEN=your-token npm run build
+   node dist/index.js
+   ```
+
+4. **Run the worker locally**:
+   ```bash
+   cd shortcut-mcp-worker
+   npm run dev
+   ```
+
+### Deployment
+
+1. **Publish the shared package** (if needed):
+   ```bash
+   cd shortcut-mcp-tools
+   npm publish
+   ```
+
+2. **Deploy the worker**:
+   ```bash
+   cd shortcut-mcp-worker
+   npm run deploy
+   ```
+
+## Architecture Benefits
+
+1. **Code Sharing**: All business logic is in one place
+2. **Consistent Behavior**: Both implementations use the same tools
+3. **Easier Maintenance**: Changes to tools only need to be made in one place
+4. **Flexible Deployment**: Can be used locally or remotely
+5. **Progressive Enhancement**: New tools can be added to the shared package and used by both implementations

package.json

@@ -28,6 +28,7 @@
 	"dependencies": {
 		"@modelcontextprotocol/sdk": "^1.6.1",
 		"@shortcut/client": "^1.1.0",
+		"@shortcut/mcp-tools": "file:./shortcut-mcp-tools",
 		"zod": "^3.24.2"
 	},
 	"scripts": {

shortcut-mcp-tools/README.md

@@ -0,0 +1,57 @@
+# Shortcut MCP Tools
+
+Shared tools library for Shortcut MCP implementations. This package provides a consistent set of tools for interacting with the Shortcut API, regardless of the transport mechanism used.
+
+## Installation
+
+```bash
+npm install @shortcut/mcp-tools
+```
+
+## Usage
+
+### Initialize the client
+
+```typescript
+import { ShortcutClient } from '@shortcut/client';
+import { ShortcutClientWrapper, StoryTools } from '@shortcut/mcp-tools';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+// Initialize the client with your API token
+const client = new ShortcutClientWrapper(new ShortcutClient('your-api-token'));
+
+// Initialize the MCP server
+const server = new McpServer({ name: 'your-mcp-server', version: '1.0.0' });
+
+// Register tools
+StoryTools.create(client, server);
+// Register other tools as needed...
+```
+
+## Available Tools
+
+- `UserTools`: Get information about the current user.
+- `StoryTools`: Work with Shortcut stories (search, create, update, comment).
+- `EpicTools`: Work with Shortcut epics.
+- `IterationTools`: Work with Shortcut iterations.
+- `ObjectiveTools`: Work with Shortcut objectives.
+- `TeamTools`: Work with Shortcut teams.
+- `WorkflowTools`: Work with Shortcut workflows.
+
+## Development
+
+### Building
+
+```bash
+npm run build
+```
+
+### Publishing
+
+```bash
+npm publish
+```
+
+## License
+
+MIT

shortcut-mcp-tools/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@shortcut/mcp-tools",
+  "version": "0.1.0",
+  "description": "Shared tools for Shortcut MCP implementations",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "@shortcut/client": "^1.1.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "@shortcut/client": "^1.1.0",
+    "typescript": "^5.0.0",
+    "zod": "^3.24.2"
+  },
+  "keywords": [
+    "shortcut",
+    "mcp",
+    "modelcontextprotocol"
+  ],
+  "author": "Shortcut (https://www.shortcut.com)",
+  "license": "MIT"
+}

shortcut-mcp-tools/src/client/cache.ts

@@ -0,0 +1,40 @@
+/**
+ * Simple key/value cache.
+ *
+ * It only supports setting **all** values at once. You cannot add to the cache over time.
+ * It tracks staleness and is hard coded to expire after 5 minutes.
+ */
+export class Cache<TId, TValue> {
+	private cache: Map<TId, TValue>;
+	private age: number;
+
+	constructor() {
+		this.cache = new Map();
+		this.age = 0;
+	}
+
+	get(key: TId) {
+		return this.cache.get(key) ?? null;
+	}
+
+	values() {
+		return Array.from(this.cache.values());
+	}
+
+	setMany(values: [TId, TValue][]) {
+		this.cache.clear();
+		for (const [key, value] of values) {
+			this.cache.set(key, value);
+		}
+		this.age = Date.now();
+	}
+
+	clear() {
+		this.cache.clear();
+		this.age = 0;
+	}
+
+	get isStale() {
+		return Date.now() - this.age > 1000 * 60 * 5;
+	}
+}