# Honkpost - Full Agent & Model Context Protocol Reference Manual

## 1. Overview & Public Routes
Honkpost provides external AI agents with direct, programmatic publishing access across social media accounts without requiring agents to manage individual OAuth tokens, browser sessions, or rate-limit refreshes.

- **`/`**: Main entry point — autonomous agent publishing runtime, visual multi-channel calendar, and live reproducible proof.
- **`/agents`**: Dedicated guide for connecting AI coding agents (Claude Code, Cursor, Codex, custom scripts) via Model Context Protocol (MCP).
- **`/scheduler`**: Visual social media calendar for founders and marketing teams featuring bulk spreadsheet import and cron dispatch.
- **`/llms.txt`**: Concise machine-readable summary for fast LLM context injection.
- **`/llms-full.txt`**: This document — complete protocol manual and API reference.
- **`/openapi.json`**: OpenAPI 3.1 schema.

## 2. Accurate Channel Status & Limits (Single Source of Truth)
- **𝕏 (Twitter)**: LIVE. Direct publishing. Strictly text-only, maximum 280 characters. Media attachments are NOT supported on 𝕏 in this version.
- **Bluesky**: LIVE. Direct publishing via AT Protocol. Text up to 300 characters. Supports optional public image URL attachments.
- **Threads**: LIVE. Direct publishing via official Meta API (`graph.threads.net`). Text-only up to 500 characters. Returns live post permalinks. Profile rate limit: 250 posts per rolling 24 hours.
- **Instagram**: LIMITED. Direct publishing via official Meta Instagram API (`graph.instagram.com`). Works only for accounts holding a registered Tester role on our Meta app, pending App Review for public access. Strictly requires an image attachment (JPEG/PNG, max 8MB, aspect ratios 4:5 to 1.91:1). Caption limit: 2,200 characters. Account rate limit: 50 posts per rolling 24 hours. Text-only posts are not supported.
- **Roadmap Platforms**: TikTok (video drafts delivered to user inbox), LinkedIn, YouTube, Facebook, Pinterest, Discord, Telegram, Mastodon, Reddit, Slack, Dev.to, Hashnode, Ghost, WordPress, Medium, Nostr, Lemmy, Tumblr, Webhook, RSS. Not connectable today.

## 3. Authentication & Rate Limits
- **Authentication**: `Authorization: Bearer <HONKPOST_API_KEY>` or `x-api-key: <HONKPOST_API_KEY>`.
- **Key Generation**: Generate keys in Dashboard -> Settings -> Developers & MCP (`https://honkpost.com/dashboard/settings`).
- **Rate Limits (Per API Key)**:
  - `publish_now`: 5 requests per minute.
  - `upload_media`: 10 requests per minute.
  - `create_post`: 30 requests per minute.
  - `general` (`list_channels`, `list_scheduled`, `cancel_post`): 60 requests per minute.
  - Exceeding limits returns HTTP 429 Too Many Requests with a `Retry-After` header.

## 4. MCP Tools Catalog (6 Tools from app/api/mcp/route.ts)

### 1. `list_channels`
- Description: List all connected social media channels and their status for the authenticated user.
- Arguments: None `{}`
- Returns: `{ "channels": [...], "platformStatus": { "x": "live", "bluesky": "live", "threads": "live", "instagram": "limited" } }`

### 2. `upload_media`
- Description: Upload and host media (images or videos) in Honkpost Blob storage for use in social posts. Re-hosts a public HTTP(S) `sourceUrl` (SSRF-verified across all hops) or stores inline `base64` data (max 10MB).
- Arguments:
  - `sourceUrl` (string, optional): Public HTTP(S) URL to download, validate, and store.
  - `base64` (string, optional): Base64-encoded image or video data (max 10MB).
  - `filename` (string, optional): Preferred filename (e.g. `"hero.png"`).
- Returns: `{ "success": true, "media": { "url": "https://...blob.vercel-storage.com/...", "mediaType": "image" | "video", "contentType": "image/png", "size": 12345, "filename": "hero.png" } }`

### 3. `create_post`
- Description: Draft and schedule a post for future publishing across connected channels in The Pond buffer queue.
- Arguments:
  - `content` (string, required): Text content (max 280 for 𝕏, max 300 for Bluesky, max 500 for Threads, max 2,200 for Instagram).
  - `targetPlatforms` (array of strings, optional): `["x", "bluesky", "threads", "instagram"]`. Defaults to active connected channels.
  - `scheduledFor` (string ISO-8601, optional): UTC execution time (e.g. `"2026-09-09T18:00:00.000Z"`). Defaults to 1 hour from now.
  - `mediaUrls` (array of strings, optional): Public media URLs. Bluesky and Instagram support images (Instagram strictly requires an image); 𝕏 is strictly text-only.
  - `firstCommentPlug` (string, optional): Follow-up reply comment to post immediately after publish.

### 4. `publish_now`
- Description: Immediately publish a post to connected social networks in a single turn.
- Arguments:
  - `content` (string, required): Text content to publish.
  - `targetPlatforms` (array of strings, optional): `["x", "bluesky", "threads", "instagram"]`. Defaults to active connected channels.
  - `mediaUrls` (array of strings, optional): Public media URLs (required for Instagram, images for Bluesky, none for 𝕏).
  - `firstCommentPlug` (string, optional): Follow-up reply comment.

### 5. `list_scheduled`
- Description: Retrieve upcoming scheduled posts in The Pond queue for the authenticated user.
- Arguments:
  - `limit` (number, optional, default: 20, max: 100): Maximum posts to return.
  - `platform` (string, optional): Filter by platform (`"x" | "bluesky" | "threads" | "instagram"`).

### 6. `cancel_post`
- Description: Cancel and remove a scheduled post from the upcoming queue before it publishes.
- Arguments:
  - `postId` (string, required): The ID or shortId (e.g. `"7307"`) of the scheduled post to cancel.

## 5. Configuration Examples

### Claude Desktop (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "honkpost": {
      "url": "https://honkpost.com/api/mcp",
      "headers": {
        "Authorization": "Bearer honk_live_YOUR_KEY"
      }
    }
  }
}
```

### Cursor (`.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "honkpost": {
      "url": "https://honkpost.com/api/mcp",
      "headers": {
        "Authorization": "Bearer honk_live_YOUR_KEY"
      }
    }
  }
}
```

### cURL (Direct HTTP JSON-RPC 2.0)
```bash
curl -X POST https://honkpost.com/api/mcp \
  -H "Authorization: Bearer honk_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "method": "tools/call", "params": {"name": "list_channels", "arguments": {}}, "id": 1}'
```