Buttondown 上下文服务后端

以下为使用指南，帮助你快速理解、安装与接入。

项目简介

该仓库实现了一个 MCP（Model Context Protocol）风格的服务器端应用，用于将 Buttondown 的邮件/订阅者等数据暴露给 LLM 客户端。服务器实现了多个工具（Tools），如获取邮件、创建草稿、发送草稿、获取分析等，LLM 客户端可通过统一的接口调用这些工具并获取结构化的 JSON 结果。

主要功能点

• MCP 风格工具定义与执行：定义 list_emails、get_email、create_draft、update_draft、send_draft、schedule_draft、get_analytics、list_subscribers、get_subscriber 等工具，支持输入校验与类型描述。
• 外部 API 封装：通过 Buttondown 客户端封装 Buttondown API 的调用，统一处理鉴权、请求与错误响应。
• JSON-RPC 交互格式：服务器接收工具调用请求，返回符合 MCP 规范的 JSON-RPC 响应数据。
• 会话与传输适配：通过 @modelcontextprotocol/sdk 提供的传输层，支持 StdIO、SSE、WebSocket 等传输形态，便于在不同环境中使用。
• 安全与可配置性：通过环境变量获取 API key，适合在受控环境中部署，支持易于替换的配置。

安装步骤

• 准备工作：需要 Node.js 环境。
• 安装依赖并构建：
  • 安装依赖并编译源码（项目通常通过 npm/yarn 安装并编译 TypeScript）。
  • 生成可执行入口（若有构建步骤，按项目实际步骤执行）。
• 运行服务器：
  • 以标准输入输出（Stdio）方式启动，或按照需要选择 SSE/WebSocket 等传输方式。
  • 需要设置 Buttondown 的 API KEY 环境变量 BUTTONDOWN_API_KEY，确保能够访问 Buttondown API。

服务器配置（JSON 形式，供 MCP 客户端参考，不由客户端直接执行）

{ "server": "buttondown", "command": "npx", "args": ["-y", "buttondown-mcp"], "env": { "BUTTONDOWN_API_KEY": "your-api-key" } } 说明：

• server: 指定服务器名称，客户端在连接时可使用该名称进行标识。
• command / args: MCP 服务器启动命令及参数，客户端需要知道如何启动服务器。
• env: 启动时的环境变量，至少包含 BUTTONDOWN_API_KEY，用于访问 Buttondown 的 API。

备注：具体启动命令与参数可根据你的运行环境调整，示例中的配置仅用于快速接入参考。

基本使用方法

• 运行并连接：按照上述配置启动 MCP 服务器后，使用支持 MCP 的客户端连接该服务器，发起对 list_emails、get_email 等工具的调用请求。
• 调用方式：通过客户端发送工具调用请求，如 name 为 list_emails 的工具，传入相应参数（如 status、page），服务器会返回带 content 的 JSON 数据，包含结构化的结果。
• 结果处理：解析返回的 JSON-RPC 响应，提取 content.text 中的 JSON 字符串并解析成对象，即可获得数据。