mcp-client-for-ollama

Establishes and manages connections to MCP servers across three transport protocols (STDIO, SSE, Streamable HTTP) with automatic server discovery. The ServerConnector component handles protocol negotiation, session management, and transport-specific serialization/deserialization, enabling seamless integration with heterogeneous MCP server implementations without requiring manual transport configuration.

Orchestrates tool invocation through a ToolManager that enables/disables tools, formats tool calls from LLM responses, executes them against MCP servers, and presents results to the user with optional approval gates. The system parses LLM-generated tool calls, validates them against available tool schemas, executes them via MCP protocol, and streams results back into the conversation context with human-in-the-loop checkpoints for safety-critical operations.

Automatically discovers and introspects MCP server capabilities including available tools, resources, and prompts with their full schema definitions. When connecting to an MCP server, the client queries the server's capabilities, parses tool schemas (including parameters, descriptions, and constraints), and makes this information available for tool selection, validation, and autocomplete. The system maintains an index of all discovered tools and their schemas for runtime validation.

Maintains conversation history and intelligently injects tool execution results back into the context for the LLM to process. The system tracks all user messages, LLM responses, and tool calls/results in a structured conversation object, formats tool results appropriately for LLM consumption, and includes relevant context in subsequent requests. This enables multi-turn conversations where the LLM can reason about tool results and take follow-up actions.

Runs entirely locally using Ollama for LLM inference and local MCP servers, with no requirement for cloud API calls or external services. All model inference, tool execution, and data processing happens on the user's machine, providing privacy, offline capability, and cost savings. The system is designed for air-gapped environments and provides full functionality without internet connectivity.

The StreamingManager processes MCP server responses and Ollama model outputs in real-time, handling token-by-token streaming from both sources with metrics collection and formatted output. It manages SSE streams from MCP servers, processes Ollama's streaming API responses, buffers partial tokens, and renders them to the terminal with latency tracking and throughput metrics.

The ModelManager abstracts Ollama model selection, parameter configuration (temperature, top_p, top_k, etc.), and request formatting. It maintains model state, validates parameter ranges, constructs properly-formatted Ollama API requests, and handles model switching without losing conversation context. The manager translates user-friendly parameter names to Ollama API fields and enforces model-specific constraints.

The ConfigManager handles saving and loading client configurations including server definitions, model preferences, tool selections, and custom system prompts. It persists state to ~/.mcp/config.json and supports multiple configuration profiles, enabling users to save different setups (e.g., 'creative-writing', 'code-generation') and switch between them. The manager handles defaults, migration, and validation of configuration files.

Implements FZF-style fuzzy autocomplete in the TUI that enables users to search and select from available commands, tools, and server options with real-time filtering. The system maintains searchable indices of available tools from connected MCP servers, command names, and model options, allowing users to type partial strings and see matching results ranked by relevance.

Enables agentic mode where the LLM can autonomously plan and execute multi-step workflows using available tools. The system implements a reasoning loop that processes LLM responses, extracts tool calls, executes them, feeds results back into context, and repeats until the LLM signals completion. This supports both explicit thinking mode (where the LLM's reasoning is visible) and implicit reasoning, with configurable iteration limits and safety checkpoints.

Manages MCP server-provided prompts and allows users to define custom system prompts that shape LLM behavior. The system loads prompt definitions from MCP servers, enables/disables them, and merges them with user-defined system prompts before sending requests to Ollama. This enables prompt composition where multiple prompts can be combined to create complex behavioral instructions.

Provides a rich terminal user interface built with Python TUI libraries that handles user input parsing, command execution, and session state management. The MCPClient class orchestrates the main interaction loop, parsing user commands (chat, tool management, model switching, configuration), executing them through appropriate managers, and rendering results to the terminal. The TUI maintains conversation history, manages session state, and provides visual feedback for all operations.

Implements a modular architecture with separate library and CLI packages, allowing the core MCP client functionality to be imported as a Python library while also providing a standalone CLI tool. The library package (mcp-client-for-ollama) exports core classes like MCPClient, ModelManager, and ToolManager for programmatic use, while the CLI package (mcp-client-for-ollama-cli) provides the TUI application. This separation enables both library users and CLI users to depend on only what they need.