🖼️ See the drawing + lab 🏠 Course home 🌿 Branch on GitHub ✏️ View source

🖼️ आकृती आणि labThe drawing + lab पूर्ण पानावर उघडा ↗Open full page ↗

🔬 धडा 06 — Server बांधा: ~125 प्रामाणिक ओळी

📍 तुम्ही इथे आहात: 8 पैकी धडा 06 · मागे: lesson-05-transports-security · पुढे: lesson-07-build-a-client

📦 या ब्रँचमध्ये काय आहे

धडे 01–05, आणि एका खऱ्या MCP server चे मार्गदर्शित वाचन — server/school_server.py — आणि त्यात तुमची पहिली भर.

🧒 5 वर्षांच्या मुलाला समजावल्यासारखे

उपकरण बांधणे भीतिदायक वाटते, जोपर्यंत तुम्ही एखादे उघडलेले पाहत नाही. आपल्या उपकरणात file मध्ये वरून खाली नेमके चार भाग आहेत:

गुंडाळलेली गोष्ट 🗄️ — एक खेळण्यातला database (DB, HOMEWORK). खऱ्या servers मध्ये हाच रंजक भाग असतो: तुमचा Postgres, तुमचा API, तुमची filesystem. MCP म्हणजे फक्त पुढे लावलेला plug.
कप्प्यांची यादी 📋 — TOOLS: नाव + वर्णन + inputSchema अशा तीन नोंदी. L03 आठवा: वर्णने model साठी असतात — आपली वर्णने प्रत्येक tool काय करतो ते सांगतात आणि add_homework write करतो हेही (धोक्याचे लेबल, L05!).
Dispatcher 🔀 — run_tool(name, args): प्रत्यक्ष काम करणारी साधी Python if-ladder. इथे protocol सारखे काहीच नाही — तुम्ही ती एकटी unit-test करू शकता.
Plumbing 🔧 — main(): एक ओळ वाचा, JSON parse करा, badge तपासा (चुकीची आवृत्ती → आपण बोलतो त्या आवृत्त्यांसह -32022), L04 मधून तुम्हाला माहीत असलेल्या तीन methods ना उत्तर द्या (server/discover, tools/list, tools/call), reply छापा. Tool अपयश → नम्र isError content, कधीच crash नाही; अज्ञात tool → योग्य -32602.

हाच server. अधिकृत SDKs (Python/TypeScript mcp packages) तुम्हाला decorators, typed schemas, transports आणि spec चे उरलेले बारीकसारीक भाग देतात — खऱ्या कामासाठी ते वापरा — पण ते याच चार भागांचे automation करतात, आणि आता तुम्ही ते भाग पाहिले आहेत.

🗺️ आकृती

flowchart TB
    subgraph file["server/school_server.py - the four parts"]
        db["1 🗄️ the wrapped thing<br/>DB + HOMEWORK (yours: Postgres, APIs…)"]
        tools["2 📋 the shelf: TOOLS<br/>name · description(for the model!) · inputSchema"]
        disp["3 🔀 run_tool()<br/>plain Python if-ladder — unit-testable"]
        plumb["4 🔧 main() loop<br/>line in → JSON-RPC → line out"]
    end
    host["🔌 any MCP host"]
    host <-->|"stdio"| plumb
    plumb --> disp --> db
    plumb --> tools

📖 या ओळी वाचा (म्हणजे तुम्ही हरवणार नाही)

server/school_server.py:

ओळी 20–25: भाग 1, गुंडाळलेली गोष्ट (DB, HOMEWORK)
ओळी 27–55: भाग 2, कप्पा (TOOLS)
ओळी 57–71: भाग 3, dispatcher (run_tool)
ओळी 74–84: भाग 4a, दोन reply helpers (प्रत्येक result वर badge + resultType)
ओळी 85–शेवट: भाग 4b, loop — आधी badge तपासणी, मग तीन verbs

❓ काय (चोरण्यासारखे तपशील)

प्रत्येक print वर flush=True — हे विसरणारे stdio servers गूढपणे "अडकतात" (पहिला classic bug: buffered replies कधीच पोहोचत नाहीत).
फक्त जे विचारले त्यालाच उत्तर द्या; अज्ञात method + id → error -32601. Notifications ना errors नव्हे, शांतता मिळते.
दोन प्रकारच्या errors, मुद्दाम: protocol error (code सह error: चुकीची आवृत्ती -32022, अज्ञात tool -32602) विरुद्ध tool error (isError: true सह result) — दुसरी model साठी आहे.
प्रत्येक reply() resultType: "complete" आणि server चा badge (_meta → serverInfo) जोडतो; list results मध्ये ttlMs/cacheScope जोडले जातात, म्हणजे hosts कप्पा cache करू शकतात.
Tool errors {"content":[…], "isError": true} म्हणून — model अपयश वाचू शकतो आणि पुन्हा प्रयत्न करू शकतो (agent चा retry loop, AI कोर्स L11, यावरच अवलंबून आहे!).
Schemas म्हणजे करार: "enum": ["3A","3B"] म्हणजे model ला कायदेशीर values सांगितल्या जातात — कमी चुकीचे calls, चांगले वर्तन. समृद्ध schemas म्हणजे model ला दिशा देण्याचा स्वस्त मार्ग.
इथून पुढच्या खऱ्या सुधारणा: अधिकृत SDK, report cards साठी resources/list (L03 चा गृहपाठ!), env-var secrets, आणि मर्यादित DB account (least privilege — AWS कोर्स L03).

