# 🧩 FastMCP Prompts Example

[![Follow on X](https://img.shields.io/badge/-Follow%20%40mcoding__off-black?style=flat&logo=x)](https://x.com/mcoding_off)
[![WhatsApp Channel](https://img.shields.io/badge/WhatsApp-Channel-25D366?style=flat&logo=whatsapp&logoColor=white)]([https://wa.me/212608105946](https://whatsapp.com/channel/0029Vb7WRtT11ulGgJPp4m3y))
[![License](https://img.shields.io/badge/License-MIT-blue?style=flat)](LICENSE)

[![Python](https://img.shields.io/badge/Python-3.12+-3776AB?style=flat&logo=python&logoColor=white)](https://www.python.org/)
[![FastMCP](https://img.shields.io/badge/FastMCP-3.x-orange?style=flat)](https://gofastmcp.com/)
[![MCP](https://img.shields.io/badge/Protocol-MCP-8A2BE2?style=flat)](https://modelcontextprotocol.io/)
[![uv](https://img.shields.io/badge/Package%20Manager-uv-DE5FE9?style=flat)](https://docs.astral.sh/uv/)

A small, focused tutorial showing how to build **MCP prompts** with [FastMCP](https://gofastmcp.com/) — reusable, parameterized message templates that any MCP client (Claude Desktop, IDEs, custom agents) can discover and render.

> 📚 Perfect as a first step into the [Model Context Protocol](https://modelcontextprotocol.io/) before diving into tools and resources.

---

## 📖 What are MCP prompts?

While MCP **tools** let a model *do* things and **resources** let it *read* things, **prompts** are user-controlled templates: the client lists them, fills in their arguments, and injects the rendered messages into the conversation. Think of them as *slash commands for LLMs*.

## ✨ What this example covers

[main.py](main.py) demonstrates the three patterns you'll use most, from simplest to most powerful:

| # | Prompt | Pattern | Concept demonstrated |
|---|--------|---------|----------------------|
| 1 | `research_prompt` | Return a plain `str` | Simplest form — auto-wrapped in a single `user` message |
| 2 | `summarize_prompt` | Optional + constrained args | `Literal` types & defaults become a client-visible argument schema |
| 3 | `code_review_prompt` | Return `list[Message]` | Seed a full multi-turn conversation (user + assistant messages) |

Along the way you'll also see: naming, descriptions, `tags`, and server `instructions`.

## 🚀 Quickstart

**Prerequisites:** [Python 3.12+](https://www.python.org/downloads/) and [uv](https://docs.astral.sh/uv/getting-started/installation/).

```bash
# 1. Clone and enter the project
git clone https://github.com/mohamedelamraoui1/fastMCP-2-0-example.git
cd fastMCP-2-0-example

# 2. Install dependencies
uv sync

# 3. Run the server (stdio transport)
uv run main.py
```

If everything is set up correctly, you'll see the FastMCP banner and the server waiting for a client on stdio:

![FastMCP server startup banner](assets/server-startup.png)

## 🔍 Test with the MCP Inspector

The fastest way to explore the prompts is the **MCP Inspector** — a web UI for poking at any MCP server. It requires [Node.js](https://nodejs.org/) (the Inspector is an npm package that FastMCP launches for you).

**Step 1 — Launch the Inspector:**

```bash
uv run fastmcp dev inspector main.py
```

You'll see output like this, and your browser opens automatically:

```
🚀 MCP Inspector is up and running at:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=<session-token>
⚙️ Proxy server listening on localhost:6277
```

> If the browser doesn't open, copy the full URL (including the token) from the terminal.

**Step 2 — Connect to the server.** The connection form is pre-filled (transport `STDIO`, command `fastmcp run main.py`). Just click **Connect** — the indicator turns green when the handshake succeeds.

**Step 3 — List the prompts.** Open the **Prompts** tab and click **List Prompts**. You should see all three: `research_prompt`, `summarize_prompt`, and `code_review_prompt`, each with its description.

**Step 4 — Render a prompt.** Click a prompt, fill in its arguments in the form (e.g. `topic = "quantum computing"` for `research_prompt`), and click **Get Prompt**. The right panel shows the exact messages the server returns.

**Step 5 — See the interesting cases:**
- On `summarize_prompt`, notice the `length` and `tone` fields only accept the `Literal` values from the type hints — that's the argument schema in action.
- On `code_review_prompt`, paste any snippet as `code` and notice the result is **three messages** (`user` → `assistant` → `user`), not one — a pre-seeded conversation.

When you're done, stop the Inspector with `Ctrl+C` in the terminal.

## 🖥️ Use it from Claude Desktop

Add the server to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "prompt-examples": {
      "command": "uv",
      "args": ["run", "--directory", "C:/absolute/path/to/fastMCP-2-0-example", "main.py"]
    }
  }
}
```

Restart Claude Desktop, then look for the prompts in the **+** (attachments) menu.

> 💡 **No API key needed.** Claude Desktop uses your Claude account, and this MCP server only serves prompt *templates* — it never calls an LLM itself. You'd only need an Anthropic API key if you wrote your own client that sends the rendered prompts to the API.

## 🗂️ Project structure

```
.
├── main.py          # The MCP server — 3 prompt patterns, fully commented
├── assets/          # Screenshots used in this README
├── pyproject.toml   # Project metadata & dependencies
├── uv.lock          # Locked dependency versions
└── README.md
```

## 📚 Learn more

- [FastMCP documentation](https://gofastmcp.com/) — the framework used here
- [FastMCP: Prompts guide](https://gofastmcp.com/servers/prompts) — deep dive on the prompt API
- [Model Context Protocol](https://modelcontextprotocol.io/) — the open protocol specification
- [MCP: Prompts concept](https://modelcontextprotocol.io/docs/concepts/prompts) — how clients consume prompts

## 🛠️ Tech stack

| Technology | Role |
|------------|------|
| [Python 3.12+](https://www.python.org/) | Language |
| [FastMCP 3.x](https://gofastmcp.com/) | MCP server framework |
| [uv](https://docs.astral.sh/uv/) | Dependency & environment management |

## 📄 License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file for details.

---

Made with ❤️ for the MCP community. Follow [@mcoding_off](https://x.com/mcoding_off) for more tutorials.