# 🎓 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**:

```python
from mcp.server.fastmcp import FastMCP
```

and pins the MCP SDK to:

```text
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:

```python
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

```text
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:

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

Verify the SDK:

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

## 🧪 Run the client checkpoint

```bash
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:

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

## 🖥️ MCP Inspector

The CLI development command is:

```bash
mcp dev server.py
```

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

## 📓 Jupyter

Open:

```text
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:

```text
1..14
```

Checklist items:

```text
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:

```python
ensure_allowed(tool_name)
```

Only the three approved learning tools may be invoked.

## ❌ Failure demonstration

Calling:

```python
explain_topic("   ")
```

returns a structured error:

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

The server does not crash.

## 🧪 Automated tests

```bash
pytest -q
```

## 📚 Official MCP references

- [MCP Introduction](https://modelcontextprotocol.io/docs/getting-started/intro)
- [Official MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [MCP GitHub Repository](https://github.com/modelcontextprotocol/modelcontextprotocol)

## 🏁 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 |