# Ariel — Bluesky MCP Server

Ariel is an [MCP](https://modelcontextprotocol.io/) (Model Context Protocol) server that exposes AT Protocol (Bluesky) operations as tools. It enables AI assistants to read, write, and interact on Bluesky with human-in-the-loop control — nothing posts without explicit action.

## Installation

```bash
npm install -g @ticktockbent/ariel
```

Or run directly with npx:

```bash
npx @ticktockbent/ariel
```

Or build from source:

```bash
git clone https://github.com/TickTockBent/ariel.git
cd ariel
npm install
npm run build
```

## Configuration

### Environment Variables

| Variable | Required | Description |
|---|---|---|
| `BLUESKY_IDENTIFIER` | Yes | Your Bluesky handle or email |
| `BLUESKY_APP_PASSWORD` | Yes | A Bluesky [app password](https://bsky.app/settings/app-passwords) |
| `BLUESKY_SERVICE_URL` | No | PDS URL (default: `https://bsky.social`) |
| `ARIEL_DATA_DIR` | No | Session storage directory (default: `~/.ariel/`) |

### MCP Client Configuration

Add to your MCP client config (e.g. `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "ariel": {
      "command": "npx",
      "args": ["-y", "@ticktockbent/ariel"],
      "env": {
        "BLUESKY_IDENTIFIER": "your.handle.bsky.social",
        "BLUESKY_APP_PASSWORD": "your-app-password"
      }
    }
  }
}
```

## Tools

Ariel exposes 33 tools across six categories.

### Authentication
- `ariel_auth_status` — Check auth state, handle, DID, and rate limits
- `ariel_auth_logout` — Log out and clear stored session

### Reading
- `ariel_get_timeline` — Home timeline
- `ariel_get_author_feed` — A user's posts
- `ariel_get_post_thread` — Post with thread context
- `ariel_get_posts` — Multiple posts by AT URI (max 25)
- `ariel_get_profile` — User profile
- `ariel_get_feed` — Custom feed generator posts
- `ariel_search_posts` — Search posts
- `ariel_search_users` — Search users
- `ariel_get_trends` — Trending topics
- `ariel_get_saved_feeds` — Your saved/pinned feeds
- `ariel_get_list` — List metadata and members
- `ariel_get_list_feed` — Posts from a list feed
- `ariel_resolve_url` — Convert bsky.app URL to AT URI

### Writing
- `ariel_create_post` — Create a post with auto-detected mentions/links/hashtags
- `ariel_create_thread` — Create a multi-post thread
- `ariel_reply` — Reply to a post (auto-resolves thread root)
- `ariel_quote_post` — Quote-post another post
- `ariel_delete_post` — Delete your post

### Media
- `ariel_upload_image` — Upload an image blob
- `ariel_create_post_with_images` — Post with images (max 4)
- `ariel_create_post_with_link_card` — Post with Open Graph link card

### Social
- `ariel_follow` / `ariel_unfollow` — Follow/unfollow users
- `ariel_get_followers` / `ariel_get_follows` — View follower/following lists
- `ariel_like` / `ariel_unlike` — Like/unlike posts
- `ariel_repost` / `ariel_unrepost` — Repost/remove reposts
- `ariel_mute` / `ariel_unmute` — Mute/unmute users
- `ariel_block` / `ariel_unblock` — Block/unblock users

### Notifications
- `ariel_get_notifications` — Recent notifications
- `ariel_get_unread_count` — Unread notification count
- `ariel_mark_notifications_read` — Mark all notifications as read

## Resources

Ariel provides three MCP resources with reference material that clients can pull into context:

- **`ariel://at-protocol-concepts`** — DIDs, handles, AT URIs, facets, embeds, and viewer state
- **`ariel://tool-conventions`** — URL acceptance, error format, the `format` parameter, and viewer state auto-resolution
- **`ariel://post-schema`** — Post record structure, embed types, facet format, and thread mechanics

## Prompts

Three built-in prompts for common workflows:

- **`summarize-timeline`** — Fetch your home timeline and produce a thematic summary
- **`draft-thread`** — Research a topic and draft a thread for review before posting
- **`review-notifications`** — Review recent notifications and suggest responses

## Development

```bash
npm run dev          # Watch mode TypeScript compilation
npm test             # Run tests
npm run build        # Production build
npm start            # Run the server
```

See [CONTRIBUTING.md](CONTRIBUTING.md) for development guidelines.

## License

[MIT](LICENSE)