内容
<div align="center">
<h1>@cyanheads/bluesky-mcp-server</h1>
<p><b>通过MCP在Bluesky上搜索帖子、个人资料、动态、线程和热门话题。支持STDIO或Streamable HTTP。</b>
<div>7 个工具 • 1 个资源</div>
</p>
</div>
<div align="center">
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/bluesky-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/bluesky-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
</div>
<div align="center">
[](https://github.com/cyanheads/bluesky-mcp-server/releases/latest/download/bluesky-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=bluesky-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvYmx1ZXNreS1tY3Atc2VydmVyIl19) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22bluesky-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fbluesky-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
</div>
<div align="center">
**公共托管服务器：** [https://bluesky.caseyjhand.com/mcp](https://bluesky.caseyjhand.com/mcp)
</div>
---
## 工具列表
七个用于只读访问公共Bluesky/AT协议应用视图的工具，无需身份验证：
| 工具 | 描述 |
|:-----|:------------|
| `bsky_search_posts` | 对公共Bluesky帖子进行全文搜索，支持作者、语言、标签、域名、日期和排序筛选 |
| `bsky_get_profile` | 通过句柄或DID获取Bluesky演员的公共个人资料 - 句柄↔DID解析器 |
| `bsky_get_author_feed` | 用户最近发布的帖子，按最新顺序排列，可按帖子类型筛选 |
| `bsky_get_post_thread` | 通过AT-URI获取帖子的完整对话 - 父链向上，回复树向下 |
| `bsky_search_actors` | 按名称或句柄片段查找Bluesky账户 |
| `bsky_get_follows` | 分页社交图谱边缘 - 用户关注或关注他们的人 |
| `bsky_get_trending` | Bluesky上的实时热门话题，包含帖子数量、类别和状态 |
### `bsky_search_posts`
对公共Bluesky帖子进行全文搜索。
- 筛选条件：作者句柄、语言（BCP-47）、哈希标签、域名、日期范围（`since`/`until`）和排序顺序（`top`或`latest`）
- 返回帖子内容、作者、互动计数（点赞/转发/回复/引用）、嵌入、AT-URI和时间戳
- `hitsTotal`（如果可用）- 匹配帖子的总数，而不仅仅是当前页面
- 通过不透明的光标进行分页；每次调用最多100个结果
- 嵌入规范化为扁平的联合体：`images`、`external`（链接卡）、`record`（引用帖子）、`video`、`unknown`
- 原样显示审核标签 - 不过滤
---
### `bsky_get_profile`
通过句柄或DID获取Bluesky演员的公共个人资料。
- 返回displayName、handle、DID、description、关注者/关注/帖子计数、头像URL、审核标签和固定帖子AT-URI
- 句柄↔DID的解析步骤 - 在只有句柄时使用需要DID或AT-URI的工具
---
### `bsky_get_author_feed`
用户最近发布的帖子，按最新顺序排列。
- 按帖子类型筛选：`posts_with_replies`、`posts_no_replies`、`posts_with_media`或`posts_and_author_threads`
- 返回帖子全文、互动计数、嵌入和AT-URI用于线程钻取
- 通过光标分页
---
### `bsky_get_post_thread`
通过AT-URI获取帖子的完整对话。
- 返回根帖子、父链（向上）和嵌套回复树（向下）
- 可配置的`depth`（回复树深度，默认为6）和`parent_height`（父链高度，默认为80）
- 截断的子树显示`truncated: true`；删除的帖子显示为`not_found`
- AT-URI来自`bsky_search_posts`或`bsky_get_author_feed`
---
### `bsky_get_follows`
获取帐户的社交图谱边缘。
- `direction`: `followers`（谁关注该演员）或`following`（该演员关注谁）
- 返回分页个人资料，包含句柄、DID、displayName、描述和关注者计数
- 顶部包含主题的个人资料摘要
---
### `bsky_get_trending`
获取Bluesky上的实时热门话题。
- 返回主题，包含显示名称、帖子数量、类别（政治、体育、流行文化等）、状态（hot/rising）和开始时间
- 无光标 - 返回当前快照，最多`limit`
- 使用`app.bsky.unspecced.getTrends` - Bluesky可能会在未通知的情况下更改此端点
## 资源
| 类型 | 名称 | 描述 |
|:-----|:-----|:------------|
| 资源 | `bsky://profile/{actor}` | Bluesky演员的公共个人资料，可通过句柄或DID寻址 |
所有资源数据也可通过工具访问。使用`bsky_get_profile`进行编程访问，或使用`bsky://profile/{actor}`直接注入个人资料上下文。
## 功能
构建于[`@cyanheads/mcp-ts-core`](https://www.npmjs.com/package/@cyanheads/mcp-ts-core）：
- 声明式工具和资源定义 - 每个基元一个文件，框架处理注册和验证
- 统一错误处理 - 处理程序抛出，框架捕获、分类和格式化
- 可插拔身份验证：`none`、`jwt`、`oauth`
- 可互换存储后端：`in-memory`、`filesystem`、`Supabase`、`Cloudflare KV/R2/D1`
- 带有可选OpenTelemetry跟踪的结构化日志记录
- STDIO和Streamable HTTP传输
Bluesky特定：
- 无需身份验证 - 所有七个工具都针对`api.bsky.app`，无需凭证
- 单个`BlueskyService`包装AT协议公共应用视图，带有重试（3次尝试，500毫秒基准）、15秒超时和版本化的`User-Agent`
- 嵌入规范化 - 原始嵌套AT协议嵌入对象展平为干净的`type` - 区分联合体
- 原样显示审核标签 - 代理和其人类决定采取什么措施
- AT协议标识符类型（句柄、DID、AT-URI）在每个工具描述中首次出现时解释
代理友好输出：
- 帖子和资源上的AT-URI - 链接`bsky_search_posts` → `bsky_get_post_thread`，无需额外步骤
- 区分嵌入联合体（`type: "images" | "external" | "record" | "video" | "unknown"`）- 根据数据分支，而不是 `$type` 字符串
- 搜索结果上的`hitsTotal` - 在不进行额外往返的情况下向用户传达结果规模
- 线程节点上的截断信号（`truncated: true`）- 代理知道树在哪里结束以及原因
## 入门指南
### 公共托管实例
直接连接 - 无需安装：
```json
{
"mcpServers": {
"bluesky-mcp-server": {
"type": "streamable-http",
"url": "https://bluesky.caseyjhand.com/mcp"
}
}
}
```
### 自托管
将以下内容添加到您的MCP客户端配置文件中。不需要API密钥。
```json
{
"mcpServers": {
"bluesky-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@cyanheads/bluesky-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
或使用npx（无需Bun）：
```json
{
"mcpServers": {
"bluesky-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@cyanheads/bluesky-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}
```
或使用Docker：
```json
{
"mcpServers": {
"bluesky-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
"ghcr.io/cyanheads/bluesky-mcp-server:latest"
]
}
}
}
```
对于Streamable HTTP，设置传输并启动服务器：
```sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# 服务器监听 http://localhost:3010/mcp
```
### 先决条件
- [Bun v1.3.0](https://bun.sh/) 或更高版本（或 Node.js v24+）。
- 无需API密钥或帐户 - 所有工具都调用 `api.bsky.app`，无需凭证。
### 安装
1. **克隆仓库：**
```sh
git clone https://github.com/cyanheads/bluesky-mcp-server.git
```
2. **导航到目录：**
```sh
cd bluesky-mcp-server
```
3. **安装依赖：**
```sh
bun install
```
4. **配置环境（可选）：**
```sh
cp .env.example .env
# 编辑.env以覆盖任何框架默认值
```
## 配置
此服务器不需要API密钥。所有框架配置都是可选的。
| 变量 | 描述 | 默认值 |
|:---------|:------------|:--------|
| `MCP_TRANSPORT_TYPE` | 传输：`stdio`或`http` | `stdio` |
| `MCP_HTTP_PORT` | HTTP服务器端口 | `3010` |
| `MCP_AUTH_MODE` | 身份验证模式：`none`、`jwt`或`oauth` | `none` |
| `MCP_LOG_LEVEL` | 日志级别（RFC 5424） | `info` |
| `LOGS_DIR` | 日志文件目录（仅限Node.js） | `<项目根目录>/logs` |
| `STORAGE_PROVIDER_TYPE` | 存储后端 | `in-memory` |
| `OTEL_ENABLED` | 启用[OpenTelemetry仪表盘](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry) | `false` |
参见[`.env.example`](./.env.example)以获取完整的覆盖选项列表。
## 运行服务器
### 本地开发
- **构建并运行：
```sh
# 一次性构建
bun run rebuild
# 运行构建的服务器
bun run start:stdio
# 或
bun run start:http
```
- **运行检查和测试：
```sh
bun run devcheck # 校验、格式化、类型检查、安全检查
bun run test # Vitest测试套件
bun run lint:mcp # 验证MCP定义是否符合规范
```
### Docker
```sh
docker build -t bluesky-mcp-server .
docker run --rm -p 3010:3010 bluesky-mcp-server
```
Dockerfile默认为HTTP传输、无状态会话模式，并将日志记录到`/var/log/bluesky-mcp-server`。OpenTelemetry peer依赖项默认安装 - 构建时添加 `--build-arg OTEL_ENABLED=false` 以省略它们。
## 项目结构
| 目录 | 目的 |
|:----------|:--------|
| `src/index.ts` | `createApp()`入口点 - 注册工具、资源并初始化服务。 |
| `src/services/bluesky` | AT协议应用视图HTTP客户端，带有重试、超时和`User-Agent`。 |
| `src/mcp-server/tools` | 工具定义（`*.tool.ts`) - 七个只读Bluesky工具。 |
| `src/mcp-server/resources` | 资源定义（`*.resource.ts`) - `bsky://profile/{actor}`。 |
| `tests/` | 单元测试和集成测试，镜像`src/`。 |
## 开发指南
参见 [`CLAUDE.md`](./CLAUDE.md) 获取开发指南和架构规则。简版：
- 处理程序抛出，框架捕获 - 工具逻辑中无 `try/catch`
- 使用 `ctx.log` 进行请求范围内的日志记录，使用 `ctx.state` 进行租户范围内的存储
- 通过 `src/index.ts` 中的数组注册新工具和资源
- 包装外部API调用：验证原始 → 规范化为域类型 → 返回输出模式；绝不构造缺失的字段
## 贡献
欢迎提出问题和拉取请求。在提交之前运行检查和测试：
```sh
bun run devcheck
bun run test
```
## 许可证
Apache-2.0 - 参见 [LICENSE](LICENSE) 获取详细信息。
