<div align="center">

# Build Your First MCP Server

**SUTD AI · Agentic Engineering Workshop · Model Context Protocol**

A three-hour, hands-on session. You will learn what the Model Context Protocol is, why it
exists and where it fits, then write your own MCP server in Python that gives an AI agent
(AWS Kiro) the ability to read and write your notes — and connect that same agent to a
shared design-thinking board.

[![License: MIT](https://img.shields.io/badge/License-MIT-0E7C86.svg)](LICENSE)
[![Docs: CC BY 4.0](https://img.shields.io/badge/Docs-CC%20BY%204.0-0E7C86.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg)](https://www.python.org)
[![MCP SDK 2.x](https://img.shields.io/badge/MCP%20SDK-2.x-000000.svg)](https://py.sdk.modelcontextprotocol.io)
[![Built for Kiro](https://img.shields.io/badge/Client-Kiro-6D28D9.svg)](https://kiro.dev)

</div>

---

## What you will walk out with

1. A working MCP server, **written by you**, that exposes a folder of Markdown notes
   (the sample `vault/`, or your own Obsidian vault) to any MCP client.
2. Kiro configured on your laptop with your server, plus one or two third-party MCP servers
   added by URL.
3. A clear mental model of what MCP is, when to reach for it, and when not to.

No prior MCP knowledge is assumed. If you can read a short Python function you can do the
hands-on part; the file operations are already written, you write the MCP layer.

## The session at a glance

| Time | Segment | You will… |
| ---- | ------- | --------- |
| 0:00 | Welcome and SUTD AI | hear what the club does and what this workshop series is |
| 0:10 | Environment check | confirm Kiro, `uv` and this repo work on your laptop |
| 0:30 | What is MCP? | learn the why, when, where and how; capabilities; trade-offs |
| 1:00 | Break | |
| 1:10 | **Hands-on: build `notes-mcp`** | write the server step by step and drive it from Kiro |
| 2:15 | Third-party MCP servers | add a remote server by URL and use it |
| 2:30 | Design-thinking board | pair Kiro to a shared board that is itself an MCP server |
| 2:50 | Wrap-up | recap, resources, what to build next |

Full minute-by-minute plan for facilitators: [`docs/facilitator-runbook.md`](docs/facilitator-runbook.md).

## Before you arrive (15 minutes)

Do the pre-work so the session is spent building, not installing:
**[`docs/00-prework.md`](docs/00-prework.md)**. In short: install Kiro and sign in, install `uv`,
get this repo, run `uv sync`, then `uv run check_env.py` until everything is green.

## Repository map

```
server.py            ← YOU edit this. The MCP server, with STEP 1–4 marked as TODOs.
notes.py             ← done for you: read/search/create/append Markdown notes (macOS/Windows/Linux)
check_server.py      ← talks to your server exactly like Kiro does, and shows the messages
check_env.py         ← pre-work check
setup_kiro.py        ← writes .kiro/settings/mcp.json with the absolute paths Kiro needs
vault/               ← sample notes so everything works out of the box
solution/server.py   ← the finished server, for comparison
.kiro/               ← workspace MCP config template + a steering file so Kiro can coach you
docs/                ← the curriculum (read in order)
```

## The curriculum

| # | Document | Segment |
| - | -------- | ------- |
| 0 | [Pre-work](docs/00-prework.md) | Kiro, `uv`, repo, green checks |
| 1 | [What is MCP?](docs/01-what-is-mcp.md) | Why it exists, when it was created, where and how to use it, capabilities, advantages and disadvantages |
| 2 | [Build `notes-mcp`](docs/02-build-notes-mcp.md) | The hands-on walkthrough, four steps plus a stretch |
| 3 | [Third-party MCP servers](docs/03-third-party-mcps.md) | Remote servers by URL, trust and approval |
| 4 | [The design-thinking board](docs/04-design-think-board.md) | A board that is also an MCP server: pair your agent, research, post evidence |
| — | [Facilitator runbook](docs/facilitator-runbook.md) | Timings, roles, checkpoints, fallbacks, pre-flight |

## Quick start (if you already did the pre-work)

```bash
uv sync                      # installs the MCP SDK into .venv
uv run check_env.py          # everything green?
uv run setup_kiro.py         # writes the Kiro config with absolute paths
uv run check_server.py       # "complete STEP 1 first" — that is your cue to open server.py
```

Open this folder in Kiro, then follow [`docs/02-build-notes-mcp.md`](docs/02-build-notes-mcp.md).

## Using your own notes

The server reads whatever folder `NOTES_VAULT` points at. To use an Obsidian vault:

```bash
uv run setup_kiro.py --vault "/Users/you/Documents/My Vault"       # macOS
uv run setup_kiro.py --vault "C:/Users/you/Documents/My Vault"      # Windows
```

Any folder of `.md` files works; nothing Obsidian-specific is required.

## Credits

Built by SUTD AI for the Agentic Engineering Workshop series. The design-thinking board used in
the final segment is [`design-think-agent`](https://github.com/SUTD-AI-Interest-Group/design-think-agent).
Code is MIT; documentation is CC BY 4.0.