🎓 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