MCP 工具包

一个模块化的服务器实现，用于构建高精度垂直 AI 代理。 旨在用于构建高精度垂直 AI 代理，但可以部署以访问通用工具功能。

使用的代码比单独的 Python MCP SDK 少 >=50%。

这种方法的好处

• 减少 Claude 的认知负荷：Claude 不需要推理工具调用的顺序
• 封装领域知识：代理可以包含关于如何在特定垂直领域中出色地执行任务的领域特定逻辑
• 简化错误处理：代理可以内部处理错误和重试，而无需 Claude 的参与
• 启用复杂的工作流程：通过单独的工具调用难以协调的多步骤流程
• 保持对话流程：用户不会接触到底层系统的复杂性

示例场景

这是一个 Claude 调用垂直代理的具体示例：

用户："我需要一份关于电动汽车市场的全面分析，用于明天的演示。"

Claude：[意识到这需要多种工具和领域专业知识]

Claude："我将帮助您进行全面的电动汽车市场分析。 我需要收集最新的市场数据、新闻和趋势。 这需要一点时间..."

[在幕后，Claude 调用 MarketAnalysisAgent]

Claude -> MarketAnalysisAgent.analyze_market(
    sector="electric vehicles",
    include_news=True,
    include_market_data=True,
    create_presentation=True
)

[代理使用您的工具包协调多个工具调用]
- news_search 用于最近的电动汽车新闻
- brave_web_search 用于市场数据
- sequential_thinking 用于分析
- write_file 用于保存报告
- ppt_create_presentation 用于生成幻灯片

[代理将结果返回给 Claude]

Claude："我已经为您分析了电动汽车市场。 以下是主要发现：
1. 特斯拉继续以 65% 的市场份额在北美领先
2. 比亚迪在全球销量上超过了大众汽车
3. 电池技术的突破正在加速采用

我还创建了一个包含详细图表和数据的演示文稿。 您可以在工作目录中找到保存为“EV_Market_Analysis.pptx”的文件。"

概述

MCP 统一服务器为 Claude 提供了一个统一的接口，用于与各种外部系统和工具进行交互，包括：

• 文件系统操作：读取、写入和操作文件
• 时间工具：获取不同时区的当前时间，在时区之间进行转换
• 顺序思考：一种用于动态和反思性问题解决的工具
• Brave 搜索：Web 和本地搜索功能
• 浏览器自动化：通过 Playwright 完全控制浏览器
• 世界银行 API：访问经济和发展数据
• 新闻 API：访问全球新闻来源和文章
• PowerPoint：创建和操作 PowerPoint 演示文稿
• Excel：创建和操作 Excel 电子表格
• Yahoo Finance：股票市场和金融数据
• FRED：联邦储备经济数据
• 代理能力：创建和部署执行复杂任务的自主代理
• 以及更多专业工具

共有 123 个可用工具

快速入门指南：使用默认工具部署您的第一个 MCP 服务器

注意：请确保您已下载 git (https://git-scm.com/downloads) 和 Docker (https://www.docker.com/products/docker-desktop/) 并正在运行。 您还必须确保将 git 可执行文件添加到路径（说明在本 README 的末尾）。

Docker 部署（推荐且最稳定）

1. 克隆存储库：

clone https://github.com/getfounded/mcp-tool-kit.git
cd mcp-tool-kit

2. 然后，您可以通过以下两种方式之一使用 Docker： 选项 1 - 使用 docker-compose：

docker-compose up

选项 2 - 直接 Docker 命令：

docker run -p 8000:8000 -v ~/documents:/app/documents getfounded/mcp-tool-kit:latest

该存储库包含一个示例 Claude 桌面配置文件 (claude_desktop_config.json)，您可以使用它：

{
  "mcpServers": {
    "unified": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "mcp-tool-kit-mcp-server",
        "python",
        "-u",
        "mcp_unified_server.py"
      ],
      "useStdio": true
    }
  }
}

Docker 故障排除

如果您在运行 docker 时遇到错误，则可能是 Claude 桌面配置文件中的镜像名称不正确。 一个常见的修复方法是使用以下 json 进行配置：

{
  "mcpServers": {
    "unified": {
      "command": "docker",
      "args": [
        "exec",
        "-i",
        "mcp-tool-kit-mcp-server-1",
        "python",
        "-u",
        "mcp_unified_server.py"
      ],
      "useStdio": true
    }
  }
}

通过 pip 安装

# 简单安装
pip install mcptoolkit

# 使用默认配置启动服务器
mcptoolkit-server

本地服务器基本配置：

