Ollama Hive MCP Server

Ollama Hive MCP 服务

一个基于 TypeScript 的 Model Context Protocol (MCP) 服务，通过 LangChain 集成 Ollama 模型。此服务通过标准化的 MCP 接口提供用于查询本地语言模型的工具和资源，并支持针对特定模型的 MCP 服务配置。

功能

• 模型管理：配置和管理多个 Ollama 模型
• 模型专属 MCP：每个模型都可以拥有自己的一组 MCP 服务
• 会话管理：通过对话会话在多次查询间保持上下文连续性
• 环境变量支持：通过环境变量覆盖端点和配置
• LangChain 集成：借助 LangChain 与模型交互
• 基于环境的配置：从 MCP_CONFIG_PATH 加载配置
• MCP 工具：查询模型、测试连接并列出可用模型
• MCP 资源：访问模型配置和元数据
• Stdio 传输：通过标准输入/输出通信实现无缝集成
• 预配置模型：定义具有专属端点和设置的模型
• 模型预加载：启动时加载所有模型，以便快速响应
• 性能监控：内置响应时间跟踪和状态监控

使用 NPX 快速开始

使用 npx 直接运行服务（无需安装）：

# Basic usage
npx ollama-hive-mcp-server

# With custom configuration
MCP_CONFIG_PATH=./my-config.json npx ollama-hive-mcp-server

# With environment overrides
OLLAMA_ENDPOINT=http://localhost:11434 MCP_CONFIG_PATH=./config.json npx ollama-hive-mcp-server

简化接口

此服务提供简洁、简化的接口：

可用工具

• query_model - 查询预配置模型，可选使用会话上下文
• test_model - 测试模型连接
• get_model_info - 获取模型详情和 MCP 信息
• list_models - 列出所有已配置模型
• get_config_summary - 查看配置概览
• get_loading_status - 查看模型加载状态
• create_session - 创建对话会话，以保持上下文连续性
• list_sessions - 列出所有活动对话会话
• get_session - 获取详细的会话信息和消息历史
• delete_session - 删除指定的对话会话
• clear_sessions - 清除所有对话会话

使用示例

{
  "tool": "query_model",
  "arguments": {
    "prompt": "Hello, world!"
  }
}

{
  "tool": "query_model", 
  "arguments": {
    "model": "llama3.2",
    "prompt": "Write a Python function to calculate fibonacci"
  }
}

{
  "tool": "query_model",
  "arguments": {
    "prompt": "Explain quantum computing",
    "createSession": true
  }
}

基于会话的对话

{
  "tool": "create_session",
  "arguments": {
    "modelName": "llama3.2",
    "title": "Coding Session"
  }
}

{
  "tool": "query_model",
  "arguments": {
    "sessionId": "your-session-id",
    "prompt": "Write a Python function to calculate fibonacci"
  }
}

{
  "tool": "query_model",
  "arguments": {
    "sessionId": "your-session-id", 
    "prompt": "Now add error handling to that function"
  }
}

模型会自动使用预配置的设置（温度、端点、MCP 服务）。会话会保留对话上下文，支持自然的多轮交互。

文档

• 会话管理指南 - 使用对话会话的完整指南
• 测试指南 - 全面的测试和验证说明
• 日志系统 - 与 MCP 兼容的日志系统文档

前提条件

• Node.js 18+
• Ollama 在本地运行（默认：http://localhost:11434）
• 用于自定义的 TypeScript 知识

安装

1. 克隆代码仓库：

git clone <repository-url>
cd ollama-hive

2. 安装依赖：

npm install

3. 构建项目：

npm run build

配置

环境变量

设置以下环境变量以配置服务：

# Required: Path to your MCP configuration file
export MCP_CONFIG_PATH=/path/to/your/mcp-config.json

# Optional: Override Ollama endpoint for all models
export OLLAMA_ENDPOINT=http://localhost:11434

# Optional: Enable debug logging
export DEBUG=true

