使用说明

Olama FastMCP包装材料

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

✨ 特性

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

问：什么是MCP？

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

⚡ 安装

克隆此存储库并安装依赖项：
```
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 -玉米 -奥拉马

确保你有：

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引入了独立的配置结构：

包装器配置 (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根据请求覆盖温度

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)

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

Ollama连接参数：

--ollama-host <address> -Ollama实例主机（默认：从配置或 localhost)
--ollama-port <number> -Ollama实例端口（默认：来自配置或 11434)
--ollama-timeout <seconds> -请求超时（秒）（默认值：来自配置或 300)
--ollama-label <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：发布历史/路线图

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

本地LLM模型与MCP服务器桥接工具

使用说明

Olama FastMCP包装材料

✨ 特性

问：什么是MCP？

⚡ 安装

⛵ 用法

📚 演示脚本

🖥️ API模式

API终点

快速入门示例

💬 命令行接口命令模式

快速开始

⚙️ 配置

配置文件

配置优先

运输方式

命令行参数

例子

📊 架构图

：bulb：发布历史/路线图

许可证

使用说明

Olama FastMCP包装材料

✨ 特性

问：什么是MCP？

⚡ 安装

⛵ 用法

📚 演示脚本

🖥️ API模式

API终点

快速入门示例

💬 命令行接口命令模式

快速开始

⚙️ 配置

配置文件

配置优先

运输方式

命令行参数

例子

📊 架构图

：bulb：发布历史/路线图

许可证

相关 MCP

Blender 3D建模MCP服务

iOS模拟器交互服务器

网页抓取与搜索MCP服务器

B站视频搜索服务

Minecraft MCP服务器

SSH远程命令执行MCP服务器