Skip to main content
Glama
enesjakozh
The-Focus-AI

Buttondown MCP Server

by The-Focus-AI
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

Buttondown API 集成

Buttondown 新闻通讯服务的全面 TypeScript 集成，提供 CLI 界面和模型上下文协议 (MCP) 服务器来管理新闻通讯、草稿和分析。

特征

  • 多种接口：

    • 用于直接交互的命令行界面 (CLI)

    • 用于 AI/LLM 集成的模型上下文协议 (MCP) 服务器

    • 用于自定义集成的编程 TypeScript API

  • 核心功能：

    • 电子邮件草稿管理（创建、更新、删除）

    • 电子邮件调度系统

    • 分析检索和格式化

    • 列表管理

    • 标签管理

  • 安全：

    • 1Password 集成用于 API 密钥管理

    • 环境变量支持

    • 安全凭证处理

  • 开发人员经验：

    • 全面支持 TypeScript

    • 全面的类型定义

    • 真正的基于 API 响应的类型

    • 内置测试实用程序

Related MCP server: Buttondown MCP Server

安装

# 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" // Optional: "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. 打开拉取请求

执照

ISC 许可证 - 详情请参阅许可证

致谢

Available Tools

4 tools
create_draftA

Create a new email draft in Buttondown with the specified content and optional title. This tool requires explicit user confirmation before proceeding as it will create a new draft in your Buttondown account.

ParametersJSON Schema
NameRequiredDescriptionDefault
contentYesThe main content/body of the email draft
titleNoOptional title/subject for the email draft
confirmedYesMust be true to confirm the draft creation

TDQS

A4.4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It successfully communicates that this is a write operation ('create a new draft'), specifies the target system ('in your Buttondown account'), and importantly discloses the confirmation requirement. However, it doesn't mention potential side effects, error conditions, or what happens to existing drafts.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is perfectly concise with two sentences: the first states the core functionality, the second adds the critical behavioral constraint. Every word earns its place, and the most important information (the confirmation requirement) is appropriately front-loaded in the second sentence.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a creation tool with no annotations and no output schema, the description does well by specifying the action, target system, and confirmation requirement. However, it doesn't describe what the tool returns (e.g., draft ID, success status) or potential error scenarios. Given the 100% schema coverage, the parameter documentation is adequate.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already fully documents all three parameters. The description mentions 'content and optional title' which aligns with the schema, but adds no additional semantic context beyond what the schema provides. The confirmation requirement is behavioral rather than parameter-specific.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Create a new email draft'), the target resource ('in Buttondown'), and the key components ('with the specified content and optional title'). It distinguishes this creation tool from sibling tools like get_analytics (read-only), list_emails (listing), and schedule_draft (scheduling).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit usage guidance: 'This tool requires explicit user confirmation before proceeding.' This creates a clear when-to-use condition (only when user confirmation is available) and implies when-not-to-use (without confirmation). While it doesn't name alternatives, the confirmation requirement serves as a strong usage constraint.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_analyticsC

Retrieve analytics data for a specific email draft from Buttondown

ParametersJSON Schema
NameRequiredDescriptionDefault
draftIdYesThe ID of the email draft to get analytics for

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states 'Retrieve analytics data' which implies a read-only operation, but doesn't specify what analytics are included (e.g., open rates, clicks), permissions required, rate limits, or response format. This is a significant gap for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence that directly states the tool's purpose without any wasted words. It is appropriately sized and front-loaded, making it easy to understand at a glance.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations and no output schema, the description is incomplete. It doesn't explain what analytics data is returned, potential errors, or behavioral traits. For a tool that retrieves data, this leaves critical gaps in understanding how to use it effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents the single parameter 'draftId' fully. The description adds no additional meaning beyond implying the parameter is for a specific email draft, which is redundant with the schema. Baseline 3 is appropriate when the schema does the heavy lifting.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Retrieve analytics data') and target resource ('for a specific email draft from Buttondown'), which is specific and unambiguous. However, it doesn't differentiate from sibling tools like 'list_emails' or 'schedule_draft', which might also involve analytics or draft operations, so it misses full sibling distinction.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., needing a draft ID), exclusions, or how it differs from sibling tools like 'list_emails' that might list drafts. This leaves usage context unclear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_emailsB

