mcpbluesky

このリポジトリは、Bluesky の API を操作するための MCP（Model Context Protocol）サーバー（FastMCP）と、動作確認用の簡易クライアントを提供します。

Python パッケージは src/mcpbluesky/ 配下にあり、サーバーは mcpbluesky.server をエントリポイントとして起動します。

pyproject.toml は Hatchling（PEP 517/518）でビルドする構成で、インストールすると mcpbluesky という コンソールスクリプト（mcpbluesky = mcpbluesky.server:main）が導入されます。

何ができるか

MCP サーバーとして Bluesky API をツール化
- 読み取り（プロフィール取得、タイムライン取得、検索など）
- 書き込み（投稿、返信、いいね、リポスト、フォロー/ブロック、リスト操作など）
複数アカウントのセッション管理（永続化）
- sessions.json にアクセストークン/リフレッシュトークン等を保存
- acting_handle 引数の省略時に使う デフォルトハンドルを保持
（任意）Jetstream を購読して日本語投稿をローカル SQLite に保存し、検索可能

ディレクトリ構成

主要ファイルは src/mcpbluesky/ にあります。

src/mcpbluesky/server.py
- FastMCP サーバー本体
- SessionManager（複数ユーザーセッションのロード/セーブ/選択）
- Jetstream 購読（オプション）と DB 保存
- ローカルDB検索ツール bsky_search_local_posts の提供
src/mcpbluesky/tools_bluesky.py
- MCP ツール（bsky_*）の登録
- acting_handle による「どのログインセッションで実行するか」の切替
src/mcpbluesky/bluesky_api.py
- BlueskyAPI（HTTP 呼び出しの薄いラッパ）
- BlueskySession（accessJwt/refreshJwt/did/handle/pds_url）
- 投稿テキストのバリデーション（grapheme 300 / bytes 3000）
- URL/ハッシュタグを facets に変換（UTF-8 バイトオフセットで index 設定）
src/mcpbluesky/common_http.py
- urllib.request ベースの HTTP 実装（requests 非依存）
- スロットリング（最小間隔 0.2 秒）
- リトライ（429/403/5xx 等）
- （環境によっては）Zscaler continue 画面の検知と迂回
src/mcpbluesky/bluesky_db.py
- Jetstream から受信した投稿を SQLite へ保存・検索
- 日本語判定（langs に ja、またはひらがな/カタカナ正規表現）
src/mcpbluesky/client.py
- HTTP transport（streamable-http）でサーバーに接続し、 list_tools() と bsky_get_profile を呼ぶ動作確認用サンプル

MCP サーバー（`server.py`）の挙動

セッション管理（`SessionManager`）

セッションは sessions.json に永続化されます。
SessionManager.default_handle を保持し、各ツールの acting_handle が省略された場合に そのデフォルトのセッションを使います。
SessionManager.get_api(handle=None)
- 対象セッションが存在すればその BlueskyAPI を返す
- 存在しなければ 未ログイン状態の BlueskyAPI を返します（この場合 auth_params() により https://public.api.bsky.app を使用）

Jetstream（オプション）

起動時デフォルトでは Jetstream は有効になりません。
--jetstream を付けた場合のみ Jetstream を別スレッドで起動し、 wss://jetstream1.us-east.bsky.network/subscribe?wantedCollections=app.bsky.feed.post を購読します。
kind == "commit" かつ operation == "create" の投稿のみを対象にし、 BlueskyDB.is_japanese(text, langs) が True のものだけ DB に保存します。

提供ツール（MCP tools）

src/mcpbluesky/tools_bluesky.py と src/mcpbluesky/server.py により、少なくとも以下のツールが登録されます。

セッション系

bsky_login(handle: Optional[str] = None, password: Optional[str] = None)
- handle/password が省略された場合は環境変数から補完
  - BSKY_HANDLE
  - BSKY_APP_PASSWORD
- 既に同一 handle のセッションが存在する場合は manager.remove_session(handle) で削除してから再ログインします。
bsky_logout(handle: str)
bsky_refresh_session(acting_handle: Optional[str] = None)

読み取り系

