Shortcut MCP Server

src
shortcut_mcp
import asyncio
import os
from typing import Any, Optional
import httpx
from mcp.server import Server, NotificationOptions
from mcp.server.models import InitializationOptions
import mcp.types as types
import mcp.server.stdio

# Initialize server
server = Server("shortcut")

# Constants
API_BASE_URL = "https://api.app.shortcut.com/api/v3"
SHORTCUT_API_TOKEN = os.getenv("SHORTCUT_API_TOKEN")

# Helper functions
async def make_shortcut_request(
    method: str,
    endpoint: str,
    json: Optional[dict] = None,
    params: Optional[dict] = None
) -> dict[str, Any]:
    """Make an authenticated request to the Shortcut API with safety checks"""
    
    # Safety check: Only allow GET and POST methods
    if method not in ["GET", "POST"]:
        raise ValueError(f"Method {method} is not allowed for safety reasons. Only GET and POST are permitted.")
    
    # Safety check: POST requests are only allowed for creation endpoints
    if method == "POST" and not any(endpoint.endswith(x) for x in ["stories", "epics", "objectives"]):
        raise ValueError(f"POST requests are only allowed for creation endpoints, not for {endpoint}")
    if not SHORTCUT_API_TOKEN:
        raise ValueError("SHORTCUT_API_TOKEN environment variable not set")

    headers = {
        "Content-Type": "application/json",
        "Shortcut-Token": SHORTCUT_API_TOKEN
    }

    async with httpx.AsyncClient() as client:
        response = await client.request(
            method=method,
            url=f"{API_BASE_URL}/{endpoint}",
            headers=headers,
            json=json,
            params=params,
            timeout=30.0
        )
        response.raise_for_status()
        return response.json()

def format_objective(objective: dict) -> str:
    """Format an objective into a readable string"""
    return (
        f"Objective: {objective['name']}\n"
        f"Status: {objective.get('status', 'Unknown')}\n"
        f"Description: {objective.get('description', 'No description')}\n"
        f"URL: {objective.get('app_url', '')}\n"
        "---"
    )

def format_epic(epic: dict) -> str:
    """Format an epic into a readable string"""
    return (
        f"Epic: {epic['name']}\n"
        f"Status: {epic.get('state', 'Unknown')}\n"
        f"Description: {epic.get('description', 'No description')}\n"
        f"Milestone: {epic.get('milestone', {}).get('name', 'None')}\n"
        f"URL: {epic.get('app_url', '')}\n"
        "---"
    )

def format_story(story: dict) -> str:
    """Format a story into a readable string"""
    return (
        f"Story {story['id']}: {story['name']}\n"
        f"Status: {story.get('workflow_state', {}).get('name', 'Unknown')}\n"
        f"Type: {story.get('story_type', 'Unknown')}\n"
        f"Description: {story.get('description', 'No description')}\n"
        f"URL: {story.get('app_url', '')}\n"
        "---"
    )

@shortcut_server.server.list_tools()
async def handle_list_tools() -> list[types.Tool]:
    """List available Shortcut tools - Read-only operations with safe creation"""
    user_info = f" (Will be created as {shortcut_server.authenticated_user.get('name')})"
    return [
        types.Tool(
            name="search-stories",
            description="Search for stories in Shortcut",
            inputSchema={
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search query (e.g. story title, description, or ID)",
                    },
                },
                "required": ["query"],
            },
        ),
        types.Tool(
            name="create-story",
            description=f"Create a new story in Shortcut{user_info}",
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Story title",
                    },
                    "description": {
                        "type": "string",
                        "description": "Story description",
                    },
                    "story_type": {
                        "type": "string",
                        "description": "Story type (feature, bug, chore)",
                        "enum": ["feature", "bug", "chore"],
                    },
                    "project_id": {
                        "type": "number",
                        "description": "Project ID to create the story in",
                    },
                },
                "required": ["name", "description", "story_type", "project_id"],
            },
        ),
        types.Tool(

        types.Tool(
            name="list-projects",
            description="List all projects in Shortcut",
            inputSchema={
                "type": "object",
                "properties": {},
            },
        ),
        types.Tool(
            name=            "list-workflows",
            description="List all workflows and their states",
            inputSchema={
                "type": "object",
                "properties": {},
            },
        ),
        types.Tool(
            name="list-objectives",
            description="List all objectives in Shortcut",
            inputSchema={
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Filter by status (active, draft, closed)",
                        "enum": ["active", "draft", "closed"],
                    },
                },
            },
        ),
        types.Tool(
            name="create-objective",
            description=f"Create a new objective in Shortcut{user_info}",
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Objective name",
                    },
                    "description": {
                        "type": "string",
                        "description": "Objective description",
                    },
                    "status": {
                        "type": "string",
                        "description": "Objective status",
                        "enum": ["active", "draft", "closed"],
                    },
                },
                "required": ["name", "description", "status"],
            },
        ),
        types.Tool(
            name="list-epics",
            description="List epics in Shortcut",
            inputSchema={
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "description": "Filter by status (to do, in progress, done)",
                        "enum": ["to do", "in progress", "done"],
                    },
                },
            },
        ),
        types.Tool(
            name="create-epic",
            description=f"Create a new epic in Shortcut{user_info}",
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Epic name",
                    },
                    "description": {
                        "type": "string",
                        "description": "Epic description",
                    },
                    "milestone_id": {
                        "type": "number",
                        "description": "Optional milestone ID to associate with the epic",
                    },
                },
                "required": ["name", "description"],
            },
        ),
        types.Tool(

    ]

