🎓 MCP Study Tools — Local MCP Study Assistant

A complete checkpoint project implementing a local Model Context Protocol (MCP) server for a study assistant.

⚠️ Version compatibility

This project intentionally targets the FastMCP API:

from mcp.server.fastmcp import FastMCP

and pins the MCP SDK to:

mcp[cli]>=1.26,<2

This avoids the MCPServer import error that occurs when code written for a different SDK generation is mixed with a FastMCP-based installation.

The project also uses the official MCP stdio client:

from mcp import ClientSession
from mcp.client.stdio import StdioServerParameters, stdio_client

✨ Checkpoint features

• Local FastMCP server: MCP Study Tools
• explain_topic
• create_study_plan
• generate_revision_checklist
• Read-only project://course-outline
• Read-only project://status
• Structured validation errors
• Empty-topic protection
• Topic length and character validation
• Study days clamped to 1–14
• Checklist items clamped to 1–12
• MCP client using stdio
• Tool discovery
• Multiple MCP tool calls
• Agent-style routing
• Explicit tool allow-list
• Failure demonstration
• Security documentation
• Jupyter notebook
• Pytest tests

📁 Structure

mcp-study-tools/
├── server.py
├── client_test.py
├── requirements.txt
├── pyproject.toml
├── README.md
├── .gitignore
├── docs/
│   └── mcp-checkpoint-report.md
├── notebooks/
│   └── mcp_study_tools_walkthrough.ipynb
└── tests/
    └── test_server.py

🚀 Installation on macOS/Linux

From the project folder:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

Verify the SDK:

python -c "import mcp; print(mcp.__version__)"
python -c "from mcp.server.fastmcp import FastMCP; print('FastMCP OK')"

🧪 Run the client checkpoint

python client_test.py

The client launches server.py through the MCP stdio transport, initializes an MCP session, discovers the three tools, calls two tools, demonstrates an empty-input failure, and performs an agent-style routing example.

Expected discovery:

=== MCP TOOL DISCOVERY ===
[
  "explain_topic",
  "create_study_plan",
  "generate_revision_checklist"
]

🖥️ MCP Inspector

The CLI development command is:

mcp dev server.py

This starts the server through the MCP development/Inspector workflow.

📓 Jupyter

Open:

notebooks/mcp_study_tools_walkthrough.ipynb

It covers:

• architecture
• validation
• direct tool behavior
• MCP client connection
• tool discovery
• tool calls
• failure handling
• agent-style routing
• checkpoint verification

🔐 Security

The tools are deliberately low-risk.

Input validation

Topics:

• must be strings;
• cannot be empty;
• maximum 160 characters;
• restricted to a simple human-readable character set.

Resource limits

Study days:

1..14

Checklist items:

1..12

Values outside these ranges are clamped.

No dangerous capabilities

The server does not:

• execute shell commands;
• execute arbitrary Python;
• make network requests;
• read secrets;
• write arbitrary files;
• mutate persistent application state.

Agent allow-list

Before an agent-style request is executed:

ensure_allowed(tool_name)

Only the three approved learning tools may be invoked.

❌ Failure demonstration

Calling:

explain_topic("   ")

returns a structured error:

{
  "ok": false,
  "error": {
    "code": "EMPTY_TOPIC",
    "message": "Please provide a topic, for example 'Python functions'.",
    "field": "topic"
  }
}

The server does not crash.

🧪 Automated tests

pytest -q

📚 Official MCP references

• MCP Introduction
• Official MCP Python SDK
• MCP GitHub Repository

🏁 Requirement mapping

Requirement	Implementation
Python MCP SDK	requirements.txt
FastMCP server	server.py
3 required tools	server.py
Read-only resource	2 resources
Input validation	validate_topic()
Empty topic safe error	EMPTY_TOPIC
Day limit 1–14	clamp_integer()
Client test	client_test.py
Agent demonstration	pick_tool() + ensure_allowed()
Failure documentation	docs/mcp-checkpoint-report.md
Jupyter	notebooks/*.ipynb
Comments/documentation	All Python files