How useshortcut/mcp-server-shortcut works
Project type and purpose
• This is a Node.js-based MCP (Model Context Protocol) server packaged as an NPM module.
• Its role is to be spawned by AI hosts (Windsurf, Cursor, Claude Code), speak JSON-RPC over stdin/stdout, fetch data from the Shortcut API, and return structured context to the host.
File structure
• Root files:
• index.ts – entrypoint for the MCP server
• package.json, bunfig.toml, biome.json, tsconfig.json – build/configuration
• src/
• src/server.ts – core protocol handler, routes incoming MCP requests
• src/client/ – client-side abstractions (caching, shortcut request wrappers)
• src/tools/ – domain modules mapping MCP methods (stories, epics, iterations, etc.) to Shortcut API calls
• src/tools/utils/ – shared helpers (formatting, search, validation)
• Tests alongside each module confirm coverage of caching, domain logic, and utils.
README for additional insights
• The module is invoked via an NPM or Node command with env var SHORTCUT_API_TOKEN
• Integrates with three host environments (Windsurf, Cursor, Claude) by updating their MCP config JSON
• No database or UI—solely a CLI server connecting two endpoints: AI host and Shortcut’s REST API
Main components
a. AI Host Environment (Windsurf / Cursor / Claude)
b. MCP Server Process (spawned via npx @shortcut/mcp or node dist/index.js)
• Protocol Handler (src/server.ts)
• Client Layer (src/client) – request caching, request shortcut module
• Domain Layer (src/tools) – epics, stories, iterations, objectives, teams, workflows, user
• Utils Layer (src/tools/utils) – formatting, search, validation
c. External Service – Shortcut REST API
Relationships and data flows
1. AI Host launches MCP Server CLI → streams JSON-RPC requests
2. Protocol Handler parses requests → dispatches to Domain Layer
3. Domain Layer calls Client Layer to execute HTTP requests to Shortcut API
4. Client Layer optionally caches responses (in-memory)
5. HTTP client (Axios or fetch) communicates with Shortcut API over HTTPS
6. Responses bubble back up → Protocol Handler formats JSON-RPC responses → stdout to AI Host
Architectural patterns and design principles
• Layered Architecture: separation of protocol (server.ts), domain (tools), infrastructure (client + HTTP)
• Single Responsibility: each domain module handles one resource (e.g., stories.ts)
• Dependency Injection via environment (SHORTCUT_API_TOKEN)
• Hexagonal/Ports & Adapters: protocol and HTTP clients as adapters around core business logic
Technologies, frameworks, and libraries
• Node.js + TypeScript (src/*.ts)
• NPM / NPX for invocation
• JSON-RPC over stdin/stdout for MCP
• HTTP client (built-in fetch or Axios, implied)
• Testing with Jest (test.ts files)
• Build tooling (biome, bunfig, tsconfig)
Detail checklist
• index.ts → server.ts → client.ts → tools/*.ts → HTTP
• Env var injection (SHORTCUT_API_TOKEN) at startup
• Caching in the client layer
• Test coverage around each module, if desired