JinDaGe - buttondown-mcp MCP Details

article

README

🚀 Buttondown API 集成

这是一个全面的 TypeScript 实现方案，用于集成 Buttondown 时事通讯服务。它提供了命令行界面 (CLI) 和模型上下文协议 (MCP) 服务器，能有效管理时事通讯、草稿和分析数据，为用户带来便捷的时事通讯管理体验。

✨ 主要特性

多接口支持

命令行界面 (CLI)：支持用户直接与系统进行交互，操作简便。
模型上下文协议 (MCP) 服务器：为 AI/LLM 集成提供支持，拓展了系统的应用场景。
自定义整合的 TypeScript API：方便开发者根据自身需求进行定制化开发。

核心功能丰富

时事通讯草稿管理：可轻松实现时事通讯草稿的创建、更新和删除操作。
时事通讯排期系统：支持对时事通讯进行排期，合理安排发送时间。
分析数据获取和格式化：能够获取并格式化分析数据，为决策提供数据支持。
列表管理：方便对时事通讯列表进行管理。
标签管理：支持对时事通讯添加标签，便于分类和查找。

安全保障有力

1Password 集成：用于 API 密钥管理，提高密钥管理的安全性。
环境变量支持：可通过环境变量提供 API 密钥，增加配置的灵活性。
安全凭证处理：确保凭证处理过程的安全性。

良好的开发者体验

全面的 TypeScript 支持：为开发者提供强大的类型检查和代码提示。
全面的类型定义：使代码更加规范和易于维护。
基于实际 API 响应的类型：确保类型定义与实际 API 响应一致。
内置测试工具：方便开发者进行代码测试。

📦 安装指南

你可以根据自己的需求选择以下任意一种包管理工具进行安装：

# 使用 pnpm（推荐）
pnpm install

# 或使用 npm
npm install

# 或使用 yarn
yarn install

📚 详细文档

配置说明

API 密钥可通过以下两种方式提供：

环境变量：
```
export BUTTONDOWN_API_KEY=your_api_key
```
1Password CLI（推荐）：
- 将 API 密钥存储在 1Password 的 op://Development/Buttondown API/notesPlain。
- 集成程序会在需要时自动获取。

使用方法

命令行界面 (CLI)

# 列出所有电子邮件
buttondown emails list

# 创建新草稿
buttondown draft create <文件>

# 排期发送电子邮件
buttondown schedule set <draft-id> <相对时间>

# 获取分析数据
buttondown analytics get <draft-id>

MCP 服务器

启动服务器：
```
pnpm mcp:start
```
带有调试功能启动（开发时）：
```
pnpm mcp:inspect
```

可用的 MCP 工具

list_emails：列出所有电子邮件，可选状态过滤

{
  "status": "draft" // 可选："draft"、"scheduled"、"发送中"
}

create_email：创建新的电子邮件草稿

{
  "subject": "字符串",
  "content": "字符串",
  "list_id": "string"
}

开发人员指南

项目结构如下：

src/
├── cli.ts - 实现 CLI 界面
├── mcp-server.ts - 实现 MCP 服务器
└── types.ts - 定义与 Buttondown API 交互的类型

测试命令

pnpm test

开发命令

pnpm dev

贡献指南

为项目提交拉取请求前，请确保代码遵循项目编码规范。
提交问题或功能请求至项目的 GitHub 仓库。

📄 许可证

本项目遵守 MIT License 协议。

致谢

感谢 Buttondown 提供了优秀的时事通讯服务。
感谢模型上下文协议提供的 AI 集成框架。

buttondown-mcp