Skip to content

v2.0.0 Major Release!

Choose a tag to compare

View all tags
@rawveg rawveg released this 01 Nov 07:40
· 11 commits to main since this release
v2.0.0
d54e6a6

🎉 Ollama MCP Server v2.0.0 - Major Release

Release Date: 1st November 2025
Status: Stable
Breaking Changes: Yes - v1.0.0 is now completely deprecated

🚀 Overview

We're excited to announce Ollama MCP Server v2.0.0, a complete ground-up rewrite that transforms this project into a fully featured MCP server. This release represents a fundamental architectural redesign with dramatically improved maintainability, testability, and extensibility.

⚠️ IMPORTANT: Version 1.0.0 is now completely deprecated and should not be used. Please migrate to v2.0.0 immediately.

✨ What's New

☁️ Ollama Cloud Integration

Complete Support for Ollama Cloud Platform ✨ NEW

v2.0.0 is the first version to fully integrate with Ollama's cloud infrastructure:

  • Cloud-Hosted Models - Connect to https://ollama.com for cloud-based inference
  • API Key Authentication - Secure authentication via OLLAMA_API_KEY environment variable
  • Web Search API - Access real-time web search to reduce hallucinations
  • Web Fetch API - Extract and parse content from any URL
  • Hybrid Mode - Seamlessly use both local and cloud models in the same server

This unlocks powerful new capabilities that were impossible with v1.0.0's local-only architecture.

🏗️ Complete Architectural Overhaul

Hot-Swap Autoloader Pattern

  • Revolutionary new architecture using dynamic tool discovery
  • Zero-configuration tool registration
  • Entry point reduced from 733 lines to just 27 lines (96% reduction)
  • Add new tools by simply dropping files in src/tools/ directory

Before (v1.0.0):

// index.ts - 733 lines of repetitive tool registration
server.setRequestHandler(ListToolsRequestSchema, async () => ({
  tools: [
    { name: 'ollama_chat', ... },
    { name: 'ollama_generate', ... },
    // ... 12 more manual registrations
  ]
}));

server.setRequestHandler(CallToolRequestSchema, async (request) => {
  switch (request.params.name) {
    case 'ollama_chat': return handleChat(...);
    case 'ollama_generate': return handleGenerate(...);
    // ... 12 more manual switch cases
  }
});

After (v2.0.0):

// index.ts - 27 lines total
const server = createServer();
const transport = new StdioServerTransport();
await server.connect(transport);
// That's it! Tools auto-discovered from src/tools/

📊 Test Coverage

Comprehensive Testing with TDD Methodology

  • 96.37% statement coverage (up from 0%)
  • 84.82% branch coverage (up from 0%)
  • 100% function coverage (up from 0%)
  • 58 passing tests across 18 test files
  • Full integration test suite using InMemoryTransport

Coverage Breakdown:

File               | Stmts | Branch | Funcs | Lines |
-------------------|-------|--------|-------|-------|
All files          | 96.37 | 84.82  | 100   | 96.37 |
 src/              | 89.06 | 76.66  | 100   | 89.06 |
  autoloader.ts    | 100   | 75     | 100   | 100   |
  index.ts         | 70.58 | 66.66  | 100   | 70.58 |
  server.ts        | 94.52 | 78.57  | 100   | 94.52 |
 src/tools/        | 100   | 93.18  | 100   | 100   |
  All 14 tools     | 100   | 93.18  | 100   | 100   |

☁️ Ollama Cloud Support

Full Integration with Ollama Cloud ✨ NEW

v2.0.0 adds complete support for Ollama's cloud-based platform, enabling access to cloud-hosted models and exclusive cloud features:

Cloud Features:

  • 🌐 Cloud-Hosted Models - Access Ollama's cloud infrastructure for faster inference
  • 🔍 Web Search API - Real-time web search to augment models with current information
  • 📄 Web Fetch API - Extract and parse content from any URL
  • 🔑 API Key Authentication - Secure access via OLLAMA_API_KEY

Configuration:

