weibo-mobile-app-mcp

轻量 MCP Server，通过专用 tools 调用微博双端 app（iOS/Android）的内部开发能力。

⚠️ 仅限微博开发包使用，线上包无法使用这些能力。

不负责 WDA 启动、设备管理、Appium session、adb forward 或 Android 设备连接。

前提是微博应用已启动。

安装与构建

npm install
npm run build       # 发布构建（无 sourcemap）
npm run build:dev   # 本地开发构建（带 sourcemap）
npm start           # 运行
npm run inspect     # 使用 fastmcp inspect 调试 tools

MCP Client 配置

本地模式

claude mcp add --transport stdio weibo-app-mcp -- node /path/to/Weibo-Mobile-App-MCP/dist/index.js

{
  "mcpServers": {
    "weibo-app-mcp": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/weibo-mobile-app-mcp/dist/index.js"],
      "env": {
        "IOS_SERVER_URL": "http://127.0.0.1:8100",
        "ANDROID_SERVER_URL": "http://127.0.0.1:10091"
      }
    }
  }
}

发布后（npm 包）

{
  "mcpServers": {
    "weibo-app-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "weibo-app-mcp"],
      "env": {
        "IOS_SERVER_URL": "http://127.0.0.1:8100",
        "ANDROID_SERVER_URL": "http://127.0.0.1:10091"
      }
    }
  }
}

环境变量

| 变量 | 默认值 | 说明 | |------|--------|------| | IOS_SERVER_URL | http://localhost:8100 | iOS WDA HTTP 服务地址 | | IOS_SERVER_TIMEOUT_MS | 60000 | iOS 请求超时 | | ANDROID_SERVER_URL | http://localhost:10091 | Android HTTP RPC endpoint | | ANDROID_SERVER_TIMEOUT_MS | 60000 | Android RPC 请求超时 | | BUNDLE_ID | com.sina.weibo | 默认 bundle ID / package name | | LOG_LEVEL | info | 日志级别 |

Tools

health_check

检查 app HTTP 服务是否可达。

{
  "platform": "ios"
}

open_scheme

在 app 内打开 scheme URL。

{
  "platform": "ios",
  "scheme": "sinaweibo://search"
}

abtest

设置或清除 AB test mock 参数。

{
  "platform": "android",
  "action": "mock",
  "params": {
    "ab_key1": "value1",
    "ab_key2": "value2"
  }
}

• action: "mock" 或 "unmock"
• params: AB test 配置键值对

account_list

获取当前已登录的微博账号列表。

{
  "platform": "ios"
}

返回数据结构：

[
  {
    "userName": "[email protected]",
    "userNick": "昵称",
    "userID": "5056753870",
    "isYouth": false,
    "isCurrent": true,
    "isGuest": false
  }
]

account_login

登录微博账号。

{
  "platform": "ios",
  "username": "[email protected]",
  "password": "your-password"
}

account_logout

退出登录。

{
  "platform": "ios",
  "all": true
}

• all: true 退出所有账号，false 仅退出当前账号（默认 true）

开发说明

项目结构

src/
├── index.ts              # 入口：启动 stdio MCP server
├── server.ts             # FastMCP 实例和 tool 注册
├── config.ts             # 环境变量配置
├── logger.ts             # pino 日志（输出到 stderr）
├── tools/                # Tool 定义
│   ├── index.ts          # Tool 注册入口
│   ├── health-check.ts
│   ├── accounts.ts
│   ├── abtest.ts
│   └── openurl.ts
├── utils/                # 通用工具
│   ├── http.ts           # 带超时的 fetch 封装
│   ├── app-operation.ts  # 操作执行核心（适配器调度）
│   ├── app-response.ts   # 响应类型定义
│   └── app-tool-response.ts  # ContentResult 构造器
└── platform-adapters/    # 双端适配器
    ├── types.ts          # 适配器接口
    ├── ios-adapter.ts    # iOS WDA 适配
    └── android-adapter.ts # Android RPC 适配

新增 Tool

1. 在 src/tools/ 下创建新文件，参考现有 tool 模式：
   • 使用 zod 定义参数 schema
   • 调用 executeOperation() 执行操作
   • 可选传入 formatResponse 自定义响应文案
2. 在 src/tools/index.ts 中注册
3. 在对应 adapter 的 ACTION_MAP 中映射 action → endpoint

双端适配差异

| | iOS | Android | |--|-----|---------| | 协议 | 自定义 WDA endpoint | HTTP RPC endpoint | | POST body | { bundleId, value: payload } | { uri, method, args: payload } | | 响应 | 从 value 字段提取 | 从嵌套 result 字段提取 | | bundleId | POST 请求必须 | 不强制 |

关键约束

• 日志必须走 stderr：MCP stdio 独占 stdout 作为 JSON-RPC 通道
• ESM 模块：所有 import 需带 .js 后缀
• 构建配置：tsconfig.json（开发，sourceMap）和 tsconfig.build.json（发布）