@shortcut_server.server.call_tool()
async def handle_call_tool(
    name: str,
    arguments: dict | None
) -> list[types.TextContent | types.ImageContent | types.EmbeddedResource]:
    """Handle tool execution requests"""
    if not arguments:
        raise ValueError("Missing arguments")

    try:
        if name == "search-stories":
            query = arguments.get("query")
            search_results = await make_shortcut_request(
                "GET",
                "search/stories",
                params={"query": query}
            )
            
            stories = search_results.get("data", [])
            if not stories:
                return [types.TextContent(
                    type="text",
                    text=f"No stories found matching query: {query}"
                )]

            formatted_stories = [format_story(story) for story in stories[:10]]
            return [types.TextContent(
                type="text",
                text="Found stories:\n\n" + "\n".join(formatted_stories)
            )]

        elif name == "create-story":
            story_data = {
                "name": arguments["name"],
                "description": arguments["description"],
                "story_type": arguments["story_type"],
                "project_id": arguments["project_id"],
            }

            new_story = await make_shortcut_request(
                "POST",
                "stories",
                json=story_data
            )

            return [types.TextContent(
                type="text",
                text=f"Created new story:\n\n{format_story(new_story)}"
            )]



        elif name == "list-projects":
            projects = await make_shortcut_request("GET", "projects")
            
            formatted_projects = []
            for project in projects:
                formatted_projects.append(
                    f"Project ID: {project['id']}\n"
                    f"Name: {project['name']}\n"
                    f"Description: {project.get('description', 'No description')}\n"
                    "---"
                )

            return [types.TextContent(
                type="text",
                text="Available projects:\n\n" + "\n".join(formatted_projects)
            )]

        elif name == "list-workflows":
            workflows = await make_shortcut_request("GET", "workflows")
            
            formatted_workflows = []
            for workflow in workflows:
                states = [
                    f"- {state['name']} (ID: {state['id']})"
                    for state in workflow.get("states", [])
                ]
                
                formatted_workflows.append(
                    f"Workflow: {workflow['name']}\n"
                    f"States:\n" + "\n".join(states) + "\n"
                    "---"
                )

            return [types.TextContent(
                type="text",
                text="Available workflows and states:\n\n" + "\n".join(formatted_workflows)
            )]

        else:
        elif name == "list-objectives":
            params = {}
            if status := arguments.get("status"):
                params["status"] = status

            objectives = await make_shortcut_request("GET", "objectives", params=params)
            
            if not objectives:
                return [types.TextContent(
                    type="text",
                    text="No objectives found"
                )]

            formatted_objectives = [format_objective(obj) for obj in objectives]
            return [types.TextContent(
                type="text",
                text="Objectives:\n\n" + "\n".join(formatted_objectives)
            )]

        elif name == "create-objective":
            objective_data = {
                "name": arguments["name"],
                "description": arguments["description"],
                "status": arguments["status"],
            }

            new_objective = await make_shortcut_request(
                "POST",
                "objectives",
                json=objective_data
            )

            return [types.TextContent(
                type="text",
                text=f"Created new objective:\n\n{format_objective(new_objective)}"
            )]

        elif name == "list-epics":
            params = {}
            if status := arguments.get("status"):
                params["status"] = status

            epics = await make_shortcut_request("GET", "epics", params=params)
            
            if not epics:
                return [types.TextContent(
                    type="text",
                    text="No epics found"
                )]

            formatted_epics = [format_epic(epic) for epic in epics]
            return [types.TextContent(
                type="text",
                text="Epics:\n\n" + "\n".join(formatted_epics)
            )]

        elif name == "create-epic":
            epic_data = {
                "name": arguments["name"],
                "description": arguments["description"],
            }

            if milestone_id := arguments.get("milestone_id"):
                epic_data["milestone_id"] = milestone_id

            new_epic = await make_shortcut_request(
                "POST",
                "epics",
                json=epic_data
            )

            return [types.TextContent(
                type="text",
                text=f"Created new epic:\n\n{format_epic(new_epic)}"
            )]



        else:
            raise ValueError(f"Unknown tool: {name}")

    except httpx.HTTPError as e:
        return [types.TextContent(
            type="text",
            text=f"API request failed: {str(e)}"
        )]

async def main():
    """Run the server using stdin/stdout streams"""
    # Initialize server and authenticate
    await shortcut_server.initialize()
    
    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
        await shortcut_server.server.run(
            read_stream,
            write_stream,
            InitializationOptions(
                server_name="shortcut",
                server_version="0.1.0",
                capabilities=shortcut_server.server.get_capabilities(
                    notification_options=NotificationOptions(),
                    experimental_capabilities={},
                ),
            ),
        )

if __name__ == "__main__":
    asyncio.run(main())