# Jteam-mcp **Repository Path**: jteam_release/jteam-mcp ## Basic Information - **Project Name**: Jteam-mcp - **Description**: Jteam MCP服务 - **Primary Language**: Java - **License**: MIT - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 1 - **Forks**: 0 - **Created**: 2026-06-21 - **Last Updated**: 2026-06-27 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # JTeam MCP Server 基于 Spring Boot + Spring AI MCP 的服务端,为 AI 助手提供 **CS2 饰品交易平台** 自动化操作能力。集成 **BUFF、C5Game、ECO、Steam** 四大平台,暴露 26 个 MCP 工具供 AI 调用。 ## 项目架构 ``` jteam-mcp/ ├── pom.xml ├── src/main/ │ ├── java/com/jteam/mcp/ │ │ ├── McpServerApplication.java # 主启动类 │ │ ├── OrderState.java # 订单状态常量 │ │ ├── SystemConstant.java # 系统常量 │ │ ├── UrlConstant.java # 各平台 API 地址常量 │ │ ├── tool/ # MCP 工具暴露层 (5 个类, 26 个工具) │ │ │ ├── BuffMcpTools.java # BUFF 平台 7 个工具 │ │ │ ├── C5McpTools.java # C5 平台 5 个工具 │ │ │ ├── EcoMcpTools.java # ECO 平台 6 个工具 │ │ │ ├── SteamMcpTools.java # Steam 平台 6 个工具 │ │ │ └── OrderMcpTools.java # 本地订单 2 个工具 │ │ ├── buff/ # BUFF 平台业务模块 │ │ │ ├── model/ # BUFF 数据模型 (6 个类) │ │ │ ├── repository/ # JPA 数据访问层 │ │ │ └── service/ # BUFF 业务逻辑 │ │ ├── c5/ # C5 平台业务模块 │ │ │ ├── model/ # C5 数据模型 (5 个类) │ │ │ └── service/ # C5 业务逻辑 │ │ ├── eco/ # ECO 平台业务模块 │ │ │ ├── model/ # ECO 数据模型 (5 个类) │ │ │ └── service/ # ECO 业务逻辑 │ │ ├── steam/ # Steam 平台业务模块 │ │ │ ├── model/ # Steam 数据模型 (6 个类) │ │ │ └── service/ # Steam 业务逻辑 (登录、订单、令牌等) │ │ ├── common/ # 通用组件 (Response, LogUtil) │ │ ├── config/ # 配置管理 (AccountConfig, ConfigManager) │ │ ├── context/ # 请求上下文 (多账号管理) │ │ ├── request/ # HTTP 客户端 (OkHttp, Cookie 管理) │ │ ├── exception/ # 异常体系 (ErrorCode 枚举) │ │ └── util/ # 工具类 (RSA, 文本, 时间, 断言) │ └── resources/ │ ├── application.yml # 应用配置 │ └── logback-spring.xml # 日志配置 └── README.md ``` ## 技术栈 | 技术 | 版本 | 用途 | |------|------|------| | Spring Boot | 3.4.1 | 基础框架 | | Spring AI MCP Server | 1.1.4 | MCP 协议支持 | | Java | 17 | 运行时 | | OkHttp | 4.12.0 | HTTP 客户端 (自动管理 Cookie) | | Hutool | 5.8.26 | 工具库 (JSON、HTTP、加密等) | | Jsoup | 1.17.2 | HTML 解析 (Steam 交易确认) | | Lombok | - | 代码简化 | | Spring Data JPA + SQLite | - | 订单数据持久化 | ## 快速开始 ### 环境要求 - Java 17+ - Maven 3.6+ ### 构建与运行 ```bash cd jteam-mcp # 构建 mvn clean package -DskipTests # 运行 (方式一:Maven) mvn spring-boot:run # 运行 (方式二:JAR) java -jar target/jteam-mcp-1.0.0.jar ``` 服务启动后默认监听 `http://localhost:8081` ## 配置说明 ### 配置文件路径 各平台配置文件默认位于 `%USERPROFILE%\.eco\config.properties`,可通过环境变量自定义: | 环境变量 | 默认路径 | 对应平台 | |----------|----------|----------| | `BUFF_CONFIG_PATH` | `%USERPROFILE%\.eco\config.properties` | BUFF | | `C5_CONFIG_PATH` | `%USERPROFILE%\.eco\config.properties` | C5 | | `ECO_CONFIG_PATH` | `%USERPROFILE%\.eco\config.properties` | ECO | | `STEAM_CONFIG_PATH` | `%USERPROFILE%\.eco\config.properties` | Steam | ### 配置项参考 ```properties # BUFF 平台 buff.account=账号名 buff.session=SessionCookie值 # C5 平台 c5.account=账号名 c5.steamId=Steam账号ID c5.appKey=AppKey c5.phone=手机号 c5.uid=用户UID # ECO 平台 eco.partnerId=PartnerID eco.privateKey=RSA私钥(PKCS#8格式) # Steam 平台 steamId=Steam账号ID steam.account=登录账号 steam.password=登录密码 steam.sharedSecret=手机令牌SharedSecret steam.identitySecret=手机令牌IdentitySecret steam.apikey=WebAPIKey # 无需填写,自动获取 steam.communityToken=CommunityToken steam.accessToken=AccessToken steam.session=SessionCookie ``` > **安全提示**: 所有敏感信息均从配置文件读取,不在代码中硬编码,也不通过 MCP 对话传输。 ### 网络配置 项目内置 Steam CDN 域名替换,解决国内网络无法直连 `steamcommunity.com` 的问题: - **CDN 域名**: `steamcdn-a.akamaihd.net`(Akamai CDN,可合法代理 steamcommunity.com) - **工作原理**: 检测到请求 URL 包含 `steamcommunity.com` 域名时,自动替换为 CDN 域名并添加原始 `Host` 请求头 - **302 重定向**: 自动处理 CDN 返回的 3xx 重定向,确保重定向请求也通过 CDN 转发(不会回落到原始域名导致超时) - **Cookie 管理**: 自动将原始域名的 Cookie 迁移到 CDN 域名,初始携带 `steamLoginSecure` 和 `sessionid` - **代理可选**: 如果配置了 `HTTP_PROXY` 环境变量或 JVM 参数 `proxy.host` / `proxy.port`,会优先走代理 ```yaml # application.yml 中也可配置 jteam: proxy: host: 127.0.0.1 port: 7890 ``` > 直接请求 `steamcommunity.com` 在国内会被 DNS 污染或 TCP 阻断,CDN 替换是默认启用的解决方案。推荐配合代理使用以获得更好的稳定性。 ### 应用配置 (application.yml) ```yaml server: port: 8081 spring: application: name: mcp-spring-boot-demo datasource: url: jdbc:sqlite:./data/work_order.db driver-class-name: org.sqlite.JDBC jpa: hibernate: ddl-auto: update show-sql: false generate-ddl: true properties: hibernate: dialect: org.hibernate.community.dialect.SQLiteDialect ai: mcp: server: name: jteam-mcp version: 1.0.0 protocol: STATELESS type: SYNC annotation-scanner: enabled: true session-timeout: 7200 heartbeat: enabled: true interval: 30 async: enabled: true thread-pool-size: 10 ``` ## 数据持久化 项目使用 SQLite 数据库存储订单信息,首次启动时会自动在 `./data/` 目录下创建 `work_order.db` 文件。 **核心实体** — `tb_order` 表: | 字段 | 类型 | 说明 | |------|------|------| | id | String | 主键 | | trade_offer_id | String | Steam 交易报价 ID | | buff_good_id | String | BUFF 商品 ID | | phone | String | 手机号 | | account_type | String | 账户类型 (STEAM/BUFF/C5/ECO) | | account | String | 账号 | | steam_id | String | Steam ID | | type | Integer | 订单类型 | | status | String | 订单状态 | | price | String | 价格 | | goods_name | String | 商品名称 | | icon_url | String | 商品图标 URL | | asset_id | String | 资产 ID | | create_time | LocalDateTime | 创建时间 | | update_time | LocalDateTime | 更新时间 | ## MCP 工具列表 (26 个) ### BUFF 平台 (7 个) | 工具名 | 功能 | 参数 | |--------|------|------| | `buff_check_login` | 校验 BUFF 登录状态 | 无 | | `buff_query_on_sell` | 查询在售商品列表 | 无 | | `buff_get_to_deliver_order` | 获取待发货订单数量 | 无 | | `buff_get_order_items` | 获取待发货订单列表 | 无 | | `buff_query_goods_info` | 根据商品 ID 查询商品信息 | `goodsId` (Long) | | `buff_on_sell` | 上架商品到 BUFF | `assetIds`, `prices`, `marketHashNames` | | `buff_cancel_on_sell` | 下架商品 | `assetIds` (List) | ### C5 平台 (5 个) | 工具名 | 功能 | 参数 | |--------|------|------| | `c5_check_login` | 校验 C5 登录状态 | 无 | | `c5_query_user` | 查询 C5 用户信息 (含余额、绑定 Steam) | 无 | | `c5_query_to_deliver_orders` | 查询待发货订单 | 无 | | `c5_query_delivering_orders` | 查询发货中订单 | 无 | | `c5_deliver_orders` | 批量发起报价/发货 | `orderIds` (List) | ### ECO 平台 (6 个) | 工具名 | 功能 | 参数 | |--------|------|------| | `eco_query_balance` | 查询账户余额 | 无 | | `eco_query_steam_accounts` | 查询绑定的 Steam 账号列表 | 无 | | `eco_query_seller_orders` | 查询卖家订单列表 | `steamId`, `startTime`, `endTime`, `state`, `pageIndex`, `pageSize` | | `eco_query_order_detail` | 查询订单详情 | `orderNum` | | `eco_query_goods_price` | 批量查询商品价格 | `hashNames` (List) | | `eco_generate_sign` | 生成 RSA-SHA256 签名 | 无 | ### Steam 平台 (6 个) | 工具名 | 功能 | 参数 | |--------|------|------| | `steam_check_login` | 校验 Steam 登录状态 | 无 | | `steam_refresh_token` | 刷新登录 Token (自动重新登录) | 无 | | `steam_get_inventory` | 获取 CS2 库存物品 | 无 | | `steam_get_trade_offer` | 获取交易报价详情 | `tradeOfferId` | | `steam_accept_trade_offer` | 批量接受交易报价,发货成功后将订单信息落库 tb_order | `tradeOfferIds` (List), `orderInfoList` (List) | | `get_steam_code` | 获取 Steam 动态令牌 (Steam Guard 5 位码) | 无 | ### 本地订单 (2 个) | 工具名 | 功能 | 参数 | |--------|------|------| | `order_query` | 查询本地订单记录 (tb_order),支持多条件过滤 | `account`, `status`, `accountType`, `tradeOfferId`, `buffGoodId`, `limit` (均可选) | | `order_stats` | 查询订单统计信息 (总数、总利润、平台/状态分布) | 无 | ## 核心功能详解 ### BUFF 平台集成 - **认证方式**: Session Cookie - **商品上架**: 支持批量上架,通过 `sell_order/create/manual_plus` 接口 - **商品下架**: 按 assetid 批量取消 - **在售查询**: 分页查询,最大 500 条/次 - **待发货管理**: 查询待发货订单数量和详细列表 ### C5 平台集成 - **认证方式**: app-key 参数 - **用户信息**: 查询用户基本信息、余额、绑定 Steam 账号列表 - **订单管理**: 待发货/发货中订单查询 - **批量发货**: 批量发起交易报价 ### ECO 平台集成 - **认证方式**: RSA-SHA256 签名 (PartnerId + Timestamp + Sign) - **签名算法**: 参数按字母排序拼接 → RSA-SHA256 签名 → Base64 编码 - **余额查询**: 查询账户总余额 - **订单管理**: 支持分页、时间范围、状态过滤的卖家订单查询 - **价格查询**: 批量查询商品售价 ### Steam 平台集成 - **登录系统**: RSA 加密密码 → BeginAuthSession → 手机令牌验证 → 获取 Token → 自动保存配置 - **Token 管理**: 自动检测登录状态,失效时重新登录并更新配置文件 - **库存查询**: 获取 CS2 (appid=730) 库存物品列表 - **交易报价**: 查询详情 + 批量接受 + 手机令牌确认,支持一次传入多个交易单号,全部处理完成后统一落库 - **动态令牌**: 基于 sharedSecret 生成 Steam Guard 5 位验证码 (30 秒周期) - **设备模拟**: 模拟 Android 设备 ID 进行令牌确认 ## 在 AI 客户端中配置 ### Qwen Code 配置示例 ```json { "mcpServers": { "jteam-mcp": { "command": "java", "args": ["-jar", "C:/Users/whr/md/jteam-mcp/target/jteam-mcp-1.0.0.jar"] } } } ``` 或者使用 HTTP 模式: ```json { "mcpServers": { "jteam-mcp": { "url": "http://localhost:8081/mcp/message", "transport": { "type": "streamable_http" } } } } ``` ### Trae 配置示例 在 Trae 的 MCP 配置文件 (`%APPDATA%\Trae CN\User\mcp.json`) 中添加: ```json { "mcpServers": { "jteam-mcp": { "url": "http://localhost:8081/mcp/message", "transport": { "type": "streamable_http" } } } } ``` ### 自动 Session 恢复 Buff 平台支持 session 自动恢复(`remember_me` 机制): - 每次 `buff_check_login` 校验登录状态成功后,自动从 CookieJar 中读取最新的 `session` 和 `remember_me` - 如果服务端下发了新的 session cookie,自动同步更新到配置文件(`accounts.json`) - 即使 session 过期,只要 `remember_me` 配置有效,服务端会自动下发新的 session ## 自定义工具 添加新工具非常简单,在 `tool` 包下的 Component 类中添加 `@McpTool` 注解方法: ```java @Component public class XxxMcpTools { @McpTool(name = "my_tool", description = "工具功能描述") public String myTool( @McpToolParam(description = "参数描述", required = true) String param) { // 业务逻辑 return "结果"; } } ``` ## 日志配置 日志默认输出到 `./logs/` 目录(可通过 `LOG_HOME` 环境变量自定义路径)。 | 日志文件 | 内容 | |----------|------| | `mcp-server.log` | 全部日志 (每天滚动,保留 30 天,总上限 3GB) | | `mcp-tools.log` | MCP 工具执行日志 | | `api-requests.log` | API 请求/响应日志 | | `errors.log` | 错误日志 (仅 ERROR 级别) | 日志配置位于 `src/main/resources/logback-spring.xml`,单文件最大 100MB,总上限 3GB。 ## 异常体系 错误码按模块划分: | 模块 | 错误码范围 | 说明 | |------|------------|------| | 用户相关 | 100000~100010 | 登录过期、参数校验、权限等 | | 账号相关 | 110001 | 不支持的账户类型 | | BUFF 平台 | 200001~200002 | Steam 绑定校验、下架失败 | | 订单相关 | 300001~300002 | 交易单状态异常、令牌确认异常 | | Steam 平台 | 400001~400003 | 冷却未解除、令牌验证、创建交易单失败 | | 网络异常 | 500001~500002 | 代理不可用、请求失败 | ## 常见问题 **Q: 工具没有被 AI 识别?** A: 检查以下几点: 1. 类是否有 `@Component` 注解 2. 方法是否有 `@McpTool` 注解 3. 参数是否有 `@McpToolParam` 注解 4. `application.yml` 中 `spring.ai.mcp.server.annotation-scanner.enabled` 是否为 `true` **Q: BUFF/C5/ECO 登录失败?** A: 检查配置文件中对应平台的 session/appKey/privateKey 是否有效,配置文件路径是否正确。 **Q: Steam 登录失败?** A: 确保配置文件中 `steam.account`、`steam.password`、`steam.sharedSecret` 等信息正确,且账号未被 Steam Guard 锁定。 **Q: 如何调试?** A: 在 `application.yml` 中设置日志级别: ```yaml logging: level: com.jteam.mcp: DEBUG ``` ## 安全说明 1. 所有平台敏感信息均从配置文件读取,不在代码中硬编码 2. 不在 MCP 对话中传输 privateKey、appKey、session 等敏感信息 3. 日志系统自动按级别分类输出 4. ECO 平台使用 RSA-SHA256 签名保证请求完整性 5. Steam 密码通过 RSA 公钥加密后传输 ## License 本项目基于 MIT License 开源授权。