bsky_get_profile(handle: str, acting_handle: Optional[str] = None)
bsky_get_author_feed(handle: str, limit: int = 10, cursor: Optional[str] = None, acting_handle: Optional[str] = None)
bsky_get_actor_feeds(handle: str, acting_handle: Optional[str] = None)
bsky_get_timeline(limit: int = 20, cursor: Optional[str] = None, acting_handle: Optional[str] = None)（要認証）
bsky_get_timeline_page(limit: int = 50, cursor: Optional[str] = None, summary: bool = True, text_max_len: int = 120, acting_handle: Optional[str] = None)（要認証）
bsky_get_post_thread(uri: str, depth: int = 6, acting_handle: Optional[str] = None)
bsky_get_follows(handle: str, limit: int = 50, cursor: Optional[str] = None, acting_handle: Optional[str] = None)
bsky_get_followers(handle: str, limit: int = 50, cursor: Optional[str] = None, acting_handle: Optional[str] = None)
bsky_get_notifications(limit: int = 20, cursor: Optional[str] = None, acting_handle: Optional[str] = None)（要認証）
bsky_resolve_handle(handle: str, acting_handle: Optional[str] = None)
bsky_search_posts(query: str, limit: int = 10, cursor: Optional[str] = None, acting_handle: Optional[str] = None)
bsky_get_likes(uri: str, acting_handle: Optional[str] = None)
bsky_get_lists(handle: str, limit: int = 50, cursor: Optional[str] = None, acting_handle: Optional[str] = None)
bsky_get_list(list_uri: str, limit: int = 50, cursor: Optional[str] = None, acting_handle: Optional[str] = None)
bsky_search_users(term: str, limit: int = 10, cursor: Optional[str] = None, acting_handle: Optional[str] = None)

書き込み系（要認証）

bsky_post(text: str, acting_handle: Optional[str] = None)
bsky_reply(text: str, parent_uri: str, parent_cid: str, root_uri: str, root_cid: str, acting_handle: Optional[str] = None)
bsky_like(uri: str, cid: str, acting_handle: Optional[str] = None)
bsky_repost(uri: str, cid: str, acting_handle: Optional[str] = None)
bsky_delete_post(post_uri: str, acting_handle: Optional[str] = None)
bsky_follow(subject_did: str, acting_handle: Optional[str] = None)
bsky_unfollow(follow_uri: str, acting_handle: Optional[str] = None)
bsky_block(subject_did: str, acting_handle: Optional[str] = None)
bsky_unblock(block_uri: str, acting_handle: Optional[str] = None)
bsky_create_list(name: str, purpose: str = "app.bsky.graph.defs#curatormodlist", description: str = "", acting_handle: Optional[str] = None)
bsky_delete_list(list_uri: str, acting_handle: Optional[str] = None)
bsky_add_to_list(subject_did: str, list_uri: str, acting_handle: Optional[str] = None)
bsky_remove_from_list(listitem_uri: str, acting_handle: Optional[str] = None)
bsky_mute(handle: str, acting_handle: Optional[str] = None)
bsky_unmute(handle: str, acting_handle: Optional[str] = None)
bsky_update_profile(displayName: Optional[str] = None, description: Optional[str] = None, acting_handle: Optional[str] = None)
bsky_set_threadgate(post_uri: str, allow_mentions: bool = True, allow_following: bool = False, acting_handle: Optional[str] = None)

ローカルDB検索（`server.py` で定義）

bsky_search_local_posts(keyword: Optional[str] = None, limit: int = 50)

セットアップ / インストール

このプロジェクトは pyproject.toml を持つ PEP 517/518 のパッケージで、ビルドバックエンドは hatchling です。

プロジェクト名: mcpbluesky
バージョン: 0.1.2
対象 Python: >= 3.10
依存:
- fastmcp
- grapheme
- websockets

依存関係だけ入れて手元で実行したい場合（開発・検証）

requirements.txt があるので、まずこれを入れて python -m ... で動かすこともできます。

pip install -r requirements.txt

ただし、この方法は「パッケージとしてインストールされる状態」を作りません。コンソールスクリプト mcpbluesky も入りません。

editable install（開発用インストール）

リポジトリを編集しながら、通常の import や mcpbluesky コマンドで動作させたい場合は editable install を使います。

pip install -e .

この形でインストールすると:

import mcpbluesky が有効になります
mcpbluesky コマンド（mcpbluesky = mcpbluesky.server:main）が導入されます

