npm package: @starstar214/kyt-mcp-server
Description: MCP Server for Beosin KYT API - Blockchain risk assessment
Author: starstar214
Latest version: 1.0.4

# KYT MCP Server

MCP (Model Context Protocol) Server for Beosin KYT API - 区块链风险评估服务

## 功能概述

本 MCP Server 封装了 Beosin KYT 的3个API接口，为大模型提供区块链地址和交易风险评估能力：

| 工具名称 | 功能 | 场景 |
|---------|------|------|
| `get_address_risk` | 地址风险评估 | 评估钱包地址风险等级 |
| `get_deposit_transaction_risk` | 存款交易风险评估 | 评估资金来源风险 |
| `get_withdraw_transaction_risk` | 提款交易风险评估 | 评估资金去向风险 |

## 安装

### 1. 安装依赖

```bash
npm install
```

### 2. 编译 TypeScript

```bash
npm run build
```

### 3. 配置环境变量

设置以下环境变量：

```bash
export KYT_APP_ID="your_app_id"
export KYT_APP_SECRET="your_app_secret"
export KYT_BASE_URL="https://api.beosin.com"  # 可选，默认值
export KYT_TIMEOUT="30000"  # 可选，默认30000ms
```

或在 Windows (PowerShell)：

```powershell
$env:KYT_APP_ID="your_app_id"
$env:KYT_APP_SECRET="your_app_secret"
```

## 使用

### 启动服务器

```bash
npm start
# 或
node dist/index.js
```

服务器通过 stdio 与大模型通信。

## 配置到大模型

### Cursor

1. 打开 Cursor 设置 (Cmd/Ctrl + ,)
2. 进入 **MCP** 页面
3. 点击 **Add new MCP Server**
4. 填写配置：

```json
{
  "name": "kyt-risk-assessment",
  "command": "node",
  "args": ["/path/to/kyt-mcp-server/dist/index.js"],
  "env": {
    "KYT_APP_ID": "your_app_id",
    "KYT_APP_SECRET": "your_app_secret"
  }
}
```

### Claude Desktop

编辑 `claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "kyt": {
      "command": "node",
      "args": ["/path/to/kyt-mcp-server/dist/index.js"],
      "env": {
        "KYT_APP_ID": "your_app_id",
        "KYT_APP_SECRET": "your_app_secret"
      }
    }
  }
}
```

配置文件位置：
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

### 其他支持 MCP 的大模型

参考您使用的大模型的 MCP 配置文档，配置方式类似。

## API 工具详情

### get_address_risk

评估区块链地址的风险等级。

**参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| chainId | string | 是 | 链ID (1=Ethereum, 137=Polygon, 43114=Avalanche) |
| address | string | 是 | 地址哈希 |
| token | string | 否 | 代币地址 (非原生代币时必填) |

**返回：**
- `score`: 总风险评分
- `riskLevel`: 风险等级 (Severe/High/Medium/Low)
- `incomingScore`: 入金风险评分
- `outgoingScore`: 出金风险评分
- `incomingDetail`/`outgoingDetail`: 详细风险因素

### get_deposit_transaction_risk

评估存款/入金交易风险。

**参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| chainId | string | 是 | 链ID |
| hash | string | 是 | 交易哈希 |
| token | string | 否 | 代币地址或名称 |

**返回：**
- `score`: 风险评分
- `riskLevel`: 风险等级
- `risks[]`: 风险详情列表

### get_withdraw_transaction_risk

评估提款/出金交易风险。

**参数：**
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| chainId | string | 是 | 链ID |
| hash | string | 是 | 交易哈希 |
| token | string | 否 | 代币地址或名称 |

**返回：**
- `score`: 风险评分
- `riskLevel`: 风险等级
- `risks[]`: 风险详情列表

## 示例对话

```
用户: 评估这个地址的风险等级: 0xc0e80a623c9593b3c3911682d2084c4e93bea4a7，链是以太坊

大模型调用: get_address_risk({ chainId: "1", address: "0xc0e80a623c9593b3c3911682d2084c4e93bea4a7" })

返回: {
  "code": 200,
  "data": {
    "score": 90,
    "riskLevel": "Low",
    ...
  }
}
```

## 错误处理

| 错误码 | 说明 |
|-------|------|
| 40001 | 参数错误 |
| 40021 | 不支持的平台 |
| 40023 | 交易哈希错误 |
| 41023 | 交易哈希不存在 |
| 41024 | 不支持非ERC-20交易评估 |
| 41035 | 代币不在代币篮子中 |
| 41038 | 任务正在执行中，稍后重试 |

## 开发

```bash
# 开发模式 (自动编译并运行)
npm run dev

# 类型检查
npx tsc --noEmit
```