关键词

AI Agent工具调用模型管理自动化上下文服务

Ultimate MCP Server 使用说明

项目简介

Ultimate MCP Server 是一个全面的、原生支持 Model Context Protocol (MCP) 的应用后端。它被设计为一个功能强大的 AI Agent 操作系统，通过 MCP 标准协议向 LLM 客户端（如 Claude）提供丰富的上下文信息和外部功能。服务器托管和管理各类资源、注册和执行多样的工具、并定义和渲染Prompt 模板，使 AI Agent 能够执行复杂的任务，超越其原生对话能力。

主要功能点

  • 多模型集成与管理: 统一访问多种 LLM 提供商（OpenAI, Anthropic, Google, DeepSeek, xAI, OpenRouter 等），提供抽象层，方便切换模型，并支持多模型并行调用。
  • 智能任务分派与成本优化: 根据任务需求、成本、性能和质量偏好，智能地将任务路由到最合适的模型或专用工具，显著降低 API 调用成本。
  • 丰富的工具生态: 提供了数十种内置工具，涵盖：
    • 文件系统操作: 安全地读写、编辑、列出、搜索文件和目录。
    • 浏览器自动化: 利用 Playwright 实现网页浏览、数据抓取、表单填写等复杂交互。
    • 文档处理: 智能分块、总结、问答生成、批量处理 PDF 和文本文件。
    • 数据提取: 从非结构化文本中提取 JSON、表格、键值对等结构化数据。
    • 知识图谱与 RAG: 构建和查询实体关系图，通过检索增强生成提高回答准确性。
    • 向量操作与搜索: 支持语义搜索和混合搜索。
    • OCR 能力: 从图片和 PDF 中提取文本，并使用 LLM 进行校正和增强。
    • CLI 工具集成: 将 ripgrep, awk, sed, jq 等本地命令行工具作为 MCP 工具安全封装。
    • SQL 数据库交互: 连接和查询数据库，分析模式，生成 SQL。
    • Excel 自动化: 创建、修改、格式化和分析 Excel 文件。
    • 音频转录: 使用 Whisper 等模型转录音频文件。
    • 文本分类: 应用文本分类模型。
    • 文本对比: 生成文本/HTML 的红线对比。
    • HTML 转 Markdown: 智能转换网页内容为 Markdown。
    • 高级缓存: 实现多级别智能缓存以减少重复 API 调用。
  • 认知与记忆系统: 提供工作记忆、情景记忆、语义记忆等层次化的记忆能力，帮助 Agent 维护状态和上下文。
  • 动态 API 集成: 通过 OpenAPI (Swagger) 规范动态注册外部 REST API 端点为可调用的 MCP 工具。
  • Prompt 模板管理: 使用 Jinja2 模板创建可复用的 Prompt。
  • 分析与报告: 跟踪模型使用量、成本、请求成功率等，提供数据分析。
  • 模型性能测试: 包含用于测试模型速度和性能的工具。
  • 错误处理与韧性: 包含智能重试、回退机制和详细错误报告。
  • 自动化文档优化: (高级功能) 利用 LLM 自主分析、测试和改进工具文档。

安装步骤

  1. 安装 'uv': 如果您没有安装 uv (一个快速的 Python 包管理器)，请先安装它。 
    curl -LsSf https://astral.sh/uv/install.sh | sh
# 或者根据 uv 官方文档使用其他安装方式
  2. 克隆仓库: 
    git clone https://github.com/Dicklesworthstone/ultimate_mcp_server.git
cd ultimate_mcp_server
  3. 创建虚拟环境并安装依赖: 
    uv venv --python 3.13 # 或其他兼容的 Python 版本
source .venv/bin/activate
uv lock --upgrade
uv sync --all-extras # 安装所有可选依赖，如需特定功能请手动调整依赖

服务器配置 (供 MCP 客户端连接使用)

MCP 客户端需要知道如何连接到 Ultimate MCP Server。常见的连接方式有两种：

  1. 通过网络连接 (如 SSE/HTTP):

    • 服务器需要以网络模式启动，例如使用 'umcp run -t sse' 命令。
    • 您需要在服务器配置文件 ('.env' 或其他配置源) 中指定 'GATEWAY_SERVER_HOST' 和 'GATEWAY_SERVER_PORT'，或者在启动命令中通过 '--host' 和 '--port' 指定。默认通常是 '127.0.0.1:8013'。
    • MCP 客户端需要配置服务器的 URL。如果使用 SSE 模式，URL 格式通常是 'http://{服务器主机}:{服务器端口}/sse'。
    • 例如，如果服务器运行在 'localhost' 的 '8013' 端口，客户端配置的 URL 将是 'http://localhost:8013/sse'。

  2. 通过标准输入输出 (Stdio):

    • 服务器需要以 Stdio 模式启动，例如使用 'umcp run -t stdio' 命令。
    • 在这种模式下，MCP 客户端负责启动服务器进程并与其标准输入输出流进行通信。
    • 客户端需要配置服务器的 启动命令 ('command') 和 参数 ('args')。
    • 启动命令通常是 'umcp'。
    • 参数通常是 '["run", "--transport-mode", "stdio"]'。
    • 您还可以根据需要添加其他参数，例如限制工具 ('--include-tools' 或 '--exclude-tools') 或设置日志级别 ('-d' 或 '--debug')。例如，'["run", "--transport-mode", "stdio", "--include-tools", "read_file,write_file"]'。

请注意: 具体如何配置连接取决于您使用的 MCP 客户端库或 Agent 框架。它们通常提供一个配置对象，让您填入上述 URL 或 Command/Args 信息。API 密钥等敏感信息应配置在服务器端，不应暴露给客户端。

基本使用方法

一旦服务器按照上述配置启动并运行，一个支持 MCP 协议的 LLM 客户端（如定制的 Claude Agent 或使用 'mcp-client' 库的应用）就可以通过配置的连接信息与服务器交互。

基本交互流程如下：

  1. AI Agent 接收任务: Agent 接收到一个需要外部工具或信息支持的任务。
  2. Agent 发现工具: Agent 可以调用服务器的元工具（如 'list_tools'）来发现可用的工具及其功能和参数。
  3. Agent 规划并调用工具: Agent 根据任务需求和发现的工具，决定调用哪个工具，并准备好相应的参数。它通过 MCP 协议向服务器发送一个工具调用请求（例如 JSON-RPC 请求）。
  4. 服务器执行工具: Ultimate MCP Server 接收到请求，验证参数，路由到相应的工具实现（调用 LLM、执行代码、与外部服务交互等）。
  5. 服务器返回结果: 工具执行完成后，服务器将结果封装在标准的 MCP 响应格式中（包含成功状态、输出数据、成本信息等），返回给 Agent。
  6. Agent 处理结果: Agent 解析响应，使用返回的数据继续任务或根据错误信息调整策略。

您可以在仓库的 'examples' 目录中找到使用 'mcp-client' 与运行中的服务器交互的 Python 示例脚本。这些脚本展示了如何以编程方式调用服务器提供的各种工具。运行这些示例前，请确保服务器已启动且 API 密钥已正确配置在服务器端。

信息

分类

AI与计算

访问项目