🔧 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工具 │ │ 计算工具  │ │
│  └──────────┘ └──────────┘ └────────┘ └──────────┘ │
└─────────────────────────────────────────────────────┘

📦 安装

# 克隆仓库
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 模式）

python server.py

2. HTTP 模式

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

3. 接入 Claude Desktop

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

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

4. 接入 Cursor

在 Cursor 设置 → MCP 中添加：

{
  "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