Getting started with OpenPub

#Installation & Setup

Build the CLI from a clone of this repository (Node 20+):

git clone https://github.com/princepal9120/openpub.git
cd openpub
npm install && npm run cli:build

Run commands with node apps/cli/dist/index.js <command>, or run npm link --workspace openpub-cli once to make the openpub binary available globally in your PATH.

Initialize the local OpenPub configuration:

node apps/cli/dist/index.js init

openpub init creates ~/.openpub and prints the next setup command. Platform credentials are saved to ~/.openpub/config.json with restrictive permissions (0600) and are only sent directly to target platform APIs when publishing.

#Command Reference Matrix

#Command Examples

Publish a post to dev.to and Hashnode:

node apps/cli/dist/index.js publish my-article.md --to devto,hashnode --status draft

Check configured platforms status:

node apps/cli/dist/index.js status

#Markdown Frontmatter Specification

Specify target platforms, canonical URLs, and tags directly inside your Markdown frontmatter:

---
title: "Shipping Edge Workers on Cloudflare"
canonical: "https://myblog.com/posts/shipping-edge-workers"
cover_image: "https://<worker>/covers/<uuid>.png"
platforms:
  - devto
  - hashnode
  - ghost
  - wordpress
tags:
  - typescript
  - cloudflare
  - webdev
status: draft
---

## Introduction

Your article content starts here in standard Markdown...

#Local stdio vs Streamable HTTP

OpenPub ships a local stdio MCP server for direct integration with Claude Code, Cursor, Codex, and VS Code without requiring a Cloudflare deployment. When self-hosting on Cloudflare, OpenPub additionally exposes a Model Context Protocol endpoint over Streamable HTTP at POST /mcp, protected by your ADMIN_KEY secret.

#Build Local stdio Server from Repo

Build the local stdio MCP server from a clone of this repository (Node 20+):

git clone https://github.com/princepal9120/openpub.git
cd openpub/apps/mcp
npm install && npm run build

#Available MCP Tools

OpenPub defines tool sets tailored to each transport: 10 local tools for stdio clients and 13 remote tools for Cloudflare Worker clients.

Local stdio MCP Tools (10 Tools · apps/mcp/handlers.ts)

Transport: stdio. Operates directly on local markdown files, ~/.openpub/config.json, and ~/.openpub/state.json.

Remote Worker MCP Tools (13 Tools · src/mcp.ts)

Transport: Streamable HTTP (POST /mcp). Requires ADMIN_KEY authentication. Worker publish tools publish live immediately; save_draft only creates a draft. Operates on Cloudflare D1, R2, Queues, and Workers AI.

#Claude Code Configuration

For local stdio mode, add to .mcp.json in your project:

{
  "mcpServers": {
    "openpub": {
      "command": "node",
      "args": ["/absolute/path/to/openpub/apps/mcp/dist/index.js"]
    }
  }
}

Or connect to your self-hosted Cloudflare Worker over HTTP:

claude mcp add --transport http openpub \
  https://openpub.<subdomain>.workers.dev/mcp \
  --header "Authorization: Bearer <ADMIN_KEY>"

#Cursor & VS Code Configuration

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "openpub": {
      "command": "node",
      "args": ["/absolute/path/to/openpub/apps/mcp/dist/index.js"]
    }
  }
}

For VS Code GitHub Copilot, use .vscode/mcp.json with a "servers" key. For remote HTTP worker access, replace command/args with "url": "https://openpub.<subdomain>.workers.dev/mcp" and headers.

#Windsurf & Codex Configuration

Add to mcp_config.json in Windsurf:

{
  "mcpServers": {
    "openpub": {
      "command": "node",
      "args": ["/absolute/path/to/openpub/apps/mcp/dist/index.js"]
    }
  }
}

For Codex CLI, add [mcp_servers.openpub] with command = "node" and args = ["/absolute/path/to/openpub/apps/mcp/dist/index.js"] in ~/.codex/config.toml.

#Generic HTTP / curl Verification

BASE=https://openpub.<subdomain>.workers.dev
KEY=<ADMIN_KEY>

# Call tools/list
curl -X POST $BASE/mcp \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}'

#Typical First Agent Session

Remote MCP cannot read local files. Include article text in your prompt. Worker publishing sends posts live immediately; use the local CLI or stdio MCP when you need draft-first publishing.

#Troubleshooting Guide

#Not released yet

For now, build the CLI from source and run a dry run before publishing. Keep credentials in repository secrets if you invoke the CLI from your own CI workflow.

#Storing and Testing Credentials

