shortcut project and story management via mcp protocol
Exposes Shortcut's project management API through the Model Context Protocol, enabling Claude and other MCP-compatible AI clients to read and manipulate stories, epics, projects, and workflows. Implements MCP resource and tool schemas that map Shortcut's REST API endpoints into standardized tool definitions, allowing LLMs to query project state and trigger mutations without direct API knowledge.
Unique: Implements MCP as a bridge between Shortcut's REST API and Claude/LLM clients, using standardized MCP tool schemas to abstract Shortcut's domain model (stories, epics, workflows) into composable agent capabilities. This allows LLMs to reason about project state and trigger mutations through a protocol-agnostic interface rather than direct API calls.
vs alternatives: Provides native MCP integration for Shortcut (vs. building custom Claude plugins or REST wrappers), enabling seamless multi-turn agent workflows without context switching or manual API orchestration.
story and epic querying with filtering and pagination
Implements read-only MCP tools that query Shortcut's story and epic endpoints with support for filtering by project, workflow state, assignee, and label. Uses Shortcut's query parameters to enable efficient server-side filtering, reducing payload size and API calls. Supports pagination to handle large result sets without overwhelming the LLM context window.
Unique: Exposes Shortcut's server-side filtering capabilities through MCP tool parameters, allowing the LLM to specify complex queries (by project, state, assignee, label) that are evaluated server-side rather than client-side, reducing data transfer and improving query performance.
vs alternatives: More efficient than fetching all stories and filtering in-memory because it leverages Shortcut's native query parameters, reducing API payload size and enabling agents to work with large projects without context window exhaustion.
story and epic creation with automatic field validation
Implements MCP tools for creating stories and epics in Shortcut with schema-based validation of required fields (name, project, workflow state). Validates input parameters against Shortcut's API constraints before submission, providing early error feedback to the LLM. Supports optional fields like description, estimate, assignee, and labels, allowing flexible story creation workflows.
Unique: Implements client-side schema validation before submitting to Shortcut's API, catching invalid field combinations (e.g., invalid workflow state) before making network requests. This reduces API errors and provides immediate feedback to the LLM, improving agent reliability.
vs alternatives: Validates input parameters before API submission (vs. raw REST calls that fail server-side), enabling agents to recover from validation errors without wasting API calls or creating partial/invalid stories.
story and epic mutation (update, delete) with change tracking
Implements MCP tools for updating story/epic fields (name, description, state, estimate, assignee, labels) and deleting stories. Supports partial updates — only specified fields are modified, leaving others unchanged. Tracks which fields were modified and returns the updated object, enabling agents to confirm changes and detect conflicts.
Unique: Supports partial updates with field-level granularity, allowing agents to modify only specific story attributes without re-submitting the entire object. Returns the updated object to enable agents to verify changes and detect conflicts.
vs alternatives: More flexible than full-object replacement because it allows agents to update individual fields (e.g., just the state) without needing to fetch and re-submit the entire story, reducing API calls and enabling atomic field updates.
workflow state and project metadata discovery
Implements MCP tools that query Shortcut's workflow definitions and project metadata, returning valid workflow states, project names, and team structures. Enables agents to discover valid values for constrained fields (e.g., workflow states) without hardcoding them, improving robustness across different Shortcut workspaces.
Unique: Exposes Shortcut's workspace configuration as queryable MCP tools, allowing agents to dynamically discover valid workflow states, projects, and team members rather than relying on hardcoded values. This enables agents to adapt to different workspace configurations without modification.
vs alternatives: Enables dynamic configuration discovery (vs. hardcoding workflow states and project IDs), making agents portable across different Shortcut workspaces and resilient to configuration changes.
mcp protocol transport and schema mapping
Implements the MCP server-side protocol handler that translates between MCP tool calls (from Claude or other MCP clients) and Shortcut API requests. Uses JSON schema definitions to describe tool parameters and return types, enabling clients to understand tool capabilities without documentation. Handles MCP request/response serialization, error handling, and protocol versioning.
Unique: Implements MCP as a protocol layer that abstracts Shortcut's REST API, using JSON schemas to describe tool capabilities. This enables any MCP-compatible client (not just Claude) to interact with Shortcut through a standardized interface.
vs alternatives: Provides protocol-agnostic integration (vs. Claude-specific plugins) by implementing MCP, enabling the same Shortcut tools to work with multiple LLM clients and frameworks that support MCP.