List all emails, optionally filtered by status (draft, scheduled, sent)

ParametersJSON Schema
NameRequiredDescriptionDefault
statusNoOptional status to filter emails by

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It states the tool lists emails with optional filtering, but doesn't cover critical aspects like whether this is a read-only operation, potential rate limits, authentication requirements, pagination behavior, or what the output format looks like. For a list tool with zero annotation coverage, this is a significant gap in transparency.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with a single sentence that efficiently communicates the core functionality. Every word earns its place, and it's front-loaded with the main purpose. No wasted verbiage or unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no annotations, no output schema, and a simple single-parameter tool, the description is incomplete. It doesn't address what the tool returns, how results are structured, whether there are limitations on the listing, or any behavioral aspects. For even a simple tool, more context about the operation would be helpful for an AI agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, with the single parameter 'status' fully documented in the schema including its enum values. The description adds minimal value beyond the schema by mentioning the optional status filtering, but doesn't provide additional context about parameter usage or implications. This meets the baseline for high schema coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose with a specific verb ('List') and resource ('emails'), and mentions optional filtering by status. However, it doesn't explicitly differentiate from sibling tools like 'get_analytics' which might also retrieve email data, leaving some ambiguity about when to choose this tool over others.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for listing emails with optional status filtering, but provides no explicit guidance on when to use this tool versus alternatives like 'get_analytics' or 'create_draft'. It mentions the filtering capability but doesn't specify scenarios or exclusions, leaving usage context to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

schedule_draftA

Schedule an existing email draft to be sent at a specific time. This tool requires explicit user confirmation before proceeding as it will modify the draft's status and schedule.

ParametersJSON Schema
NameRequiredDescriptionDefault
draftIdYesThe ID of the email draft to schedule
scheduledTimeYesWhen to send the email (ISO 8601 datetime format)
confirmedYesMust be true to confirm the scheduling

TDQS

A4.1/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes key traits: it modifies the draft's status and schedule (indicating a mutation), requires user confirmation, and implies a time-based action. However, it lacks details on error handling, rate limits, or specific permissions needed.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized with two sentences that are front-loaded and efficient. The first sentence states the purpose, and the second adds crucial behavioral context (confirmation requirement and modification effects), with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (a mutation with user confirmation), no annotations, and no output schema, the description is somewhat complete but has gaps. It covers the action and confirmation need but lacks details on return values, error cases, or full behavioral context, making it adequate but not fully comprehensive.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 100%, so the schema already documents all parameters (draftId, scheduledTime, confirmed). The description adds minimal value beyond the schema by implying the purpose of scheduling but does not provide additional syntax, format details, or usage examples for the parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('Schedule an existing email draft') and the resource ('email draft'), distinguishing it from sibling tools like create_draft (creation), get_analytics (analysis), and list_emails (listing). It specifies the outcome ('to be sent at a specific time') without being tautological.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides clear context for when to use this tool ('Schedule an existing email draft') and includes a prerequisite ('requires explicit user confirmation'), but it does not explicitly state when not to use it or name alternatives among the sibling tools (e.g., when to use create_draft instead).

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 4 tool updates
    • First observedcreate_draft
    • First observedget_analytics
    • First observedlist_emails
    • First observedschedule_draft
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.7/5.0

Scored across 4 tools

Disambiguation5/5

Each tool has a clearly distinct purpose targeting specific actions in the email lifecycle: create_draft for creation, list_emails for listing, get_analytics for analytics retrieval, and schedule_draft for scheduling. There is no overlap or ambiguity between these functions.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with snake_case (create_draft, get_analytics, list_emails, schedule_draft). The verbs are appropriate and predictable, making the set easy to understand and use.

Tool Count4/5

With 4 tools, the count is reasonable for an email newsletter server, covering core operations. However, it feels slightly thin as it lacks tools for updating or deleting drafts, which are common in such domains, but the scope is still well-defined.

Completeness4/5

The tool set covers key email lifecycle stages: creation, listing, analytics, and scheduling. Minor gaps exist, such as no update_draft or delete_draft tools, but agents can work around this by creating new drafts or using existing ones, and the core workflow is supported.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers