内容
# Blogger MCP
TypeScript MCP 服务器，用于 Blogger 草稿，帖子管理，项目开发日志和截图，以及 Strava 跑步回顾。
## 한국어 안내
Blogger MCP 是用于 Codex、Claude 等 MCP 客户端的 TypeScript MCP 服务器，用于管理和创建 Blogger 帖子。基本操作始终为 **创建草稿**，只有在明确调用 `publish_blogger_post` 时才会发布帖子。
主要功能：
- 创建 Blogger 草稿
- 查询最近的帖子和草稿
- 修改现有的帖子
- 明确发布帖子
- 使用 Google OAuth refresh token 进行本地存储
- 将 Markdown 转换为 HTML 以插入 Blogger 正文
- 将图片 URL 或本地图片路径插入帖子
- 创建项目开发日志草稿
- 创建基于 Strava 活动数据的跑步回顾草稿
### 快速开始
```bash
git clone https://github.com/powerofdeen/BloggerMCP.git
cd BloggerMCP
npm install
cp .env.example .env
npm run build
```
在 `.env` 中填写 Blogger 的 Google OAuth 值和博客 ID。
```bash
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
BLOGGER_BLOG_ID=...
```
进行 Google OAuth 登录。
```bash
npm run oauth:google
```
打开终端中输出的 Google 登录 URL 并授权后，refresh token 将自动存储在 `http://localhost:3000/oauth2callback` 中。token 存储在 `.tokens/google.json` 中，不会被提交到 Git。
### 注册到 Codex
```bash
codex mcp add blogger -- /opt/homebrew/bin/npm --prefix /Users/powerofdeen/Documents/BloggerMCP run start
```
确认注册：
```bash
codex mcp list
```
在 Codex 中输入 `/mcp` 时，应能看到 `blogger` 服务器。
### 注册到 Claude Desktop
macOS 示例的 Claude Desktop 配置文件：
```text
~/Library/Application Support/Claude/claude_desktop_config.json
```
配置示例：
```json
{
"mcpServers": {
"blogger": {
"command": "/opt/homebrew/bin/npm",
"args": [
"--prefix",
"/Users/powerofdeen/Documents/BloggerMCP",
"run",
"start"
]
}
}
}
```
保存后完全退出并重新启动 Claude Desktop。
### 使用示例
创建草稿：
```text
使用 create_blogger_draft 创建标题为“测试文章”，正文为“## 测试\nBlogger MCP 创建的第一个草稿。”
```
查询最近的帖子和草稿：
```text
使用 list_blogger_posts 查询最近的帖子和草稿
```
创建项目开发日志草稿：
```text
使用 create_project_devlog_draft 创建项目名 BloggerMCP、今日工作内容为“Blogger MCP 服务器实现”和“OAuth 回调助手添加”的草稿
```
发布帖子：
```text
使用 publish_blogger_post 发布 postId=“POST_ID” 且 confirmPublish=true 的帖子
```
### 提供工具
- `blogger_login`：生成 Google OAuth 登录 URL 或交换 OAuth 代码
- `create_blogger_draft`：基于 Markdown 创建 Blogger 草稿
- `list_blogger_posts`：查询最近的帖子和草稿
- `update_blogger_post`：修改现有的 Blogger 帖子
- `publish_blogger_post`：明确发布帖子
- `score_blog_post`：检查帖子结构和 SEO 基本分数
- `upload_post_image`：准备插入帖子的图片 URL
- `create_project_devlog_draft`：创建项目开发日志草稿
- `create_strava_activity_draft`：创建基于 Strava 活动的跑步回顾草稿
### 安全原则
- 默认始终创建草稿。
- 只有明确调用 `publish_blogger_post` 才能发布帖子。
- `publish_blogger_post` 需要 `confirmPublish: true`。
- `.env` 和 `.tokens` 不会被提交到 Git。
- 客户端密钥、访问令牌和刷新令牌不会被记录或返回。
## 功能
- 默认创建 Blogger 帖子为草稿。
- 列出最近的实时帖子和草稿。
- 在不发布的情况下更新现有的帖子。
- 仅通过 `publish_blogger_post` 且带有 `confirmPublish: true` 发布帖子。
- 本地存储 Google OAuth 刷新令牌。
- 将 Markdown 输入转换为 Blogger HTML。
- 将图片 URL 或本地图片插入帖子 HTML。
- 从 `screenshots` 目录自动检测最新的截图。
- 用于跑步回顾草稿的独立 Strava OAuth/客户端模块。
- 不记录或返回客户端密钥、访问令牌或刷新令牌。
## 设置
```bash
npm install
cp .env.example .env
npm run build
```
填写 `.env`：
```bash
GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback
BLOGGER_BLOG_ID=...
STRAVA_CLIENT_ID=...
STRAVA_CLIENT_SECRET=...
STRAVA_REDIRECT_URI=http://localhost:3000/strava/callback
```
## Google Cloud / Blogger API
1. 打开 [Google Cloud Console](https://console.cloud.google.com/)。
2. 创建或选择项目。
3. 启用 **Blogger API v3**。
4. 配置 **OAuth 同意屏幕**。
5. 创建 **OAuth 客户端 ID**。
6. 添加 `.env` 中的重定向 URI，例如 `http://localhost:3000/oauth2callback`。
7. 将客户端 ID 和客户端密钥复制到 `.env` 中。
8. 在 Blogger 设置或通过 Blogger API 中查找您的 Blogger 博客 ID 并设置 `BLOGGER_BLOG_ID`。
首次登录：
推荐的本地回调流程：
```bash
npm run oauth:google
```
然后打开打印的 Google OAuth URL。授权后，本地 `http://localhost:3000/oauth2callback` 页面存储刷新令牌并显示成功消息。
手动回退：
1. 调用 MCP 工具 `blogger_login` 且不带 `code`。
2. 打开返回的 `authUrl`。
3. 从重定向 URL 中复制 `code` 查询参数。
4. 使用该 `code` 再次调用 `blogger_login`。
刷新令牌存储在 `.tokens/google.json` 下。
## Strava 设置
1. 在 [Strava API 设置](https://www.strava.com/settings/api) 中创建应用。
2. 设置回调域/重定向以匹配 `STRAVA_REDIRECT_URI`。
3. 在 `.env` 中填写 `STRAVA_CLIENT_ID` 和 `STRAVA_CLIENT_SECRET`。
4. 调用 `create_strava_activity_draft` 且模式为 `auth_url`。
5. 打开 URL，授权访问，然后使用返回的代码调用工具且模式为 `exchange_code`。
Strava 令牌存储在 `.tokens/strava.json` 下。
## MCP 配置
示例：
```json
{
"mcpServers": {
"blogger": {
"command": "node",
"args": ["/absolute/path/to/BloggerMCP/dist/server.js"],
"env": {
"NODE_ENV": "production"
}
}
}
}
```
用于本地开发：
```json
{
"mcpServers": {
"blogger-dev": {
"command": "npm",
"args": ["run", "dev"],
"cwd": "/absolute/path/to/BloggerMCP"
}
}
}
```
## 工具
### `blogger_login`
返回 Google OAuth URL 或交换 OAuth 代码并存储刷新令牌。
### `create_blogger_draft`
从 Markdown 创建草稿帖子。
输入包括：
- `title`
- `markdown`
- `labels`
- `imageUrls`
- `imagePaths`
- `altTexts`
本地图片路径需要：
```bash
BLOGGER_IMAGE_ASSET_DIR=public/blogger-assets
BLOGGER_IMAGE_PUBLIC_BASE_URL=https://your-site.example/blogger-assets
```
如果图片上传/复制失败，草稿创建将继续进行并返回警告。
### `list_blogger_posts`
列出最近的帖子。使用 `status: ["draft"]` 仅获取草稿。
### `update_blogger_post`
修补标题、内容、标签和可选图片。不发布。
### `publish_blogger_post`
仅在明确调用时发布帖子：
```json
{
"postId": "123",
"confirmPublish": true
}
```
### `score_blog_post`
评估标题长度、标题结构、内容深度、图片、总结和 SEO 标签。
### `upload_post_image`
准备插入帖子的图片 URL。支持：
- `png`
- `jpg`
- `jpeg`
- `webp`
### `create_project_devlog_draft`
创建结构化的开发日志草稿：
1. 今日工作总结
2. 问题情况
3. 解决方法
4. 结果截图
5. 学习心得
6. 下一步工作计划
它可以自动加载 `projectDir` 下的 `screenshots` 中的最新图片，以及明确的 `screenshotPaths`。
### `create_strava_activity_draft`
模式：
- `auth_url`
- `exchange_code`
- `list_recent`
- `create_draft`
跑步回顾包括距离、时间、平均配速、平均心率、海拔、活动名称、日期和圈速数据（如果可用）。
## 图片存储设计
Blogger API 图片上传支持有限，因此图片处理通过 `ImageStorage` 进行分离。
当前适配器：
- URL 图片：直接插入为 `<img src="...">`。
- 本地公共资产：将本地文件复制到 `BLOGGER_IMAGE_ASSET_DIR`，然后从 `BLOGGER_IMAGE_PUBLIC_BASE_URL` 构建 URL。
未来适配器可以添加 Google Photos、Google Drive、S3 或另一个 CDN，而无需更改 Blogger 工具。
## 安全注意事项
- 默认创建草稿。
- 除非明确调用 `publish_blogger_post`，否则不会发布任何内容。
- `publish_blogger_post` 需要 `confirmPublish: true`。
- 客户端密钥和令牌必须保留在 `.env` 和 `.tokens` 中。
- `.env` 和 `.tokens` 被 Git 忽略。
