# mcp-micro-tools

<div align="center">

**Agent 的瑞士军刀 —— 把 LLM 不擅长的微任务交给它**

[![PyPI](https://img.shields.io/badge/pypi-v0.1.0-blue)](https://pypi.org/project/mcp-micro-tools/)
[![MCP](https://img.shields.io/badge/MCP-compatible-green)](https://modelcontextprotocol.io/)
[![Python](https://img.shields.io/badge/python-3.10+-blue)](https://python.org)

</div>

---

## 为什么需要这个？

大模型在处理自然语言时很强，但有些"精确计算"类的任务经常出错：

| 任务 | 模型表现 | mcp-micro-tools |
|------|---------|-----------------|
| "3月15日 + 45个工作日是哪天" | 经常算错 | `time_calc("2026-03-15 + 45 days")` ✅ |
| 复杂正则提取 | 编造正则、幻觉匹配 | `regex_test()` 真实 Python re 引擎 ✅ |
| Base64 解码 | 偶尔编造内容 | `decode()` 精确计算 ✅ |
| URL query 参数提取 | 可能遗漏 | `url_parse()` 结构化输出 ✅ |
| JSON 深度对比 | 100行以上必丢字段 | `json_diff()` 递归精确对比 ✅ |

**一句话**：把确定性计算还给工具，把不确定性推理留给模型。

---

## 安装

```bash
pip install mcp-micro-tools
```

需要 Python 3.10+。

---

## 配置 AI Agent

### Claude Code / Claude Desktop

```json
{
  "mcpServers": {
    "micro-tools": {
      "command": "python",
      "args": ["-m", "mcp_micro_tools.server"]
    }
  }
}
```

### Codex / Cursor / Continue

```json
{
  "mcpServers": {
    "micro-tools": {
      "command": "python",
      "args": ["-m", "mcp_micro_tools.server"]
    }
  }
}
```

### OpenClaw

在 `openclaw.json` 中添加：

```json
{
  "mcp_servers": [
    {
      "name": "micro-tools",
      "command": "python",
      "args": ["-m", "mcp_micro_tools.server"]
    }
  ]
}
```

---

## 工具列表

| 工具 | 功能 | 示例 |
|------|------|------|
| `time_calc` | 日期时间运算 | `"now + 3 weeks - 1 day"` |
| `timezone_convert` | 时区转换 | UTC → Asia/Shanghai |
| `regex_test` | 正则测试（findall/search/match/split） | 提取所有邮箱 |
| `regex_replace` | 正则替换 | 格式化电话号码 |
| `encode` | 编码 | base64 / URL / hex / HTML |
| `decode` | 解码 | base64 / URL / hex / HTML |
| `json_query` | JSON 路径查询 | `users.0.email` |
| `json_diff` | JSON 深度对比 | 递归找出所有差异 |
| `url_parse` | URL 解析 | scheme / host / path / query |
| `hash_text` | 哈希计算 | md5 / sha1 / sha256 / sha512 |
| `generate_uuid` | UUID 生成 | 单个或批量 |

---

## 使用示例

### 场景 1：时间计算

```
User: "合同签于 2026-03-15，90 个工作日后是哪天？"

Agent 调用 → time_calc("2026-03-15 + 90 days")
结果 → 2026-06-13T00:00:00
```

### 场景 2：正则提取

```
User: "从这段日志里提取所有 IP 地址"

Agent 调用 → regex_test("\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}", log_text)
结果 → ["192.168.1.1", "10.0.0.5", ...]
```

### 场景 3：JSON 对比

```
User: "对比这两个 API 返回的 JSON，看看少了什么字段"

Agent 调用 → json_diff(api_response_a, api_response_b)
结果 → {"users[2].email": {"removed": "..."}, "metadata.version": {"changed": {...}}}
```

### 场景 4：编码解码

```
User: "这段 Base64 解码出来是什么？"

Agent 调用 → decode("SGVsbG8gV29ybGQ=", "base64")
结果 → Hello World
```

---

## 设计哲学

1. **零依赖（核心）**：除 `mcp` 和 `python-dateutil` 外，只用 Python 标准库
2. **单文件**：核心逻辑一个 `server.py`，方便审查和 fork
3. **无状态**：每次调用独立，不存任何数据
4. **静默输出**：只返回结果，不废话

---

## 扩展

欢迎贡献更多微工具。一个好的微工具满足：

- LLM 天然不擅长（精确计算、结构化操作）
- 输入输出明确（可 JSON 序列化）
- 单次调用完成（无状态）

PR 直接开，README 底部留个 Credits 就够。

---

## License

MIT

---

## 相关项目

- [awesome-mcp-servers](https://github.com/punkpeye/awesome-mcp-servers) — MCP Server 合集
- [Superpowers](https://github.com/obra/superpowers) — Agent Skill 框架
- [OpenClaw](https://github.com/openclaw/openclaw) — 跨平台 AI 助手
- [claw-code](https://github.com/ultraworkers/claw-code) — Claude Code Rust 实现