# onion-mcp-server

> A feature-rich MCP Server for [onion-ai](https://github.com/onion-ai) — 30 tools across 6 categories.

[![PyPI](https://img.shields.io/pypi/v/onion-mcp-server)](https://pypi.org/project/onion-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

## ✨ 工具列表（30 个）

| 分组 | 工具 | 说明 |
|------|------|------|
| 🤖 AI | `ai_chat` | 多轮对话，支持历史和 system prompt |
| 🤖 AI | `ai_translate` | 智能翻译，40+ 语言，自动检测源语言 |
| 🤖 AI | `ai_summarize` | 长文摘要（要点/段落/一句话） |
| 🤖 AI | `ai_rewrite` | 文本改写（正式/口语/简洁/扩写） |
| 🤖 AI | `ai_extract` | 结构化信息提取（人名/地名/关键词等） |
| 🤖 AI | `ai_classify` | 文本分类（情感/主题/意图/自定义） |
| 💻 Code | `code_explain` | 解释代码逻辑 |
| 💻 Code | `code_review` | 代码审查（Bug/安全/性能/风格） |
| 💻 Code | `code_generate` | 根据描述生成代码 |
| 💻 Code | `code_convert` | 代码语言转换 |
| 💻 Code | `code_fix` | 修复代码错误 |
| 💻 Code | `code_docstring` | 生成文档注释 |
| 📝 Text | `text_format` | JSON/YAML/纯文本格式化 |
| 📝 Text | `text_diff` | 文本差异对比（unified diff） |
| 📝 Text | `text_template` | 模板渲染（`{变量}` 语法） |
| 📝 Text | `text_count` | 字数/行数/Token 统计 |
| 📝 Text | `text_clean` | 清理文本（去空行/去重/标准化） |
| 📊 Data | `data_json_query` | JSONPath 风格查询 |
| 📊 Data | `data_csv_analyze` | CSV 数据分析与统计 |
| 📊 Data | `data_table_format` | 数据转 Markdown 表格 |
| 📊 Data | `data_convert` | JSON/CSV/YAML/TOML 互转 |
| 🌐 Web | `web_fetch` | 抓取网页内容（返回纯文本） |
| 🌐 Web | `web_search` | DuckDuckGo 搜索（无需 API Key） |
| 🌐 Web | `web_extract` | 提取网页结构化信息 |
| ⚙️ System | `sys_time` | 获取当前时间（支持时区） |
| ⚙️ System | `sys_uuid` | 生成 UUID（v1/v4） |
| ⚙️ System | `sys_hash` | 计算 Hash（md5/sha256 等） |
| ⚙️ System | `sys_base64` | Base64 编解码 |
| ⚙️ System | `sys_url_encode` | URL 编解码 |
| ⚙️ System | `sys_json_valid` | JSON 格式验证 |

## 🚀 快速开始

### 方式一：通过 onion CLI（推荐）

```bash
# 1. 设置 API Key
export ONION_MCP_API_KEY=sk-...
export ONION_MCP_MODEL=gpt-4o-mini        # 可选，默认 gpt-4o-mini
export ONION_MCP_BASE_URL=https://...     # 可选，兼容 DeepSeek/Qwen/Ollama

# 2. 添加到 onion
onion mcp add onion-mcp \
  -c uvx \
  -a '["onion-mcp-server"]' \
  --env '{"ONION_MCP_API_KEY":"sk-...","ONION_MCP_MODEL":"gpt-4o-mini"}'

# 3. 测试
onion mcp inspect onion-mcp
onion mcp call onion-mcp sys_time '{}'
onion mcp call onion-mcp ai_translate '{"text":"Hello world","target_language":"中文"}'
```

### 方式二：Claude Desktop / Cursor

```bash
# 导出配置
onion mcp config --claude-format
```

或手动添加到 `~/.config/claude/claude_desktop_config.json`：

```json
{
  "mcpServers": {
    "onion-mcp": {
      "command": "uvx",
      "args": ["onion-mcp-server"],
      "env": {
        "ONION_MCP_API_KEY": "sk-...",
        "ONION_MCP_MODEL": "gpt-4o-mini"
      }
    }
  }
}
```

### 方式三：本地开发

```bash
git clone https://github.com/onion-ai/mcp-server
cd mcp-server
pip install -e ".[all]"

export ONION_MCP_API_KEY=sk-...
python -m onion_mcp_server
```

## ⚙️ 环境变量

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `ONION_MCP_API_KEY` | API Key（必填，AI 工具需要） | — |
| `ONION_MCP_BASE_URL` | API Base URL | `https://api.openai.com/v1` |
| `ONION_MCP_MODEL` | 模型名称 | `gpt-4o-mini` |
| `ONION_MCP_MAX_TOKENS` | 最大输出 Token | `4096` |

> **兼容任何 OpenAI 格式接口**：DeepSeek、通义千问、Moonshot、本地 Ollama 等

## 📦 依赖说明

| 依赖 | 用途 | 是否必须 |
|------|------|---------|
| `mcp` | MCP 协议 | ✅ 必须 |
| `openai` | AI 工具调用 LLM | AI 工具需要 |
| `httpx` | web 工具网络请求 | web 工具需要 |
| `beautifulsoup4` | web 工具 HTML 解析 | web 工具需要 |
| `pyyaml` | YAML 格式支持 | data/text 工具可选 |

## 🔗 相关项目

- [onion-ai/onion](https://github.com/onion-ai/onion) — onion CLI 主项目
- [onion-ai/skill-hub](https://github.com/onion-ai/skill-hub) — Skill 模板仓库