Shortcut.com MCP 服务器

一个用于访问和搜索 Shortcut.com 上的工单的模型上下文协议 (MCP) 服务器的实现。

概述

本项目实现了一个 MCP 服务器，允许 Claude 和其他 MCP 兼容的 AI 助手与 Shortcut.com 的工单管理系统进行交互。通过此集成，AI 助手可以：

• 在 Shortcut 中列出和搜索故事（工单）
• 获取有关特定故事的详细信息
• 创建新故事
• 更新现有故事
• 向故事添加评论
• 检索工作流程状态和项目

前提条件

• Python 3.10+
• Shortcut.com API 令牌

安装

1. 克隆此存储库：

   git clone https://github.com/yourusername/mcp-server-shortcut.git
   cd mcp-server-shortcut
   

2. 创建一个虚拟环境并安装依赖项：

   # 使用 uv (推荐)
   curl -LsSf https://astral.sh/uv/install.sh | sh  # For Mac/Linux
   uv venv
   source .venv/bin/activate  # On Mac/Linux or .venv\Scripts\activate on Windows
   uv pip install -r requirements.txt
   
   # 使用 pip
   python -m venv venv
   source venv/bin/activate  # On Mac/Linux or venv\Scripts\activate on Windows
   pip install -r requirements.txt
   

3. 在项目根目录中创建一个 .env 文件，其中包含您的 Shortcut API 令牌：

   SHORTCUT_API_TOKEN=your_token_here
   SERVER_PORT=5000
   SERVER_HOST=0.0.0.0
   DEBUG_MODE=True
   

运行服务器

使用以下命令启动 MCP 服务器：

python -m src.server

配置 Claude Desktop

要将此 MCP 服务器与 Claude Desktop 一起使用：

1. 编辑 Claude Desktop 配置文件：

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. 添加 MCP 服务器配置：

   {
     "mcpServers": {
       "shortcut": {
         "command": "python",
         "args": ["-m", "src.server"],
         "env": {
           "SHORTCUT_API_TOKEN": "your_token_here"
         }
       }
     }
   }
   

3. 重新启动 Claude Desktop。

可用的 MCP 功能

资源

• shortcut://stories - 访问故事列表
• shortcut://story/{story_id} - 访问特定故事

工具

• list_stories - 列出故事，可选择过滤
• search_stories - 使用文本查询搜索故事
• get_story_details - 获取有关特定故事的详细信息
• create_story - 创建新故事
• update_story - 更新现有故事
• add_comment - 向故事添加评论
• list_workflow_states - 列出所有工作流程状态
• list_projects - 列出所有项目

提示

• create_bug_report - 生成错误报告的模板
• create_feature_request - 生成功能请求的模板

项目结构

• src/ - 源代码目录
  • server.py - 主要 MCP 服务器实现
  • config.py - 配置管理
  • shortcut_client.py - Shortcut API 的客户端
  • utils.py - 实用程序函数和数据模型
• requirements.txt - 项目依赖项
• .env - 环境变量（未在 git 中跟踪）

开发

添加新功能

要向 MCP 服务器添加新功能：

1. 将任何新的 API 方法添加到 shortcut_client.py
2. 如果需要，在 utils.py 中定义 Pydantic 模型
3. 使用 server.py 中的装饰器实现 MCP 功能：
   • 对于只读资源，使用 @mcp.resource()
   • 对于可以修改数据的操作，使用 @mcp.tool()
   • 对于生成模板或结构化文本，使用 @mcp.prompt()

贡献

欢迎贡献！请随时提交 Pull Request。

许可证

MIT 许可证