Ollama MCP Proxy

无法使用 MCP 代理

一个全面的模型上下文协议（MCP）代理服务器，将MCP客户端与Ollama的本地语言模型连接起来，提供RAG集成、上下文管理、缓存和生产就绪安全等高级功能。

🌟 特性

核心功能

• MCP协议实现：通过工具、资源和提示提供完整的服务器端MCP支持
• Olama集成：与当地Ollama语言模型无缝连接
• 多种运输方式：支持服务器发送事件（SSE）和WebSocket的HTTP
• 高级上下文管理：基于会话的隔离，会话分支和合并

先进的人工智能能力

• RAG集成：使用FAISS和句子变换器进行基于矢量的文档检索
• 知识库连接：与外部知识来源的整合
• 高级总结：具有智能摘要的上下文窗口管理
• 多模型支持：动态模型发现和切换

性能和生产特点

• 智能高速缓存：使用Redis和本地回退的多层缓存
• 断路器型式：具有自动恢复功能的容错
• 速率限制：可配置的请求限制和保护
• 流媒体优化：高效的实时响应流

安全和身份验证

• OAuth 2.0支持：全面的身份验证和授权
• 基于角色的访问控制（RBAC）：精细的权限管理
• 数据加密：对敏感对话数据进行静态加密
• 安全标头：生产就绪安全配置

开发者体验

• 综合测试：单元、集成和负载测试套件
• 开发工具：热重新加载、分析和调试支持
• 结构化日志记录：带有相关ID的JSON格式日志
• 配置管理：基于环境的配置和验证

🏗️ 建筑

┌─────────────────┐    ┌──────────────────────┐    ┌─────────────────┐
│   MCP Client    │    │   Ollama MCP Proxy   │    │  Ollama Server  │
│  (Claude, etc.) │◄──►│                      │◄──►│   (Local AI)    │
└─────────────────┘    └──────────────────────┘    └─────────────────┘
                              │
                              ▼
                       ┌─────────────────┐
                       │  Configuration  │
                       │   & Storage     │
                       └─────────────────┘

关键组件

• OllamaMCP服务器：使用工具和资源处理程序实现主MCP服务器
• OllamaClient：具有重试逻辑和断路器的强大HTTP客户端
• 上下文管理器：具有分支和搜索功能的复杂会话管理
• RAG集成：基于矢量的文档检索和知识增强
• 安全框架：身份验证、授权和数据保护
• 缓存系统：具有智能升温和失效功能的多级缓存

🚀 快速开始

先决条件

• Python 3.8或更高版本
• Ollama在本地安装并运行
• Redis（可选，用于分布式缓存）

安装

1. 克隆存储库：

git clone https://github.com/ollama-mcp-proxy/ollama-mcp-proxy.git
cd ollama-mcp-proxy

1. 创建并激活虚拟环境：

python -m venv venv
# Windows
venv\Scripts\activate
# Unix/macOS
source venv/bin/activate

1. 安装依赖项：

pip install -r requirements.txt

1. 启动Ollama（如果尚未运行）：

ollama serve

1. 运行MCP代理：

python -m ollama_mcp_proxy.server --config config/development.json

或者使用CLI：

ollama-mcp-proxy --config config/development.json

📝 配置

代理为不同的环境使用JSON配置文件：

• config/development.json -具有调试模式的开发设置
• config/production.json -生产就绪配置

关键配置部分

{
  "ollama": {
    "host": "localhost",
    "port": 11434,
    "timeout": 30,
    "max_retries": 3
  },
  "mcp": {
    "port": 8000,
    "transport": "http",
    "auth_enabled": false
  },
  "cache": {
    "enabled": true,
    "type": "hybrid",
    "redis": {
      "enabled": true,
      "host": "localhost",
      "port": 6379
    }
  },
  "rag": {
    "enabled": false,
    "vector_store": "faiss",
    "embedding_model": "all-MiniLM-L6-v2"
  }
}

环境变量

• OLLAMA_HOST -Ollama服务器主机（默认：本地主机：11434）
• MCP_PROXY_PORT -MCP代理端口（默认值：8000）
• OLLAMA_MCP_CONFIG -配置文件的路径

🔧 Claude桌面集成

添加到您的Claude Desktop MCP配置中：

{
  "mcpServers": {
    "ollama-proxy": {
      "command": "python",
      "args": ["-m", "ollama_mcp_proxy"],
      "env": {
        "OLLAMA_HOST": "localhost:11434",
        "MCP_PROXY_PORT": "8000"
      }
    }
  }
}

🛠️ 可用工具

代理暴露了几个MCP工具：

文本完成

