https://github.com/the-focus-ai/buttondown-mcp
ModelContextProtocal server for interacting with buttondown
https://github.com/the-focus-ai/buttondown-mcp
buttondown modelcontextprotocol
Last synced: 2 months ago
JSON representation
ModelContextProtocal server for interacting with buttondown
- Host: GitHub
- URL: https://github.com/the-focus-ai/buttondown-mcp
- Owner: The-Focus-AI
- License: mit
- Created: 2025-03-21T05:23:29.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2025-07-15T10:52:10.000Z (3 months ago)
- Last Synced: 2025-07-16T00:40:12.290Z (3 months ago)
- Topics: buttondown, modelcontextprotocol
- Language: TypeScript
- Homepage:
- Size: 127 KB
- Stars: 0
- Watchers: 1
- Forks: 1
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Changelog: newsletter.md
- License: LICENSE
Awesome Lists containing this project
README
# Buttondown API Integration
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
```bash
# 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:
```bash
export BUTTONDOWN_API_KEY=your_api_key
```
2. 1Password CLI (recommended):
- Store your API key in 1Password at `op://Development/Buttondown API/notesPlain`
- The integration will automatically fetch it when needed
## Usage
### CLI Interface
```bash
# List all emails
buttondown emails list
# Create a new draft
buttondown draft create
# Schedule an email
buttondown schedule set
# Get analytics
buttondown analytics get
```
### MCP Server
1. Start the server:
```bash
pnpm mcp:start
```
2. Start with inspector (for development):
```bash
pnpm mcp:inspect
```
Available MCP tools:
- `list_emails`: List all emails with optional status filtering
```json
{
"status": "draft" // Optional: "draft", "scheduled", "sent"
}
```
- `create_draft`: Create a new email draft
```json
{
"content": "Email content in markdown",
"title": "Optional email subject"
}
```
- `get_analytics`: Get analytics for a specific email
```json
{
"draftId": "email-id-here"
}
```
- `schedule_draft`: Schedule an email for sending
```json
{
"draftId": "email-id-here",
"scheduledTime": "2024-03-27T10:00:00Z"
}
```
### Programmatic Usage
```typescript
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
```bash
# 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:
```bash
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](LICENSE) for details
## Acknowledgments
- [Buttondown](https://buttondown.email/) for their excellent newsletter service
- [Model Context Protocol](https://github.com/cursor-ai/model-context-protocol) for the AI integration framework