🤔 का

कारण "आपल्या X साठी MCP server बांधला पाहिजे" हे आता अर्ध्या उद्योगात sprint ticket आहे — आणि तुम्ही त्याचा प्रामाणिक अंदाज देऊ शकता: plug म्हणजे एक दिवस (SDK ने काही तास); खरे काम भाग 1 (काय उघड करायचे) आणि भाग 2 ची वर्णने + धोक्याची लेबले आहे (रचना, L03/L05). जे teams हे बरोबर करतात ते असे servers देतात जे agents खरोखर बरोबर वापरतात.

🧪 करून पाहा — खरोखर वाढवा

# 1) prove the baseline:
python3 client/mini_client.py

# 2) YOUR first tool — add to TOOLS in server/school_server.py:
#    {"name":"list_homework","description":"Show the homework list (read-only).",
#     "inputSchema":{"type":"object","properties":{}}}
#    …and to run_tool():
#    if name == "list_homework":
#        return f"Homework: {json.dumps(HOMEWORK) or '[]'}"

# 3) rerun the client — your tool appears in discovery, callable:
python3 client/mini_client.py --drive
# model calls> list_homework {}

तुमचा पहिला MCP server बदल: shipped. 🔬

✅ तपासा — तुम्हाला काय दिसायला हवे

list_homework जोडल्यानंतर discovery चार tools दाखवते आणि --drive → list_homework {} homework list छापतो. fly_to_moon {} ❌ server error -32602: Unknown tool देतो (protocol error), तर lookup_grade {"student":"nobody"} isError चिन्हांकित result देतो (tool बोलतो आहे).

🏁 तुम्ही आत्ताच काय सिद्ध केले

तुम्ही खऱ्या MCP server चा कप्पा आणि dispatcher त्याच्या plumbing ला हात न लावता बदलला — आणि spec ने ठरवलेल्या दोन्ही प्रकारच्या errors पाहिल्या.

⚠️ नेहमीच्या चुका

flush=True विसरणे — classic "server अडकतो" bug: replies buffer मध्येच पडून राहतात
debug output stdout वर छापणे — stdout म्हणजेच wire; stderr वर log करा
notifications ना (id नसलेले messages) उत्तर देणे — त्यांना शांतता मिळते, कधीच reply नाही
tool मधून exceptions बाहेर फेकणे — isError: true content परत द्या म्हणजे model प्रतिसाद देऊ शकतो

🏭 प्रत्यक्ष वापरात हे का महत्त्वाचे: अधिकृत SDKs (Python/TypeScript साठी mcp) हे चार भाग automate करतात आणि transports, schemas आणि auth जोडतात — खऱ्या servers साठी ते वापरा. ते तुमच्यासाठी करू शकत नाहीत असे रचनेचे काम म्हणजे भाग 1 आणि 2: काय उघड करायचे, आणि प्रामाणिक धोक्याच्या लेबलांसह वर्णने.

⏭️ पुढे

Socket ची दुसरी बाजू: mini_client.py वाचणे — आणि सत्ता models कडे नव्हे तर hosts कडे का असते.

git checkout lesson-07-build-a-client

🔬 Lesson 06 — Build a server: ~125 honest lines

📍 You are here: Lesson 06 of 8 · Previous: lesson-05-transports-security · Next: lesson-07-build-a-client

📦 What's in this branch

Lessons 01–05, plus the guided read of a REAL MCP server — server/school_server.py — and your first extension to it.

🧒 Explain like I'm 5

Building an instrument sounds scary until you see one opened up. Ours has exactly four parts, top to bottom of the file:

The thing being wrapped 🗄️ — a toy database (DB, HOMEWORK). In real servers this is the interesting part: your Postgres, your API, your filesystem. MCP is just the plug on the front.
The shelf list 📋 — TOOLS: three entries of name + description + inputSchema. Remember L03: descriptions are for the model — ours say what each tool does AND that add_homework writes (danger label, L05!).
The dispatcher 🔀 — run_tool(name, args): a plain Python if-ladder doing the actual work. Nothing protocol-ish here — you could unit-test it alone.
The plumbing 🔧 — main(): read a line, parse JSON, check the badge (wrong revision → -32022 with the revisions we do speak), answer the three methods you know from L04 (server/discover, tools/list, tools/call), print the reply. Tool failures → polite isError content, never a crash; unknown tool → a proper -32602.

