# useshortcut/mcp-server-shortcut architecture

> Architecture diagram of the GitHub repository useshortcut/mcp-server-shortcut, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/useshortcut/mcp-server-shortcut
- Repository: https://github.com/useshortcut/mcp-server-shortcut

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Systems
    subgraph "AI Host Environment"
        Host["AI Host"]:::external
    end

    %% MCP Server Layers
    subgraph "MCP Server"
        direction TB
        Index["index.ts"]:::entry
        Server["Protocol Handler (src/server.ts)"]:::protocol

        subgraph "Client Layer"
            direction TB
            Cache["Caching Module"]:::cache
            ShortcutWrapper["Shortcut API Wrapper"]:::cache
        end

        subgraph "Domain Layer"
            direction TB
            BaseTool["Base Tooling"]:::domain
            Epics["Epics Module"]:::domain
            Stories["Stories Module"]:::domain
            Iterations["Iterations Module"]:::domain
            Objectives["Objectives Module"]:::domain
            Teams["Teams Module"]:::domain
            Workflows["Workflows Module"]:::domain
            User["User Module"]:::domain
        end

        subgraph "Utils Layer"
            direction TB
            Format["Formatting Helpers"]:::utils
            Search["Search Helpers"]:::utils
            Validation["Validation Helpers"]:::utils
        end

        HTTPClient["HTTP Client"]:::infra
    end

    %% External Shortcut API
    ShortcutAPI["Shortcut REST API"]:::external

    %% Data Flows
    Host -->|"JSON-RPC Requests"| Index
    Index -->|spawns & init| Server
    Server -->|"dispatches to"| BaseTool
    BaseTool --> Epics
    BaseTool --> Stories
    BaseTool --> Iterations
    BaseTool --> Objectives
    BaseTool --> Teams
    BaseTool --> Workflows
    BaseTool --> User
    Epics -->|"uses client"| Cache
    Stories --> Cache
    Iterations --> Cache
    Objectives --> Cache
    Teams --> Cache
    Workflows --> Cache
    User --> Cache
    Cache --> ShortcutWrapper
    ShortcutWrapper --> HTTPClient
    HTTPClient -->|"HTTPS"| ShortcutAPI
    ShortcutAPI -->|"responses"| HTTPClient
    HTTPClient --> ShortcutWrapper
    ShortcutWrapper --> Cache
    Cache --> Server
    Server -->|"JSON-RPC Responses"| Host

    %% Click Events
    click Index "https://github.com/useshortcut/mcp-server-shortcut/blob/main/index.ts"
    click Server "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/server.ts"
    click Cache "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/client/cache.ts"
    click ShortcutWrapper "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/client/shortcut.ts"
    click BaseTool "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/tools/base.ts"
    click Epics "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/tools/epics.ts"
    click Stories "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/tools/stories.ts"
    click Iterations "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/tools/iterations.ts"
    click Objectives "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/tools/objectives.ts"
    click Teams "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/tools/teams.ts"
    click Workflows "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/tools/workflows.ts"
    click User "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/tools/user.ts"
    click Format "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/tools/utils/format.ts"
    click Search "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/tools/utils/search.ts"
    click Validation "https://github.com/useshortcut/mcp-server-shortcut/blob/main/src/tools/utils/validation.ts"

    %% Styles
    classDef external fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef entry fill:#90EE90,stroke:#333,stroke-width:1px
    classDef protocol fill:#98FB98,stroke:#333,stroke-width:1px
    classDef cache fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef domain fill:#90EE90,stroke:#333,stroke-width:1px
    classDef utils fill:#FFFFE0,stroke:#333,stroke-width:1px
    classDef infra fill:#FFDAB9,stroke:#333,stroke-width:1px
```
