# fastmcp-notes

A [FastMCP](https://github.com/jlowin/fastmcp) v3 feature showcase: a note-taking knowledge base exposed as an MCP server.

## Features demonstrated

- **Tools** -- CRUD operations on notes with tag categorization
- **Resources** -- note listing (static URI) and note detail (URI template)
- **Prompts** -- parameterized templates for note analysis and brainstorming
- **Context** -- structured logging (`ctx.info`), progress reporting (`ctx.report_progress`), and cross-resource reads (`ctx.read_resource`)
- **Lifespan** -- server startup/shutdown lifecycle with shared state
- **Error handling** -- `ToolError` for domain-specific errors

## Setup

```bash
git clone <repo-url>
cd fastmcp-notes
uv sync
```

## Usage

### Run the server (stdio, for Claude Desktop)

```bash
fastmcp run server.py
```

### Run the server (HTTP, for the client demo)

```bash
fastmcp run server.py -t streamable-http -p 8000
```

### Run the client demo

```bash
# In another terminal, with the server running on port 8000:
python client.py
```

## Claude Desktop configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "notes": {
      "command": "uv",
      "args": [
        "run", "--directory", "/absolute/path/to/fastmcp-notes",
        "fastmcp", "run", "server.py"
      ]
    }
  }
}
```

## Screenshots

### Creating a note via Claude Desktop

![Creating a note](images/img01.png)

### Prompts and resources available from the + menu

![Prompts and resources](images/img02.png)

### Reading a note by title

![Reading a note](images/img03.png)

## Project structure

```
server.py    # MCP server -- tools, resources, prompts, lifespan, error handling
client.py    # Async client demo
```

## License

MIT