# Agents

This is a starter kit for building apps on the Atmosphere with Quickslice.

## Project Structure

- `index.html` - Main frontend with OAuth login flow
- `docker-compose.yml` - Quickslice server configuration
- `lexicons/` - AT Protocol lexicon schemas
- `favicon.svg` - Slices logo

## Key Technologies

- **Quickslice** - Backend server for AT Protocol apps
- **AT Protocol** - Decentralized social protocol (Bluesky)
- **OAuth** - Authentication via Bluesky accounts
- **Web Components** - `<qs-actor-autocomplete>` for handle input

## Configuration

In `index.html`:
- `SERVER_URL` - Quickslice server (default: `http://127.0.0.1:8080`)
- `CLIENT_ID` - OAuth client ID from Quickslice settings

## Development

```bash
docker compose up        # Start Quickslice server
make serve               # Serve frontend
make format              # Format HTML with Prettier
make zip                 # Create lexicons.zip
```

## MCP Server

Quickslice exposes an MCP server at `http://127.0.0.1:8080/mcp`. Add it to your AI assistant:

```bash
claude mcp add --scope user quickslice http://127.0.0.1:8080/mcp
```

Use MCP tools to:
- Query the GraphQL API
- Explore available lexicon schemas
- Generate GraphQL queries/mutations
- Understand record structures

## Lexicons

Custom lexicons go in `/lexicons` following AT Protocol naming conventions (e.g., `com/example/myrecord.json`). Run `make zip` and upload via the Quickslice settings page.

See the [Lexicon Style Guide](https://github.com/bluesky-social/atproto/discussions/4245) for best practices.

## Common Tasks

**Add a new feature**: Ask the Quickslice MCP about relevant lexicons, then update `index.html` with new GraphQL queries and UI.

**Add custom lexicons**: Create JSON schemas in `/lexicons`, run `make zip`, upload via settings page. If the lexicon already has published records across multiple PDSes, click "Trigger Backfill" on the Quickslice dashboard to sync existing data. Note: Avoid backfilling well-known lexicons like `app.bsky.*` as this will take days and require large amounts of disk space.

**Style the app**: CSS variables are defined in `:root` - modify colors, spacing as needed.