mac shortcuts MCP

mac_shortcuts_mcp

概述

mac_shortcuts_mcp 是一个最小的MCP（模型上下文协议）服务器，允许ChatGPT兼容的客户端触发本地macOS快捷方式。它包裹着 shortcuts CLI支持模式感知MCP工具，因此助手可以执行命名快捷方式、传递可选文本输入并接收结构化结果。

目录

• 先决条件
• 安装
• 运行服务器

- 快速入门（STDIO） - 可流式传输HTTP/SSE

• 客户端集成

- STDIO客户端 - HTTP/SSE客户端 - 工具有效载荷示例

• 高级配置

先决条件

• 带有Shortcuts应用程序的macOS主机 shortcuts 命令行工具在中可用 PATH.
• Python 3.12或更高版本，外加 紫外线 用于依赖性管理。
• FastMCP （通过自动安装 uv)提供流线型MCP转轮。

安装

初始设置

uv sync

拉取更改后进行更新

跑 uv sync 每当你 git pull 新的承诺。该命令读取项目的 pyproject.toml/uv.lock 并确保虚拟环境完全匹配——安装新的依赖项、更新现有的依赖项，并删除不再需要的任何内容。除非您有意清除缓存的轮子，否则不需要额外的清理(uv cache prune)或者从头开始重建环境。

运行服务器

快速入门（STDIO）

uv run fastmcp run src/mac_shortcuts_mcp/server.py --transport stdio

这将在STDIO模式下使用推荐的FastMCP CLI启动MCP服务器。配置您的客户端以执行确切的命令，并通过stdin/stdout上的JSON-RPC进行通信。

可流式传输HTTP/SSE

uv run fastmcp run src/mac_shortcuts_mcp/server.py \
  --transport streamable-http \
  --host 0.0.0.0 \
  --port 8000

• 使用 --transport http 相反，当您需要JSON响应而不是SSE流时。
• 调整 --host/--port 以匹配您的网络环境。

客户端集成

大多数MCP客户端都期望生成STDIO进程或HTTP端点。FastMCP运行程序使用上述命令公开两者。

STDIO客户端

1. 使用启动服务器 快速开始 命令。
2. 配置客户端以运行确切的命令并保持进程活动。
3. 客户端应通过stdin/stdout发送和接收JSON-RPC帧。

HTTP/SSE客户端

1. 使用启动服务器 可流式传输HTTP/SSE 命令。
2. 向客户指出 http://$HOST:$PORT/mcp （使用 https:// 在其他地方终止TLS时）。
3. 选择SSE作为流式响应，或选择JSON作为离散响应。

工具有效载荷示例

在调用公开的工具时，向MCP客户端提供如下有效负载：

{
  "shortcutName": "Show Content",
  "textInput": "testing output",
  "timeoutSeconds": 30
}

• shortcutName 选择要执行的macOS快捷方式。
• textInput （可选）将文本传输到快捷方式的标准输入，镜像 ` echo "value" | shortcuts run "Shortcut Name" `.
• timeoutSeconds 限制执行时间以防止进程失控。

高级配置

FastMCP运行器在没有TLS的情况下绑定，并禁用DNS重新绑定保护。对于HTTPS终止或强制执行 allowed_hosts / allowed_origins 策略中，请改用基于Typer的CLI：

uv run python -m mac_shortcuts_mcp http \
  --host 0.0.0.0 \
  --port 8443 \
  --allowed-host example.com \
  --allowed-origin https://example.com \
  --certfile /path/to/fullchain.pem \
  --keyfile /path/to/privkey.pem

• 省略 --certfile/--keyfile 仅提供HTTP服务，或更改 --host 到 127.0.0.1 当通过反向代理终止TLS时。
• 提供多种 --allowed-host / --allowed-origin 根据需要标记以重新启用FastMCP的DNS重新绑定保护。