{
  "name": "ollama_completion",
  "arguments": {
    "prompt": "Explain quantum computing",
    "model": "llama2",
    "temperature": 0.7,
    "max_tokens": 500
  }
}

代码补全

{
  "name": "code_completion",
  "arguments": {
    "code": "def factorial(n):",
    "language": "python",
    "model": "codellama"
  }
}

工具链

{
  "name": "tool_chain",
  "arguments": {
    "tools": [
      {"tool": "research", "args": {"topic": "AI ethics"}},
      {"tool": "summarize", "args": {"input": "{{previous}}"}}
    ]
  }
}

📚 资源

MCP资源提供以下访问权限：

• 模型信息: /models/{model_name} -模型功能和元数据
• 系统状态: /system/status -健康和绩效指标
• 配置: /config/current -当前配置设置
• 会话信息: /sessions/{session_id} -会议背景和历史

🧪 发展

设置开发环境

1. 安装开发依赖项：

pip install -e ".[dev]"

1. 设置预提交挂钩：

pre-commit install

1. 在开发模式下运行：

python -m ollama_mcp_proxy.server --config config/development.json --debug

代码质量工具

• 黑色：代码格式
• isort：导入排序
• 薄片8：林婷
• mypy：类型检查

# Format code
black src/ tests/

# Sort imports
isort src/ tests/

# Run linting
flake8 src/ tests/

# Type checking
mypy src/

🧪 测试

该项目包括使用pytest进行全面测试：

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=ollama_mcp_proxy --cov-report=html

# Run specific test categories
pytest -m unit          # Unit tests only
pytest -m integration   # Integration tests only
pytest -m load          # Load tests only

# Run specific test file
pytest tests/test_auth.py -v

测试类别

• 单元测试：使用模拟依赖关系进行单个组件测试
• 集成测试：使用真正的Ollama集成进行端到端测试
• 负载测试：性能和并发测试

测试配置

测试使用中定义的综合夹具 conftest.py:

• 以可预测的反应模拟Ollama客户
• 样本测试数据和配置
• 错误场景模拟
• 异步测试支持

📊 性能特点

缓存策略

• 响应缓存：基于TTL过期的智能缓存
• 模型输出缓存：Ollama响应缓存用于重复查询
• 缓存预热：针对流行型号的主动缓存填充
• 分布式缓存：用于多实例部署的Redis集成

内存管理

• 上下文窗口滑动：长对话的自动上下文截断
• 内存压力处理：达到内存限制时自动清理
• 会话压缩：非活动会话的Zlib压缩
• 垃圾收集：高效清理过期会话

断路器

• 容错：自动故障检测和恢复
• 指数退避：智能重试策略
• 健康监测：对依赖关系进行持续的健康检查

🔒 安全功能

身份验证和授权

• API密钥验证：基于密钥的安全访问控制
• OAuth 2.0集成：行业标准认证
• 基于角色的访问控制：精细的权限管理
• JWT代币支持：使用JSON Web令牌进行无状态身份验证

数据保护

• 静态加密：对存储的对话数据进行AES加密
• 请求消毒：输入验证和净化
• 审计日志：全面的安全事件记录
• 安全标头：CORS、CSP和其他安全标头

速率限制

• 每用户限制：个人用户费率限制
• 全球限制：全系统防止滥用
• 滑动窗：先进的速率限制算法

🚀 生产部署

Docker部署

# Build Docker image
docker build -t ollama-mcp-proxy .

# Run with Docker Compose
docker-compose up -d

环境配置

# Production environment variables
export OLLAMA_MCP_CONFIG=/app/config/production.json
export REDIS_URL=redis://localhost:6379
export LOG_LEVEL=INFO

监控

• 健康终点: /health 和 /metrics 端点
• 结构化日志记录：带有相关ID的JSON日志
• 性能指标：请求/响应时间跟踪
• 错误率监控：全面的错误跟踪

🤝 贡献

我们欢迎捐款！请查看我们的 贡献指南 了解详情。

开发工作流程

1. 分叉存储库
2. 创建要素分支
3. 通过测试进行更改
4. 运行测试套件
5. 提交拉取请求

代码的风格

• 遵循PEP 8风格指南
• 全程使用类型提示
• 编写全面的文档字符串
• 保持测试覆盖率在90%以上

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 没有 用于提供本地语言模型API
• 模型上下文协议 对于协议规范
• Anthropic 用于MCP开发和Claude集成
• 所有帮助改善这个项目的贡献者

📞 支持

• 问题:
• 讨论:
• 文档: 阅读文档

______________________________________________________________________

内置于❤️ 对于MCP社区