# jersonalvr/mcp architecture

> Architecture diagram of the GitHub repository jersonalvr/mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-03). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/jersonalvr/mcp
- Repository: https://github.com/jersonalvr/mcp

## Overview

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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Layer
    UI["User/CLI Interface"]:::cli

    %% Python Client Layer
    subgraph "Python Client (clients/ollama-py)"
        Chat["Chat Interface/Tool Manager (ollama-python-app.py)"]:::python
        MCPClient["MCP Client (mcp_client.py)"]:::python
        PyConfig1["Python Package Lock (uv.lock)"]:::python
        PyConfig2["Python Project Config (pyproject.toml)"]:::python
    end

    %% MCP Server Layer
    subgraph "MCP Server (servers/basic)"
        NodeServer["MCP Server (server.ts)"]:::node
        ServerConfig1["Server Package (package.json)"]:::node
        ServerConfig2["Server Config (tsconfig.json)"]:::node
    end

    %% External Service
    External["External Ollama API Service"]:::external

    %% Data Flows and Relationships
    UI -->|"sendsMessage"| Chat
    Chat -->|"triggersFunctionCall"| MCPClient
    Chat -->|"sendsLMQuery"| External
    MCPClient -->|"functionCallRequest"| NodeServer
    NodeServer -->|"returnsResponse"| MCPClient

    %% Click Events
    click UI "https://github.com/jersonalvr/mcp/blob/main/clients/ollama-py/ollama-python-app.py"
    click Chat "https://github.com/jersonalvr/mcp/blob/main/clients/ollama-py/ollama-python-app.py"
    click MCPClient "https://github.com/jersonalvr/mcp/blob/main/clients/ollama-py/mcp_client.py"
    click PyConfig1 "https://github.com/jersonalvr/mcp/blob/main/clients/ollama-py/uv.lock"
    click PyConfig2 "https://github.com/jersonalvr/mcp/blob/main/clients/ollama-py/pyproject.toml"
    click NodeServer "https://github.com/jersonalvr/mcp/blob/main/servers/basic/src/server.ts"
    click ServerConfig1 "https://github.com/jersonalvr/mcp/blob/main/servers/basic/package.json"
    click ServerConfig2 "https://github.com/jersonalvr/mcp/blob/main/servers/basic/tsconfig.json"

    %% Styles
    classDef cli fill:#D1E8E2,stroke:#333,stroke-width:2px;
    classDef python fill:#F9E79F,stroke:#333,stroke-width:2px;
    classDef node fill:#AED6F1,stroke:#333,stroke-width:2px;
    classDef external fill:#F5CBA7,stroke:#333,stroke-width:2px;
```
