内容
<div align="center">
# 通用MCP
### 💍 *一个MCP统治所有，一个MCP寻找所有，*<br>*一个MCP聚集所有，并在一个服务器中绑定它们。*
</div>
通用MCP是一个Python MCP服务器，为代理和兼容MCP的客户端提供实用的工具。
## 可用工具
天气和时间：
- `get_forecast`：使用纬度和经度从Open-Meteo获取24小时天气预报。
- `search_location`：按名称搜索地点并返回纬度/经度候选项。
- `get_current_time`：获取UTC偏移量或IANA时区名称的当前日期和时间。
货币和网址：
- `get_coin_price`：使用UniRate将一种货币或加密货币转换为另一种货币。
- `shorten_url`：使用TinyURL缩短网址，无需帐户或API密钥。
哈希和编码：
- `detect_hash`：检测可能的哈希格式。
- `hash_text`：使用`md5`、`sha1`、`sha256`或`sha512`哈希文本。
- `base64_encode`：将文本编码为Base64。
- `base64_decode`：解码Base64文本。
- `url_encode`：URL编码文本。
- `url_decode`：URL解码文本。
密码和标识符：
- `generate_password`：生成一个或多个随机密码而不保存它们。
- `generate_uuid`：生成UUID v4（随机）或v7（时间有序）。
- `validate_uuid`：验证UUID字符串。
JWT、JSON和文本：
- `decode_jwt`：在不验证签名的情况下解码JWT头部和有效载荷。
- `validate_json`：验证JSON文本。
- `format_json`：格式化JSON文本。
- `minify_json`：压缩JSON文本。
- `json_keys`：列出JSON对象的顶级键。
- `text_stats`：统计字符、单词和行数。
- `transform_text`：转换文本大小写或修剪多余空格。
- `slugify_text`：创建URL友好的slug。
日期、颜色和二维码：
- `unix_timestamp_to_date`：将Unix时间戳转换为ISO日期时间。
- `date_to_unix_timestamp`：将ISO日期时间转换为Unix时间戳。
- `date_difference`：计算两个ISO日期时间之间的差值。
- `add_time`：在ISO日期时间上添加或减去时间。
- `validate_color`：验证十六进制颜色。
- `convert_color`：将十六进制转换为RGB和HSL。
- `generate_color_palette`：生成简单的十六进制颜色调色板。
- `generate_qr_code`：生成二维码PNG作为Base64数据网址。
数字和单位：
- `convert_number_base`：在基数2到36之间转换数字。
- `convert_angle`：在度、弧度、梯度之间转换角度。
- `convert_unit`：在温度、长度、质量、数据大小单位之间转换。
正则表达式和网络：
- `test_regex`：测试正则表达式与文本并列出匹配项。
- `validate_ip`：验证IPv4或IPv6地址并描述它。
- `cidr_info`：描述CIDR网络（网络掩码、范围、主机数）。
- `ip_in_cidr`：检查IP地址是否属于CIDR网络。
## 可用资源
- `currency://coins`：支持的法定货币代码的静态列表。
- `currency://crypto`：支持的加密货币代码的静态列表。
## 要求
- Python `>=3.14`
- `uv`
项目依赖项在`pyproject.toml`中定义。
## 安装
克隆仓库并安装依赖项：
```bash
git clone https://github.com/GuilhermeNobre/universal-mcp.git
cd universal-mcp
uv sync
```
## 环境变量
货币转换需要UniRate API密钥：
```bash
export UNIRATE_API_KEY="your-api-key"
```
不调用UniRate的工具无需此变量。
## 运行MCP服务器
直接运行服务器：
```bash
uv run python server.py
```
`universal-mcp.py`仍然可用作兼容性包装器，但新配置应使用`server.py`。
服务器通过MCP stdio运行，因此通常由MCP兼容客户端启动，而不是手动启动。
## MCP客户端配置
从MCP客户端使用以下命令：
```bash
uv --directory /absolute/path/to/universal-mcp run python server.py
```
示例JSON样式MCP配置：
```json
{
"mcpServers": {
"universal-mcp": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/universal-mcp",
"run",
"python",
"server.py"
],
"env": {
"UNIRATE_API_KEY": "your-api-key"
}
}
}
}
```
将 `/absolute/path/to/universal-mcp` 替换为机器上的实际路径。
## 代理说明
此仓库包含 [AGENT.md](./AGENT.md)，其中包含AI编码代理的设置和使用说明。
将其与以下内容连接时使用：
- Claude Desktop 或 Claude Code
- Codex
- 任何其他MCP兼容代理或客户端
代理在修改或安装项目之前应阅读`AGENT.md`。
## 开发说明
- 保持工具小而专注。
- 在`tools/<category>/`下添加新工具，并在模块的`TOOLS`中列出它们；`server.py`自动注册`tools.ALL_TOOLS`中的所有内容。
- 创建新模块时，在`tools/__init__.py`中导入它。
- 不存储生成的密码、机密、令牌或用户提供的敏感值。
- 优先使用异步HTTP助手来调用外部API的工具。
- 优先使用环境变量来存储API密钥。
- 在提交更改前运行检查：
```bash
uv run ruff check .
uv run ruff format --check .
uv run python -m compileall -q server.py universal-mcp.py common tools tests
uv run python -m unittest discover -s tests
```
代码检查和格式化使用`ruff`（通过`uv sync`与`dev`依赖组一起安装）。
