ollama-MCP-server

与Ollama通信的Model Context Protocol (MCP) 服务器

概要

这个MCP服务器实现了本地Ollama LLM实例和MCP兼容应用程序之间的无缝集成，并提供高级的任务分解、评估和工作流管理。

主要功能:

• 复杂问题的任务分解
• 结果的评估和验证
• Ollama模型的管理和执行
• 通过MCP协议进行标准化通信
• 高级错误处理和详细的错误消息
• 性能优化（连接池、LRU缓存）

组件

资源

服务器实现了以下资源:

• task:// - 用于访问单个任务的URI方案
• result:// - 用于访问评估结果的URI方案
• model:// - 用于访问可用的Ollama模型的URI方案

每个资源都配置了适当的元数据和MIME类型，以便与LLM进行最佳交互。

提示和工具的关系

在MCP服务器中，提示和工具紧密相关，但具有不同的角色。

• 提示：类似于Schema，为LLM提供特定的思考方法或结构
• 工具：类似于Handler，实际执行操作

每个工具都需要对应的Schema（提示），从而有效地协调LLM的思考能力和实际的系统功能。

提示

服务器提供了一些特殊的提示:

• decompose-task - 将复杂的任务分解为易于管理的子任务

  • 获取任务的描述和粒度级别的可选参数
  • 返回包含依赖关系和估计复杂性的结构化分解

• evaluate-result - 根据指定的标准分析任务结果

  • 获取结果的内容和评估参数
  • 返回包含分数和改进建议的详细评估

工具

服务器实现了一些强大的工具:

• add-task

  • 必需参数: name (字符串), description (字符串)
  • 可选参数: priority (数值), deadline (字符串), tags (数组)
  • 在系统中创建一个新任务，并返回其标识符
  • 对应的Schema: 用于任务创建的数据验证Schema

• decompose-task

  • 必需参数: task_id (字符串), granularity (字符串: "high"|"medium"|"low")
  • 可选参数: max_subtasks (数值)
  • 使用Ollama将复杂的任务分解为可管理的子任务
  • 对应的Schema: 上述的decompose-task提示

• evaluate-result

  • 必需参数: result_id (字符串), criteria (对象)
  • 可选参数: detailed (布尔值)
  • 根据指定的标准评估结果，并提供反馈
  • 对应的Schema: 上述的evaluate-result提示

• run-model

  • 必需参数: model (字符串), prompt (字符串)
  • 可选参数: temperature (数值), max_tokens (数值)
  • 使用指定的参数运行Ollama模型
  • 对应的Schema: Ollama模型运行参数的验证Schema

新功能和改进点

扩展错误处理

服务器提供更详细和结构化的错误消息。这使客户端应用程序能够更有效地处理错误。错误响应示例:

{
  "error": {
    "message": "Task not found: task-123",
    "status_code": 404,
    "details": {
      "provided_id": "task-123"
    }
  }
}

性能优化

• 连接池: 通过使用共享HTTP连接池，提高了请求的性能并降低了资源使用率。
• LRU缓存: 通过缓存对相同或相似请求的响应，缩短了响应时间并减轻了Ollama服务器的负载。

这些设置可以在 config.py 中调整:

# 性能相关设置
cache_size: int = 100                 # 缓存中保存的最大条目数
max_connections: int = 10             # 最大并发连接数
max_connections_per_host: int = 10    # 每个主机的最大连接数
request_timeout: int = 60             # 请求超时（秒）

模型指定功能

概要

Ollama-MCP-Server提供了一种灵活的功能，可以通过多种方式指定Ollama模型。

模型指定的优先顺序

模型按照以下优先级指定：

1. 工具调用时的参数 (model 参数)
2. MCP配置文件的 env 部分
3. 环境变量 (OLLAMA_DEFAULT_MODEL)
4. 默认值 (llama3)

使用MCP配置文件指定模型

当与Claude Desktop等客户端一起使用时，可以使用MCP配置文件来指定模型：

{
  "mcpServers": {
    "ollama-MCP-server": {
      "command": "python",
      "args": [
        "-m",
        "ollama_mcp_server"
      ],
      "env": [
        {"model": "llama3:latest"}
      ]
    }
  }
}

检查可用模型

服务器启动时，会检查配置的模型是否存在。如果找不到模型，则会输出警告日志。此外，run-model工具会返回可用模型列表，以便用户可以选择有效的模型。

改进的错误处理