# Optional: Set Node environment
export NODE_ENV=production

配置文件格式

创建一个具有以下结构的 JSON 配置文件：

{
  "globalEndpoint": "http://localhost:11434",
  "models": [
    {
      "name": "llama3.2",
      "endpoint": "http://custom-endpoint:11434",
      "model": "llama3.2:latest", 
      "temperature": 0.7,
      "maxTokens": 2048,
      "description": "Llama 3.2 model for general purpose tasks",
      "mcps": [
        {
          "name": "filesystem-server",
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-filesystem", "/allowed/path"],
          "description": "Filesystem access MCP server",
          "env": {
            "NODE_ENV": "production"
          }
        }
      ]
    }
  ],
  "defaultModel": "llama3.2"
}

配置字段

全局配置：

• globalEndpoint：所有模型的默认端点（可选）
• defaultModel：要使用的默认模型名称（可选）

模型配置：

• name：模型的唯一标识符（必需）
• endpoint：模型专用的端点覆盖设置（可选）
• model：Ollama 模型名称（必需，例如：llama3.2:latest）
• temperature：生成响应的温度，范围为 0.0-2.0（可选，默认值：0.7）
• maxTokens：要生成的最大 token 数（可选）
• description：易于理解的描述（可选）
• mcps：此模型的 MCP 服务数组（可选，默认值：[]）

MCP 服务配置：

• name：MCP 服务的唯一标识符（必需）
• command：要执行的服务命令（必需）
• args：命令行参数（可选）
• env：服务的环境变量（可选）
• description：易于理解的描述（可选）

端点解析优先级

服务按以下优先级顺序解析端点：

1. OLLAMA_ENDPOINT 环境变量（优先级最高）
2. 模型专用的 endpoint 配置
3. 全局 globalEndpoint 配置
4. 默认值：http://localhost:11434（优先级最低）

配置示例

请参阅 config/example-mcp-config.json，其中提供了包含多个模型及其关联 MCP 服务的完整示例。

用法

启动服务

# Set configuration path
export MCP_CONFIG_PATH=./config/example-mcp-config.json

# Optional: Override Ollama endpoint
export OLLAMA_ENDPOINT=http://localhost:11434

# Start the server
npm start

开发模式

npm run dev

使用 MCP Inspector

使用 MCP Inspector 测试服务：

npm run inspector

可用工具

query_model

使用提示词查询已配置的 Ollama 模型。

参数：

• prompt（必需）：要发送给模型的提示词
• model（可选）：模型名称（未指定时使用默认模型）
• sessionId（可选）：用于对话上下文的会话 ID
• createSession（可选）：如果未提供 sessionId，则自动创建新会话（启用自动保持对话连续性）

示例：

{
  "model": "llama3.2",
  "prompt": "Explain the concept of Model Context Protocol",
  "createSession": true
}

会话示例：

// Auto-create session for conversation continuity
{
  "prompt": "Write a Python function",
  "createSession": true
}

// Use existing session
{
  "prompt": "Now add error handling to that function",
  "sessionId": "existing-session-id"
}

test_model

测试与指定模型及其 MCP 连接的连通性。

参数：

• model（必需）：要测试的模型名称

示例：

{
  "model": "llama3.2"
}

get_model_info

获取模型及其 MCP 服务的详细信息。

参数：

• model（必需）：要获取信息的模型名称

示例：

{
  "model": "codellama"
}

list_models

列出所有已配置的可用模型及其 MCP 数量。

参数： 无

get_config_summary

获取包含环境覆盖设置的配置摘要。

参数： 无

可用资源

model://list

返回所有已配置模型的列表，其中包含解析后的端点和可用状态。

model://default

返回默认模型配置。

model://{name}

按名称返回指定模型的配置。

config://summary

返回包含环境覆盖设置的配置摘要。

config://environment

返回当前环境配置。

集成示例

与 Claude Desktop 配合使用

将以下内容添加到 Claude Desktop 配置中：

