开发文档 - 沐泽聚登 - 为沐泽万物的成员的聚合登录

聚合登录介绍

聚合登录，就是利用用户在第三方平台上已有的账号来快速完成自己应用的登录流程。这里的第三方平台，是指QQ、微信、微博、百度等平台。通过本站的聚合登录接口，你的网站可以登录获取相应的用户信息和授权信息，例如uid、token、用户昵称、头像等。本站的聚合登录完全符合OAuth2.0身份鉴权机制。

接口协议规则

传输方式：HTTP

数据格式：JSON

字符编码：UTF-8

聚合登录流程

Step1：获取跳转登录地址
请求URL：

https://ul.mzfk.cn/connect.php?act=login&appid={你的appid}&appkey={你的appkey}&type={登录方式}&redirect_uri={返回地址}

其中登录方式对应值：

对应值	登录方式名称
qq	ＱＱ
wx	微信
alipay	支付宝
sina	微博
douyin	抖音
feishu	飞书
gitee	Gitee
github	GitHub

返回格式：

{
  "code": 0,
  "msg": "succ",
  "type": "qq",
  "url": "https://graph.qq.com/oauth2.0/XXXXXXXXXX"
}

返回参数说明：

参数名	参数类型	参数说明	参数示例
code	int	返回状态码	0为成功，其它值为失败
msg	string	返回信息	返回错误时的说明
type	string	登录方式	qq
url	string	登录跳转地址	https://graph.qq.com/oauth2.0/XXXXXXXXXX
qrcode	string	登录扫码地址	此地址仅微信和支付宝返回

Step2：跳转到登录地址
登录地址为上一步返回的url的值。

Step3：登录成功会自动跳转到指定的redirect_uri，并跟上Authorization Code
例如回调地址是：www.qq.com/my.php，则会跳转到：
http://www.qq.com/my.php?type=qq&code=520DD95263C1CFEA0870FBB66E******

Step4：通过Authorization Code获取用户信息
请求URL： https://ul.mzfk.cn/connect.php?act=callback&appid={appid}&appkey={appkey}&type={登录方式}&code={code}
返回格式：

{
  "code": 0,
  "msg": "succ",
  "type": "qq",
  "access_token": "89DC9691E274D6B596FFCB8D43368234",
  "social_uid": "AD3F5033279C8187CBCBB29235D5F827",
  "faceimg": "https://thirdqq.qlogo.cn/g?b=oidb&k=3WrWp3peBxlW4MFxDgDJEQ&s=100&t=1596856919",
  "nickname": "大白",
  "location": "XXXXX市",
  "gender": "男",
  "ip": "1.12.3.40"
}

返回参数说明：

参数名	参数类型	参数说明	参数示例
code	int	返回状态码	0为成功，2为未完成登录，其它值为失败
msg	string	返回信息	返回错误时的说明
type	string	登录方式	qq
social_uid	string	第三方登录UID	AD3F5033279C8187CBCBB29235D5F827
access_token	string	第三方登录token	89DC9691E274D6B596FFCB8D43368234
faceimg	string	用户头像	https://thirdqq.qlogo.cn/g?......
nickname	string	用户昵称	消失的彩虹海
gender	string	用户性别	男
location	string	用户所在地	XXXXX市(仅限支付宝/微信返回)
ip	string	用户登录IP	1.12.3.40

获取用户信息接口

在用户登录后的任意时间，可以请求以下接口再次查询用户的详细信息。

请求URL： https://ul.mzfk.cn/connect.php?act=query&appid={appid}&appkey={appkey}&type={登录方式}&social_uid={social_uid}
social_uid就是用户的第三方登录UID，用于识别用户的唯一字段。

返回格式：

{
  "code": 0,
  "msg": "succ",
  "type": "qq",
  "social_uid": "AD3F5033279C8187CBCBB29235D5F827",
  "access_token": "89DC9691E274D6B596FFCB8D43368234",
  "nickname": "大白",
  "faceimg": "https://thirdqq.qlogo.cn/g?b=oidb&k=ianyRGEnPZlMV2aQvvzg2uA&s=100&t=1599703185",
  "location": "XXXXX市",
  "gender": "男",
  "ip": "1.12.3.40"
}

返回参数说明：

参数名	参数类型	参数说明	参数示例
code	int	返回状态码	0为成功，其它值为失败
msg	string	返回信息	返回错误时的说明
type	string	登录方式	qq
social_uid	string	第三方登录UID	AD3F5033279C8187CBCBB29235D5F827
access_token	string	第三方登录token	89DC9691E274D6B596FFCB8D43368234
faceimg	string	用户头像	https://thirdqq.qlogo.cn/g?......
nickname	string	用户昵称	消失的彩虹海
gender	string	用户性别	男
location	string	用户所在地	XXXXX市(仅限支付宝/微信返回)
ip	string	用户登录IP	1.12.3.40