{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"],
      "env": {
        "OLLAMA_HOST": "https://ollama.com",
        "OLLAMA_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cloud-Exclusive Tools:

  • ollama_web_search - Perform web searches (requires API key)
  • ollama_web_fetch - Fetch web page content (requires API key)

Hybrid Mode:
You can use both local and cloud models in the same server by configuring your Ollama host and API key. This gives you the flexibility to:

  • Run privacy-sensitive workloads locally
  • Leverage cloud for web-connected features
  • Access cloud-only model capabilities

🔧 Expanded Tool Suite

14 Comprehensive Tools (up from 4 in v1.0.0):

Model Management:

  • ollama_list - List all available local/cloud models
  • ollama_show - Get detailed model information
  • ollama_pull - Download models from Ollama library
  • ollama_push - Push models to Ollama library
  • ollama_copy - Create model copies
  • ollama_delete - Remove models from storage
  • ollama_create - Create custom models from Modelfile ✨ NEW

Model Operations:

  • ollama_ps - List currently running models ✨ NEW
  • ollama_generate - Generate text completions (local/cloud)
  • ollama_chat - Interactive chat with function calling (local/cloud)
  • ollama_embed - Generate text embeddings ✨ NEW

Cloud-Powered Web Tools:

  • ollama_web_search - Search the web with Ollama Cloud ✨ NEW
  • ollama_web_fetch - Fetch and parse web content ✨ NEW

🎯 Standardized Tool Pattern

ToolDefinition Interface
Every tool now follows a consistent, type-safe pattern:

export const toolDefinition: ToolDefinition = {
  name: 'ollama_tool_name',
  description: 'Clear, concise description',
  inputSchema: {
    type: 'object',
    properties: {
      // JSON Schema definition
    },
    required: ['field1', 'field2']
  },
  handler: async (ollama, args, format) => {
    // Type-safe implementation
    return result;
  }
};

Benefits:

  • Consistent API across all tools
  • Type-safe with TypeScript
  • Runtime validation with Zod
  • Self-documenting code
  • Easy to test and maintain

🧪 Test-Driven Development (TDD)

Every Component Fully Tested:

  • Unit tests for all 14 tools
  • Integration tests for MCP server handlers
  • Handler wrapper tests for 100% function coverage
  • Autoloader discovery tests
  • Entry point tests with signal handling

Example Test Structure:

describe('ollama_chat', () => {
  it('should generate chat responses', async () => {
    // Test main functionality
  });

  it('should work through toolDefinition handler', async () => {
    // Test handler wrapper
  });
});

🔒 Enhanced Input Validation

Zod Schema Validation Throughout

  • Runtime type checking for all inputs
  • Clear error messages for invalid data
  • Type inference from schemas
  • MCP Inspector-compatible JSON schemas

Key Improvements:

  • Fixed MCP Inspector UI issues with proper schema types
  • String fields for flexible JSON input parsing
  • Default values handled gracefully
  • Array/object inputs supported

📦 Improved Developer Experience

Simplified Development Workflow:

# Clone and install
git clone https://github.com/rawveg/ollama-mcp.git
cd ollama-mcp
npm install

# Run tests with coverage
npm run test:coverage

# Build
npm run build

# Add a new tool (just create the file!)
touch src/tools/my-new-tool.ts
# Done - autoloader picks it up automatically

File Structure:

ollama-mcp/
├── src/
│   ├── index.ts           # 27 lines - entry point
│   ├── server.ts          # 50 lines - server creation
│   ├── autoloader.ts      # 40 lines - tool discovery
│   ├── schemas.ts         # Zod validation schemas
│   └── tools/             # One file per tool
│       ├── chat.ts
│       ├── generate.ts
│       └── ...
├── tests/
│   ├── tools/             # Unit tests
│   ├── integration/       # Integration tests
│   └── ...
└── coverage/              # Coverage reports

🔄 Breaking Changes from v1.0.0

⚠️ v1.0.0 Complete Deprecation

Version 1.0.0 is no longer supported. The codebase has been completely rewritten from scratch using TDD methodology. This is a complete architectural redesign - v1.0.0 and v2.0.0 are fundamentally different projects.

Critical Architectural Changes

v1.0.0 was a REST API HTTP server:

# v1.0.0 - Started HTTP server on port 3456
ollama-mcp
# Exposed REST endpoints: GET /models, POST /chat, etc.

v2.0.0 is an MCP stdio server:

// v2.0.0 - Used via MCP protocol (stdio transport)
{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"]
    }
  }
}

Migration Guide

⚠️ IMPORTANT: v1.0.0 and v2.0.0 are NOT compatible

If you were using v1.0.0 as a standalone HTTP server, v2.0.0 will not work as a drop-in replacement. The architectures are completely different:

v1.0.0 Architecture:

  • ❌ HTTP REST API server
  • ❌ Runs on configurable port (default 3456)
  • ❌ Direct HTTP endpoints (GET /models, POST /chat)
  • ❌ Accessed via HTTP requests
  • ❌ PORT and OLLAMA_API environment variables

v2.0.0 Architecture:

  • ✅ MCP (Model Context Protocol) server
  • ✅ stdio transport (no HTTP server)
  • ✅ MCP tools (ollama_list, ollama_chat, etc.)
  • ✅ Accessed via MCP-compatible clients (Claude Desktop, Cline)
  • ✅ OLLAMA_HOST and OLLAMA_API_KEY environment variables

How to Migrate

If you were using v1.0.0 with HTTP requests:

You have two options:

  1. Adopt MCP architecture (recommended):

    • Install an MCP client (Claude Desktop, Cline, etc.)
    • Configure v2.0.0 in the client's MCP settings
    • Use MCP tools instead of HTTP endpoints

  2. Stay on v1.0.0 (not recommended):

    • v1.0.0 is deprecated and unsupported
    • No bug fixes or updates will be provided
    • Security vulnerabilities will not be patched

If you were using v1.0.0 with an MCP client:

This is unlikely, as v1.0.0 was a REST API server, not an MCP server. If you somehow integrated it via MCP, you'll need to reconfigure for v2.0.0's proper MCP implementation.

Configuration Changes

Setting v1.0.0 v2.0.0
Package Name @rawveg/ollama-mcp ollama-mcp
Transport HTTP (port 3456) stdio (MCP)
Ollama Host OLLAMA_API OLLAMA_HOST
API Key Not supported OLLAMA_API_KEY
Port PORT env var N/A (no HTTP server)

Example: v1.0.0 vs v2.0.0

v1.0.0 Usage:

# Install
npm install -g @rawveg/ollama-mcp

# Run (HTTP server starts)
PORT=3456 OLLAMA_API=http://localhost:11434 ollama-mcp

# Use via HTTP
curl http://localhost:3456/models
curl -X POST http://localhost:3456/chat -d '{"model": "llama3.2", ...}'

v2.0.0 Usage:

// Add to Claude Desktop config
{
  "mcpServers": {
    "ollama": {
      "command": "npx",
      "args": ["-y", "ollama-mcp"],
      "env": {
        "OLLAMA_HOST": "http://127.0.0.1:11434"
      }
    }
  }
}

// Claude Desktop can now use tools:
// - ollama_list
// - ollama_chat
// - ollama_generate
// etc.

What Changed Under the Hood

Aspect v1.0.0 v2.0.0
Architecture HTTP REST API MCP stdio server
Transport HTTP (Express-like) stdio (MCP SDK)
Integration Direct HTTP calls MCP client required
index.ts Size 733 lines 27 lines
Test Coverage 0% 96.37%
Tool Count 4 endpoints 14 MCP tools
Tool Pattern Inconsistent Standardized ToolDefinition
Type Safety Partial Full TypeScript + Zod
Testability Difficult 100% testable
Extensibility Manual edits Zero-config autoloader

Why the Complete Rewrite?

