Ollama Fastmcp Wrapper

Olama FastMCP包装材料

桥接的代理服务 奥拉马 随着 FastMCP 从而允许模型与MCP服务器及其工具直接在本地机器上本地结合使用。

______________________________________________________________________

✨ 特性

• 连接/断开多个 MCP服务器 在运行时（使用FastMCP）。
• 将FastMCP工具作为可调用函数公开给Ollama模型。
• 在本地使用Ollama，并使用工具增强推理。
• 与LLM模型在磁盘上持久化的历史对话 异步I/O.
• 自动总结与模型的历史对话。
• 运行方式：

- API服务器 （通过FastAPI+Uvicorn） - 交互式CLI

______________________________________________________________________

问：什么是MCP？

模型上下文协议（MCP）是一种协议，它允许您构建服务器，以安全、标准化的方式向LLM应用程序公开数据和功能。 仅限于此包装，MCP的使用仅限于工具部分。

⚡ 安装

1. 克隆此存储库并安装依赖项：

   git clone https://github.com/andreamoro/ollama-fastmcp-wrapper.git

根据您正在使用的包管理器安装依赖项。如果是紫外线：

   cd ollama-fastmcp-wrapper
   uv sync

否则，请使用传统的（过时的）pip：

   cd ollama-fastmcp-wrapper
   pip install -r requirements.txt

Python要求包括： -aiofiles（异步文件I/O） -fastapi -fastmcp -玉米 -奥拉马

1. 确保你有：

• Ollama客户 启动并运行：

  ollama serve

• 使用工具功能的MCP服务器

- 如果没有MCP服务器，您可以将此包装器用作对话接口 - MCP服务器示例包含在 mcp_servers/ 目录： - math_server.py -基本算术运算（加、减、乘、除） - ipinfo_server.py -使用20个预设组织进行IP地理定位查找

⛵ 用法

运行包装程序：

uv run python ollama_wrapper.py

系统将询问您以哪种模式启动：

• API模式 → 在上启动REST API http://127.0.0.1:8000
• CLI模式 → 启动基于终端的聊天循环

📚 演示脚本

这 demos/ 目录包含shell和Python格式的综合使用示例：

• 基本帽子 -无需工具的简单聊天
• 数学运算 -使用数学MCP服务器
• ipinfo_lookup -IP地理定位查询
• 服务器管理 -连接/断开连接/列出服务器
• 历史管理 -对话持久性
• 温度测试多模式py -多个型号的先进温度测试

看 demos/README.md 了解详细的使用说明和示例。

______________________________________________________________________

🖥️ API模式

启动API：

uv run python ollama_wrapper.py
# choose "api"

📖 有关全面的API文档、使用模式和示例，请参阅 API_USAGE.md

API终点

根：

• GET / → API文档和端点列表

聊天：

• POST /chat → 发送聊天请求（使用可选的MCP工具）

模型管理：

• GET /model → 获取当前会话模型
• GET /model/list → 列出所有可用的Olama型号
• POST /model/switch/{model_name} → 切换会话模型并重置上下文
• GET /ollama/config → 获取Ollama实例配置（主机、标签、活动模型）
• GET /ollama/status → Ollama的快速健康检查（5秒超时）

历史：

• GET /history → 获取当前对话历史记录
• GET /history/clear → 清除当前对话历史记录
• GET /history/load/{file_name} → 从磁盘加载对话历史记录
• GET /history/overwrite/{file_name} → 覆盖现有对话文件
• GET /history/save/{file_name} → 将对话历史记录保存到磁盘

服务器：

• GET /servers → 从配置中列出可用的FastMCP服务器
• POST /servers/{server_name}/connect → 连接到MCP服务器
• POST /servers/{server_name}/disconnect → 断开与MCP服务器的连接
• GET /servers/{server_name}/tools → 列出特定MCP服务器的可用工具

快速入门示例

# Start API server
uv run python ollama_wrapper.py api

# Simple chat request (uses session model from config)
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello! Tell me about Python"}'

# Connect to MCP server and use tools
curl -X POST http://localhost:8000/servers/math/connect
curl -X POST http://localhost:8000/chat \
  -H "Content-Type: application/json" \
  -d '{
    "message": "What is 25 * 4?",
    "mcp_server": "math"
  }'

有关详细的使用模式，包括模型切换、多模型测试、温度测试等，请参阅 API_USAGE.md.

______________________________________________________________________

💬 命令行接口命令模式

uv run python ollama_wrapper.py
# choose "cli"

📖 有关全面的CLI文档、命令和使用模式，请参阅 CLI_USAGE.md

快速开始

# Start CLI
uv run python ollama_wrapper.py cli

# Chat naturally
You: Hello! How are you?
Bot: I'm doing well, thank you for asking!

# Use commands
You: /help       # Show available commands
You: /model      # Change model interactively
You: /clear      # Clear conversation context
You: /exit       # Exit CLI

有关包括模型切换、持久对话和温度调整在内的详细使用模式，请参阅 CLI_USAGE.md.

______________________________________________________________________

⚙️ 配置

配置文件

版本0.4.0引入了独立的配置结构：

