bluesky-mcp

bluesky-mcp is Kai's authenticated, strictly read-only Bluesky MCP. It uses the official AT Protocol SDK to create and refresh an internal app-password session, and the official MCP SDK streamable-HTTP transport to serve a small, reviewed tool surface.

Transport and configuration

The process serves GET /healthz and MCP streamable HTTP at POST /mcp. Defaults are HOST=0.0.0.0 and PORT=9113. Set these runtime variables:

• BSKY_APP_PASSWORD (required): app password supplied only at runtime.
• BSKY_HANDLE (optional): authenticated account handle; defaults to coilysiren.me.
• MCP_ALLOWED_HOSTS (optional): comma-separated hosts accepted by the MCP transport's DNS-rebinding defense. It defaults to local development hosts.

Run locally with an app password supplied out of band:

ward install
BSKY_APP_PASSWORD=... ward run

Exact tool inventory

1. get_profile
2. search_profiles
3. search_posts
4. get_author_feed
5. get_posts
6. get_post_thread
7. list_followers
8. list_follows
9. get_home_timeline
10. list_notifications
11. get_kai_liked_posts

All page sizes are bounded to 50 or below. Post batches are capped at 25 and thread depth plus parent height at 6.

Threat model

The configured app password can authorize account writes, so the adapter must never expose that authority. It has no post, reply, follow, like, repost, delete, mute, block, report, moderation, chat, account mutation, login, generic URL, arbitrary XRPC, or raw HTTP tool. Inputs accept only bounded, validated actors, post AT URIs, cursors, queries, and limits. The app password and session tokens remain in process memory and credential-shaped result fields are stripped before an MCP response is created. SDK failures are deliberately logged without their values.

The source image runs as the non-root node user. Deployment access control, secret injection, and network exposure are intentionally outside this source repository.

Development

ward lint, ward typecheck, ward test, ward audit, and ward precommit are the supported validation verbs. A main-branch workflow tests and publishes the private image forgejo.coilysiren.me/coilyco-flight-deck/bluesky-mcp:<full-source-sha>. Deployment uses a separate read-only forgejo-registry pull credential.

See AGENTS.md and docs/FEATURES.md.