freepost
by Youhai020616
README.md
# Freepost for agents
Use Freepost from Claude Code, Codex, Cursor, or your terminal. The package talks to your Freepost workspace and can work with social accounts you already connected in **Freepost → Accounts**.
## Install
After the npm release, use Node.js 20 or newer and run:
```sh
npx freepost setup
```
Create a workspace API key in **Freepost → Settings → API keys** and enter it at the hidden prompt. Setup checks the key against Freepost, stores it in `~/.config/freepost/credentials` with mode `0600` on Unix, registers MCP, and installs the bundled skill. Restart the agent after setup. Re-running setup preserves other server entries and skips its existing configuration and identical skill files. On a clean machine with no detected clients, setup configures all three.
```sh
npx freepost setup --dry-run
npx freepost setup --only claude,codex,cursor --yes
npx freepost login
npx freepost doctor
```
For non-interactive setup, supply `FREEPOST_API_KEY` through your environment or secrets manager, use a stored key, or pass `--key`. Prefer the environment over `--key` when shell history or process arguments are visible. The key stays out of the MCP configurations. The CLI and stdio server prefer `FREEPOST_API_KEY` over the stored key. Set `FREEPOST_API_URL` (or `FREEPOST_BASE_URL`) to an HTTPS service base URL or an HTTP loopback base URL for local testing. The default is `https://freepost.io`.
Doctor checks authenticated MCP initialization and reports both CLI and server versions. It reports `null` for the key's scopes and plan, which the current server does not disclose on initialization. Review them in Freepost Settings.
### Claude Code
```sh
npx freepost setup --only claude
```
Setup runs `claude mcp add freepost -s user -- npx -y freepost mcp` when the Claude CLI is on PATH. The fallback writes the user MCP entry in `~/.claude.json`. The skill installs to `~/.claude/skills/freepost`. With `CLAUDE_CONFIG_DIR` set, setup uses that directory for the user config and skill.
### Codex
```sh
npx freepost setup --only codex
```
Setup uses `~/.codex/config.toml` (or `$CODEX_HOME/config.toml`) and installs the skill to `~/.agents/skills/freepost`. To configure MCP manually after `npx freepost login`, add:
```toml
[mcp_servers.freepost]
command = "npx"
args = ["-y", "freepost", "mcp"]
env_vars = ["FREEPOST_API_KEY", "FREEPOST_API_URL", "FREEPOST_BASE_URL"]
```
### Cursor
```sh
npx freepost setup --only cursor
```
Setup registers the server in `~/.cursor/mcp.json` and installs the skill to `~/.cursor/skills/freepost`. To configure MCP manually after `npx freepost login`, merge this entry into your existing config:
```json
{
"mcpServers": {
"freepost": {
"command": "npx",
"args": ["-y", "freepost", "mcp"]
}
}
}
```
### Skill-only installation
Once the standalone source repository is public, install the [Freepost skill](skills/freepost/SKILL.md) through the skills CLI:
```sh
npx skills add Youhai020616/freepost-agent
```
The skill works with the local stdio server or a direct connection to [Freepost remote MCP](https://freepost.io/api/mcp) using Streamable HTTP and OAuth. See the bundled [Claude Code](skills/freepost/examples/claude-code.md), [Codex](skills/freepost/examples/codex.md), and [MCP-only](skills/freepost/examples/mcp-only.md) examples.
## Use the CLI
```sh
npx freepost --help
npx freepost accounts
npx freepost rules xiaohongshu
npx freepost posts --status draft --limit 10
npx freepost upload ./cover.png
npx freepost validate @draft.json
npx freepost draft @draft-with-idempotency-key.json
npx freepost post <post-id>
```
`draft`, `validate`, and `update` accept an inline JSON object, `@FILE`, or `-` for stdin. See the [Freepost API contract](https://freepost.io/api/v1/openapi.json) for input fields. For example, a draft's JSON can include `content`, `targetAccounts` (Freepost account IDs), optional `title` and `mediaIds`, and an `idempotencyKey` you retain for retries.
Ask the user to approve the exact content, destination, and time before publishing or scheduling. The bundled stdio tools require `confirmed: true`, and the CLI requires `--confirmed`. Freepost enforces `publish:write` for publishing and `schedules:write` for scheduling. Select those scopes when creating a key that needs them.
```sh
npx freepost publish <post-id> --idempotency-key <publish-key> --confirmed
npx freepost schedule <post-id> 2099-07-02T09:00:00+08:00 --idempotency-key <schedule-key> --confirmed
npx freepost publication <delivery-id>
```
Reuse the same idempotency key for the same request after a lost response. Check a pending or unknown delivery with `publication` before taking further action.
## MCP tools
`freepost mcp` discovers the service's tool and resource schemas over Streamable HTTP. These are the tools implemented by the Freepost remote MCP API at this release:
| Tools | CLI |
| --- | --- |
| `accounts_list`, `usage_get`, `platforms_rules` | `accounts`, `usage`, `rules` |
| `media_upload` | `upload` accepts a local file or a public URL |
| `posts_validate`, `posts_create`, `posts_update`, `posts_delete` | `validate`, `draft`, `update`, `delete` |
| `posts_get`, `publications_get` | `post`, `publication` |
| `posts_publish`, `posts_schedule`, `schedules_cancel` | `publish`, `schedule`, `cancel` |
The CLI's `posts` and `media` list commands use the corresponding REST endpoints. The upload tool takes a URL or base64 bytes, and the CLI can encode a local file for it. Analytics is outside the current remote MCP tool surface. Draft text comes from the user's agent.
## Build and test
From a Freepost monorepo checkout:
```sh
pnpm install --frozen-lockfile
pnpm --filter ./packages/freepost-agent build
pnpm --filter ./packages/freepost-agent test
pnpm platform-rules:check
node packages/freepost-agent/dist/cli.js --help
```
From a standalone source checkout, use `npm install`, `npm test`, and `npm run build`. The monorepo generates the bundled platform files from the platform skills and shared content rules. Change those upstream sources and regenerate before exporting a new version.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues