内容
# 短网址MCP
<!-- mcp-name: io.github.AceDataCloud/mcp-shorturl -->
[](https://pypi.org/project/mcp-shorturl/)
[](https://pypi.org/project/mcp-shorturl/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
一个用于网址缩短的 [模型上下文协议（MCP）](https://modelcontextprotocol.io) 服务器，通过 [AceDataCloud API](https://platform.acedata.cloud) 使用 [短网址 API](https://platform.acedata.cloud/documents/a2303356-6672-4eb8-9778-75f55c998fe9)。
直接从 Claude、VS Code 或任何兼容 MCP 的客户端创建短网址。
## 功能
- **网址缩短** - 将长网址转换为短的、可分享的链接
- **批量缩短** - 一次缩短多个网址（最多 10 个/批次）
- **免费服务** - 每个请求零信用消耗
- **永久链接** - 短网址永不过期
- **surl.id 域名** - 短网址使用干净的 `surl.id` 域名
- **Bearer 认证** - 使用令牌认证的安全 API 访问
## 工具参考
| 工具 | 描述 |
|------|-------------|
| `shorturl_create` | 从长网址创建短网址。 |
| `shorturl_batch_create` | 在单个批次中为多个长网址创建短网址。 |
| `shorturl_get_usage_guide` | 获取有关使用 ShortURL 工具的综合指南。 |
| `shorturl_get_api_info` | 获取有关 ShortURL API 服务的信息。 |
## 快速入门
### 1. 获取您的 API 令牌
1. 在 [AceDataCloud 平台](https://platform.acedata.cloud) 注册
2. 进入 [API 文档页面](https://platform.acedata.cloud/documents/a2303356-6672-4eb8-9778-75f55c998fe9)
3. 点击 **"获取"** 获取您的 API 令牌
4. 复制令牌以备下步使用
### 2. 使用托管服务器（推荐）
AceDataCloud 托管了一个受管理的 MCP 服务器 - **无需本地安装**。
**端点：** `https://shorturl.mcp.acedata.cloud/mcp`
所有请求都需要 Bearer 令牌。使用步骤 1 中的 API 令牌。
#### Claude.ai
直接在 [Claude.ai](https://claude.ai) 上使用 OAuth 连接 - **无需 API 令牌**：
1. 进入 Claude.ai **设置 → 集成 → 添加更多**
2. 输入服务器网址：`https://shorturl.mcp.acedata.cloud/mcp`
3. 完成 OAuth 登录流程
4. 在您的对话中使用工具
#### Claude 桌面版
添加到您的配置（`~/Library/Application Support/Claude/claude_desktop_config.json` 在 macOS 上）：
```json
{
"mcpServers": {
"shorturl": {
"type": "streamable-http",
"url": "https://shorturl.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Cursor / Windsurf
添加到您的 MCP 配置（`.cursor/mcp.json` 或 `.windsurf/mcp.json`）：
```json
{
"mcpServers": {
"shorturl": {
"type": "streamable-http",
"url": "https://shorturl.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### VS Code (Copilot)
添加到您的 VS Code MCP 配置（`.vscode/mcp.json`）：
```json
{
"servers": {
"shorturl": {
"type": "streamable-http",
"url": "https://shorturl.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
或安装 [Ace Data Cloud MCP 扩展](https://marketplace.visualstudio.com/items?itemName=acedatacloud.acedatacloud-mcp) 用于 VS Code，它通过一键设置注册托管的 MCP 服务器。
#### JetBrains IDEs
1. 进入 **设置 → 工具 → AI 助手 → 模型上下文协议（MCP）**
2. 点击 **添加** → **HTTP**
3. 粘贴：
```json
{
"mcpServers": {
"shorturl": {
"url": "https://shorturl.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Claude 代码
Claude 代码原生支持 MCP 服务器：
```bash
claude mcp add shorturl --transport http https://shorturl.mcp.acedata.cloud/mcp \
-h "Authorization: Bearer YOUR_API_TOKEN"
```
或添加到您的项目的 `.mcp.json`：
```json
{
"mcpServers": {
"shorturl": {
"type": "streamable-http",
"url": "https://shorturl.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Cline
添加到 Cline 的 MCP 设置（`.cline/mcp_settings.json`）：
```json
{
"mcpServers": {
"shorturl": {
"type": "streamable-http",
"url": "https://shorturl.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Amazon Q 开发者
添加到您的 MCP 配置：
```json
{
"mcpServers": {
"shorturl": {
"type": "streamable-http",
"url": "https://shorturl.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Roo 代码
添加到 Roo 代码的 MCP 设置：
```json
{
"mcpServers": {
"shorturl": {
"type": "streamable-http",
"url": "https://shorturl.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
```
#### Continue.dev
添加到 `.continue/config.yaml`：
```yaml
mcpServers:
- name: shorturl
type: streamable-http
url: https://shorturl.mcp.acedata.cloud/mcp
headers:
Authorization: "Bearer YOUR_API_TOKEN"
```
#### Zed
添加到 Zed 的设置（`~/.config/zed/settings.json`）：
```json
{
"language_models": {
"mcp_servers": {
"shorturl": {
"url": "https://shorturl.mcp.acedata.cloud/mcp",
"headers": {
"Authorization": "Bearer YOUR_API_TOKEN"
}
}
}
}
}
```
#### cURL 测试
```bash
# 健康检查（无需身份验证）
curl https://shorturl.mcp.acedata.cloud/health
# MCP 初始化
curl -X POST https://shorturl.mcp.acedata.cloud/mcp \
-H "Content-Type: application/json" \
-H "Accept: application/json" \
-H "Authorization: Bearer YOUR_API_TOKEN" \
-d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}}}'
```
### 3. 或在本地运行（替代方案）
如果您更喜欢在自己的机器上运行服务器：
```bash
# 从 PyPI 安装
pip install mcp-shorturl
# 或
uvx mcp-shorturl
# 设置您的 API 令牌
export ACEDATACLOUD_API_TOKEN="your_token_here"
# 运行（stdio 模式适用于 Claude Desktop / 本地客户端）
mcp-shorturl
# 运行（HTTP 模式适用于远程访问）
mcp-shorturl --transport http --port 8000
```
#### Claude 桌面版（本地）
```json
{
"mcpServers": {
"shorturl": {
"command": "uvx",
"args": ["mcp-shorturl"],
"env": {
"ACEDATACLOUD_API_TOKEN": "your_token_here"
}
}
}
}
```
#### Docker（自托管）
```bash
docker pull ghcr.io/acedatacloud/mcp-shorturl:latest
docker run -p 8000:8000 ghcr.io/acedatacloud/mcp-shorturl:latest
```
客户端使用自己的 Bearer 令牌连接 - 服务器从每个请求的 `Authorization` 头部提取令牌。
## 可用工具
### 网址缩短工具
| 工具 | 描述 |
| ----------------------- | -------------------------------------- |
| `shorturl_create` | 缩短单个网址 |
| `shorturl_batch_create` | 同时缩短多个网址（最多 10 个） |
### 信息工具
| 工具 | 描述 |
| -------------------------- | ------------------------------- |
| `shorturl_get_usage_guide` | 获取综合使用指南 |
| `shorturl_get_api_info` | 获取 API 详细信息和错误代码 |
## 使用示例
### 缩短单个网址
```
用户：缩短此网址：https://platform.acedata.cloud/documents/a2303356-6672-4eb8-9778-75f55c998fe9
Claude：我将为您缩短该网址。
[调用 shorturl_create，网址="https://platform.acedata.cloud/documents/a2303356-6672-4eb8-9778-75f55c998fe9"]
结果：https://surl.id/1uHCs01xa5
```
### 批量缩短多个网址
```
用户：为我的社交媒体帖子缩短这些网址：
- https://example.com/blog/very-long-article-title-about-ai
- https://example.com/products/new-release-2024
Claude：我将一次性缩短这两个网址。
[调用 shorturl_batch_create，网址=[...]]
```
### 为文档创建链接
```
用户：我需要为我的文档中的这些参考网址创建干净的短链接。
Claude：我将为您的所有参考资料创建短链接。
[调用 shorturl_batch_create，网址列表]
```
## 响应结构
### 成功响应
```json
{
"success": true,
"data": {
"url": "https://surl.id/1uHCs01xa5"
}
}
```
### 错误响应
```json
{
"success": false,
"error": {
"code": "api_error",
"message": "获取失败"
},
"trace_id": "2cf86e86-22a4-46e1-ac2f-032c0f2a4e89"
}
```
## 配置
### 环境变量
| 变量 | 描述 | 默认值 |
| --------------------------- | --------------------------- | --------------------------- |
| `ACEDATACLOUD_API_TOKEN` | 来自 AceDataCloud 的 API 令牌 | **必填** |
| `ACEDATACLOUD_API_BASE_URL` | API 基本网址 | `https://api.acedata.cloud` |
| `ACEDATACLOUD_OAUTH_CLIENT_ID` | OAuth 客户端 ID（托管模式） | — |
| `ACEDATACLOUD_PLATFORM_BASE_URL` | 平台基本网址 | `https://platform.acedata.cloud` |
| `SHORTURL_REQUEST_TIMEOUT` | 请求超时（秒） | `30` |
| `LOG_LEVEL` | 日志级别 | `INFO` |
### 命令行选项
```bash
mcp-shorturl --help
选项：
--version 显示版本
--transport 传输模式：stdio（默认）或 http
--port HTTP 传输端口（默认：8000）
```
## 开发
### 设置开发环境
```bash
# 克隆仓库
git clone https://github.com/AceDataCloud/ShortURLMCP.git
cd ShortURLMCP
# 创建虚拟环境
python -m venv .venv
source .venv/bin/activate # 或 `.venv\Scripts\activate` 在 Windows 上
# 安装开发依赖项
pip install -e ".[dev,test]"
```
### 运行测试
```bash
# 运行单元测试
pytest
# 运行覆盖率测试
pytest --cov=core --cov=tools
# 运行集成测试（需要 API 令牌）
pytest tests/test_integration.py -m integration
```
### 代码质量
```bash
# 格式化代码
ruff format .
# 检查代码
ruff check .
# 类型检查
mypy core tools
```
### 构建和发布
```bash
# 安装构建依赖项
pip install -e ".[release]"
# 构建包
python -m build
# 上传到 PyPI
twine upload dist/*
```
## 项目结构
```
ShortURLMCP/
├── core/ # 核心模块
│ ├── __init__.py
│ ├── client.py # ShortURL API 的 HTTP 客户端
│ ├── config.py # 配置管理
│ ├── exceptions.py # 自定义异常
│ └── server.py # MCP 服务器初始化
├── tools/ # MCP 工具定义
│ ├── __init__.py
│ ├── shorturl_tools.py # 网址缩短工具
│ └── info_tools.py # 信息工具
├── prompts/ # MCP 提示模板
│ └── __init__.py
├── tests/ # 测试套件
│ ├── conftest.py
│ ├── test_client.py
│ ├── test_config.py
│ └── test_integration.py
├── deploy/ # 部署配置
│ ├── run.sh
│ └── production/
│ ├── deployment.yaml
│ ├── ingress.yaml
│ └── service.yaml
├── .env.example # 环境模板
├── .gitignore
├── .ruff.toml # Ruff 检测器配置
├── CHANGELOG.md
├── Dockerfile # HTTP 模式的 Docker 镜像
├── docker-compose.yaml # Docker Compose 配置
├── LICENSE
├── main.py # 入口点
├── pyproject.toml # 项目配置
└── README.md
```
## API 参考
此服务器封装了 [AceDataCloud 短网址 API](https://platform.acedata.cloud/documents/a2303356-6672-4eb8-9778-75f55c998fe9)：
- **端点**：`POST /shorturl`
- **输入**：`{ "content": "https://long-url.example.com/..." }`
- **输出**：`{ "success": true, "data": { "url": "https://surl.id/..." } }`
- **定价**：免费（0 积分）
- **身份验证**：Bearer 令牌
完整 API 文档： [AceDataCloud 平台](https://platform.acedata.cloud/documents/a2303356-6672-4eb8-9778-75f55c998fe9)
## 许可证
MIT 许可证 - 参见 [LICENSE](LICENSE) 获取详细信息。
