Shortcut MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is a Shortcut API MCP (Model Context Protocol) Server that provides comprehensive access to Shortcut (formerly Clubhouse) for: - Reading and updating stories, comments, and project management data - Analyzing Loom videos attached to stories for debugging assistance - Correlating video content with codebase to identify relevant files - Generating debugging plans based on video analysis The server implements multiple tools for interacting with the Shortcut API and analyzing video content to help developers debug issues more effectively. ## Architecture The project consists of a Node.js server that: 1. Reads Shortcut API token from ~/.shortcut_mcp/.env 2. Connects to the Shortcut API using axios 3. Provides MCP tools for various Shortcut operations 4. Supports both reading and updating stories 5. Integrates with Loom API for video analysis 6. Analyzes video transcripts and content for debugging insights 7. Correlates video content with codebase files Key architectural decisions: - Uses ES modules (`"type": "module"` in package.json) - Implements a clean client/server separation - All API calls include proper error handling - TypeScript for type safety - Environment-based configuration for API tokens - Response size management (warns when responses exceed 20k tokens) - Modular video analysis services for different analysis types ## Running the Server Start the MCP server: ```bash ./start_mcp.sh # Standard mode (no hot reload) ./start_mcp_with_proxy.sh # With hot reload support ``` The proxy script enables hot reloading without losing the MCP connection: - Maintains stdin/stdout connection with Claude - Buffers messages during server restarts - Rebuilds and restarts server on SIGHUP signal - Use `./reload_mcp.sh` to trigger a reload Standard script features: - Checks for ~/.shortcut_mcp/.env file containing SHORTCUT_TOKEN - Logs debug output to `/tmp/shortcut-mcp-debug.log` (when DEBUG=true) - Starts the Node.js server with proper stdout/stderr handling for MCP protocol - Supports development mode with `./start_mcp.sh dev` ## Available MCP Tools ### Core Shortcut API Tools - `shortcut_get_story`: Get details for a specific story by ID - `shortcut_create_story`: Create a new story with enhanced features: - **Smart defaults**: Automatically sets workflow state, labels, epic, deadline based on story type - **Bug story enhancements**: Auto-adds 🐞 emoji prefix, sets investigate label, assigns to bugs epic - **All fields supported**: deadline, custom fields, followers, iteration, group, template, and more - `shortcut_search_stories`: Search for stories using query syntax - `shortcut_get_project_stories`: Get all stories in a project - `shortcut_get_epic_stories`: Get all stories in an epic - `shortcut_update_story`: Update story details (description, labels, state, etc.) - `shortcut_add_comment`: Add a comment to a story - `shortcut_get_comments`: Get all comments for a story - `shortcut_list_workflows`: List all workflows and their states - `shortcut_list_projects`: List all projects in the workspace - `shortcut_list_epics`: List all epics in the workspace - `shortcut_get_story_files`: Get all file attachments for a story - `shortcut_download_file`: Download file content from a story attachment (text or binary) ### Video Analysis Tools - `shortcut_get_story_loom_videos`: Extract all Loom video links from a story - `shortcut_analyze_loom_video`: Analyze Loom video content including: - Video metadata and transcript - Account information detection - Feature analysis - Audio insights for debugging - `shortcut_analyze_video_with_codebase`: Correlate video content with codebase to find relevant files - Analyzes video transcript and actions - Searches codebase for related files - Ranks files by relevance to video content - `shortcut_debug_video_issue`: Deep debugging analysis with: - Detailed action tracking from video - Error detection and analysis - Generated debugging plan - Correlation with codebase - `shortcut_analyze_video_with_anthropic`: (Currently disabled) Would use Claude Vision for visual analysis **Note**: Direct video file download is not supported due to Loom API limitations. Video analysis works with publicly available Loom metadata and transcripts. ## Security Considerations - API token is stored in ~/.shortcut_mcp/.env file - Token is never logged or exposed in responses - All API calls use HTTPS - Environment file location is in user's home directory for security - Consider using proper secrets management for production use ## Development **IMPORTANT: This project uses pnpm as the package manager. Always use pnpm commands instead of npm.** Common commands: ```bash pnpm install # Install dependencies pnpm run build # Build TypeScript to JavaScript pnpm run dev # Run in development mode with hot reload pnpm run typecheck # Check TypeScript types pnpm run lint # Run linter pnpm run format # Format code ``` The project is written in TypeScript and requires building before running in production. Testing: - Unit tests are available in `tests/unit/` - Integration tests are available in `tests/integration/` - Run tests with `pnpm test` ## Configuration Create the configuration file at `~/.shortcut_mcp/.env`: ```bash SHORTCUT_TOKEN=your-shortcut-api-token ``` To get your Shortcut API token: 1. Log in to Shortcut 2. Go to Settings > API Tokens 3. Generate a new token 4. Save it in the .env file ## Smart Defaults and Enhancements The MCP now includes intelligent defaults to streamline story creation: ### Bug Stories When creating a bug story, the MCP automatically: - Adds 🐞 emoji prefix to the title - Sets the "🧐 Investigate" label - Assigns to Epic 27912 (bugs epic) - Sets priority custom field to "Medium" by default - Sets deadline to next business day at 7am - Associates with bug report template (5fda555d-02f3-4741-b9a3-8b263c0be423) ### Label Detection The MCP analyzes story title and description to automatically add relevant labels: - "Kiosk" - if content mentions kiosk - "Audience" - if content mentions audience - "Tag" - if content mentions tag - "Intercom" - if content mentions intercom, customer, or partner ### Workflow States The MCP automatically sets the appropriate default workflow state based on the project's workflow configuration. ### Custom Fields Supports the priority custom field (6260465b-2009-456c-b2fe-ce32bb284231) with values: - Highest: 6260465b-9ae6-4667-88d6-51f634f75d6b - Medium: 6260465b-552c-4138-83ec-a52cb9f6f4f5 - Low: 6260465b-a812-4a6d-8e71-4dce16aed4f5