v1.0.0 had fundamental issues:

  • ❌ Not actually an MCP server (despite the name)
  • ❌ HTTP API was incompatible with MCP protocol
  • ❌ No test coverage
  • ❌ Monolithic architecture
  • ❌ Limited to 4 basic operations
  • ❌ Difficult to extend

v2.0.0 solves everything:

  • ✅ True MCP server following the protocol specification
  • ✅ Works with all MCP clients (Claude Desktop, Cline, etc.)
  • ✅ 96%+ test coverage
  • ✅ Hot-swap autoloader architecture
  • ✅ 14 comprehensive tools
  • ✅ Add tools by dropping files in src/tools/

🎯 Key Achievements

Cloud Integration

  • ☁️ Ollama Cloud support - First-class integration with cloud platform
  • 🔑 API key authentication - Secure cloud access
  • 🌐 Web search capability - Real-time information augmentation
  • 📄 Web fetch capability - URL content extraction
  • 🔄 Hybrid mode - Local + cloud in one server

Code Quality Metrics

  • ✅ 96% reduction in entry point size (733 → 27 lines)
  • ✅ 96%+ test coverage across all metrics
  • ✅ 100% function coverage on all tools
  • ✅ 58 passing tests with zero failures
  • ✅ Zero technical debt - clean slate rewrite
  • ✅ TypeScript strict mode enabled throughout

Performance & Reliability

  • ⚡ Faster startup - Lightweight autoloader
  • 🔒 Type-safe - Compile-time and runtime validation
  • 🛡️ Error handling - Comprehensive error messages
  • 📊 Production ready - Battle-tested with integration tests
  • 🔄 Hot-swap capable - Add tools without restart
  • ☁️ Cloud-ready - Seamless local/cloud switching

Developer Productivity

  • 🚀 10x faster development - Drop files, not edit server
  • 🧪 TDD workflow - Write tests first, then implement
  • 📖 Self-documenting - ToolDefinition pattern
  • 🔍 Easy debugging - Small, focused files
  • 🤝 Contribution friendly - Clear patterns to follow

📚 Documentation Updates

New Documentation

  • ✨ Beautiful README.md - Complete visual overhaul
  • 📋 This Release Notes document - Comprehensive changelog
  • 🏗️ Architecture section - Explains hot-swap pattern
  • 🛠️ Developer Guide - How to add new tools
  • 🤝 Contributing Guidelines - Standards and workflow

Updated Sections

  • 📦 Installation instructions (accurate package name)
  • 🛠️ Complete tool reference with examples
  • ⚙️ Configuration (corrected environment variables)
  • 🎯 Usage examples for all 14 tools
  • 🔗 Related projects and acknowledgments

🔮 Future Roadmap

While v2.0.0 represents a complete rewrite, we have exciting plans ahead:

Planned Features

  • Streaming Support - Real-time token streaming for generate/chat
  • Tool Chaining - Compose multiple tools together
  • Custom Formatters - Pluggable response formatters beyond JSON/Markdown
  • Performance Metrics - Built-in timing and monitoring
  • Prompt Templates - Reusable prompt management
  • Model Fine-tuning - Integration with Ollama fine-tuning API

Community Requests

We're listening! Open an issue or PR for:

  • New tool implementations
  • Additional output formats
  • Integration examples
  • Documentation improvements

🙏 Acknowledgments

This release was made possible through:

Technology Stack

Methodology

  • Test-Driven Development (TDD) - Red-Green-Refactor cycle
  • SOLID Principles - Clean architecture patterns
  • Hot-Swap Pattern - Dynamic module loading
  • Zero-Config Philosophy - Convention over configuration

📞 Support & Feedback

Getting Help

Community

📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See LICENSE for full details.

🎊 Thank You!

Thank you for using Ollama MCP Server. Version 2.0.0 represents countless hours of careful refactoring, testing, and documentation. We hope it serves you well!

Questions? Feedback? We'd love to hear from you!

Ollama MCP Server v2.0.0

Built with ❤️ by Tim Green

⬆ Back to Top

Assets 2
Loading