<div align="center">

<img src="assets/logo.jpg" alt="SteamDT MCP Logo" width="160" style="border-radius: 50%; box-shadow: 0 0 20px rgba(0, 195, 255, 0.4);" />

# SteamDT MCP (Flagship Edition)
### 🚀 全网最全的 CS2 饰品行情、多维技术面与 3D 渲染决策 MCP 服务

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg?style=for-the-badge&logo=python&logoColor=white)](https://www.python.org/)
[![MCP Protocol](https://img.shields.io/badge/MCP-Protocol%202024--11--05-orange.svg?style=for-the-badge&logo=anthropic&logoColor=white)](https://modelcontextprotocol.io/)
[![FastMCP](https://img.shields.io/badge/Built%20with-FastMCP-green.svg?style=for-the-badge)](https://github.com/jlowin/fastmcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT)

<p align="center">
  <b>让你的 AI Agent（Claude、Codex、Cursor、Antigravity）直接化身职业级 CS2 饰品操盘手与验货专家</b>
</p>

</div>

---

<p align="center">
  <img src="assets/banner.jpg" alt="SteamDT MCP Banner" width="100%" style="border-radius: 12px; box-shadow: 0 8px 30px rgba(0,0,0,0.5);" />
</p>

---

## 📖 项目简介 (Overview)

**`steamDT-mcp`** 是针对 CS2（反恐精英 2）饰品交易市场打造的下一代 Model Context Protocol (MCP) 服务端。

它 **100% 完整封装了 [SteamDT 官方开放平台](https://open.steamdt.com) 的全部 10 大核心 API**，并结合本地高性能分词引擎，将数据能力提升至 **12 大超级工具**。

告别只能查静态报价的简易机器人，赋予你的大模型获取 **365 天高精度日 K 线**、**官方大盘 24H 实时分时走势**、以及 **免登游戏云端 3D 渲染武器正反面 8K 检视图** 的顶尖超能力！

---

## ✨ 核心特性 (Key Features)

- 📊 **365 天全量 K 线形态**：大盘日 K 线与任意单品日 K 线（开/高/低/收/最新价），轻松回溯牛熊周期与支撑位。
- 📈 **官方大盘分时引擎**：实时提取大盘点位、日内涨跌幅、以及 24 小时完整分时波动序列。
- 🔍 **云端 3D 高清免进游戏检视**：输入检视链接，云端 GPU 直接渲染正/反两面高清特写图，磨损掉漆、模板与印花一览无余。
- ⚡ **本地全量饰品字典库**：自动持久化缓存全网所有 CS2 饰品中英文映射，毫秒级模糊检索、拼音缩写与别名识别（如 `usp`, `ak`, `沙鹰`）。
- 🛡️ **高可用与风控防御**：内置 4005 智能限流重试、SSL 容错通道与凭据隔离保护，开箱即用。

---

## 🛠 12 大工具全量矩阵 (Tool Catalog)

| 分类 | 工具名称 (Tool Name) | 官方接口 | 说明与输出能力 |
| :--- | :--- | :---: | :--- |
| **技术分析** | `get_item_kline` | `POST /open/cs2/item/v1/kline` | **365 天单品日 K 线**：开盘、最高、最低、收盘成交价，支持 `1=时K, 2=日K, 3=周K` |
| **大盘指数** | `get_broad_index` | `GET /open/cs2/broad/v1/index` | **官方大盘实时指数**：当前点位、涨跌点数、涨跌%及当日 24 小时逐小时走势 |
| **大盘形态** | `get_broad_kline` | `POST /open/cs2/broad/v1/kline` | **365 天大盘日 K 线**：回溯市场生命线与多空牛熊周期 |
| **云端检视** | `get_inspect_image_by_url` | `POST /open/cs2/v1/inspect` | **正反面 3D 高清渲染图**：基于 `inspectUrl` 云端渲染正反两面特写 |
| **云端检视** | `get_inspect_image_by_asmd` | `POST /open/cs2/v2/inspect` | **批量 3D 检视图渲染**：基于 ASMD 参数免进游戏云端渲染 |
| **行情报价** | `get_item_price` | `GET /open/cs2/v1/price/single` | **单品全平台深度报价**：悠悠有品、BUFF、Steam 挂单底价、在售量、求购量 |
| **批量查价** | `get_item_prices_batch` | `POST /open/cs2/v1/price/batch` | **多饰品批量极速查价**：一次调用获取多件持仓最新价格快照 |
| **均价走势** | `get_item_price_history` | `GET /open/cs2/v1/price/avg` | **多周期均价曲线**：查询指定饰品 7天 / 30天 / 90天 全网成交均价 |
| **微观磨损** | `get_item_wear_by_inspect_url`| `POST /open/cs2/v1/wear` | **精确磨损 Float 解析**：提取 0.00xxx 磨损、Paint Seed 模板号与贴纸刮损 |
| **微观磨损** | `get_item_wear_by_asmd` | `POST /open/cs2/v2/wear` | **ASMD 微观数据解析**：通过 ASMD 底层参数解析磨损与印花 |
| **数据字典** | `get_item_base_info` | `GET /open/cs2/v1/base` | **全量基础数据字典**：全网饰品数据本地持久化为 `steam_items_base.json` |
| **智能搜索** | `search_item_by_name` | 本地分词匹配引擎 | **中英模糊混合检索**：输入中文、拼音或别名即可自动匹配标准英文 HashName |

---

## 🏗 架构工作流 (Architecture)

```mermaid
flowchart TD
    User([用户/投资者]) <--> Agent[AI Agent (Claude / Codex / Cursor / Antigravity)]
    Agent <-->|MCP Protocol (stdio)| Server[SteamDT MCP Flagship Server]
    
    subgraph Local Engine [本地高性能引擎]
        Cache[(steam_items_base.json\n全量字典缓存)]
        Search[智能分词 & 别名匹配引擎]
    end
    
    subgraph SteamDT Cloud [SteamDT OpenAPI 开放平台]
        API_Price[实时价格 & 批量均价]
        API_Kline[大盘/单品 365天 K线集群]
        API_Wear[磨损解析 & ASMD 解码]
        API_Inspect[GPU 云端 3D 正反面检视渲染]
    end

    Server <--> Local Engine
    Server <-->|HTTPS Bearer Auth| SteamDT Cloud
```

---

## ⚡ 快速开始 (Quick Start)

### 1. 克隆与安装依赖

```bash
git clone https://github.com/Kairo-WU/steamDT-mcp.git
cd steamDT-mcp

pip install -r requirements.txt
```

### 2. 配置环境变量

复制 `.env.example` 为 `.env` 并填入你的 SteamDT API 密钥：

```bash
cp .env.example .env
```

编辑 `.env`：
```env
STEAMDT_API_KEY=你的SteamDT开放平台API密钥
STEAMDT_BASE_URL=https://open.steamdt.com
```
> 💡 *提示：API 密钥可在 [SteamDT 开放平台](https://open.steamdt.com) 免费申请获取。*

### 3. 本地全量测试

运行内置的端到端自动化测试脚本：
```bash
python test_steamdt_mcp.py
```

---

## 🔌 各客户端集成配置 (Client Configurations)

### 1. Claude Desktop
在 `claude_desktop_config.json` 中添加：
```json
{
  "mcpServers": {
    "steamdt": {
      "command": "python",
      "args": ["F:/MCP-Management/steamdt/server.py"],
      "env": {
        "STEAMDT_API_KEY": "你的API_KEY",
        "STEAMDT_BASE_URL": "https://open.steamdt.com"
      }
    }
  }
}
```

### 2. OpenAI Codex / Cursor
在 `config.toml` 或 `.cursor/mcp.json` 中添加：
```toml
[mcp_servers.steamdt]
type = "stdio"
command = "python"
args = ["F:/MCP-Management/steamdt/server.py"]

[mcp_servers.steamdt.env]
STEAMDT_API_KEY = "你的API_KEY"
STEAMDT_BASE_URL = "https://open.steamdt.com"
```

### 3. Antigravity / Gemini CLI (`mcp_config.json`)
```json
{
  "mcpServers": {
    "steamdt": {
      "command": "python",
      "args": ["F:/MCP-Management/steamdt/server.py"],
      "env": {
        "STEAMDT_API_KEY": "你的API_KEY"
      }
    }
  }
}
```

---

## 💬 典型调用示例 (Example Prompts)

配置完成后，你可以直接对你的 AI 助手说：

- 🗣️ **查 K 线**：*“帮我调出 USP 印花集过去一年的日 K 线，分析它现在的价格支撑区间。”*
- 🗣️ **大盘复盘**：*“查看今天大盘的实时指数和 24 小时分时走势，判断当前是放量还是缩量。”*
- 🗣️ **免进游戏验货**：*“这是我的淬火检视链接 `steam://...`，帮我渲染正反面高清检视图，并查一下磨损度。”*
- 🗣️ **快速匹配**：*“帮我查一下‘二号玩家’和‘冲出重围’对应的官方标准英文 HashName。”*

---

## 📄 开源许可证 (License)

本项目遵循 [MIT License](LICENSE) 开源协议。欢迎提交 PR、Issue 以及 Star ⭐️ 支持！