MCP 服务器¶

WeiLink 提供可选的 MCP（Model Context Protocol）服务器，将 bot 能力暴露为 AI agent 可调用的工具。

安装¶

pip install weilink[mcp]

这会在核心包之外安装 toolregistry-server 的 MCP 支持。

pip install weilink[server]

运行¶

WeiLink MCP 服务器支持三种传输模式：stdio（默认）、SSE 和 streamable-http。

stdio（默认）¶

# 通过统一 CLI
weilink mcp

# 或通过 Python 模块
python -m weilink.server

stdio 传输由 MCP 客户端（Claude Desktop、Cursor 等）启动，而非独立运行。

SSE / HTTP¶

# SSE 传输
weilink mcp -t sse -p 8000

# Streamable HTTP 传输（推荐用于网络访问）
weilink mcp -t http -p 8000

# 同时运行管理面板
weilink mcp -t http -p 8000 --admin-port 8080

# 绑定到所有网卡
weilink mcp -t http --host 0.0.0.0 -p 8000

CLI 选项¶

客户端配置¶

Claude Desktop¶

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "weilink": {
      "command": "weilink",
      "args": ["mcp"]
    }
  }
}

Claude Code（stdio）¶

claude mcp add weilink -- weilink mcp

Claude Code（HTTP）¶

先启动 MCP 服务器：

weilink mcp -t http -p 8000

然后在 Claude Code 设置（~/.claude/settings.json）中添加：

{
  "mcpServers": {
    "weilink": {
      "type": "http",
      "url": "http://127.0.0.1:8000/mcp"
    }
  }
}

Cursor / VS Code¶

在 MCP 设置中添加：

{
  "mcpServers": {
    "weilink": {
      "command": "python",
      "args": ["-m", "weilink.server"]
    }
  }
}

可用工具¶

recv¶

轮询接收微信用户的新消息。

返回 JSON 消息数组。每条消息包含 message_id、from_user、msg_type、text、timestamp、bot_id，以及媒体元数据（如有）。

send¶

向微信用户发送文本和/或媒体。

download¶

下载已接收消息中的媒体文件。

返回保存路径和文件大小。

history¶

从持久化存储中查询消息历史。

返回 JSON，包含 messages 数组、total 总数、limit 和 offset。

sessions¶

列出所有会话及其连接状态。无参数。

login¶

带内置轮询的二维码登录。该工具是有状态的——其行为取决于是否已有登录流程在进行中：

典型 agent 工作流：

1. 调用 login() — 返回 {"status": "pending", "qr_url": "..."}。将 QR URL 展示给用户。
2. 再次调用 login() — 内部轮询最多 30 秒，返回 {"status": "scanned"} 或 {"status": "confirmed", ...}。
3. 如仍为 pending，继续调用 login() 直到 confirmed 或 expired。

logout¶

登出会话并移除持久化凭据。

rename_session¶

重命名会话。

set_default¶

将指定会话设为默认。

架构¶

graph LR
    A[AI Agent] -->|MCP 协议| B[WeiLink MCP]
    B -->|WeiLink SDK| C[iLink API]
    C --> D[微信]

MCP 服务器内部封装了一个 WeiLink 实例。通过 recv 接收的消息会被缓存（最多 1000 条），以便后续通过 download 下载媒体。

Skills 元数据¶

WeiLink 附带两个元数据文件用于注册表发现：

• server.json — MCP 官方标准，供 MCP 注册表和包管理器使用。
• smithery.yaml — Smithery 注册表格式，用于自动配置。