1. 包装器配置 (wrapper_config.toml -根目录）：

   [wrapper]
   transport = "HTTP"              # Transport method: "HTTP" or "STDIO" (default: HTTP)
   host = "0.0.0.0"                # Server host address (default: 0.0.0.0)
   port = 8000                     # Server port (default: 8000)
   history_file = ""               # Path to conversation history file (default: none)
   overwrite_history = false       # Overwrite history file on exit (default: false)
   max_history_messages = 20       # Maximum messages before summarization kicks in (default: 20)

   [ollama]
   host = "localhost"              # Ollama instance host (default: localhost)
   port = 11434                    # Ollama instance port (default: 11434)
   timeout = 300                   # Request timeout in seconds (default: 300)
   label = ""                      # Optional label to identify this Ollama instance
   model = { default = "llama3.2:3b", temperature = 0.2 }  # Model settings

包装器设置：

- max_history_messages：自动摘要前的最大消息数（默认值：20） - 当消息计数超过此限制时，会对较旧的消息进行汇总以保存上下文 - 有助于保持对话的连续性，同时保持令牌使用的可管理性 - 根据模型的上下文窗口和用例进行调整

Ollama设置：

- host：Ollama实例主机（与远程/隧道实例的端口一起使用） - port：Ollama实例端口（默认值：11434） - timeout：请求超时时间（秒）（默认值：300）。防止在SSH隧道中断或远程Ollama无响应时，包装器无限期挂起。 - label：用于标识此Ollama实例的人类可读标签（如果未设置，则在启动时提示） - 有关服务器端设置（并行性、VRAM、网络访问），请参阅 OLLAMA_SERVER.md

模型设置：

- default：如果请求中未指定默认型号名称 - temperature：控制响应随机性（0.0-2.0） - 低（0.0-0.3）：一致、确定的响应（建议用于实际任务） - 中等（0.7-1.0）：平衡的创造力 - 高（1.5-2.0）：非常有创意，不太可预测 - 可通过API根据请求覆盖温度

1. MCP服务器配置 (mcp_servers/mcp_servers_config.toml):

   [[servers]]
   name = "math"
   command = "uv"
   args = ["run", "--with", "fastmcp", "mcp_servers/math_server.py"]
   host = "http://localhost:5000/mcp"
   port = 5000
   enabled = true

   [[servers]]
   name = "ipinfo"
   command = "uv"
   args = ["run", "--with", "fastmcp", "mcp_servers/ipinfo_server.py"]
   host = "http://localhost:5001/mcp"
   port = 5001
   enabled = true
   token_file = "mcp_tokens.toml"  # Optional: specify token file (default: mcp_tokens.toml)

1. API令牌 (mcp_servers/mcp_tokens.toml -gignored）：

   # Copy from mcp_tokens.toml.example and add your tokens
   [ipinfo]
   token = "your_ipinfo_token_here"

配置优先

命令行参数优先于配置文件设置：

• 如果您指定 --host 或 --port 在命令行上，将使用这些值
• 如果未在命令行上指定，则值来自 wrapper_config.toml 将被使用
• 如果不在配置文件中，将使用默认值

运输方式

• STDIO传输 → 在本地生成服务器
• HTTP传输 → 连接到远程MCP服务器

命令行参数

立场争论：

• mode -操作模式： api 或 cli （默认值： api)
• model -使用Ollama模型（例如。， llama3.2:3b, gemma3:1b)

可选参数：

• -c, --wrapper-config -包装器配置文件的路径（默认值： wrapper_config.toml)
• --mcp-config -MCP服务器配置文件名位于MCP_seservers/目录中（默认值： mcp_servers_config.toml)
• --history-file -要加载/保存的对话历史文件的路径
• -o, --overwrite-history -允许覆盖现有历史文件
• -t, --transport -运输方式： HTTP 或 STDIO （默认：从配置或 HTTP)
• --wrapper-host -包装器API服务器主机地址（默认：来自配置或 0.0.0.0)
• --wrapper-port -包装器API服务器端口号（默认值：来自配置或 8000)

Ollama连接参数：

• --ollama-host -Ollama实例主机（默认：从配置或 localhost)
• --ollama-port -Ollama实例端口（默认：来自配置或 11434)
• --ollama-timeout -请求超时（秒）（默认值：来自配置或 300)
• --ollama-label -标识Ollama实例的标签（默认值： local-server)

例子

# Use custom wrapper config file
uv run python ollama_wrapper.py api -c my_wrapper_config.toml

# Override config file settings
uv run python ollama_wrapper.py api --wrapper-host 127.0.0.1 --wrapper-port 9000

# Specify transport method
uv run python ollama_wrapper.py api -t STDIO

# Load conversation history
uv run python ollama_wrapper.py cli --history-file my_conversation.json

# Start with specific model and auto-save history
uv run python ollama_wrapper.py api llama3.2:3b --history-file conversation.json -o

# Use alternate MCP servers config
uv run python ollama_wrapper.py api --mcp-config alternate_servers.toml

# Connect to remote Ollama via SSH tunnel (with custom timeout)
uv run python ollama_wrapper.py api --ollama-host localhost --ollama-port 11435 \
  --ollama-timeout 600 --ollama-label "remote-vps-via-tunnel"

______________________________________________________________________

📊 架构图

flowchart TD
    O[Ollama] --> W[Ollama-FastMCP Wrapper]
    W -->|API mode| A[API]
    W -->|CLI mode| C[CLI]
    A --> M{ MCP Server Available?} 
    C --> Z
    M -->|Yes| F[FastMCP Tools]
    F --> Z[Chat]
    M -->|No| Z

______________________________________________________________________

：bulb：发布历史/路线图

请检查 更新日志 文件以获取更多信息。

______________________________________________________________________

许可证

麻省理工学院许可证©2025 Andrea MORO