# mcp-server-demo

A minimal [Model Context Protocol](https://modelcontextprotocol.io) server that gives an LLM a persistent scratchpad. It exists to demonstrate all three MCP primitives — tools, resources, and prompts — in about 80 lines of Python.

Built against the Python SDK v2 (`mcp>=2.1.1`), where `FastMCP` was renamed to `MCPServer`.

## What it exposes

| Primitive | Name | Purpose |
|---|---|---|
| Tool | `add_note(message)` | Appends a note. Model-invoked. |
| Tool | `read_notes()` | Returns every stored note. |
| Resource | `notes://latest` | The most recent note, as read-only context. |
| Prompt | `note_summary_prompt` | A reusable prompt that pulls the notes in and asks for a summary. |

The tool/resource split is the point worth noticing. `read_notes` is a tool because the model decides when to call it. `notes://latest` is a resource because the *client* decides when to attach it — it's context, not an action.

## Install

Requires Python 3.12+ and [uv](https://docs.astral.sh/uv/).

```bash
git clone https://github.com/DinaMMahfouz/mcp-server-demo.git
cd mcp-server-demo
uv sync
```

Verify it imports cleanly:

```bash
uv run python -c "import mcp_server_demo.main; print('ok')"
```

## Run

```bash
uv run mcp-server-demo
```

The process will appear to hang. That is correct — it speaks JSON-RPC over stdio and is waiting for a client. Ctrl+C to exit.

To poke at it interactively:

```bash
uv run mcp dev src/mcp_server_demo/main.py
```

## Connect to Claude Desktop

Edit `claude_desktop_config.json`:

- **Windows** — `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS** — `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "sticky-notes": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-server-demo",
        "run",
        "mcp-server-demo"
      ]
    }
  }
}
```

The path must be absolute. Restart Claude Desktop; the tools appear in the tools menu.

## Storage

Notes are written to a per-user data directory, not into the package:

- Windows — `%LOCALAPPDATA%\mcp-server-demo\notes.txt`
- Linux/macOS — `$XDG_DATA_HOME/mcp-server-demo/notes.txt`, falling back to `~/.local/share/`

Override with the `STICKY_NOTES_FILE` environment variable.

## Scope

This is a learning project. It has no tests, no concurrency handling, and no input validation beyond stripping whitespace — a plain-text file appended to by one process. Don't build on it.

## License

MIT.