Build interfaces · Lesson 04
Call RGB and HSV conversions through MCP
The video uses TheAlgorithms/Python to convert colours. A Python MCP client makes discovery, successful results and input errors visible without requiring a language model.
By the end of this lesson
- Select rgb_to_hsv and hsv_to_rgb while keeping their helper private.
- Explain the stdio client/server lifecycle.
- Check the error flag before reading structured_content.
Watch the lesson
English · 5:09 · Recorded with Apizr 0.4.3.
Chapters in this recording
| Time | Chapter |
|---|---|
| 00:00 | Turn existing Python into callable MCP tools. |
| 00:19 | One color. Two representations. |
| 00:41 | Pin the project and locate the conversion module. |
| 01:17 | Inspect the contract before generation. |
| 01:46 | Generate an MCP bundle with an explicit selection. |
| 02:16 | The client starts the local server. |
| 02:39 | Prepare the MCP runtime. |
| 03:07 | A small client makes the protocol exchange explicit. |
| 03:41 | List the tools and make two real calls. |
| 04:18 | Check the error flag before using a result. |
| 04:44 | Python functions, verified as MCP tools. |
Read the recording transcript and commands
This is the retained English narration, in the original chapter order. Commands keep the recorded version and prerequisites; setup additions in the lesson are labelled separately.
00:00 — Turn existing Python into callable MCP tools.
In this episode, we will generate MCP tools from existing Python code and call them through the official Python client. Our example converts colors between R G B and H S V. You will see the actual tool list, returned values, and an invalid input response.
00:19 — One color. Two representations.
R G B represents red using two hundred fifty five, zero, zero. H S V represents the same color using hue zero, saturation one, and value one. We will expose both conversion directions from The Algorithms Python repository. A comparison helper will remain outside the tool list.
00:41 — Pin the project and locate the conversion module.
Clone The Algorithms Python repository and check out the recorded commit. Locate the color conversion module under conversions. This is existing Python source with ordinary function declarations. We do not add MCP decorators or rewrite the arithmetic to fit a server framework.
git clone --depth 1 https://github.com/TheAlgorithms/Python.git
cd Python
git fetch --depth 1 origin ef2ecc4d34d17ce6249ba5d3f3c17822dfd7bd50
git checkout ef2ecc4d34d17ce6249ba5d3f3c17822dfd7bd50
git rev-parse --short HEAD
sed -n '14,23p' conversions/rgb_hsv_conversion.py
01:17 — Inspect the contract before generation.
Inspect the module and save the report. Its three functions have ready input contracts. We will expose two conversion functions, leaving the comparison helper private. This readiness result concerns the interface. The direct mode runtime will execute trusted source, so we have also reviewed the conversion code itself.
apizr inspect conversions/rgb_hsv_conversion.py > inspection.txt
grep -E '^[a-z_]+$|readiness:|can generate interface:' inspection.txt
01:46 — Generate an MCP bundle with an explicit selection.
Generate the MCP bundle, selecting only R G B to H S V and H S V to R G B. The output includes a server, the original source, tool definitions and runtime requirements. The tool definitions describe what a client can call. Generating these files does not start the server or make a tool call.
apizr generate mcp conversions/rgb_hsv_conversion.py --select rgb_to_hsv,hsv_to_rgb --output-dir mcp
ls mcp
02:16 — The client starts the local server.
We will use standard input and output transport. The Python client launches the generated server, completes the protocol handshake, lists the tools, and sends a call with named arguments. This verifies the same tool boundary an MCP compatible application can use. No language model account is needed for this test.
02:39 — Prepare the MCP runtime.
Create the runtime environment and install the bundle requirements. They include the MCP Python SDK, so the same runtime can run our test client and the generated server. Apizr itself is not needed inside this environment. We will keep the test client beside the generated bundle.
uv venv --python python3.14 runtime
uv pip install --python runtime/bin/python -r mcp/requirements.txt
03:07 — A small client makes the protocol exchange explicit.
Save this client as call tools dot py. The server parameters point to the generated server and select standard input and output transport. Entering the client context connects and negotiates the protocol. Listing tools and calling a tool are separate operations. Always check is error before using the structured result.
sed -n '1,14p' call_tools.py
sed -n '15,28p' call_tools.py
03:41 — List the tools and make two real calls.
Ask the running server for its tools. Only the two selected conversions are listed. Now convert red from R G B to H S V. The returned object contains a result list with zero, one, one. Convert a green H S V value in the other direction and read zero, two hundred fifty five, zero. These are actual server responses, not values inferred by an assistant.
runtime/bin/python call_tools.py list
runtime/bin/python call_tools.py red
runtime/bin/python call_tools.py green
04:18 — Check the error flag before using a result.
Finally, send a string for the red channel, which requires an integer. The call returns an error and no structured result. The client checks that flag instead of treating every response as success. Input validation and the function execution result are both part of a useful integration test.
runtime/bin/python call_tools.py invalid
04:44 — Python functions, verified as MCP tools.
You have inspected existing code, selected two tools, generated a server, and verified real MCP calls. To connect an application, use its MCP configuration with the same runtime Python, generated server, and standard input and output transport. Keep the returned tool results as your evidence that the integration works.
1. Pin and generate the recorded module
The video uses Apizr 0.4.3 and this exact repository revision:
git clone --depth 1 https://github.com/TheAlgorithms/Python.git
cd Python
git fetch --depth 1 origin ef2ecc4d34d17ce6249ba5d3f3c17822dfd7bd50
git checkout ef2ecc4d34d17ce6249ba5d3f3c17822dfd7bd50
apizr inspect conversions/rgb_hsv_conversion.py > inspection.txt
apizr generate mcp conversions/rgb_hsv_conversion.py --select rgb_to_hsv,hsv_to_rgb --output-dir mcp
uv venv --python python3.14 runtime
uv pip install --python runtime/bin/python -r mcp/requirements.txt
The inspected module has three ready functions. The selection makes the two conversions public; the comparison helper remains outside the tool list. Generating the bundle does not start its server.
2. Use the recorded client
Download the original call_tools.py, saving it beside mcp/ as call_tools.py. This is the actual client used in the recording. Its StdioServerParameters selects the current runtime interpreter and the generated server. The client context performs connection and handshake before discovery or a call.
runtime/bin/python call_tools.py list
runtime/bin/python call_tools.py red
runtime/bin/python call_tools.py green
runtime/bin/python call_tools.py invalid
| Operation | Retained response |
|---|---|
| List tools | hsv_to_rgb, rgb_to_hsv |
| RGB red: 255, 0, 0 | {"result": [0.0, 1.0, 1.0]} |
| HSV green: 120, 1, 1 | {"result": [0, 255, 0]} |
| Red channel passed as a string | is_error: True, structured_content: null |
These are actual server results. Tool discovery and tool invocation are separate protocol operations. A model's later prose is not a replacement for either.
Practice
Predict both colour conversions, verify that only the two selected tools are listed, and run the invalid-input case. Explain why checking only whether a response object exists would miss the error.
Check your reasoning
Red has hue 0, saturation 1 and value 1. HSV hue 120 gives RGB green. The invalid string returns an error and no structured result. Check is_error before interpreting structured_content; a completed protocol exchange can carry a failed tool call.