{
  "tools": [
    {
      "name": "MCP Toolkit",
      "url": "http://localhost:8000"
    }
  ],
  "settings": {
    "allowed_directories": ["~/Documents", "~/Downloads"],
    "default_tools": ["MCP Toolkit"]
  }
}

配置 Claude 桌面以访问您的服务器

1. 打开 Claude 桌面应用程序
2. 转到文件 > 设置 > 开发者 > 编辑配置
3. 添加“claude_desktop_configuration.json”文件
4. 保存配置
5. 使用您集成的新工具重新启动 MCP 服务器
6. 重新启动并打开 Claude 桌面应用程序（对于 Windows 用户，您必须使用任务管理器结束所有 Claude 实例的任务）

您可以将此配置导入 Claude 桌面应用程序，或将其用作创建您自己的配置的参考。

现在，您可以立即访问强大的功能，包括文件操作、Web 搜索、时间工具等，而无需任何 API 密钥或复杂的设置。

设置环境变量

克隆存储库后，您有两种选择来配置您的环境变量：

选项 1：交互式设置脚本

运行设置脚本，该脚本将指导您设置环境变量：

python setup_env.py

此脚本将在存储库中创建一个包含您的配置的 .env 文件。

选项 2：手动配置

或者，您可以手动在存储库根目录中创建一个包含以下变量的 .env 文件：

# 外部服务的 API 密钥
BRAVE_API_KEY=your_brave_api_key
NEWS_API_KEY=your_news_api_key
FRED_API_KEY=your_fred_api_key

# 应用程序配置
STREAMLIT_APPS_DIR=/path/to/streamlit/apps
MCP_FILESYSTEM_DIRS=/path/to/allowed/dir1,/path/to/allowed/dir2
MCP_LOG_LEVEL=info

示例 Claude 提示

设置完成后，您可以要求 Claude 使用以下提示使用这些工具：

• "在网上搜索最新的 AI 研究论文并总结结果。"
• "创建一个关于气候变化的 PowerPoint 演示文稿，包含三张幻灯片。"
• "使用 weather_checker 代理告诉我东京的当前情况。"
• "您可以使用 quick_lookup 代理来研究量子计算的进展吗？"
• "下载我的 QuickBooks 发票数据并分析我们过去一个季度的收入。"
• "使用这些详细信息和定价在我的 Shopify 商店中设置一个产品。"
• "使用 Yahoo Finance 获取特斯拉的当前股价和历史数据。"
• "使用 FRED 经济数据分析过去 5 年的通货膨胀趋势。"
• "使用浏览器自动化填写 [网站 URL] 上的此表单。"
• "读取我的 Downloads 文件夹中名为 'project_notes.txt' 的文本文件。"
• "获取有关技术的最新新闻标题。"

可用工具

文件系统工具

• read_file：读取文件的内容

• read_multiple_files：同时读取多个文件

• write_file：创建或覆盖文件

• edit_file：对文件进行基于行的编辑

• create_directory：创建一个新目录

• list_directory：获取目录内容

• directory_tree：获取递归树视图

• move_file：移动或重命名文件/目录

• search_files：搜索与模式匹配的文件

• get_file_info：获取文件元数据

• list_allowed_directories：列出允许的目录

• Browser_Automation:

  • playwright_launch_browser：启动一个新的浏览器实例
  • playwright_navigate：导航到 URL
  • playwright_screenshot：截取屏幕截图
  • playwright_click：单击元素
  • playwright_fill：填写输入字段
  • playwright_evaluate：执行 JavaScript
  • playwright_get_content：获取页面的 HTML 内容

代理工具

• run_agent：使用参数执行已注册的代理
• list_agents：列出所有可用的代理及其元数据

金融数据工具

• Yahoo Finance:

  • yfinance：获取股票报价和历史数据
  • yfinance_get_quote：获取当前股票报价
  • yfinance_get_history：获取历史股票数据
  • yfinance_get_info：获取详细的公司信息
  • yfinance_get_options：获取期权链数据
  • yfinance_get_recommendations：获取分析师建议

• FRED (联邦储备经济数据):

  • fred_get_series：获取经济数据序列
  • fred_get_series_info：获取有关序列的元数据
  • fred_search：搜索经济数据序列
  • fred_get_category：按类别浏览数据
  • fred_get_releases：获取经济数据发布
  • fred_get_sources：获取数据源

时间工具

• get_current_time：获取指定时区的当前时间
• convert_time：在时区之间转换时间

顺序思考

• sequentialthinking：一种使用逐步思考过程分解复杂问题的工具

Brave 搜索

• brave_web_search：执行 Web 搜索
• brave_local_search：搜索本地企业和地点

世界银行 API

• worldbank_get_indicator：获取国家/地区的指标数据

