登录 / 注册
banner
约 1,500 字
5 分钟

MCP 服务器连接指南 — Flare Stack Blog

-
-
无标签

摘要

如何让 AI Agent 通过 OAuth 授权流程连接到 Flare Stack Blog 的 MCP Server

MCP 服务器连接指南 — Flare Stack Blog

概述

Flare Stack Blog 内置了 MCP (Model Context Protocol) 服务器，支持 AI Agent（如 OpenClaw / MClaw）通过 HTTP 协议直接管理博客。MCP 服务器端点位于 /mcp，采用 OAuth 2.0 授权码流程（PKCE）保护，需获得用户授权后才能调用。

本指南记录完整的连接流程，方便未来直接复用。

连接前置条件

  1. 博客拥有 GitHub 账号并已配置 OAuth 登录

  2. AI Agent 环境（如 MClaw / OpenClaw / Claude Desktop 等）

  3. mcporter CLI — MCP 客户端管理工具（Node.js 版本）

    bash
    npm install -g mcporter

完整连接流程

第一步：注册 OAuth 客户端

向博客的 /oauth/register 端点注册一个新的 OAuth 客户端。回调地址设为博客的 /mcp 路径，这样用户授权后会跳转到博客页面，授权码会出现在 URL 中。

bash
curl -X POST <blog_url>/oauth/register \
  -H "Content-Type: application/json" \
  -d '{"client_name":"mclaw-agent","redirect_uris":["<blog_url>/mcp"],"grant_types":["authorization_code","refresh_token"]}'

响应示例：

JSON
{
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "redirect_uris": ["<blog_url>/mcp"],
  "token_endpoint_auth_method": "client_secret_basic"
}

注意：redirect_uri 设置为 /mcp 是关键，用户批准后浏览器会跳转到 /mcp?code=xxx，可以从地址栏获取授权码。

第二步：生成 PKCE 密钥对并构造授权 URL

使用 PKCE（Proof Key for Code Exchange）增强安全性：

JavaScript
const crypto = require("crypto");

// 生成 code_verifier（32 字节随机数，Base64URL 编码）
const verifier = crypto.randomBytes(32).toString("base64url");

// 计算 code_challenge（SHA256 哈希后 Base64URL 编码）
const challenge = crypto.createHash("sha256")
  .update(verifier)
  .digest("base64url");

// 生成随机 state 值
const state = crypto.randomBytes(16).toString("hex");

构造授权 URL：

纯文本
<blog_url>/oauth/consent?response_type=code&client_id=<client_id>&redirect_uri=https%3A%2F%2Fblog.521523.xyz%2Fmcp&scope=analytics:read+posts:read+posts:write+comments:read+comments:write+media:read+media:write+friend-links:read+friend-links:write&state=<state>&code_challenge=<challenge>&code_challenge_method=S256

第三步：用户授权

将上一步生成的授权 URL 提供给博客管理员：

  • 方法一：直接发送链接

  • 方法二：生成二维码（避免微信等应用修改 URL 参数中的下划线）

用户操作流程：

  1. 在系统浏览器（非微信内置浏览器）打开授权链接

  2. 点击 "Login via GitHub" 登录

  3. 点击 "Authorize" 授权博客访问 GitHub

  4. 在 OAuth 授权页面点击 "允许"（Allow）

  5. 浏览器跳转到 /mcp?code=xxx&state=yyy

第四步：获取授权码

用户浏览器跳转到 /mcp?code=xxx 后，由于 MCP 端点期望 Bearer Token 而非授权码，会返回 401 错误。这是正常现象——授权码已经在 URL 中了。用户需要将完整的跳转 URL 提供给 AI Agent。

URL 示例：

纯文本
<blog_url>/mcp?code=<authorization_code>&state=<state>

第五步：兑换 Access Token

使用授权码和 code_verifier 向 /oauth/token 端点兑换 token：

