使用说明

项目简介

本项目 'ollama-mcp-agent' 是一个基于 Model Context Protocol (MCP) 的智能体应用，它允许你使用本地部署的 Ollama 或 Google Gemini 大模型，并通过 MCP 协议扩展模型的功能。项目核心在于MCP客户端的实现，能够连接和利用外部MCP服务器提供的工具。同时，仓库内也包含了示例MCP服务器的Python代码，方便用户理解和扩展MCP服务器的功能。

主要功能点

本地LLM支持: 支持 Ollama 和 Google Gemini，可在本地运行大模型，无需额外云端服务费用。
MCP协议扩展: 通过 MCP 协议连接外部服务器，为 LLM 扩展工具调用等功能。
流式响应: 支持流式输出 LLM 的响应，提升用户体验。
工具调用监控: 可以监控工具的调用信息，方便调试和理解智能体的行为。
示例MCP服务器: 提供天气查询和文件管理两个示例 MCP 服务器，展示如何构建和扩展 MCP 服务器功能。

安装步骤

克隆仓库:

git clone https://github.com/godstale/ollama-mcp-agent
cd ollama-mcp-agent

安装 uv (可选，推荐): uv 是一个更快的 Python 包管理器。

# 使用 pip 安装
pip install uv

# 或者使用 curl (Unix-like 系统)
curl -LsSf https://astral.sh/uv/install.sh | sh

# 或者使用 PowerShell (Windows)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

创建虚拟环境并安装依赖:

# 创建并激活虚拟环境
uv venv
source .venv/bin/activate  # For Unix-like systems
# 或
.venv\Scripts\activate     # For Windows

# 安装依赖
uv sync

安装 Ollama (如果选择使用 Ollama) 并下载模型: 访问 Ollama 官网根据你的操作系统安装 Ollama。安装完成后，下载支持工具调用 (Tool calling) 功能的模型，例如：
```
ollama pull MFDoom/deepseek-r1-tool-calling:14b
```
配置 Google Gemini API Key (如果选择使用 Gemini): 如果你希望使用 Google Gemini 模型，需要设置 'GOOGLE_API_KEY' 环境变量。推荐在项目根目录下创建 '.env' 文件，并添加以下内容：
```
GOOGLE_API_KEY=你的_google_api_key
```
将 '你的_google_api_key' 替换为你的 Google API Key。

服务器配置 (MCP客户端配置)

MCP 客户端需要配置要连接的 MCP 服务器信息。配置文件为 'mcp_config.json'。你可以配置多个 MCP 服务器，客户端会根据需要自动选择合适的工具。

以下是一个 'mcp_config.json' 的示例配置，包含了天气查询和文件管理两个 MCP 服务器的配置：

{
  "mcpServers": {
    "weather": {  // 服务器名称，客户端用此名称引用
      "command": "python", // 启动服务器的命令
      "args": ["./mcp_server/mcp_server_weather.py"], // 启动命令的参数，指向天气查询服务器的 Python 脚本
      "transport": "stdio" // 通信协议，这里使用标准输入输出流
    },
    "file_manager": { // 服务器名称，客户端用此名称引用
      "command": "python", // 启动服务器的命令
      "args": ["./mcp_server/mcp_server_file_manager.py"], // 启动命令的参数，指向文件管理服务器的 Python 脚本
      "transport": "stdio" // 通信协议，这里使用标准输入输出流
    },
    "fetch": { // 服务器名称，客户端用此名称引用 (示例：Smithery 提供的 fetch 工具)
      "command": "npx", // 启动服务器的命令 (使用 npx 运行 npm 包)
      "args": [
        "-y",
        "@smithery/cli@latest",
        "run",
        "@smithery-ai/fetch",
        "--key",
        "your_unique_uuid" // 替换为你在 Smithery 上的唯一 UUID
      ]
    }
  }
}

配置说明:

'mcpServers': JSON 对象，包含所有要配置的 MCP 服务器。
服务器名称 (例如 'weather', 'file_manager', 'fetch'): 每个服务器配置的键名，客户端通过此名称引用服务器提供的工具。
'command': 启动 MCP 服务器的命令。通常是 Python 解释器 ('python') 或 Node.js 包管理器 ('npx')。
'args': 启动命令的参数列表。
- 对于 Python 服务器，通常指向服务器脚本的路径 (例如 '"./mcp_server/mcp_server_weather.py"').
- 对于 Node.js 服务器 (例如 Smithery 的工具)，包含运行 npm 包的命令和参数。
'transport': MCP 客户端与服务器之间的通信协议。本项目示例和 'mcp_config.json' 示例中使用了 'stdio' (标准输入输出流) 协议。

请注意: 你需要根据实际情况修改 'mcp_config.json' 文件，例如修改文件路径、Smithery 工具的 UUID 等。示例配置文件中 'fetch' 服务器的配置仅为参考，你需要根据 Smithery 提供的具体信息进行配置。

基本使用方法

启动 MCP 服务器 (示例): 如果你想使用示例 MCP 服务器，需要先分别启动它们。打开两个新的终端窗口，分别进入 'ollama-mcp-agent' 仓库目录，然后运行以下命令：

终端窗口 1 (天气查询服务器):
```
uv run mcp_server/mcp_server_weather.py
```
终端窗口 2 (文件管理服务器):
```
uv run mcp_server/mcp_server_file_manager.py
```
这些命令会启动两个基于 'stdio' 协议的 MCP 服务器。
运行 MCP 客户端 (智能体应用): 在另一个终端窗口 (或任意一个未被服务器占用的终端窗口) 中，进入 'ollama-mcp-agent' 仓库目录，然后运行以下命令启动 MCP 客户端：

使用 Ollama 模型:
```
uv run main.py
```
使用 Google Gemini 模型:
```
uv run gemini.py
```
你可以添加命令行参数来调整客户端的行为，例如：
- '--temp <temperature>': 设置温度系数 (0.0 ~ 1.0)，例如 'uv run main.py --temp 0.8'。
- '--timeout <seconds>': 设置请求超时时间 (秒)，例如 'uv run main.py --timeout 60'。
- '--show-tools': 显示工具调用信息，例如 'uv run main.py --show-tools'。
与智能体对话: 客户端启动后，你可以在终端中输入问题，与智能体进行对话。智能体会根据你的问题，选择是否调用配置的 MCP 服务器提供的工具来辅助回答。
退出程序: 在对话过程中，输入 'quit', 'exit' 或 'bye' 即可退出程序。

扩展 MCP 工具

你可以参考 'mcp_server' 目录下的示例代码，编写自己的 MCP 服务器，扩展智能体的功能。主要步骤包括：

创建新的 MCP 服务器 Python 脚本: 例如，'mcp_server/mcp_server_mytool.py'。
在脚本中使用 'FastMCP' 初始化服务器，并使用 '@mcp.tool()' 装饰器定义工具函数。
在 'mcp_config.json' 文件中添加新的服务器配置， 包括服务器名称、启动命令和参数等。
启动新的 MCP 服务器。
重启 MCP 客户端 (如果客户端已经在运行)。

更多关于 MCP 服务器和工具的信息，可以参考 smithery.ai。

关键词