如果指定的模型不存在或发生通信错误，则会提供详细的错误消息。错误消息包含可用模型列表，以便用户可以快速解决问题。

测试

项目包含一个全面的测试套件:

• 单元测试: 测试单个组件的功能
• 集成测试: 测试端到端的工作流程

要运行测试:

# 运行所有测试
python -m unittest discover

# 运行特定的测试
python -m unittest tests.test_integration

配置

环境变量

OLLAMA_HOST=http://localhost:11434
DEFAULT_MODEL=llama3
LOG_LEVEL=info

Ollama的设置

确保Ollama已安装并使用适当的模型运行:

# 安装Ollama（如果尚未安装）
curl -fsSL https://ollama.com/install.sh | sh

# 下载推荐模型
ollama pull llama3
ollama pull mistral
ollama pull qwen2

快速开始

安装

pip install ollama-mcp-server

Claude Desktop设置

MacOS

路径: ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

路径: %APPDATA%/Claude/claude_desktop_config.json

<details> <summary>开发/未公开服务器的设置</summary>

"mcpServers": {
  "ollama-MCP-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/ollama-MCP-server",
      "run",
      "ollama-MCP-server"
    ],
    "ENV":["model":"deepseek:r14B"]
  }
}

</details>

<details> <summary>公开服务器的设置</summary>

"mcpServers": {
  "ollama-MCP-server": {
    "command": "uvx",
    "args": [
      "ollama-MCP-server"
    ]
  }
}

</details>

使用例

任务分解

要将复杂的任务分解为可管理的子任务:

result = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "decompose-task",
    "arguments": {
        "task_id": "task://123",
        "granularity": "medium",
        "max_subtasks": 5
    }
})

结果评估

要根据特定标准评估结果:

evaluation = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "evaluate-result",
    "arguments": {
        "result_id": "result://456",
        "criteria": {
            "accuracy": 0.4,
            "completeness": 0.3,
            "clarity": 0.3
        },
        "detailed": true
    }
})

Ollama模型的执行

要直接查询Ollama模型:

response = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "run-model",
    "arguments": {
        "model": "llama3",
        "prompt": "量子コンピューティングを簡単な言葉で説明してください",
        "temperature": 0.7
    }
})

开发

项目的设置

1. 克隆存储库:

git clone https://github.com/yourusername/ollama-MCP-server.git
cd ollama-MCP-server

2. 创建并激活虚拟环境:

python -m venv venv
source venv/bin/activate  # Windowsの場合: venv\Scripts\activate

3. 安装开发依赖项:

uv sync --dev --all-extras

本地开发

该项目包含方便的开发脚本：

运行服务器

./run_server.sh

选项:

• --debug: 以调试模式运行（日志级别: DEBUG）
• --log=LEVEL: 指定日志级别（DEBUG, INFO, WARNING, ERROR, CRITICAL）

运行测试

./run_tests.sh

选项:

• --unit: 仅运行单元测试
• --integration: 仅运行集成测试
• --all: 运行所有测试（默认）
• --verbose: 详细的测试输出

构建和发布

要准备用于分发的软件包：

1. 同步依赖项并更新锁定文件：

uv sync

2. 构建软件包分发：

uv build

这将在dist/目录中创建源和wheel分发。

3. 发布到PyPI：

uv publish

注意：您需要通过环境变量或命令行标志设置PyPI凭据：

• 令牌：--token或UV_PUBLISH_TOKEN
• 或用户名/密码：--username/UV_PUBLISH_USERNAME和--password/UV_PUBLISH_PASSWORD

调试

由于MCP服务器通过stdio运行，因此调试可能很困难。为了获得最佳的调试 体验，强烈建议使用MCP Inspector。

要使用npm启动MCP Inspector，请运行以下命令：

npx @modelcontextprotocol/inspector uv --directory /path/to/ollama-MCP-server run ollama-mcp-server

启动时，Inspector将显示一个URL，您可以在浏览器中访问该URL以开始调试。

架构

贡献

欢迎贡献！请随时提交pull request。

1. Fork 存储库
2. 创建功能分支 (git checkout -b feature/amazing-feature)
3. 提交更改 (git commit -m 'Add some amazing feature')
4. 推送到分支 (git push origin feature/amazing-feature)
5. 打开 pull request

许可证

该项目在MIT许可证下获得许可 - 有关详细信息，请参阅LICENSE文件。

鸣谢

• Model Context Protocol 团队提供了出色的协议设计
• Ollama 项目使本地LLM执行成为可能
• 该项目的所有贡献者