MCPRepo — NextFlows Academy Starter

Part of NextFlows Academy — the free cohort program Building an MCP for an AI Engine.

Clone this repo to build your Model Context Protocol (MCP) server in TypeScript. By Demo Day you will ship a public GitHub repo with real tools, Zod validation, docs, and a live demo — the same path used in the free NextFlows Academy cohort.

Program hub: nextflows.ai/academy
Full program page (in this repo): docs/PROGRAM.md
Apply: Cohort application

---

About NextFlows Academy

NextFlows Academy runs structured, cohort-based programs with live sessions, mentor support, and a real project you ship by the end.

This repository belongs to:

Program	Building an MCP for an AI Engine
Audience	4th & 5th year CS / CE students
Duration	6 weeks
Format	Cohort + project
Price	Free
Level	Intermediate
Outcome	Shipped MCP server on GitHub
Schedule	Wed & Sat online 1:30–3:30 PM + Monday on-site workshop days

You go from “what’s an MCP?” to a working MCP server connected to an AI engine (for example Claude), fully documented, and live on GitHub.

See docs/PROGRAM.md for outcomes, weekly plan, starter projects, and who it’s for.

---

What you get

Path	Purpose
src/index.ts	MCP server + stdio transport
src/tools/	One register helper per tool
src/schemas/	Zod input contracts (with .describe(...))
examples/	Sample JSON args for Inspector
docs/PROGRAM.md	Full NextFlows Academy program page
docs/WEEK-2.md	Full Week 2 step-by-step plan
docs/CURRICULUM.md	6-week overview
docs/project-choice.md	Week 2 project choice template
docs/design.md	Week 2 design doc template

Week 1 is already wired: a working greet tool so you can open Inspector on day one.

Week 2 examples included: stub tools for Notes & FAQ Search (search_notes, list_notes, add_note). Enable them when you pick that starter (or copy the pattern for your own idea).

Prerequisites

• Node.js 20+ (node -v)
• npm (npm -v)
• Git + a GitHub account
• Cursor or VS Code

Quick start

git clone <YOUR_FORK_OR_ORG_URL>/MCPRepo.git
cd MCPRepo
npm install
npm run inspect

In the Inspector browser tab:

1. Click Connect
2. Open Tools
3. Select greet and put Alex in the name field (see examples/greet.json for the full args shape)
4. Try invalid input (empty name) and confirm Zod rejects it

To run the server alone (waits on stdin):

npm run dev

Important: log only with console.error. Never use console.log — stdout is reserved for the MCP protocol.

Week 2

Week 2 is design-first. Follow docs/WEEK-2.md.

Useful scripts:

Script	What it does
npm run dev	Start the MCP server on stdio (stays alive; stop with Ctrl+C)
npm start	Same as dev
npm run inspect	Open MCP Inspector against this server

Stack

• TypeScript via tsx (no build step early on)
• Official MCP TypeScript SDK (@modelcontextprotocol/server)
• Zod for tool inputSchema
• MCP Inspector for local testing
• stdio transport for Claude Desktop / Cursor demos

Six-week journey

Week	Focus
1	Set up & first MCP tool (greet ✅ in this repo)
2	Design your own tools → see docs/WEEK-2.md
3	Connect tools to real data
4	Make it safe & reliable
5	Test & write docs people can follow
6	Ship on GitHub & Demo Day

Full program details: docs/PROGRAM.md

Starter project options (pick in Week 2)

1. Notes & FAQ Search — fully offline (example stubs included)
2. Personal Expense Tracker — summarize spending from a spreadsheet
3. To-Do List — create / list / complete tasks
4. Weather Briefing — free API (e.g. Open-Meteo), no paid keys
5. Quote of the Day — simple offline or public API

Advanced ideas (repo health, course planner, job tracker) need mentor approval before you expand scope.

Repo layout after Week 2

MCPRepo/
├── docs/
│   ├── PROGRAM.md
│   ├── CURRICULUM.md
│   ├── WEEK-2.md
│   ├── project-choice.md
│   └── design.md
├── examples/
│   └── <tool_name>.json
├── src/
│   ├── index.ts
│   ├── schemas/
│   └── tools/
├── package.json
└── README.md

Rules that matter

• One job per tool; use verb_noun names (search_notes, add_expense)
• Write descriptions for the model, not only for humans
• Every Zod field needs .describe(...)
• Prefer small focused tools over one mega-tool with an action enum
• Avoid paid APIs / OAuth-heavy projects in Weeks 1–2

Links

• NextFlows Academy
• Program page (this repo)
• Apply for Cohort #1
• MCP docs
• MCP specification
• Build your first server (TypeScript SDK)

License

MIT — built for NextFlows Academy students.