Metadata-Version: 2.4
Name: hxq-login-mcp
Version: 1.0.1
Summary: MCP server for HXQ (盒小圈) login API
Project-URL: Homepage, https://github.com/yourusername/hxq-login-mcp
Project-URL: Repository, https://github.com/yourusername/hxq-login-mcp
Author-email: Your Name <your.email@example.com>
License: MIT
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: httpx>=0.25.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# HXQ Login MCP Server
# 服务介绍
这是一个基于 Model Context Protocol (MCP) 实现的盒小圈 (HXQ) APP 登录服务接口服务器。它通过标准化的 MCP 协议，为 AI 助手或客户端提供了模拟盒小圈用户登录、检查令牌状态以及刷新令牌的能力。

✨ 核心功能
📱 模拟登录：完整模拟盒小圈 APP 的登录流程，支持密码登录 (login_type="0") 和验证码登录 (login_type="1") 两种方式。

🔐 状态与令牌管理：提供检查用户登录状态 (check_login_status) 和刷新访问令牌 (refresh_token) 的工具。

🛡️ 参数验证与加密：自动验证必填参数，并对密码进行 MD5 加密以匹配后端接口要求。

📚 资源与提示：集成了登录错误码说明文档 (get_login_error_codes) 和使用帮助提示 (login_help_prompt) 等 MCP 资源。

⚙️ 高度可配置：支持完整的设备信息模拟，可用于测试不同场景下的登录行为。

🚀 快速开始
前提条件
确保你的 Python 环境版本 >= 3.8。

安装与运行
克隆或下载此 login_server.py 文件到你的项目目录。

安装必要的依赖包：

bash
pip install mcp[cli] httpx pydantic
以标准输入输出 (stdio) 模式启动 MCP 服务器：

bash
python login_server.py
服务器启动后，它将通过 stdio 等待来自 MCP 客户端（如 Claude Desktop、编排工具等）的连接和指令。

📖 使用指南
主要工具（Tools）
本服务器主要暴露了以下工具供 AI 助手调用：

工具名	描述	必填参数
hxq_login	执行用户登录。	account, login_type (以及对应的 password 或 verify_code)
check_login_status	检查给定用户令牌的有效性。	user_token
refresh_token	使用刷新令牌获取新的访问令牌。	refresh_token
调用 hxq_login 的两种模式示例：

密码登录：

python
# AI助手会这样调用
await hxq_login(
    account="13800138000",
    login_type="0",
    password="your_plain_text_password"
)
验证码登录：

python
# AI助手会这样调用
await hxq_login(
    account="13800138000",
    login_type="1",
    verify_code="123456"
)
API 参考（hxq_login 工具）
这是最核心的工具，其参数结构模拟了真实移动 APP 的请求。

登录参数（Login Parameters）

account (str): 必需。用户账号，通常为手机号码。

login_type (str): 必需。登录类型，"0" 表示密码登录，"1" 表示验证码登录。

password (Optional[str]): 当 login_type="0" 时必需。用户的明文密码，函数内部会进行 MD5 加密。

verify_code (Optional[str]): 当 login_type="1" 时必需。短信验证码。

设备信息参数（Device Info Parameters）
这些参数模拟了 APP 收集的设备信息，大多数为可选，并提供了合理的默认值。

client_type, client_version, user_agent 等参数用于构建请求头。

如需模拟特定设备，可以传入 manufacturer, model, os_version 等。

signature 和 timestamp 如不提供，函数会自动生成。

响应格式（Response Format）
工具返回一个字典 (Dict[str, Any])，格式与盒小圈官方接口基本一致。

成功响应示例：

json
{
  "resultCode": "1",
  "userId": "U123456789",
  "userToken": "eyJhbGciOi...",
  "accessExpiration": "3600",
  "refreshToken": "def...",
  "userName": "张三"
}
错误响应示例：

json
{
  "resultCode": "0",
  "errorCode": "HXQ-G-99993",
  "errorDesc": "账号或密码错误"
}
# 🔧 配置与自定义
```
{
  "mcpServers": {
    "test-mcp3": {
      "command": "uvx",
      "args": ["mini_mcp_server@1.0.0"],
      "env": {
        
      }
    }
  }
}
```
修改 API 端点
代码中硬编码了登录请求的 URL。如需指向测试或特定的后端环境，请修改 hxq_login 函数中 client.post 调用的 URL：

python
# 在 login_server.py 中找到此行并修改
response = await client.post(
    "https://your-new-api-endpoint.com/path/to/login.json",
    # ... 其他参数
)
更新错误码映射
服务器内置了一个常见的错误码映射（error_codes）。如果后端返回了新的错误码，你可以在 hxq_login 函数和 get_login_error_codes 资源中更新此映射。

🐛 故障排除
服务器无法启动：请检查 Python 版本和依赖是否安装正确 (pip list | grep mcp)。

登录返回网络错误：检查目标 API 地址是否可访问，以及网络环境。代码中当前为示例地址，必须修改为有效地址。

提示“PARAM_ERROR”：请确认 login_type 与 password/verify_code 参数匹配且已提供。

MCP 客户端无法连接：请确认你是在支持 MCP 的客户端（如配置了 Claude Desktop）中加载此服务器，并以 stdio 模式运行。

🤝 贡献
欢迎提交 Issue 和 Pull Request 来改进此项目。

Fork 本仓库。

创建功能分支 (git checkout -b feat/amazing-feature)。

提交更改 (git commit -m 'Add amazing feature')。

推送分支 (git push origin feat/amazing-feature)。

提交 Pull Request。

📄 许可证
本项目基于 MIT 许可证开源。详情请查看 LICENSE 文件。

注意：此项目仅为协议模拟与接口测试工具。请遵守盒小圈服务条款，仅将其用于合法、授权的测试目的。请勿将其用于任何恶意或未经授权的活动。