Store Worker credentials via REST API using POST /api/platforms/:name. The local CLI stores credentials separately in ~/.openpub/config.json and does not configure the Worker:

# Via REST API:
curl -X POST \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"api_key": "your-devto-key"}' \
  https://<worker>/api/platforms/devto

# Test connectivity:
curl -X POST -H "Authorization: Bearer $ADMIN_KEY" \
  https://<worker>/api/platforms/devto/test
# {"ok":true}

#Quick Reference Matrix

#dev.to (devto)

Scope: read and write articles. Go to dev.to -> Settings -> Extensions -> DEV Community API Keys. Create a key named openpub and paste into credentials:

{
  "api_key": "xxxxxxxxxxxxxxxxxxxxxxxx"
}

#Hashnode (hashnode)

Go to hashnode.com -> Account Settings -> Developer Settings -> Personal Access Tokens:

{
  "token": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "publication_id": "65f1a2b3c4d5e6f7a8b9c0d1"
}

#WordPress (wordpress)

Go to WP Admin -> Users -> Profile -> Application Passwords. Generate an application password:

{
  "site_url": "https://yourblog.com",
  "username": "your-wp-username",
  "app_password": "xxxx xxxx xxxx xxxx xxxx xxxx"
}

#Ghost (ghost)

Go to Ghost Admin -> Settings -> Integrations -> Add custom integration. Copy the Admin API Key (format <id>:<secret>):

{
  "site_url": "https://yourblog.ghost.io",
  "admin_key": "64f1a2b3c4d5e6f7a8b9c0d1:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}

#Medium (medium)

Integration tokens available from medium.com/me/settings -> Security and apps:

{
  "integration_token": "2a1b3c4d5e6f..."
}

#Substack (substack)

Copy connect.sid from browser DevTools Cookies on your publication domain:

{
  "publication_url": "https://yourpub.substack.com",
  "connect_sid": "s%3Axxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

#GitHub Pages (github-pages)

Directly commits Markdown files into your static site repository (Astro, Hugo, Jekyll, Next.js, mdBook):

{
  "token": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "repo": "youruser/yourblog",
  "dir": "content/posts",
  "branch": "main"
}

#X Articles (x)

Publishes articles via the X Articles API v2. Requires an account with active X Premium:

{
  "access_token": "xxxxxxxxxxxxxxxxxxxxxxxx"
}

#System Diagram

                          +---------------------------------------------+
  MCP clients ----------->|   Cloudflare Worker (Hono)                  |
  (Claude Code, Cursor)   |                                             |
  Dashboard ------------->|   /api/*   REST    /mcp   JSON-RPC          |
                          +------+-+------------------+-+---------------+
                                 | |                  | |
                    +------------v-+ |      +---------v-+-+
                    |  D1            |      |  Queue      |
                    |  drafts, creds,|      |  openpub-  |
                    |  publish_log   |      |  publish    |
                    +------------+-+-+      +---------+-+-+
                               | |                 | | consumer (retry x3)
                               | |                 | v
                               | |        +--------+-------+
                               | |        | Platform       |---> dev.to API
                               | |        | adapters       |---> Hashnode GraphQL
                               | |        |                |---> WP REST
                               | |        |                |---> Ghost Admin API
                               | |        |                |---> Medium API
                               | |        |                |---> Substack drafts
                               | |        |                |---> GitHub Contents API
                               | |        |                |---> X Articles API
                               | |        +--------+-------+
                               | |                 | canonical URL of first
                               | +-----------------+ success feeds the rest
                               v
        KV: KEYS (unused)  R2: MEDIA (cover images)  Workers AI: FLUX schnell

#Core Edge Components

#Publish Lifecycle & Canonical Injection

1. Draft Creation: Content is submitted through the dashboard or remote MCP API with title, tags, and target platforms. Worker tag parsing accepts inline tags: [a, b] only (max 6); YAML block-list tags are ignored. The local CLI and stdio MCP publish directly to platform APIs instead of this Worker.
2. Queue Dispatch: Individual queue messages are enqueued for each platform adapter.
3. First-Success Canonical Wiring: The first platform that successfully creates a public post sets the post URL as the article canonical URL.
4. Cross-Post Attribution: Subsequent platform publications automatically include that canonical tag, preserving your original search engine ranking equity.

#Idempotent Republishing

The local CLI hashes content in ~/.openpub/state.json; unchanged posts are skipped, and supported platforms update in place when remote IDs exist. X Articles, Substack, and Medium cannot be updated by the CLI. The Worker uses a separate queue: platforms already marked successful are skipped rather than updated.

#REST API Reference