Ollama Hive MCP Server

Ollama Hive MCP服务器

基于TypeScript的模型上下文协议（MCP）服务器，使用LangChain与Ollama模型集成。该服务器提供工具和资源，用于通过标准化的MCP接口查询本地语言模型，并具有特定于模型的MCP服务器配置。

特性

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

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 
cd ollama-hive

1. 安装依赖项：

npm install

1. 构建项目：

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：要生成的最大令牌数（可选）
• 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检查器

使用MCP检查器测试您的服务器：

npm run inspector

可用工具

query_model

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

参数：

• prompt （必填）：发送到模型的提示
• model （可选）：型号名称（如果未指定，则使用默认值）
• sessionId （可选）：会话上下文的会话ID
• createSession （可选）：如果没有提供会话ID，则自动创建新会话（启用自动会话连续性）

例子：

{
  "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配置中：

{
  "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"
      }
    }
  }
}

使用游标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. “配置未加载”错误

- 确保 MCP_CONFIG_PATH 设置正确 - 验证配置文件是否存在并且是有效的JSON

1. “找不到模型”错误

- 检查Ollama是否在配置的端点上运行 - 验证型号名称是否与Ollama型号完全匹配 - 检查端点解析顺序

1. 连接超时

- 确保Ollama服务器可访问 - 如果使用远程端点，请检查防火墙设置 - 验证 OLLAMA_ENDPOINT 环境变量（如果已设置）

1. MCP服务器连接问题

- 检查MCP服务器命令和参数 - 验证MCP服务器的环境变量 - 检查MCP包是否已安装

调试模式

启用调试日志记录：

export DEBUG=true
npm start

贡献

1. 分叉存储库
2. 创建要素分支
3. 进行更改
4. 如果适用，添加测试
5. 提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

相关项目

• 模型上下文协议
• MCP TypeScript SDK
• LangChain
• 没有

支持

如有疑问和支持：

• 在存储库中创建问题
• 检查 MCP文件
• 查看 LangChain文档