# Publer Gateway MCP

**One safe MCP doorway into every Publer workspace you manage.**

Publer Gateway MCP is a TypeScript MCP server for teams, agencies, and solo builders who use Publer across more than one brand, business, client, or social account set. It gives Codex, Claude, and other MCP clients a careful way to discover Publer workspaces, map projects to the right account defaults, preview scheduling payloads, and only perform live writes after explicit approval.

It is built for the work that happens before the post goes out: choosing the right workspace, checking the right accounts, preparing platform-aware payloads, reviewing the dry run, and keeping secrets out of the repo.

## Why This Exists

Most social scheduling automations assume one account, one workspace, one happy path. Real Publer usage is messier:

- one API key may see multiple businesses or workspaces
- one repo may map to a specific client, brand, or product
- posts need preview and approval before a scheduling write
- agents need guardrails so they do not publish to the wrong account
- API keys must stay local, server-side, and out of chat transcripts

Publer Gateway MCP turns that into a safer workflow.

```mermaid
flowchart LR
  A["Codex / Claude / MCP client"] --> B["Publer Gateway MCP"]
  B --> C["Local secret env<br/>PUBLER_API_KEY"]
  B --> D["Local non-secret defaults<br/>project -> workspace/accounts"]
  B --> E["Publer API"]
  E --> F["Workspaces"]
  E --> G["Accounts"]
  E --> H["Posts, media, jobs, analytics"]
```

## What You Get

- Workspace-aware Publer access from a single MCP server.
- Project defaults stored locally outside app repos by default.
- Read tools for workspaces, accounts, posts, jobs, best times, and analytics.
- Write-capable tools that preview first and require `dryRun: false` plus `confirm: true`.
- Reusable Codex/agent skills for safe Publer workflows.
- Mocked tests, MIT license, security notes, examples, and CI.

## Safety Model

Publer Gateway MCP is intentionally conservative.

| Area | Default behavior |
| --- | --- |
| API keys | Read from local environment only. Never stored in project defaults. |
| Project defaults | Store workspace/account IDs only. No secrets. |
| Read tools | May call Publer directly. |
| Write tools | Return previews unless the call explicitly sets `dryRun: false` and `confirm: true`. |
| Media URL previews | Redact full URL; show host only to avoid leaking signed URLs. |
| Errors | Return safe status/message without API keys or raw auth headers. |

## Tool Surface

| Tool | Purpose | Write risk |
| --- | --- | --- |
| `publer_list_workspaces` | List available Publer businesses/workspaces. | Read |
| `publer_list_accounts` | List connected social accounts in a workspace. | Read |
| `publer_get_project_default` | Read local project routing defaults. | Local read |
| `publer_set_project_default` | Set local workspace/account defaults for a project. | Local write |
| `publer_preview_schedule_post` | Build a Publer schedule payload without calling Publer writes. | Preview |
| `publer_schedule_post` | Schedule a post only with explicit live-write confirmation. | Publer write |
| `publer_list_posts` | List scheduled, draft, failed, or published posts. | Read |
| `publer_upload_media_from_url` | Import media from a URL, preview-first. | Publer write |
| `publer_get_job_status` | Poll async Publer jobs. | Read |
| `publer_get_best_times` | Retrieve best-time suggestions for an account. | Read |
| `publer_get_analytics` | Retrieve analytics charts or post insights. | Read |

## Install

```bash
npm install
npm run build
npm test
```

Run the MCP server with your MCP client. Set `PUBLER_API_KEY` through the client environment, a local process manager, or a trusted secret manager. Avoid putting real keys directly in shell commands that may be saved to history.

## Configuration

| Name | Required | Default | Description |
| --- | --- | --- | --- |
| `PUBLER_API_KEY` | yes | none | Publer API key from your local Publer account settings. |
| `PUBLER_BASE_URL` | no | `https://app.publer.com/api/v1` | Override for testing or future API changes. |
| `PUBLER_DEFAULT_DRY_RUN` | no | `true` | Keeps write-capable tools in preview mode by default. Live writes still require call-level `dryRun: false`. |
| `PUBLER_DEFAULTS_PATH` | no | OS config folder | Path for non-secret project default mappings. |

## MCP Client Examples

### Codex

```json
{
  "mcpServers": {
    "publer-gateway": {
      "command": "node",
      "args": ["/absolute/path/to/publer-gateway-mcp/dist/src/index.js"],
      "env": {
        "PUBLER_API_KEY": "set-this-locally",
        "PUBLER_DEFAULT_DRY_RUN": "true"
      }
    }
  }
}
```

### Claude Desktop

```json
{
  "mcpServers": {
    "publer-gateway": {
      "command": "node",
      "args": ["/absolute/path/to/publer-gateway-mcp/dist/src/index.js"],
      "env": {
        "PUBLER_API_KEY": "set-this-locally",
        "PUBLER_DEFAULT_DRY_RUN": "true"
      }
    }
  }
}
```

## Recommended Workflow

1. Call `publer_list_workspaces`.
2. Pick the correct business/workspace.
3. Call `publer_list_accounts` for that workspace.
4. Call `publer_set_project_default` with the project path, workspace ID, and target account IDs.
5. Call `publer_preview_schedule_post`.
6. Review workspace, accounts, schedule, copy, media, and platform payload.
7. Only after explicit approval, call `publer_schedule_post` with `dryRun: false` and `confirm: true`.
8. Poll `publer_get_job_status` if Publer returns a job ID.

## Included Agent Skills

The `skills/` folder is part of the product, not an afterthought. These skills teach future agents how to use the MCP without drifting into unsafe publishing behavior.

| Skill | Use it for |
| --- | --- |
| `publer-gateway` | General safe use of the MCP server. |
| `publer-social-scheduler` | Preparing, previewing, and scheduling approved social content. |
| `publer-workspace-router` | Mapping projects, repos, clients, and brands to Publer workspace/account defaults. |
| `publer-analytics-reviewer` | Retrieving and interpreting Publer analytics and best-time suggestions. |

Copy these folders into a compatible Codex skill directory or package them with your own agent setup.

## Example Preview Call

```json
{
  "projectPath": "/work/acme-launch",
  "text": "Launch week starts now. See what shipped today.",
  "scheduledAt": "2026-07-14T15:00:00Z"
}
```

The preview tool returns the exact Publer payload it would send. The live scheduling tool will not call Publer unless the caller adds:

```json
{
  "dryRun": false,
  "confirm": true
}
```

## Development

```bash
npm install
npm run build
npm test
npm pack --dry-run
```

Tests use mocked Publer responses and do not call real Publer endpoints.

## Project Plan

See [docs/PROJECT_PLAN.md](docs/PROJECT_PLAN.md) for the v1 milestone breakdown and acceptance criteria.

## Security

See [SECURITY.md](SECURITY.md). The short version: do not paste Publer secrets into chat, do not commit `.env`, and do not grant live write approval until the exact payload is reviewed.

## License

MIT. Use it, fork it, improve it, and ship safer social automation.