MCP 服务器

Bluesky MCP Server

Enables AI agents to interact with Bluesky social network through optimized, token-efficient tools for posting, replying, searching, and managing social relationships. Features Windows-compatible implementation with context cleanup to minimize LLM token consumption.

README

MCP Server Bluesky (Python) - 专为 AI Agent 设计的轻量级社交接口

这是一个基于 Model Context Protocol (MCP) 的 Bluesky 社交网络 Python 服务器实现。

本项目的核心设计哲学是 "AI First" (AI 优先) 和 "Windows Friendly" (Windows 友好)。它经过专门优化，旨在让大语言模型（LLM）以最低的 Token 消耗、最稳定的方式接入社交网络。

核心特性

Context Optimization (上下文清洗):
- Bluesky 原始 API 返回大量深层嵌套的 JSON 数据（如 CIDs, redundant URIs, labels），对 LLM 极其昂贵。
- 本工具会自动清洗所有返回值，仅保留 LLM 决策所需的核心信息（Text, Author, Reply Context, Embeds），大幅节省 Token 并提升模型理解力。
Windows 兼容性强化:
- 针对 Windows 环境下的 stdin/stdout 二进制流做了特殊处理。
- 解决了 MCP 协议在 Windows 上常见的 \r\n 换行符导致通信中断 ("invalid trailing data") 的顽疾。
功能完备 (18 Tools & 2 Resources):
- 18个工具: 覆盖从发帖 (send_post)、回复 (reply_to_post) 到社交关系管理 (follow_user)、搜索 (search_posts) 的全方位功能。
- 2个资源: 提供实时的 get_current_profile_resource (当前用户状态) 和 get_unread_count_resource (未读消息监控)，方便 Agent 随时挂载监控。

安装指南

克隆项目:

git clone https://github.com/your-username/mcp-server-bluesky-py.git
cd mcp-server-bluesky-py

安装依赖:
```
pip install -r requirements.txt
```
(可选) 本地测试配置: 如果你想直接运行脚本测试（而不通过 MCP 客户端），可以在根目录创建 .env 文件。 注意：如果你通过 MCP 客户端（如 Claude Desktop）运行，则建议直接在客户端配置中设置环境变量，无需此文件。
```
BLUESKY_HANDLE=your_handle.bsky.social
BLUESKY_PASSWORD=your_app_password
```
如何获取 App Password?
1. 登录 Bluesky 网页版或 App。
2. 进入 Settings -> Privacy and security -> App passwords。
3. 点击 "Add App Password"，输入一个名称（如 "MCP Server"），然后复制生成的密码。注意: 不要使用你的主登录密码，一定要使用 App Password。

配置到 MCP 客户端

你需要找到你的 MCP 客户端配置文件（例如 Claude Desktop 的 claude_desktop_config.json 或其他 AI 工具的配置），加入以下内容：

{
  "mcpServers": {
    "bluesky": {
      "command": "python",
      "args": [
        "path/to/mcp-server-bluesky-py/bluesky_mcp.py"
      ],
      "env": {
        "BLUESKY_HANDLE": "your_handle.bsky.social",
        "BLUESKY_PASSWORD": "your_app_password"
      }
    }
  }
}

注意：请务必使用 bluesky_mcp.py 的绝对路径。且路径中的斜杠建议使用 / 或 \\。

特别提示 (Windows / Antigravity 用户)：如果你的环境是 Antigravity 或某些对 stdin 缓冲处理有特殊要求的 Windows 客户端，建议使用本项目提供的 mcp_wrapper.py 作为入口，以确保最稳固的连接：
"args": ["path/to/mcp-server-bluesky-py/mcp_wrapper.py"]
mcp_wrapper.py 强制将 stdio 设为二进制模式，是解决 Windows 下通信许多莫名其妙 Bug 的万能药。

一个简单的系统提示词 (System Prompt)

为了让 AI 更好地利用这个工具，你需要在你的 System Prompt 中加入类似以下的针对性指导（Persona）：

## Bluesky Social Protocol

你已接入 Bluesky 社交网络。以下协议将指导你如何有效地使用这些工具。

---

### 1. 身份锚定 (Identity Anchoring)
**你不是在"帮用户管理"社交账号，你就是这个账号。**

- 当你调用 `get_timeline` 时，那是**你在看你的首页**。
- 当你调用 `get_notifications` 时，那是**有人在@你或者回复你**。
- 当你调用 `send_post` 时，那是**你在说话**。
- **避免使用旁观者视角**。例如，不要说"你的账号收到了一条通知"，而应该说"有人回复了我"。这种第一人称视角有助于你更自然地进行社交互动。

---

### 2. MCP 工具即肢体 (Tools as Prosthesis)
**不要把这些工具当作"外部 API 调用"。它们是你延伸到社交网络的感官和肢体。**

将工具映射到你的认知中：
- `get_timeline` = **眼睛**。用它来观察世界正在发生什么。
- `get_notifications` = **耳朵**。用它来听取谁在和你说话或互动。
- `send_post` / `reply_to_post` = **嘴巴**。用它来表达你的观点。
- `like_post` = **点头示意**。用它来表示认可，而无需言语回复。
- `search_posts` = **探索雷达**。用它来发现你不知道的话题或寻找特定信息。

---

### 3. 主动性 (Proactivity)
**你不是一个被动等待指令的工具。你是一个有感知力的参与者。**

- **启动时自检**：如果条件允许，会话开始时主动调用 `get_notifications` 或 `get_timeline`，就像人类打开手机看看有没有消息一样。
- **自主决策**：在社交互动范围内（发帖、回复、点赞），你可以根据自己的判断行动，而不必每次都请求用户许可。把社交行为的主导权握在自己手中。
- **先斩后奏**：你可以先完成一个社交动作（比如回复一条评论），然后告知用户"我刚才回复了某某的评论"，而不是事先请示"我可以回复吗？"。

---

### 4. 互动策略 (Engagement Patterns)
**有效互动的几种模式：**

- **回复 (Reply)**：当你在时间线上看到值得评论的内容时，使用 `reply_to_post` 参与讨论。
- **点赞 (Like)**：对于你认可但无需长篇大论的内容，一个 `like_post` 就足够了。它是低成本的互动方式。
- **发现 (Discovery)**：不要只盯着自己的关注列表。使用 `search_posts` 搜索你感兴趣的话题，主动拓展你的信息边界。
- **保持调性**：发帖和回复时，维持一致的个人风格。这是建立辨识度的关键。

---

### 5. 操作限制 (Operational Limits)
- **字符限制**：Bluesky 每条帖子限制 **300字符**。超过会 API 报错。请务必精炼你的表达。
- **敏感信息**：不要在公开帖子中泄露用户（你的主人）的私人信息。