# tool-mcp-server

[![npm version](https://img.shields.io/npm/v/tool-mcp-server.svg)](https://www.npmjs.com/package/tool-mcp-server)
[![Publish](https://github.com/maple-awa/tool-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/maple-awa/tool-mcp/actions/workflows/publish.yml)

一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) 的 stdio 服务端，将 [tool-website](https://github.com/sisi0318/tool-website) 的在线工具能力以 MCP Tool 的形式暴露出来，供支持 MCP 的客户端调用。

> **说明**：本项目中的工具实现移植自 [https://github.com/sisi0318/tool-website](https://github.com/sisi0318/tool-website)。

---

## 功能特性

- **58 个 MCP Tool**：包含 54 个具体工具 + 4 个元工具
- **8 大工具分类**：基础、加密、数据、开发、图片、文本、实用、预览
- **Stdio 传输**：标准 MCP stdio 协议，兼容 Claude Desktop、Cline、Windsurf 等客户端
- **工作流支持**：通过 `run_workflow` 将多个工具按有向图拓扑执行
- **完整测试覆盖**：单元测试、工具逻辑测试、MCP 协议调用测试全部通过

---

## 一键使用

如果你已经安装了 Node.js，可以直接通过 `npx` 一键启动，无需克隆仓库：

```bash
npx -y tool-mcp-server
```

---

## 安装

### 方式一：通过 npm / pnpm 安装

```bash
pnpm add -g tool-mcp-server
# 或
npm install -g tool-mcp-server
```

### 方式二：本地开发

```bash
git clone https://github.com/maple-awa/tool-mcp.git
cd tool-mcp
pnpm install
pnpm build
```

---

## MCP 客户端配置

### Claude Desktop

编辑 `claude_desktop_config.json`：

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "tool-mcp-server": {
      "command": "npx",
      "args": ["-y", "tool-mcp-server"]
    }
  }
}
```

### Cline / Roo Code

在 Cline 的 MCP Servers 设置中添加：

```json
{
  "mcpServers": {
    "tool-mcp-server": {
      "command": "npx",
      "args": ["-y", "tool-mcp-server"],
      "disabled": false,
      "autoApprove": []
    }
  }
}
```

### 本地开发配置

如果你使用本地构建产物：

```json
{
  "mcpServers": {
    "tool-mcp-server": {
      "command": "node",
      "args": ["/path/to/tool-mcp/dist/index.js"]
    }
  }
}
```

---

## 使用

### 启动 MCP 服务

```bash
pnpm start
```

服务通过 stdio 与 MCP 客户端通信。

### 开发模式

```bash
pnpm dev
```

### 测试

```bash
# 全部测试
pnpm test:all

# 仅单元测试
pnpm test:unit

# 仅工具逻辑测试
pnpm test:tools

# 仅 MCP 协议测试
pnpm test:mcp
```

---

## 工具清单

| 分类 | 数量 | 示例 |
|---|---|---|
| basic | 5 | string、number、json、file、boolean |
| crypto | 8 | hash、hmac、crypto、encoding、jwt、classic-cipher 等 |
| data | 12 | json-format、json-path、protobuf、yaml-to-json、base64-to-file 等 |
| dev | 4 | http-tester、crontab、docker-converter、whois |
| image | 8 | image-to-base64、exif-viewer、image-compress、qrcode、meme-splitter 等 |
| text | 4 | text-stats、case-converter、regex、diff |
| utility | 7 | uuid、totp、color、base-converter、currency、bmi 等 |
| viewer | 6 | device-info、office-viewer、time、string-preview、image-preview 等 |

完整的工具列表可通过 MCP 调用 `list_tools` 获取。

---

## MCP 元工具

| 工具名 | 说明 |
|---|---|
| `list_tools` | 列出所有可用工具 |
| `get_tool_schema` | 获取指定工具的输入输出 schema |
| `execute_tool` | 直接执行某个工具 |
| `run_workflow` | 按节点和边构建工作流并执行 |

每个具体工具也会以 `tool_<type>` 的形式注册，例如 `tool_hash`、`tool_qrcode`。

---

## 测试状态

- ✅ TypeScript 编译通过
- ✅ 单元测试：14 / 14 通过
- ✅ 工具逻辑测试：54 / 54 通过
- ✅ MCP 协议调用测试：58 / 58 通过

---

## 自动发布到 npm

本仓库配置了 GitHub Actions，在创建 Release 时会自动构建、测试并发布到 npm。

### 配置方法

1. 在 npm 生成 Access Token（Publish 权限）
2. 在 GitHub 仓库设置 → Secrets and variables → Actions 中添加 `NPM_TOKEN`
3. 在 GitHub 创建 Release，Actions 会自动执行发布

### 手动发布

```bash
pnpm build
pnpm test:unit
pnpm publish --access public
```

---

## 项目结构

```
├── .github/workflows/        # GitHub Actions 工作流
├── src/
│   ├── index.ts              # MCP 服务入口
│   ├── lib/adapters/         # 各工具适配器实现
│   ├── lib/canvas/           # 节点注册表和工作流引擎
│   ├── mcp/                  # MCP schema、文件工具、工作流运行器
│   ├── test-all-tools.ts     # 工具逻辑集成测试
│   ├── test-mcp-all-tools.ts # MCP 协议集成测试
│   └── tool-test-cases.ts    # 共享测试用例
├── dist/                     # 编译输出
├── package.json
├── tsconfig.json
└── vitest.config.ts
```

---

## 许可证

MIT