That's a server. The official SDKs (Python/TypeScript mcp packages) give you decorators, typed schemas, transports and the long tail of the spec — use them for real work — but they're automating THESE four parts, and now you've seen the parts.

🗺️ Diagram

flowchart TB
    subgraph file["server/school_server.py - the four parts"]
        db["1 🗄️ the wrapped thing<br/>DB + HOMEWORK (yours: Postgres, APIs…)"]
        tools["2 📋 the shelf: TOOLS<br/>name · description(for the model!) · inputSchema"]
        disp["3 🔀 run_tool()<br/>plain Python if-ladder — unit-testable"]
        plumb["4 🔧 main() loop<br/>line in → JSON-RPC → line out"]
    end
    host["🔌 any MCP host"]
    host <-->|"stdio"| plumb
    plumb --> disp --> db
    plumb --> tools

📖 Read these lines (so you don't get lost)

server/school_server.py:

lines 20–25: part 1, the wrapped thing (DB, HOMEWORK)
lines 27–55: part 2, the shelf (TOOLS)
lines 57–71: part 3, the dispatcher (run_tool)
lines 74–84: part 4a, the two reply helpers (badge + resultType on every result)
lines 85–end: part 4b, the loop — badge check first, then the three verbs

❓ What (the details worth stealing)

flush=True on every print — stdio servers that forget this "hang" mysteriously (the classic first bug: buffered replies never arrive).
Answer only what you're asked; unknown method + id → error -32601. Notifications get silence, not errors.
Two error kinds, on purpose: a protocol error (error with a code: wrong version -32022, unknown tool -32602) vs a tool error (result with isError: true) — the second is for the model.
Every reply() adds resultType: "complete" and the server's badge (_meta → serverInfo); list results add ttlMs/cacheScope so hosts may cache the shelf.
Tool errors as {"content":[…], "isError": true} — the model can read the failure and try again (an agent's retry loop, AI course L11, depends on this!).
Schemas are contracts: "enum": ["3A","3B"] means the model gets told the legal values — fewer bad calls, better behavior. Rich schemas are cheap model-steering.
Real-world upgrades from here: the official SDK, resources/list for report cards (L03's homework!), env-var secrets, and a scoped DB account (least privilege — AWS course L03).

🤔 Why

Because "we should build an MCP server for our X" is now a sprint ticket in half the industry — and you can estimate it honestly: the plug is a day (SDK makes it hours); the REAL work is part 1 (what to expose) and part 2's descriptions + danger labels (design, L03/L05). Teams that get those right ship servers agents actually use correctly.

🧪 Try it — extend it for real

# 1) prove the baseline:
python3 client/mini_client.py

# 2) YOUR first tool — add to TOOLS in server/school_server.py:
#    {"name":"list_homework","description":"Show the homework list (read-only).",
#     "inputSchema":{"type":"object","properties":{}}}
#    …and to run_tool():
#    if name == "list_homework":
#        return f"Homework: {json.dumps(HOMEWORK) or '[]'}"

# 3) rerun the client — your tool appears in discovery, callable:
python3 client/mini_client.py --drive
# model calls> list_homework {}

Your first MCP server change: shipped. 🔬

✅ Verify — what you should see

After adding list_homework, discovery lists four tools and --drive → list_homework {} prints the homework list. fly_to_moon {} gives ❌ server error -32602: Unknown tool (a protocol error), while lookup_grade {"student":"nobody"} gives a result flagged isError (the tool talking).

🏁 What you just proved

You changed a real MCP server's shelf and dispatcher without touching its plumbing — and you saw both error kinds the spec defines.

⚠️ Common mistakes

forgetting flush=True — the classic "the server hangs" bug: replies sit in a buffer
printing debug output to stdout — stdout IS the wire; log to stderr
answering notifications (messages without id) — they get silence, never a reply
raising exceptions out of a tool — return isError: true content so the model can react

🏭 Why this matters in production: the official SDKs (mcp for Python/TypeScript) automate these four parts and add transports, schemas and auth — use them for real servers. The design work they cannot do for you is parts 1 and 2: what to expose, and descriptions with honest danger labels.

⏭️ Next

The other side of the socket: reading mini_client.py — and why hosts, not models, hold the power.

git checkout lesson-07-build-a-client

← Previoustransports security Next →build a client

This page is the lesson's README from the lesson-06-build-a-server branch, shown here so the whole School stays on one site. Code files open on GitHub at the same branch.