ビルドしてインストール（配布物の作成）

1) wheel/sdist をビルド

PEP 517 の標準ツール build を使うのが簡単です。

python -m pip install --upgrade build
python -m build

成功すると dist/ 配下に成果物ができます（例）:

dist/mcpbluesky-0.1.2-py3-none-any.whl
dist/mcpbluesky-0.1.2.tar.gz

2) wheel をインストール

python -m pip install dist/mcpbluesky-0.1.2-py3-none-any.whl

（バージョンは pyproject.toml の version に合わせてください）

3) インストール確認

mcpbluesky --help
python -c "import mcpbluesky; print(mcpbluesky.__all__)"

起動方法

1) インストール済みの場合（推奨）

pyproject.toml の [project.scripts] により、インストールすると mcpbluesky コマンドが使えます。

stdio

mcpbluesky --transport stdio

HTTP: streamable-http

mcpbluesky --transport streamable-http --host 127.0.0.1 --port 8000 --mount-path /mcp

HTTP: sse

mcpbluesky --transport sse --host 127.0.0.1 --port 8000 --mount-path /mcp

Jetstream を有効化

mcpbluesky --transport stdio --jetstream

2) リポジトリから直接起動する場合

python -m mcpbluesky.server --transport stdio

クライアントサンプル（動作確認）

src/mcpbluesky/client.py は、streamable-http で http://127.0.0.1:8000/mcp に接続するサンプルです。

python -m mcpbluesky.client

このスクリプトは:

list_tools() を実行してツール一覧を表示
bsky_get_profile を呼び出して bsky.app のプロフィールを取得

を行います。

LLM エージェントからの利用（`mcp_servers.json` の例）

HTTP transport の例（mount-path /mcp の場合）:

{
  "mcp_servers": [
    {
      "name": "mcpbluesky",
      "url": "http://127.0.0.1:8000/mcp",
      "transport": "streamable-http"
    }
  ]
}

transport=stdio で使う場合は、エージェント側の stdio 起動設定（command/args 等）に合わせてください。
HTTP transport を使う場合、URL は FastMCP の mount_path と一致させてください。

認証情報について

bsky_login は Bluesky のアプリパスワードを使います（通常のログインパスワードは使わないでください）。
引数で渡すか、環境変数で設定します。
- BSKY_HANDLE
- BSKY_APP_PASSWORD

ローカルDB（Jetstream保存）について

DB ファイル（デフォルト）: ~/.mcpbluesky/bluesky_posts.db
--jetstream で Jetstream を購読している間、日本語と判定できた投稿が posts テーブルに保存されます。
bsky_search_local_posts で保存済み投稿をキーワード検索できます。

注意事項 / セキュリティ

sessions.json にはアクセストークン/リフレッシュトークン等が保存されます。取り扱いに注意してください。
Jetstream を有効にした場合、Jetstream の受信処理は別スレッドで動きます。
common_http.py には短時間大量アクセスを抑えるためのスロットリングと、 429/5xx 等の簡易リトライが入っていますが、過剰なリクエストは避けてください。

mcpbluesky

mcpbluesky

何ができるか

ディレクトリ構成

MCP サーバー（server.py）の挙動

セッション管理（SessionManager）

Jetstream（オプション）

提供ツール（MCP tools）

セッション系

読み取り系

書き込み系（要認証）

ローカルDB検索（server.py で定義）

セットアップ / インストール

依存関係だけ入れて手元で実行したい場合（開発・検証）

editable install（開発用インストール）

ビルドしてインストール（配布物の作成）

1) wheel/sdist をビルド

2) wheel をインストール

3) インストール確認

起動方法

1) インストール済みの場合（推奨）

stdio

HTTP: streamable-http

HTTP: sse

Jetstream を有効化

2) リポジトリから直接起動する場合

クライアントサンプル（動作確認）

LLM エージェントからの利用（mcp_servers.json の例）

認証情報について

ローカルDB（Jetstream保存）について

注意事項 / セキュリティ

Reviews

MCP サーバー（`server.py`）の挙動

セッション管理（`SessionManager`）

ローカルDB検索（`server.py` で定義）

LLM エージェントからの利用（`mcp_servers.json` の例）