Buttondown API 集成

一个全面的 TypeScript 集成，用于 Buttondown 通讯服务，提供了命令行界面 (CLI) 和模型上下文协议 (MCP) 服务器来管理通讯、草稿和分析数据。

特性

• 多接口：

  • 命令行界面 (CLI) 用于直接交互
  • 模型上下文协议 (MCP) 服务器用于 AI/LLM 集成
  • 程序化的 TypeScript API 用于自定义集成

• 核心功能：

  • 电子邮件草稿管理（创建、更新、删除）
  • 电子邮件调度系统
  • 分析数据检索和格式化
  • 列表管理
  • 标签管理

• 安全性：

  • 1Password 集成用于 API 密钥管理
  • 环境变量支持
  • 安全凭证处理

• 开发者体验：

  • 完整的 TypeScript 支持
  • 全面的类型定义
  • 基于实际 API 响应的类型
  • 内置测试工具

安装

# Install using pnpm (recommended)
pnpm install

# Or using npm
npm install

# Or using yarn
yarn install

配置

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

1. 环境变量：

   export BUTTONDOWN_API_KEY=your_api_key
   

2. 1Password CLI（推荐）：

   • 将您的 API 密钥存储在 1Password 中：op://Development/Buttondown API/notesPlain
   • 集成将在需要时自动获取它

使用

CLI 界面

# List all emails
buttondown emails list

# Create a new draft
buttondown draft create <file>

# Schedule an email
buttondown schedule set <draft-id> <relative-time>

# Get analytics
buttondown analytics get <draft-id>

MCP 服务器

1. 启动服务器：

   pnpm mcp:start
   

2. 启动带有检查器（用于开发）：

   pnpm mcp:inspect
   

可用的 MCP 工具：

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

  {
    "status": "draft" // 可选："draft", "scheduled", "sent"
  }
  

• create_draft：创建新的电子邮件草稿

  {
    "content": "Email content in markdown",
    "title": "Optional email subject"
  }
  

• get_analytics：获取特定电子邮件的分析数据

  {
    "draftId": "email-id-here"
  }
  

• schedule_draft：安排电子邮件发送

  {
    "draftId": "email-id-here",
    "scheduledTime": "2024-03-27T10:00:00Z"
  }
  

程序化使用

import { ButtondownAPI } from "api-integrator";

// Initialize the client
const api = new ButtondownAPI(); // Will use 1Password or env var

// List drafts
const drafts = await api.getDrafts();

// Create a draft
const draft = await api.createEmail({
  subject: "My Newsletter",
  body: "Content here",
  status: "draft",
});

// Schedule an email
const scheduled = await api.scheduleEmail(draft.id, "2024-03-27T10:00:00Z");

// Get analytics
const analytics = await api.getEmailStats(draft.id);

开发

# Build the project
pnpm build

# Run tests
pnpm test

# Start MCP server in development mode
pnpm mcp:inspect

# Build MCP server
pnpm mcp:build

测试

项目包括几种类型的测试：

• 核心功能的单元测试
• API 交互的集成测试
• CLI 命令测试
• MCP 服务器测试

运行测试：

pnpm test

项目结构

.
├── src/
│   ├── api/          # Core API client
│   ├── cli/          # CLI implementation
│   ├── mcp/          # MCP server
│   ├── types/        # TypeScript definitions
│   └── utils/        # Shared utilities
├── tests/            # Test files
├── api-responses/    # Cached API responses
└── memory-bank/      # Project documentation

贡献

1. 分叉仓库
2. 创建你的特性分支 (git checkout -b feature/amazing-feature)
3. 提交你的更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开一个 Pull Request

许可证

ISC 许可证 - 详情请参阅 LICENSE

致谢

• Buttondown 提供了出色的通讯服务
• Model Context Protocol 提供了 AI 集成框架