{
  "mcpServers": {
    "ollama-hive": {
      "command": "node",
      "args": ["/path/to/ollama-hive/dist/index.js"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/your/config.json",
        "OLLAMA_ENDPOINT": "http://localhost:11434"
      }
    }
  }
}

与 Cursor IDE 配合使用

在 Cursor 的 MCP 设置中进行配置：

{
  "servers": {
    "ollama-hive": {
      "command": "node",
      "args": ["/path/to/ollama-hive/dist/index.js"],
      "env": {
        "MCP_CONFIG_PATH": "/path/to/your/config.json",
        "OLLAMA_ENDPOINT": "http://localhost:11434"
      }
    }
  }
}

环境文件设置

在项目根目录中创建 .env 文件：

MCP_CONFIG_PATH=./config/example-mcp-config.json
OLLAMA_ENDPOINT=http://localhost:11434
DEBUG=false
NODE_ENV=development

模型专用 MCP 服务

每个模型都可以拥有自己的一组 MCP 服务，从而使用专门的工具集：

• 通用模型：文件系统、网页搜索、记忆工具
• 代码模型：GitHub 集成、用于代码的文件系统、文档工具
• 研究模型：网页搜索、学术数据库、参考工具
• 创意模型：图像生成、创意写作工具

这样，你就可以根据每个模型的预期用途定制可用工具。

错误处理

服务包含全面的错误处理：

• 配置错误：JSON 无效或缺少必填字段
• 环境错误：缺少或无效的环境变量
• 模型错误：连接失败或模型名称无效
• MCP 错误：MCP 服务连接或工具执行失败
• 工具错误：参数无效或执行失败

所有错误均以标准化格式返回，并包含详细的错误消息。

开发

项目结构

src/
├── index.ts           # Main server implementation
├── config.ts          # Configuration loader with environment support
├── langchain-manager.ts # LangChain model management with MCP integration
└── types.ts           # TypeScript type definitions

config/
└── example-mcp-config.json # Example configuration

构建

npm run build

监视更改

npm run watch

类型检查

项目采用严格的 TypeScript 设置，并提供全面的类型安全保障。

安全注意事项

• 模型访问：只能访问已配置的模型
• MCP 隔离：每个模型的 MCP 均与其他模型隔离
• 配置验证：使用 Zod 模式验证所有配置
• 环境变量安全：可通过环境变量传递敏感数据
• 错误清理：对错误消息进行清理，以防信息泄露

性能

• 连接复用：跨请求复用模型连接
• 延迟加载：仅在首次访问时初始化模型和 MCP
• 环境缓存：在启动时缓存环境配置
• 内存管理：通过适当的清理，高效使用内存

故障排除

常见问题

1. “Configuration not loaded”错误

   • 确保正确设置了 MCP_CONFIG_PATH
   • 确认配置文件存在且为有效的 JSON

2. “Model not found”错误

   • 检查 Ollama 是否在已配置的端点上运行
   • 确认模型名称与 Ollama 中的模型名称完全一致
   • 检查端点解析顺序

3. 连接超时

   • 确保可以访问 Ollama 服务
   • 如果使用远程端点，请检查防火墙设置
   • 如果设置了 OLLAMA_ENDPOINT 环境变量，请确认其值

4. MCP 服务连接问题

   • 检查 MCP 服务命令和参数
   • 确认 MCP 服务的环境变量
   • 检查是否已安装 MCP 软件包

调试模式

启用调试日志：

export DEBUG=true
npm start

贡献

1. Fork 此仓库
2. 创建功能分支
3. 进行更改
4. 如适用，请添加测试
5. 提交拉取请求

许可证

MIT 许可证——详情请参阅 LICENSE 文件。

相关项目

• Model Context Protocol
• MCP TypeScript SDK
• LangChain
• Ollama

支持

如有疑问或需要支持：

• 在仓库中创建议题
• 查看 MCP 文档
• 查阅 LangChain 文档