# Honkpost - Autonomous Agentic Social Media Delivery Platform

> Honkpost is an AI-native social media scheduling and publishing runtime. Connect accounts once, then let Claude Code, Cursor, Codex, or custom scripts schedule and publish directly across social channels via Model Context Protocol (MCP) or REST API.

## Public Routes
- **Homepage (`/`)**: Main entry point detailing the agent publishing runtime, visual calendar, and reproducible proof.
- **Agents Guide (`/agents`)**: Technical guide for connecting AI coding agents (Claude Code, Cursor, Codex) to the MCP server.
- **Human Scheduler (`/scheduler`)**: Multi-channel visual scheduling calendar with bulk spreadsheet import and serverless cron dispatch.
- **Documentation (`/llms.txt`, `/llms-full.txt`)**: Machine-readable specification for LLMs and crawler agents.
- **OpenAPI Schema (`/openapi.json`)**: REST API contract.

## Accurate Channel Status (Single Source of Truth)
- **𝕏 (Twitter)**: LIVE. Direct publishing (strictly text-only, up to 280 characters). Media attachments not supported.
- **Bluesky**: LIVE. Direct publishing via AT Protocol (text up to 300 characters + image attachments).
- **Threads**: LIVE. Direct publishing via official Meta Graph API (text-only up to 500 characters, returns real permalink, 250 posts/24h profile rate limit).
- **Instagram**: LIMITED. Works only for accounts holding a registered Tester role on our Meta app, pending App Review for public access. Image attachment required (JPEG/PNG), captions up to 2,200 characters.
- **Roadmap Platforms**: TikTok (video drafts to inbox), LinkedIn, YouTube, Facebook, Pinterest, Discord, Telegram, Mastodon, Reddit, Slack, Dev.to, Hashnode, Ghost, WordPress, Medium, Nostr, Lemmy, Tumblr, Webhook, RSS. Not connectable today.

## Model Context Protocol (MCP) Server
- **Server Endpoint**: `https://honkpost.com/api/mcp`
- **Transport**: HTTP POST (JSON-RPC 2.0 tools/call or direct REST `{ "tool": "<name>", "args": { ... } }`)
- **Authentication**: `Authorization: Bearer <HONKPOST_API_KEY>` or `x-api-key: <HONKPOST_API_KEY>`
  *(Generate keys in Honkpost Dashboard -> Settings -> Developers & MCP)*

## The Six MCP Tools (Signatures & Constraints)

1. **`list_channels`**
   - Signature: `{}`
   - Description: List authenticated user's connected social media accounts and active publishing capabilities.
   - Output: `{ "channels": [{ "id": "...", "platform": "x" | "bluesky" | "threads" | "instagram", "name": "..." }], "platformStatus": { ... } }`

2. **`upload_media`**
   - Signature: `{ sourceUrl?: string, base64?: string, filename?: string }`
   - Description: Upload and host an image or video asset in Honkpost Blob storage for use in social posts. Pass a public HTTP(S) sourceUrl to re-host (SSRF-checked) or base64 data (max 10MB).
   - Supported: Images (JPEG, PNG, WebP, GIF, AVIF for Bluesky and Instagram); Videos (MP4, MOV for TikTok drafts).
   - Output: `{ "success": true, "media": { "url": "https://...blob.vercel-storage.com/...", "mediaType": "image" | "video", "size": number } }`

3. **`create_post`**
   - Signature: `{ content: string, targetPlatforms?: string[], scheduledFor?: string, mediaUrls?: string[], firstCommentPlug?: string }`
   - Description: Draft and schedule a post for future delivery into The Pond queue buffer.
   - Limits: 𝕏 (max 280 chars, text-only), Bluesky (max 300 chars, image media), Threads (max 500 chars), Instagram (max 2,200 chars, image required, tester role only). scheduledFor defaults to 1 hour from now (ISO-8601 UTC).

4. **`publish_now`**
   - Signature: `{ content: string, targetPlatforms?: string[], mediaUrls?: string[], firstCommentPlug?: string }`
   - Description: Immediately publish a post across connected platforms in a single agent turn.
   - Limits: Same character and media limits as create_post. Returns per-platform publishing results and live permalinks.

5. **`list_scheduled`**
   - Signature: `{ limit?: number, platform?: string }`
   - Description: Retrieve upcoming scheduled posts in The Pond queue (limit default 20, max 100; optional platform filter).

6. **`cancel_post`**
   - Signature: `{ postId: string }`
   - Description: Cancel and delete a scheduled post from the upcoming queue before it dispatches. Accepts post ID or shortId (e.g. "7307").

## End-to-End Agent Turn Example
```bash
# 1. Re-host media
UPLOAD_RES=$(curl -s -X POST https://honkpost.com/api/mcp \
  -H "Authorization: Bearer $HONKPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tool": "upload_media", "args": {"sourceUrl": "https://example.com/photo.png"}}')
MEDIA_URL=$(echo $UPLOAD_RES | jq -r '.media.url')

# 2. Publish post across X, Bluesky, and Threads
curl -s -X POST https://honkpost.com/api/mcp \
  -H "Authorization: Bearer $HONKPOST_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"tool\": \"publish_now\", \"args\": {\"content\": \"Autonomous post dispatched from Claude Code\", \"targetPlatforms\": [\"bluesky\"], \"mediaUrls\": [\"$MEDIA_URL\"]}}"
```

## Developer & Documentation URLs
- **MCP Server**: `https://honkpost.com/api/mcp`
- **Full Reference**: `https://honkpost.com/llms-full.txt`
- **OpenAPI 3.1 Spec**: `https://honkpost.com/openapi.json`
- **Agents Guide**: `https://honkpost.com/agents`
- **Scheduler**: `https://honkpost.com/scheduler`