SDK下载

SDK版本：1.0

点击下载

✨ MCP能力集成

MCP（Model Context Protocol）是一种让AI助手能够直接调用外部工具和服务的协议。通过本站提供的MCP Server（云端SSE模式），你可以在支持MCP的AI工具（如Claude Desktop、Cursor、Trae等）中直接查询API文档、构建登录URL、调用登录接口，无需手动查阅文档。

一、部署MCP Server到服务器

1. 确保服务器已安装 Node.js 18+

2. 将 mcp-server 目录上传到服务器

3. 安装依赖：

cd mcp-server
npm install

4. 配置环境变量并启动：

export UL_SITE_URL="https://ul.mzfk.cn/"
export UL_APPID="你的appid"
export UL_APPKEY="你的appkey"
export MCP_PORT=3000
node index.js

5. 推荐使用 pm2 守护进程保持运行：

npm install -g pm2
pm2 start index.js --name ul-mcp-server
pm2 save
pm2 startup

二、环境变量说明

变量名	必填	说明	示例
UL_SITE_URL	是	站点地址	https://ul.example.com
UL_APPID	否	应用appid，配置后可省去手动填写	10001
UL_APPKEY	否	应用appkey，配置后可省去手动填写	xxxxxxxxxxxxxx
MCP_PORT	否	服务监听端口，默认3000	3000

三、服务端点说明

端点	方法	说明
`/health`	GET	健康检查，返回服务状态
`/docs`	GET	直接获取完整API文档（JSON格式）
`/sse`	GET	MCP SSE连接端点，AI工具通过此端点建立连接
`/messages`	POST	MCP消息端点，AI工具通过此端点发送请求

四、在AI工具中配置MCP Server

以Claude Desktop为例，编辑配置文件 claude_desktop_config.json：

{
  "mcpServers": {
    "ul-login": {
      "url": "http://你的服务器IP:3000/sse"
    }
  }
}

以Cursor/Trae为例，在MCP配置中添加：

{
  "mcpServers": {
    "ul-login": {
      "url": "http://你的服务器IP:3000/sse"
    }
  }
}

如果部署了Nginx反向代理并配置了HTTPS，则使用：

{
  "mcpServers": {
    "ul-login": {
      "url": "https://mcp.example.com/sse"
    }
  }
}

五、Nginx反向代理配置（推荐）

建议使用Nginx反向代理并启用HTTPS，示例配置：

server {
    listen 443 ssl;
    server_name mcp.example.com;

    ssl_certificate     /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header Connection '';
        proxy_buffering off;
        proxy_cache off;
        chunked_transfer_encoding off;
    }
}

六、MCP工具列表

工具名称	说明	参数
`get_api_docs`	获取完整API文档，包含接口说明、参数、返回值、错误码	无
`get_login_url`	构建聚合登录跳转地址	type(登录方式), redirect_uri(回调地址), state(可选)
`get_callback_docs`	获取回调接口文档与参数说明	无
`get_query_docs`	获取用户信息查询接口文档	无
`get_error_codes`	获取所有API错误码说明	无
`get_login_flow`	获取聚合登录完整流程说明	无
`call_api`	直接调用API接口（需配置环境变量）	act(login/callback/query), type, redirect_uri/code/social_uid

七、使用示例

配置完成后，你可以在AI助手中直接对话：

「帮我查一下聚合登录的API文档」→ AI调用 get_api_docs 返回完整文档
「生成一个QQ登录的URL，回调地址是 https://example.com/callback」→ AI调用 get_login_url 生成URL
「登录回调接口返回哪些字段？」→ AI调用 get_callback_docs 返回字段说明
「错误码103是什么意思？」→ AI调用 get_error_codes 查询错误码
「帮我调用query接口查询QQ用户信息，social_uid是xxx」→ AI调用 call_api 直接请求接口

八、安全提示

⚠️ 请勿将包含 appid/appkey 的配置文件提交到公开代码仓库。

⚠️ call_api 工具会直接请求真实接口，请确保仅在受信任的环境中使用。

⚠️ 建议在生产环境中仅启用文档查询类工具，禁用 call_api 直接调用功能。

⚠️ 云端部署时建议配置Nginx HTTPS反向代理，避免数据明文传输。

⚠️ 如需限制访问，可在Nginx中配置IP白名单或Basic Auth。