qiuxinmcp-sms/README.md

MCP 协议手机验证码服务，支持发送验证码并返回标准格式。

# mcp-sms

基于 Model Context Protocol (MCP) 协议的手机验证码服务器。提供标准的 MCP 工具，可与 Claude Desktop、VSCode 等 MCP 客户端无缝集成。

## 功能特性

- 🔌 **标准 MCP 协议**: 完全兼容 MCP 1.0 规范
- 📱 **手机验证码**: 支持通过手机号获取验证码信息
- 🛠️ **多种运行模式**: 可作为 MCP 服务器或命令行工具使用
- 🔗 **客户端集成**: 支持 Claude Desktop、VSCode 等 MCP 客户端
- ✅ **参数验证**: 自动验证手机号格式和参数完整性
- 📝 **详细日志**: 提供完整的操作日志和错误信息

## 安装

### 通过 npm 安装

```bash
# 作为依赖安装
npm install mcp-sms

# 或全局安装
npm install -g mcp-sms
```

### 本地开发安装

```bash
# 克隆仓库
git clone <repository-url>
cd mcp-sms

# 安装依赖
npm install

# 构建项目
npm run build
```

## 使用方法

### 1. 作为 MCP 服务器运行

这是推荐的使用方式，可与各种 MCP 客户端集成：

```bash
# 直接运行（作为 MCP 服务器）
mcp-sms

# 或者
node mcp-sms.js
```

### 2. 在 MCP 客户端中配置

#### Claude Desktop 配置

编辑 Claude Desktop 配置文件：

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "mcp-sms": {
      "command": "npx",
      "args": ["mcp-sms"]
    }
  }
}
```

#### VSCode (Cline) 配置

在 VSCode 中安装 Cline 扩展，然后配置 MCP 服务器：

```json
{
  "mcpServers": {
    "mcp-sms": {
      "command": "npx",
      "args": ["mcp-sms"]
    }
  }
}
```

### 3. 命令行模式

也可以作为传统的命令行工具使用：

```bash
# 获取验证码
mcp-sms send 13800138000

# 查看帮助
mcp-sms --help
```

## MCP 工具说明

### get_verification_code

获取手机验证码的 MCP 工具。

#### 参数

| 参数名 | 类型   | 必填 | 说明                        |
|--------|--------|------|----------------------------|
| mobile | string | 是   | 手机号码（11位数字）         |

#### 返回格式

成功响应：
```json
{
  "success": true,
  "mobile": "13800138000",
  "contract_data": "合同名称《MCP协议》",
  "message": "操作成功",
  "timestamp": "2024-01-01T12:00:00.000Z"
}
```

错误响应：
```json
{
  "success": false,
  "mobile": "13800138000",
  "error": "错误信息",
  "timestamp": "2024-01-01T12:00:00.000Z"
}
```

#### 使用示例

在 Claude Desktop 中：

```
请帮我获取手机号 13800138000 的验证码
```

Claude 会自动调用 `get_verification_code` 工具并返回结果。

## API 接口

本服务使用以下 API 接口：

- **接口地址**: https://xydapi.qiuxin.tech/v1_mcp/check
- **请求方法**: GET
- **请求参数**: mobile（手机号）
- **响应字段**: contract_data（业务数据）

## 错误处理

### 常见错误

1. **手机号格式错误**
   - 错误信息：`手机号格式不正确，请输入有效的11位手机号码`
   - 解决方案：检查手机号是否为11位数字且以1开头

2. **API 调用失败**
   - 错误信息：`HTTP 错误: 500 Internal Server Error`
   - 解决方案：检查网络连接和 API 服务状态

3. **参数缺失**
   - 错误信息：`缺少必需参数: mobile`
   - 解决方案：确保传入了 mobile 参数

### 调试模式

服务器会输出详细的调试信息到 stderr，包括：

- 服务器启动信息
- API 调用日志
- 错误详情
- 响应数据

## 开发

### 项目结构

```
mcp-sms/
├── mcp-sms.js          # 主程序文件
├── package.json        # 项目配置
├── README.md          # 文档
├── .gitignore         # Git 忽略文件
└── bin/
    └── cli.js         # 命令行入口（自动生成）
```

### 本地开发

```bash
# 安装依赖
npm install

# 构建项目
npm run build

# 运行服务器
npm start

# 测试 MCP 工具
npx @modelcontextprotocol/inspector node mcp-sms.js
```

### 测试

使用 MCP Inspector 进行测试：

```bash
# 安装 MCP Inspector（如果未安装）
npm install -g @modelcontextprotocol/inspector

# 启动测试界面
npx @modelcontextprotocol/inspector node mcp-sms.js
```

在测试界面中：
1. 选择 `get_verification_code` 工具
2. 输入测试参数：`{"mobile": "13800138000"}`
3. 查看返回结果

## 系统要求

- **Node.js**: 14.16 或更高版本
- **操作系统**: Windows、macOS、Linux
- **网络**: 需要访问 https://xydapi.qiuxin.tech

## 许可证

MIT License

## 支持

如果遇到问题或有建议，请提交 Issue 或联系开发者。

## 更新日志

### v1.0.0
- 基于 MCP 协议重构
- 支持标准 MCP 客户端集成
- 新增 get_verification_code 工具
- 改进错误处理和日志记录
- 更新 API 接口至 https://xydapi.qiuxin.tech/v1_mcp/check