# WordPress Blog MCP

A small, purpose-built Model Context Protocol (MCP) service for a review-first WordPress blogging workflow.

The project exists to let an AI assistant inspect a WordPress blog, reuse existing public media, prepare drafts, manage a deliberately small taxonomy surface, and publish only after explicit human approval. It is intentionally **not** a general WordPress administration bridge.

## Status

Early foundation work. No WordPress write capability is implemented yet.

## Goals

- Inspect the WordPress site capabilities relevant to blogging.
- Read existing categories, tags, posts, and media-library metadata.
- Search and reuse existing media instead of uploading duplicates unnecessarily.
- Create and update **draft** posts through a narrow, auditable interface.
- Support controlled media upload and featured-image assignment when reuse is not appropriate.
- Create a category or tag only through an explicit operation; editorial policy should prefer existing taxonomy.
- Publish only an already-reviewed WordPress draft through a dedicated publication operation.
- Preserve the site's intended human/public WordPress author independently from the technical account used to authenticate the MCP integration.

## Non-goals

V0 does not expose generic WordPress administration. In particular, it must not provide:

- arbitrary WordPress REST calls;
- WP-CLI or shell execution;
- database queries;
- plugin or theme management;
- user management;
- site settings management;
- delete operations for posts, media, categories, or tags.

If a future requirement needs one of these capabilities, it requires an explicit architecture/security decision rather than being added as a convenience escape hatch.

## Planned V0 tool surface

The exact schemas will be hardened before implementation, but the intended boundary is approximately:

### Read

- site/blog capability inspection;
- list/search categories and tags;
- search/get posts;
- search/get media metadata and usable image URLs.

### Write

- create a draft;
- update an existing draft;
- upload media through a bounded interface;
- assign existing media as a featured image;
- explicitly create a category or tag;
- publish an existing reviewed draft.

Published-post editing and destructive operations are outside the initial boundary.

## Review-first workflow

```text
idea / sources
    -> research outside this service
    -> article + taxonomy + media proposal
    -> human content review
    -> create/update WordPress draft
    -> inspect real WordPress preview
    -> explicit human publication approval
    -> publish the existing draft
```

Research is intentionally outside this MCP server. GitHub, the public web, Wayfarer, photo sources, and other future research integrations remain separate concerns. This service owns only the constrained WordPress content boundary.

## WordPress identities and authorship

The WordPress account used to authenticate the MCP does not have to be the public author of the posts it creates.

For sites where the human/public author is also a WordPress Administrator, the recommended model is:

```text
human/public WordPress user (may be Administrator)
        ^
        | fixed WORDPRESS_AUTHOR_ID
        |
technical least-privilege integration user
        |
        | Application Password
        v
WordPress Blog MCP
```

The technical account exists only for API authentication. When `WORDPRESS_AUTHOR_ID` is configured, MCP-created posts are attributed to that fixed WordPress author ID. The author is server configuration, not a per-call MCP argument, so an agent cannot select or impersonate arbitrary WordPress users.

Do not attach the MCP Application Password to an Administrator account merely to preserve the correct public author metadata.

## Security model

The security goal is least privilege and a small blast radius.

- Use a dedicated WordPress integration identity with only the capabilities required for the delivered blogging workflow.
- Use a WordPress Application Password rather than the user's normal login password.
- Keep the technical authentication identity separate from the public author when that avoids granting the MCP Administrator credentials.
- Keep credentials in runtime configuration; never commit them.
- Require HTTPS for non-local WordPress connections.
- Do not expose a generic REST passthrough.
- Do not make deletion available through MCP.
- Keep publication separate from draft creation/update so review remains meaningful.
- Treat remote MCP deployment/authentication as a security boundary of its own; do not expose an unauthenticated MCP endpoint to the internet.

See [architecture](docs/architecture.md) and [security policy](SECURITY.md).

## Development

The project uses Python, `uv`, the official MCP Python SDK v2, `ruff`, and `pytest`.

```bash
uv sync
uv run ruff format --check .
uv run ruff check .
uv run pytest
```

Run the development server over stdio:

```bash
uv run wordpress-blog-mcp
```

The initial package deliberately exposes no WordPress tools yet. Product behavior will be added through bounded issues after the contracts and security checks are explicit.

## Documentation

- [Architecture](docs/architecture.md)
- [Roadmap](docs/roadmap.md)
- [Security policy](SECURITY.md)

## License

MIT. See [LICENSE](LICENSE).