buttondown mcp

A comprehensive TypeScript integration for the Buttondown newsletter service, providing both a CLI interface and a Model Context Protocol (MCP) server for managing newsletters, drafts, and analytics.

Features

• Multiple Interfaces:

• Command Line Interface (CLI) for direct interaction

• Model Context Protocol (MCP) server for AI/LLM integration

• Programmatic TypeScript API for custom integrations

• Core Functionality:

• Email draft management (create, update, delete)

• Email scheduling system
• Analytics retrieval and formatting
• List management

• Tag management

• Security:

• 1Password integration for API key management

• Environment variable support

• Secure credential handling

• Developer Experience:

• Full TypeScript support
• Comprehensive type definitions
• Real API response-based types
• Built-in testing utilities

Installation

# Install using pnpm (recommended)
pnpm install

# Or using npm
npm install

# Or using yarn
yarn install

Configuration

The API key can be provided in two ways:

1. Environment variable:

export BUTTONDOWN_API_KEY=your_api_key

1. 1Password CLI (recommended):
2. Store your API key in 1Password at op://Development/Buttondown API/notesPlain
3. The integration will automatically fetch it when needed

Usage

CLI Interface

# 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 Server

1. Start the server:

pnpm mcp:start

1. Start with inspector (for development):

   pnpm mcp:inspect

Available MCP tools:

• list_emails: List all emails with optional status filtering

{
  "status": "draft" // Optional: "draft", "scheduled", "sent"
}

• create_draft: Create a new email draft

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

• get_analytics: Get analytics for a specific email

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

• schedule_draft: Schedule an email for sending

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

Programmatic Usage

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);

Development

# Build the project
pnpm build

# Run tests
pnpm test

# Start MCP server in development mode
pnpm mcp:inspect

# Build MCP server
pnpm mcp:build

Testing

The project includes several types of tests:

• Unit tests for core functionality
• Integration tests for API interactions
• CLI command tests
• MCP server tests

Run tests with:

pnpm test

Project Structure

.
├── 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

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

ISC License - See LICENSE for details

Acknowledgments

• Buttondown for their excellent newsletter service
• Model Context Protocol for the AI integration framework