Local MCP Study Tools Server

An MCP server that gives a study assistant three tools — explain a topic, build a study plan, generate a revision checklist — plus two read-only resources, project://course-outline and project://status. It runs over stdio, so the client starts it as a child process and nothing listens on a network port.

The interesting half is what the tools do with bad input. A failure is returned, not raised: an empty topic comes back as {"ok": false, "error": {"code": "EMPTY_TOPIC", "field": "topic", "hint": "..."}}, because an exception inside a tool reaches the agent as a stack trace it can't branch on. Out-of-range values aren't errors at all — days=30 is clamped to 14 and the response says it was clamped, since a caller that silently gets 14 can't tell a limit from a bug. And a topic that reads as an instruction rather than a subject never reaches the model.

uv venv
uv pip install -r requirements.txt

.venv/bin/python client_test.py     # connect over stdio, list tools, call them
.venv/bin/python agent_demo.py      # choose a tool, check it's allowed, then call it
.venv/bin/python tests.py           # 47 tests, no server or model needed

A local Ollama model (qwen3:8b) is used for explanations if it's running, and the response labels which source answered. Everything works without it.

Also in this repo

• docs/mcp-checkpoint-report.md — the MCP architecture, every tool and resource, the client test output, the documented failure, the security notes, and two things measured while building (including a prompt guard sentence that became the topic, 6 runs out of 6)

• docs/output.txt — raw log of the client test, the agent demo and the tests

Author: Oussama Ezitouni