STARWARCLOUD STARWAR.AI
返回市场
奥拉玛-MCP服务器

奥拉玛-MCP服务器

作者：NewAITees6 星标更新：2025-03-03
安装使用来源：spider==github.com

项目介绍

技术文档摘要

ollama-MCP-server

与Ollama通信的模型上下文协议（MCP）服务器

概要

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

主要功能：

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

组件

资源

服务器实现了以下资源：

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

每个资源都设置了适当的元数据和MIME类型，以确保与最佳LLM的有效对话。

提示词与工具的关系

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

  • 提示词：为LLM提供特定思维模式或结构的模式（Schema）角色
  • 工具：实际执行操作的处理器（Handler）角色

每个工具都需要一个对应的模式（提示词），这使得LLM的思维能力和实际系统功能能够有效协同。

提示词

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

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

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

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

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

工具

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

  • add-task

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

  • decompose-task

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

  • evaluate-result

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

  • run-model

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

新功能与改进

扩展错误处理

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

{
  "error": {
    "message": "未找到任务：task-123",
    "status_code": 404,
    "details": {
      "提供的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
  1. 创建并激活虚拟环境：
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
  1. 安装开发依赖项：
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
  1. 构建分发包：
uv build

这将在dist/目录中生成源代码和轮子的分发包。

  1. 发布到PyPI：
uv publish

注意：需要设置PyPI认证信息，可通过环境变量或命令标志：

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

调试

由于MCP服务器是通过标准I/O运行的，因此调试可能会比较困难。为了获得最佳的调试体验，强烈建议使用MCP Inspector。

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

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

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

贡献

欢迎贡献！请随意提交拉取请求。

  1. 分叉仓库
  2. 创建功能分支 (git checkout -b feature/amazing-feature)
  3. 提交更改 (git commit -m '添加一些惊人的功能')
  4. 推送到分支 (git push origin feature/amazing-feature)
  5. 打开拉取请求

许可证

本项目在MIT许可证下发布 - 详情请参阅LICENSE文件。

致谢