Metadata-Version: 2.4
Name: chuanglan-mcp-server
Version: 1.0.0
Summary: MCP Server for Chuanglan 253 SMS Platform - 创蓝 253 短信平台 MCP 服务器
Author-email: ChuangLan <support@chuanglan.com>
License: MIT
Project-URL: Homepage, https://github.com/chuanglan/chuanglan-mcp-server
Project-URL: Documentation, https://github.com/chuanglan/chuanglan-mcp-server#readme
Project-URL: Repository, https://github.com/chuanglan/chuanglan-mcp-server.git
Project-URL: Issues, https://github.com/chuanglan/chuanglan-mcp-server/issues
Keywords: mcp,chuanglan,sms,modelscope,fastmcp,253
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: build>=1.4.0
Requires-Dist: fastmcp>=0.1.0
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: tenacity>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Requires-Dist: twine>=4.0.0; extra == "dev"
Dynamic: license-file

# 创蓝 253 MCP Server

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![ModelScope](https://img.shields.io/badge/modelscope-ready-purple.svg)](https://modelscope.cn/)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-ruff-black.svg)](https://github.com/astral-sh/ruff)

**创蓝 253 短信平台 MCP 服务器 - 企业级实现**

基于 FastMCP 框架构建，提供短信发送、余额查询、状态报告等功能的标准化 MCP 接口。

## 特性

- 企业级代码质量
- 完整的类型注解
- Pydantic 数据验证
- 异步 I/O 支持
- 完善的错误处理
- 完整的测试覆盖
- 详细的文档

## 快速开始

### 1. 环境要求

- Python >= 3.10
- pip >= 21.0

### 2. 安装依赖

```bash
pip install -r requirements.txt
```

### 3. 配置

```bash
# 复制环境变量模板
cp .env.example .env

# 编辑 .env 文件，填入创蓝账号信息
```

### 4. 运行

```bash
# 方式一：使用 uvicorn 运行
fastmcp run src/chuanglan_mcp/server.py

# 方式二：直接运行
python -m chuanglan_mcp
```

## 目录结构

```
chuanglan-mcp/
├── src/
│   └── chuanglan_mcp/
│       ├── __init__.py          # 包初始化
│       ├── __main__.py          # 入口点
│       ├── server.py            # MCP 服务器定义
│       ├── client.py            # 创蓝 API 客户端
│       ├── config.py            # 配置管理
│       ├── models.py            # 数据模型
│       └── exceptions.py        # 自定义异常
├── tests/
│   ├── __init__.py
│   ├── conftest.py              # pytest 配置
│   ├── test_client.py           # 客户端测试
│   ├── test_server.py           # 服务器测试
│   └── test_models.py           # 模型测试
├── examples/
│   ├── basic_usage.py           # 基础使用示例
│   └── advanced_usage.py        # 高级使用示例
├── docs/
│   ├── api.md                   # API 文档
│   └── deployment.md            # 部署文档
├── scripts/
│   ├── lint.py                  # 代码检查
│   └── test.py                  # 运行测试
├── .env.example                 # 环境变量示例
├── .gitignore
├── LICENSE
├── README.md
├── README_EN.md                 # 英文文档
├── pyproject.toml               # 项目配置
├── requirements.txt             # 依赖
├── requirements-dev.txt         # 开发依赖
└── setup.cfg                    # 安装配置
```

## MCP 工具

| 工具 | 描述 | 参数 |
|------|------|------|
| `send_template_sms` | 发送模板短信 | phone, template_id, params, extend, batch_id |
| `query_balance` | 查询余额 | 无 |
| `query_status` | 查询发送状态 | task_id, start_time, end_time, page, page_size |

## 配置说明

### 环境变量

| 变量 | 必填 | 说明 |
|------|------|------|
| `CHUANGLAN_ACCOUNT` | 是 | 创蓝 API 账号 |
| `CHUANGLAN_PASSWORD` | 是 | 创蓝 API 密码 |
| `CHUANGLAN_SMS_URL` | 否 | 短信发送地址（默认：https://smssh1.253.com/msg/json） |
| `CHUANGLAN_BALANCE_URL` | 否 | 余额查询地址（默认：https://smssh1.253.com/msg/balance/json） |
| `CHUANGLAN_STATUS_URL` | 否 | 状态报告地址（默认：https://smssh1.253.com/msg/status/json） |
| `REQUEST_TIMEOUT` | 否 | 请求超时时间（默认：30 秒） |

## 开发指南

### 运行测试

```bash
# 安装开发依赖
pip install -r requirements-dev.txt

# 运行所有测试
pytest tests/

# 运行测试并生成覆盖率报告
pytest tests/ --cov=chuanglan_mcp --cov-report=html
```

### 代码检查

```bash
# 运行 Ruff 检查
ruff check src/

# 运行 Ruff 格式化
ruff format src/

# 运行 mypy 类型检查
mypy src/
```

## 部署

### 本地开发

```bash
pip install -e .
```

### 生产环境

```bash
# 构建包
pip install build
python -m build

# 安装
pip install dist/chuanglan_mcp_server-*.whl
```

### 魔搭社区发布

1. 访问 [魔搭社区](https://modelscope.cn/) 注册账号
2. 创建新模型
3. 上传项目文件
4. 填写模型卡片
5. 发布版本

详细步骤请参考 [docs/deployment.md](docs/deployment.md)

## API 文档

完整的 API 文档请参考 [docs/api.md](docs/api.md)

## 常见问题

### Q: 如何获取创蓝账号？

A: 访问 [创蓝 253 官网](https://www.253.com/) 注册账号

### Q: 模板 ID 如何获取？

A: 登录创蓝控制台，创建短信模板并审核通过后获得

### Q: 返回码 102 是什么意思？

A: 密码错误，请检查密码配置

## 相关资源

- [创蓝 253 官网](https://www.253.com/)
- [创蓝 API 文档](https://doc.chuanglan.com/)
- [FastMCP 文档](https://github.com/jlowin/fastmcp)
- [魔搭社区](https://modelscope.cn/)
- [MCP 协议](https://modelcontextprotocol.io/)

## 许可证

MIT License

## 联系方式

- 技术支持：support@chuanglan.com
- 项目地址：https://github.com/chuanglan/chuanglan-mcp-server
