How jersonalvr/mcp works
1. The Python client (located in clients/ollama-py) that serves as the interactive application and MCP client:
• It contains files like ollama-python-app.py (the main application that handles chat interaction, function calling, and tool management) and mcp_client.py (which encapsulates communication with MCP servers).
• It relies on packages managed via uv (with uv.lock) and uses environment variables for configuration (e.g., URLs for the Ollama API and the MCP server).
The Node.js-based MCP server (located under servers/basic)
• This part includes a TypeScript/Node.js server (server.ts) along with package.json and tsconfig.json, indicating that it exposes the MCP endpoints that the Python client will interact with.
• It is a lightweight server that is configured (and possibly compiled via npm run build) to receive and process function calling requests.
A. Main Components
1. User Interface (CLI): Represented by the console-based chat interface provided by the Python application.
2. Python Application (Clients/ollama-py):
• Core logic (ollama-python-app.py) handling interaction with external entities.
• Tool Manager and the built-in tools (like get_current_weather and sum_two_numbers) along with extension points for new tools.
• MCP Client functionality (mcp_client.py) which communicates with MCP servers.
3. MCP Server (servers/basic):
• Node.js/TypeScript-based server that accepts requests from the client.
• Acts as a bridge to extend the capabilities of the language model via MCP.
4. External Ollama API:
• The local Ollama service (accessed at a configurable URL, usually http://localhost:11434) which provides responses from a language model and supports function calling.
B. Relationships & Data Flows
• The user enters messages in the CLI. The Python Application processes these messages.
• When a function call is needed, the Python app uses mcp_client.py to send a request to the MCP Server.
• The MCP Server, built in Node.js, processes these requests (and may trigger specific tool functionalities or integrate further external APIs).
• The Python app also directly communicates with the Ollama API (to retrieve model responses or send/receive data) using configured URLs.
C. Architectural Patterns & Design Principles
• Separation of concerns: The Python application is primarily responsible for client interactions and MCP communication, while the Node.js server isolates the MCP functionality.
• Extensibility: The design allows for built-in tools and future extension by modifying the ToolManager in python code.
• Integration Pattern: The project serves as a middleware integrating external systems (Ollama API and additional MCP capabilities).
D. Technologies, Frameworks, and Libraries
• Python 3.9+ alongside a package manager (uv) for dependency management.
• Node.js and TypeScript forming the backend MCP server.
• Ollama local API (external dependency) which must be running and accessible.
• Use of environment configuration variables to toggle key parameters (like the server path and API URL).
• User/CLI Interface
• Python Application (with two sub-components: Chat Interface/Tool Manager and MCP Client)
• MCP Server (Node.js/TypeScript-based)
• External Ollama API Service
• User interactions flowing into the Python Application.
• Python Application sending requests to the MCP Server.
• Communication between the Python Application and the Ollama API (direct API calls).
• Any potential callback or response paths.
Brief notes on key functions
• In the Python application, highlight that “ollama-python-app.py” drives the chat interface and manages tool interactions.
• In the MCP Server block, note that it leverages server.ts (TypeScript) to handle incoming function call requests.
• Under “External Services,” denote that the Ollama API acts as the language model provider.
Be as detailed as possible
• Separate the system into many components rather than one big block.
• Dependencies like configuration (environment variables), package management (uv.lock vs. package.json/tsconfig.json), and versioning (Python versions, Node.js requirements) are noted.
• Integration points – especially where function calling occurs – to give clarity on data paths and control flow.