Metadata-Version: 2.4
Name: atproto-mcp
Version: 0.3.1
Summary: MCP server providing AT Protocol documentation, lexicons, Bluesky API docs, and cookbook examples as a searchable knowledge base powered by semantic search.
Author: Evelyn Osman
License: MIT
License-File: LICENSE
Keywords: atproto,bluesky,lexicon,mcp,txtai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.12
Requires-Dist: gitpython>=3.1.0
Requires-Dist: mcp[cli]<3.0.0,>=2.0.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: txtai>=9.0.0
Description-Content-Type: text/markdown

# atproto-mcp

[![Tests](https://github.com/Ashex/atproto-mcp/actions/workflows/tests.yml/badge.svg?branch=main)](https://github.com/Ashex/atproto-mcp/actions/workflows/tests.yml)

MCP server providing a searchable knowledge base for the [AT Protocol](https://atproto.com/) ecosystem — protocol documentation, lexicon schemas, Bluesky developer API docs, and cookbook examples — powered by [txtai](https://github.com/neuml/txtai) semantic search.

## Data Sources

| Source | Repository | Description |
| -------- | ----------- | ------------- |
| **AT Protocol Website** | [bluesky-social/atproto-website](https://github.com/bluesky-social/atproto-website) | Protocol specs, guides, and blog posts from atproto.com |
| **Bluesky API Docs** | [bluesky-social/bsky-docs](https://github.com/bluesky-social/bsky-docs) | Developer docs from docs.bsky.app — tutorials, guides, advanced topics |
| **AT Protocol Lexicons** | [bluesky-social/atproto](https://github.com/bluesky-social/atproto/tree/main/lexicons) | JSON schemas defining all AT Protocol endpoints and record types |
| **Cookbook** | [bluesky-social/cookbook](https://github.com/bluesky-social/cookbook) | Example projects in Python, Go, TypeScript, and JavaScript |

## Tools

| Tool | Description |
| ------ | ------------- |
| `search_atproto_docs` | Semantic search across all documentation sources |
| `get_lexicon` | Retrieve a specific lexicon by NSID (e.g. `app.bsky.feed.post`) |
| `list_lexicons` | List all lexicons, optionally filtered by namespace |
| `search_lexicons` | Semantic search within lexicon schemas |
| `get_cookbook_example` | Get a specific cookbook example by project name |
| `list_cookbook_examples` | List all cookbook examples, optionally by language |
| `search_bsky_api` | Semantic search within Bluesky API docs |
| `refresh_sources` | Force re-fetch repos and rebuild the index |

## Prompts

| Prompt | Description |
| -------- | ------------- |
| `explain_lexicon` | Get a comprehensive explanation of a lexicon |
| `implement_feature` | Get implementation guidance with code examples |
| `debug_atproto` | Help debug AT Protocol / Bluesky API issues |
| `explore_namespace` | Explore all lexicons in a namespace |

## Installation

### Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/uv/) (recommended) or pip
- Git (for cloning source repositories)

### Install from source

```bash
git clone https://github.com/Ashex/atproto-mcp.git
cd atproto-mcp
uv sync
```

### Run with uvx

```bash
uvx atproto-mcp
```

## Configuration

### Claude Desktop (MCPB bundle) — recommended

Download `atproto-mcp-<version>.mcpb` from the
[latest release](https://github.com/Ashex/atproto-mcp/releases/latest) and open
it. Claude Desktop shows an install dialog with optional fields for the cache
directory, refresh interval, and embedding model; leave them blank for the
defaults. No Python or JSON editing required — the host installs dependencies
with uv.

> Bundles are self-signed, so the installer shows an "unknown publisher"
> warning. See [Releases](#releases) for what that does and does not guarantee.

Every other host below uses the PyPI package and is unaffected by the bundle.

### VS Code / Copilot

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_ATproto_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=ffffff)](vscode:mcp/install?%7B%22name%22%3A%22atproto-mcp%22%2C%22type%22%3A%22stdio%22%2C%22command%22%3A%22uv%22%2C%22args%22%3A%5B%22atproto-mcp%22%5D%7D)

Add to `.vscode/mcp.json` in your workspace:

```json
{
  "mcpServers": {
    "atproto": {
      "command": "uvx",
      "args": [
        "atproto-mcp"
        ]
    }
  }
}
```

### Kiro Power

1. Open **Kiro → Powers**
2. Select **Import power from GitHub**
3. Enter `https://github.com/Ashex/atproto-mcp`

### Claude Desktop (manual)

Prefer the [MCPB bundle](#claude-desktop-mcpb-bundle--recommended) above. To
configure by hand instead, add to
`~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "atproto": {
      "command": "uvx",
      "args": [
         "atproto-mcp"
      ]
    }
  }
}
```

### MCPHub

Add to `~/.config/mcphub/servers.json`:

```json
{
  "mcpServers": {
    "atproto": {
      "command": "uvx",
      "args": ["atproto-mcp"]
    }
  }
}
```

### OpenCode

Add to your `opencode.json`:

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "atproto": {
      "type": "local",
      "command": ["uvx", "atproto-mcp"]
    }
  }
}
```

## Environment Variables

| Variable | Default | Description |
| ---------- | --------- | ------------- |
| `ATPROTO_MCP_CACHE_DIR` | `~/.cache/atproto-mcp` | Where repos and the search index are stored |
| `ATPROTO_MCP_REFRESH_HOURS` | `24` | Hours before re-fetching repositories |
| `ATPROTO_MCP_EMBEDDING_MODEL` | `BAAI/bge-small-en-v1.5` | Sentence-transformers model for embeddings |

## How It Works

The server connects immediately and warms up in the background, so a slow first
run never blocks the host's startup handshake.

On first launch, warmup:

1. Shallow clones the repos into `~/.cache/atproto-mcp/repos/`
2. Parses MDX docs, lexicon schemas, and cookbook examples into text chunks
3. Indexes the chunks using txtai **hybrid search** (BM25 keyword + dense vectors from the `bge-small-en-v1.5` sentence-transformer, ~130MB, runs locally) — exact identifiers like NSIDs match reliably alongside semantic queries
4. Index is persisted in `~/.cache/atproto-mcp/index/` for subsequent starts

This takes a few minutes. Until it finishes, tools return a short message
describing what the server is doing rather than failing. If warmup fails — no
network yet, for example — the server stays up, says so, and retries on its
own with exponential backoff until an index is in service. `refresh_sources`
forces a retry immediately.

On subsequent launches the cached index is loaded and put into service *before*
any network access, so queries work within seconds even offline. Repos older
than 24 hours are then refreshed with a shallow fetch and a hard reset to the
tracked branch. If the refreshed repos differ
from what the index was built from, the existing index keeps serving queries
while a fresh one is rebuilt in the background and swapped in when ready.

## Development

```bash
# Install in development mode
uv sync

# Run the server locally (stdio)
uv run atproto-mcp

# Test with the MCP Inspector
uv run mcp dev src/atproto_mcp/server.py

# Run with debug logging
ATPROTO_MCP_CACHE_DIR=/tmp/atproto-mcp uv run atproto-mcp

# Run the test suite (what CI runs)
uv run python -m unittest discover -s tests -p 'test*.py'

# Build the MCPB bundle
npm install -g @anthropic-ai/mcpb
mcpb validate .
mcpb pack . /tmp/atproto-mcp.mcpb
```




## License

MIT