新闻 API

• news_top_headlines：获取热门新闻标题
• news_search：搜索新闻文章
• news_sources：列出可用的新闻来源

PowerPoint 工具

• ppt_create_presentation：创建一个新的 PowerPoint 演示文稿
• ppt_open_presentation：打开现有的演示文稿
• ppt_save_presentation：保存演示文稿
• ppt_add_slide：添加新幻灯片
• ppt_add_text：向幻灯片添加文本
• ppt_add_image：向幻灯片添加图像
• ppt_add_chart：向幻灯片添加图表
• ppt_add_table：向幻灯片添加表格
• ppt_analyze_presentation：分析演示文稿结构
• ppt_enhance_presentation：建议增强功能
• ppt_generate_presentation：从文本生成演示文稿
• ppt_command：处理自然语言命令

有关可用工具的完整列表，请参阅文档或浏览工具目录。 有关可用工具的完整列表，请参阅文档或浏览工具目录。

添加新的工具模块

1. 在 tools 目录中创建一个新文件（例如，my_tool.py）
2. 遵循现有的模块模式：
   • 创建服务类
   • 定义工具函数
   • 实现注册函数
3. 更新 mcp_unified_server.py 以导入和注册您的新模块

扩展现有的工具模块

1. 向服务类添加新方法
2. 添加新的工具函数
3. 更新注册函数以包含您的新工具

使用 Docker 进行开发

您可以使用 Docker 进行开发，以确保一致的环境：

# 构建开发镜像
docker build -t mcp-tool-kit:dev .

# 运行并挂载源代码以进行开发
docker run -p 8000:8000 \
    -v $(pwd):/app \
    -v ~/documents:/app/documents \
    mcp-tool-kit:dev

这会将您的本地存储库挂载到容器中，因此对代码的更改会立即反映出来（对于大多数文件）。

哲学视角：人机认知伙伴关系

MCP 工具包代表了我们如何概念化人类智能和 AI 系统之间关系的一种范式转变。 该框架不是将 AI 定位为仅用于任务自动化的工具，而是建立了一种认知伙伴关系，其中人类的战略思维和 AI 的运营能力以深刻的方式相互补充。

代理架构体现了一种变革性的愿景：AI 系统可以独立解释上下文，在有限的参数范围内做出决策，并执行复杂的行动序列，同时保持人类的监督和战略方向。 这不仅代表了技术进步，而且代表了一种根本上新的人机协作模式。

在这种不断发展的认知环境中，最成功的实现将是那些深思熟虑地平衡技术潜力与人类能力，创建增强而非取代人类决策和创造力的接口的实现。

故障排除

• 模块未加载：检查导入路径和依赖项
• API 密钥错误：验证 .env 文件中的 API 密钥
• 权限错误：检查 MCP_FILESYSTEM_DIRS 中允许的目录
• 连接错误：确保服务器正在运行并且端口可访问
• 未检测到代理：验证代理文件是否位于正确的目录中并遵循所需的格式
• 路径问题：确保按照以下说明将 git 添加到路径

#要在 Windows 上将 Git 添加到 PATH，请按照以下步骤操作：

1. 找到 Git 安装：确定 Git 在您的系统上的安装路径。 常见路径包括 C:\Program Files\Git\bin\git.exe 和 C:\Program Files\Git\cmd（对于标准 Git 安装），或者 C:\Users<username>\AppData\Local\GitHub\PortableGit_<guid>\bin 和 C:\Users<username>\AppData\Local\GitHub\PortableGit_<guid>\cmd（如果您通过 GitHub for Windows 或 GitHub Desktop 安装了 Git）。

2. 编辑环境变量：通过控制面板打开“编辑环境变量”应用程序，或者在“开始”菜单中搜索“编辑系统环境变量”。 在“系统变量”部分下，找到“Path”变量，单击“编辑...”，然后添加 Git 可执行文件和命令文件的路径。 确保分隔路径的分号周围没有空格。

3. 保存更改：添加 Git 路径后，单击“确定”保存更改。 关闭并重新打开任何命令提示符窗口以应用新的 PATH 设置。

4. 验证安装：打开命令提示符并运行 git --version 以验证是否可以从命令行访问 Git。

许可证

MCP 统一服务器在 MIT 许可证下获得许可。

致谢

本项目使用了多个开源库和 API：

• 用于 Claude AI 助手的 MCP SDK
• 用于新闻访问的 NewsAPI
• 用于 Web 搜索的 Brave Search API
• 用于经济数据的世界银行 API
• 用于 PowerPoint 操作的 python-pptx
• 用于 Excel 电子表格的 XlsxWriter