Mcp-basics

# MCP Basics I built this repository while learning MCP because AI agents I worked with kept asking me to use a minimal tool-calling protocol. I wanted to understand what was happening under the hood, so I implemented both the server and client from scratch in Python without any extra modules. ## What you will find here - `basic-mcp-server.py` – a minimal server reading JSON requests from `stdin` and returning JSON responses to `stdout` - `basic-mcp-client.py` – a client that starts the server as a subprocess and sends a request - `mcp-server.py` – a slightly richer server that follows a simple JSON-RPC-like format with `initialize`, `tools/list`, and `tools/call` - `mcp-client.py` – a client that exercises the richer server by initializing, listing tools, and calling one ## How it works The basic idea is: 1. The server listens on `stdin` line by line. 2. The client sends one JSON object per line to the server. 3. The server parses the request, runs a tool function, and writes a JSON response to `stdout`. 4. The client reads the response line and processes it. This keeps the implementation small and dependency-free. ## Basic server / client ### Run the basic server manually ```bash python3 basic-mcp-server.py ``` Then type a request like this (one line): ```json {"tool": "say_hello", "arguments": {"name": "bro"}} ``` The server prints a response such as: ```json {"result": "Hello bro"} ``` ### Run the basic client ```bash python3 basic-mcp-client.py ``` This client starts `mcp-server.py` as a subprocess, sends a single `say_hello` request, and prints the response. ## JSON-RPC-style server / client The richer example uses a very small JSON-RPC-like protocol. ### Supported methods in `mcp-server.py` - `initialize` – returns server name and version - `tools/list` – returns a list of available tools - `tools/call` – invokes a tool by name with arguments ### Supported tools - `say_hello(name)` – returns `Hello {name}` - `add(a, b)` – returns the numeric sum ### Run the richer client ```bash python3 mcp-client.py ``` This client sends three requests in sequence: 1. initialize 2. tools/list 3. tools/call with `say_hello` ## Why this is useful This project is a hands-on way to learn how a tool-calling protocol can be built from scratch: - no module imports beyond Python standard library - simple text-based process communication using `stdin`/`stdout` - JSON message structure makes the protocol easy to extend - server and client can be separated cleanly even in a minimal setup - the protocol can stay tiny while still letting the agent discover and call tools