# 🔧 MCP Toolkit Server

> 基于 **Model Context Protocol (MCP)** 的多功能工具服务器，提供文件操作、数据库查询、Web 搜索、计算等工具，可被 Claude Desktop、Cursor、Cline 等 MCP 客户端接入。

## ✨ 功能特性

### 📁 文件操作工具
- `list_directory` - 列出目录内容
- `read_file` - 读取文本文件
- `write_file` - 写入/追加文件
- `file_info` - 获取文件元信息
- `search_files` - 按通配符搜索文件

### 🗄️ 数据库工具
- `query_database` - 执行 SQL SELECT 查询（只读安全）
- `list_tables` - 列出所有表
- `describe_table` - 查看表结构
- `init_sample_database` - 初始化示例数据库

### 🌐 Web 工具
- `web_search` - DuckDuckGo 网页搜索（无需 API Key）
- `fetch_webpage` - 抓取网页正文内容
- `webpage_info` - 获取网页元信息

### 🧮 计算工具
- `calculate` - 安全数学表达式计算
- `convert_unit` - 单位转换（长度/重量/温度/面积/体积）
- `date_calculation` - 日期计算（差值/加减）
- `percentage_calculation` - 百分比计算

## 🏗️ 架构设计

```
┌─────────────────────────────────────────────────────┐
│              MCP 客户端 (Claude/Cursor)              │
└──────────────────────┬──────────────────────────────┘
                       │ MCP Protocol (stdio / HTTP)
┌──────────────────────▼──────────────────────────────┐
│              FastMCP Server 核心                      │
│  ┌──────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐ │
│  │ 文件工具  │ │ 数据库工具│ │Web工具 │ │ 计算工具  │ │
│  └──────────┘ └──────────┘ └────────┘ └──────────┘ │
└─────────────────────────────────────────────────────┘
```

## 📦 安装

```bash
# 克隆仓库
git clone <repo-url>
cd mcp-toolkit-server

# 创建虚拟环境
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp .env.example .env
```

## 🚀 使用方法

### 1. 直接运行（stdio 模式）

```bash
python server.py
```

### 2. HTTP 模式

```bash
python server.py --transport http --host 127.0.0.1 --port 8000
```

### 3. 接入 Claude Desktop

编辑 Claude Desktop 配置文件（`claude_desktop_config.json`）：

```json
{
  "mcpServers": {
    "toolkit": {
      "command": "python",
      "args": ["path/to/mcp-toolkit-server/server.py"],
      "env": {
        "ALLOWED_DIRS": "/path/to/your/workspace"
      }
    }
  }
}
```

### 4. 接入 Cursor

在 Cursor 设置 → MCP 中添加：

```json
{
  "mcpServers": {
    "toolkit": {
      "command": "python",
      "args": ["path/to/mcp-toolkit-server/server.py"]
    }
  }
}
```

## 📁 项目结构

```
mcp-toolkit-server/
├── server.py                 # MCP 服务器主入口
├── config.py                 # 配置管理
├── requirements.txt          # 依赖
├── .env.example              # 环境变量模板
├── .gitignore
├── README.md
└── src/
    ├── __init__.py
    └── tools/
        ├── __init__.py
        ├── file_tools.py     # 文件操作工具
        ├── db_tools.py       # 数据库查询工具
        ├── web_tools.py      # Web 搜索/抓取工具
        └── calc_tools.py     # 计算/转换工具
```

## 🔒 安全机制

1. **路径隔离**: 文件操作限制在 `ALLOWED_DIRS` 配置的目录内，防止路径遍历
2. **SQL 只读**: 数据库工具仅允许 SELECT 查询，禁止写操作
3. **标识符校验**: 表名等标识符通过正则校验，防止 SQL 注入
4. **表达式沙箱**: 数学计算使用受限的 eval 环境，禁止访问内置函数

## 🎯 核心亮点

1. **符合 MCP 规范**: 基于官方 FastMCP 框架，兼容所有 MCP 客户端
2. **工具丰富**: 4 大类 17 个工具，覆盖常见开发场景
3. **安全优先**: 多层安全机制，防止滥用
4. **易于扩展**: 模块化设计，新增工具只需编写函数并注册
5. **双传输模式**: 支持 stdio（本地）和 HTTP（远程）两种传输方式

## 🤝 扩展方向

- [ ] 添加 Git 操作工具
- [ ] 添加代码执行工具（沙箱化）
- [ ] 添加邮件发送工具
- [ ] 添加日历管理工具
- [ ] 支持工具权限细粒度控制
- [ ] 添加工具调用审计日志

## 📄 License

MIT