npm package: @archy-ai/blog-post-mcp
Description: Minimal MCP server that exposes tools to: - summarize the current git workspace changes - create/update/publish blog posts - trigger featured image / featured video generation via the existing Archy admin API
Latest version: 0.0.3

# Blog Post MCP (Archy)

Minimal MCP server that exposes tools to:
- summarize the current git workspace changes
- create/update/publish blog posts
- trigger featured image / featured video generation via the existing Archy admin API

## Env vars

- `ARCHY_BLOG_BASE_URL` (default: `http://localhost:4280`)
- `ARCHY_PUBLISHER_KEY` (recommended; per-user key sent as `x-archy-publisher-key`)
- `ARCHY_INTEGRATIONS_API_KEY` (legacy/shared integration key; sent as Bearer or `x-archy-api-key`)
- `ARCHY_API_KEY_HEADER` (optional: `authorization`, `x-archy-api-key`, or `x-archy-publisher-key`; default: `authorization`)

### Auth notes

- In your API, server-to-server auth is controlled by `INTEGRATIONS_API_KEY` + `INTEGRATIONS_API_ROLES`.
	- Publishing and AI image/video require `admin` role.
	- Draft creation can work with `writer` role.
- For local development you can bypass auth entirely by setting `LOCAL_DEV_ADMIN_BYPASS=true` in the API environment.

## Run

### Standalone (recommended)

After publishing this package, you can run it without cloning `meet.archy-ai.com`:

```bash
ARCHY_BLOG_BASE_URL=https://meet.archy-ai.com \
ARCHY_INTEGRATIONS_API_KEY=... \
npx -y @archy-ai/blog-post-mcp
```

Notes:
- The `archy_workspace_summary` tool is optional; it will only be useful when run in a folder that is a git repo.

#### CLI flags (no env vars)

The published binary also supports flags that populate env vars internally (useful for VS Code MCP configs):

```bash
npx -y @archy-ai/blog-post-mcp \
	--base https://meet.archy-ai.com \
	--header x-archy-publisher-key \
	--publisher-key pk_...
	--timeout-ms 120000 \
	--debug
```

Notes:
- `--debug` logs **only** to stderr (stdout stays clean for MCP protocol).
- `--timeout-ms` controls how long the MCP waits for API responses before aborting (useful when image/video prompts are complex).

### From source

```bash
cd meet.archy-ai.com/tools/blog-post-mcp
npm install
ARCHY_BLOG_BASE_URL=http://localhost:4280 \
ARCHY_INTEGRATIONS_API_KEY=... \
node ./index.mjs
```

You can also pass flags when running from source:

```bash
node ./index.mjs \
	--base http://localhost:7072 \
	--header x-archy-publisher-key \
	--publisher-key pk_...
```

## Smoke test (recommended)

Use this when you want a **repeatable**, **one-command** verification that:
- VS Code can spawn the MCP server (stdio)
- the full toolchain works end-to-end
- the backing local SWA dev server is reachable (`ARCHY_BLOG_BASE_URL`)

### What it does

The smoke script runs **only** via MCP tool calls (not `curl`):
1. `archy_blog_create_draft` (creates a dev-only draft)
2. `archy_blog_ai_draft` (fills body + SEO)
3. `archy_blog_ai_image` (generates a featured image)
4. `archy_blog_attach_feature_image`
5. `archy_blog_ai_video` (starts a featured video job conditioned on the image)
6. `archy_blog_ai_video_status` (polls until succeeded/failed)
7. `archy_blog_attach_feature_video`
8. `archy_blog_publish`

### Prereqs

- Start your local SWA stack so `http://localhost:4280` is serving:
	- `npm run swa:dev` (from `meet.archy-ai.com`)
- Auth:
	- Local dev: set `LOCAL_DEV_ADMIN_BYPASS=true` in the API environment (recommended), OR
	- Provide `ARCHY_INTEGRATIONS_API_KEY` / `INTEGRATIONS_API_KEY` so the admin endpoints authorize.

### Run

From `meet.archy-ai.com`:

```bash
npm run mcp:blog:smoke
```

Optional flags:

```bash
node ./scripts/archy-blog-mcp-smoke.mjs \
	--base http://localhost:4280 \
	--title "MCP Smoke Test (manual title)" \
	--video-polls 30 \
	--video-poll-ms 5000
```

### Expected result

On success, it prints a single JSON object like:

```json
{
	"ok": true,
	"baseUrl": "http://localhost:4280",
	"post": {
		"id": "...",
		"slug": "...",
		"status": "published",
		"publishedAt": "..."
	},
	"featureImage": { "assetId": "...", "url": "..." },
	"featureVideo": { "requestId": "...", "assetId": "...", "url": "..." }
}
```

If it fails, it exits non-zero and prints an error with context.

## Agentic composer

These tools help an agent compose a validated TipTap/ProseMirror `doc` body from a safe “blocks” spec, then write it to a post.

### Tools

- `archy_blog_get_post`: fetch a post by id
- `archy_blog_compose_doc`: convert blocks → TipTap `doc` JSON (no network)
- `archy_blog_set_body_from_blocks`: replace the post body with blocks
- `archy_blog_append_blocks`: append blocks to an existing TipTap `doc`

### Block format (overview)

Each block is an object with a `type`.

Supported `type` values:

- `heading` (attrs: `level` 1-3; content from `text` or `inlines`)
- `paragraph` (content from `text` or `inlines`)
- `quote` (`paragraphs: string[]`)
- `bulletList`, `orderedList` (`items: string[]`)
- `image` (`src`, optional `alt`)
- `video` (`src`)
- `embed` (`url`, optional `provider`)
- `slider` (`items: [{ src, alt?, assetId? }]`)
- `card`
- `cardSet` (`cards: [...]`)
- `cta`

Inline rich text is supported in `heading` and `paragraph` via:

`inlines: [{ text, bold?, italic?, href? }]` where `href` must be `http(s)://...` or a site-relative path like `/pricing`.