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:

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.

Related MCP server: Notes Manager

What you get

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:

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

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.