JavaScript
const code = decodeURIComponent(authCodeFromURL);
const auth = Buffer.from(clientId + ":" + clientSecret).toString("base64");

const params = new URLSearchParams();
params.append("grant_type", "authorization_code");
params.append("code", code);
params.append("redirect_uri", "<blog_url>/mcp");
params.append("code_verifier", verifier);
params.append("client_id", clientId);

fetch("<blog_url>/oauth/token", {
  method: "POST",
  headers: {
    "Content-Type": "application/x-www-form-urlencoded",
    "Authorization": "Basic " + auth
  },
  body: params
});

响应示例：

JSON
{
  "access_token": "<access_token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "analytics:read posts:read posts:write comments:read comments:write media:read media:write friend-links:read friend-links:write",
  "refresh_token": "<refresh_token>"
}

第六步：使用 mcporter 配置 MCP 服务器

bash
# 添加服务器配置
mcporter config add blog-mcp <blog_url>/mcp \
  --auth oauth \
  --client-name "mclaw-agent" \
  --oauth-client-id "<client_id>" \
  --oauth-client-secret-env "MCP_SECRET" \
  --oauth-redirect-url "<blog_url>/mcp" \
  --description "Flare Stack Blog MCP Server"

# 注入 Token
echo '{"tokens":{"access_token":"<access_token>","token_type":"Bearer","refresh_token":"<refresh_token>"},"clientInfo":{"client_id":"<client_id>"}}' | mcporter vault set blog-mcp --stdin

# 测试连接
mcporter list blog-mcp --schema

第七步：直接通过 MCP HTTP 接口调用

mcporter 在某些环境下会尝试监听不存在的 IP 地址，此时可以直接用 curl 调用 MCP 的 JSON-RPC 接口：

bash
# 列出所有工具
curl -X POST <blog_url>/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

# 调用工具
curl -X POST <blog_url>/mcp \
  -H "Authorization: Bearer <access_token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"posts_list","arguments":{"limit":5}}}'

MCP 工具列表

连接成功后，可用以下 23 个工具：

📊 分析

  • analytics_overview — 博客流量分析（24h / 7d / 30d / 90d）

📝 文章管理

  • posts_list — 列出文章（支持分页、按状态/关键词筛选）

  • posts_get — 获取单篇文章详情（含 Markdown 正文）

  • posts_create_draft — 创建空白草稿

  • posts_update — 更新文章（标题、摘要、正文等）

  • posts_delete — 删除文章

  • posts_set_visibility — 发布/下架文章

  • posts_set_tags — 设置文章标签

  • search_posts — 全文搜索已发布文章

💬 评论管理

  • comments_list — 列出评论（支持按状态/文章筛选）

  • comments_set_status — 审核评论（通过/待审/删除）

  • comments_delete — 永久删除评论

🔗 友链管理

  • friend_links_list — 列出友链

  • friend_links_create — 创建友链

  • friend_links_update — 更新友链

  • friend_links_delete — 删除友链

🖼️ 媒体管理

  • media_list — 列出媒体文件

  • media_get_usage — 查看媒体引用情况

  • media_delete — 删除未使用的媒体

🏷️ 标签管理

  • tags_list — 列出标签

  • tags_create — 创建标签

  • tags_update — 重命名标签

  • tags_delete — 删除标签

安全说明

  • Access Token 有效期 1 小时，过期后可用 Refresh Token 自动刷新

  • Token 存储在 mcporter 的凭据文件（~/.mcporter/credentials.json）中

  • 所有 API 调用需要 Accept: application/json, text/event-stream 头部，MCP 使用 SSE 协议

  • 博客的 OAuth 端点：

    • 授权页面：/oauth/consent

    • Token 端点：/oauth/token

    • 客户端注册：/oauth/register

    • 受保护资源：/.well-known/oauth-protected-resource

    • MCP 端点：/mcp

END

相关文章

暂无相关文章

- / RSS / Sitemap
Powered by Tanstack Start & Flare Stack Blog