feat: add new exercises for user authentication and scopes, including problem and solution implementations

Author: kentcdodds

exercises/02.init/01.problem.authenticate/README.mdx

@@ -0,0 +1 @@
+# Authenticate Header

…9.finished/99.solution/package-lock.json …1.problem.authenticate/package-lock.jsonexercises/99.finished/99.solution/package-lock.json renamed to exercises/02.init/01.problem.authenticate/package-lock.json exercises/99.finished/99.solution/package-lock.json renamed to exercises/02.init/01.problem.authenticate/package-lock.json

@@ -0,0 +1,38 @@
+{
+  "name": "exercises_02.init_01.problem.authenticate",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "pretypecheck": "wrangler types ./types/worker-configuration.d.ts",
+    "typecheck": "tsc",
+    "build": "wrangler build",
+    "dev": "mcp-dev",
+    "dev:server": "cross-env wrangler dev --port ${PORT:-8787}",
+    "inspect": "mcp-inspector"
+  },
+  "dependencies": {
+    "@epic-web/epicme-db-client": "*",
+    "@epic-web/invariant": "^1.0.0",
+    "@modelcontextprotocol/sdk": "^1.17.4",
+    "agents": "^0.0.113",
+    "zod": "^3.25.67"
+  },
+  "devDependencies": {
+    "@epic-web/config": "^1.21.3",
+    "@epic-web/mcp-dev": "*",
+    "@faker-js/faker": "^10.0.0",
+    "@modelcontextprotocol/inspector": "0.16.5",
+    "@types/node": "^24.3.0",
+    "cross-env": "^10.0.0",
+    "eslint": "^9.34.0",
+    "execa": "^9.6.0",
+    "prettier": "^3.6.2",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4",
+    "wrangler": "^4.33.0"
+  },
+  "prettier": "@epic-web/config/prettier",
+  "license": "GPL-3.0-only"
+}

exercises/02.init/01.problem.authenticate/package.json

@@ -0,0 +1,35 @@
+import { EPIC_ME_AUTH_SERVER_URL } from './client.ts'
+
+/**
+ * This retrieves the protected resource configuration from the EpicMe server.
+ * This is how the client knows where to request authorization from.
+ */
+export async function handleOAuthProtectedResourceRequest(request: Request) {
+	// This server is the protected resource server, so we return our own configuration
+	const resourceServerUrl = new URL(request.url)
+	resourceServerUrl.pathname = '/mcp' // Point to the MCP endpoint
+
+	return Response.json({
+		resource: resourceServerUrl.toString(),
+		authorization_servers: [EPIC_ME_AUTH_SERVER_URL],
+	})
+}
+
+/**
+ * Handles requests for OAuth authorization server metadata.
+ * Fetches the metadata from the auth server and forwards it to the client.
+ * This should only be used for backwards compatibility. Newer clients should
+ * use `/.well-known/oauth-protected-resource/mcp` to discover the authorization
+ * server and make this request directly to the authorization server instead.
+ */
+export async function handleOAuthAuthorizationServerRequest() {
+	const metadataUrl = new URL(
+		'/.well-known/oauth-authorization-server',
+		EPIC_ME_AUTH_SERVER_URL,
+	)
+
+	const response = await fetch(metadataUrl.toString())
+	const data = await response.json()
+
+	return Response.json(data)
+}

exercises/02.init/01.problem.authenticate/src/auth.ts

@@ -0,0 +1,7 @@
+import { DBClient } from '@epic-web/epicme-db-client'
+
+export const EPIC_ME_AUTH_SERVER_URL = 'http://localhost:7788'
+
+export function getClient() {
+	return new DBClient(EPIC_ME_AUTH_SERVER_URL)
+}

exercises/02.init/01.problem.authenticate/src/client.ts

@@ -0,0 +1,96 @@
+import { type DBClient } from '@epic-web/epicme-db-client'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import {
+	SetLevelRequestSchema,
+	type LoggingLevel,
+} from '@modelcontextprotocol/sdk/types.js'
+import { McpAgent } from 'agents/mcp'
+import {
+	handleOAuthAuthorizationServerRequest,
+	handleOAuthProtectedResourceRequest,
+} from './auth.ts'
+import { getClient } from './client.ts'
+import { initializePrompts } from './prompts.ts'
+import { initializeResources } from './resources.ts'
+import { initializeTools } from './tools.ts'
+import { withCors } from './utils.ts'
+
+type State = { loggingLevel: LoggingLevel }
+
+export class EpicMeMCP extends McpAgent<Env, State> {
+	db!: DBClient
+	initialState: State = { loggingLevel: 'info' }
+	server = new McpServer(
+		{
+			name: 'epicme',
+			title: 'EpicMe Journal',
+			version: '1.0.0',
+		},
+		{
+			capabilities: {
+				tools: { listChanged: true },
+				resources: { listChanged: true, subscribe: true },
+				completions: {},
+				logging: {},
+				prompts: { listChanged: true },
+			},
+			instructions: `
+EpicMe is a journaling app that allows users to write about and review their experiences, thoughts, and reflections.
+
+These tools are the user's window into their journal. With these tools and your help, they can create, read, and manage their journal entries and associated tags.
+
+You can also help users add tags to their entries and get all tags for an entry.
+			`.trim(),
+		},
+	)
+
+	async init() {
+		this.db = getClient()
+		this.server.server.setRequestHandler(
+			SetLevelRequestSchema,
+			async (request) => {
+				this.setState({ ...this.state, loggingLevel: request.params.level })
+				return {}
+			},
+		)
+		await initializeTools(this)
+		await initializeResources(this)
+		await initializePrompts(this)
+	}
+}
+
+export default {
+	fetch: withCors({
+		getCorsHeaders: (request) => {
+			if (request.url.includes('/.well-known')) {
+				return {
+					'Access-Control-Allow-Origin': '*',
+					'Access-Control-Allow-Methods': 'GET, HEAD, OPTIONS',
+					'Access-Control-Allow-Headers': 'mcp-protocol-version',
+					'Cross-Origin-Resource-Policy': 'cross-origin',
+				}
+			}
+		},
+		handler: async (request, env, ctx) => {
+			const url = new URL(request.url)
+
+			// for backwards compatibility with old clients that think we're the authorization server
+			if (url.pathname === '/.well-known/oauth-authorization-server') {
+				return handleOAuthAuthorizationServerRequest()
+			}
+
+			if (url.pathname.startsWith('/.well-known/oauth-protected-resource')) {
+				return handleOAuthProtectedResourceRequest(request)
+			}
+
+			if (url.pathname === '/mcp') {
+				const mcp = EpicMeMCP.serve('/mcp', {
+					binding: 'EPIC_ME_MCP_OBJECT',
+				})
+				return mcp.fetch(request, env, ctx)
+			}
+
+			return new Response('Not found', { status: 404 })
+		},
+	}),
+} satisfies ExportedHandler<Env>

exercises/02.init/01.problem.authenticate/src/index.ts

@@ -0,0 +1,99 @@
+import { invariant } from '@epic-web/invariant'
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { type EpicMeMCP } from './index.ts'
+
+export async function initializeResources(agent: EpicMeMCP) {
+	agent.server.registerResource(
+		'tags',
+		'epicme://tags',
+		{
+			title: 'Tags',
+			description: 'All tags currently in the database',
+		},
+		async (uri) => {
+			const tags = await agent.db.getTags()
+			return {
+				contents: [
+					{
+						mimeType: 'application/json',
+						text: JSON.stringify(tags),
+						uri: uri.toString(),
+					},
+				],
+			}
+		},
+	)
+
+	agent.server.registerResource(
+		'tag',
+		new ResourceTemplate('epicme://tags/{id}', {
+			complete: {
+				async id(value) {
+					const tags = await agent.db.getTags()
+					return tags
+						.map((tag) => tag.id.toString())
+						.filter((id) => id.includes(value))
+				},
+			},
+			list: async () => {
+				const tags = await agent.db.getTags()
+				return {
+					resources: tags.map((tag) => ({
+						name: tag.name,
+						uri: `epicme://tags/${tag.id}`,
+						mimeType: 'application/json',
+					})),
+				}
+			},
+		}),
+		{
+			title: 'Tag',
+			description: 'A single tag with the given ID',
+		},
+		async (uri, { id }) => {
+			const tag = await agent.db.getTag(Number(id))
+			invariant(tag, `Tag with ID "${id}" not found`)
+			return {
+				contents: [
+					{
+						mimeType: 'application/json',
+						text: JSON.stringify(tag),
+						uri: uri.toString(),
+					},
+				],
+			}
+		},
+	)
+
+	agent.server.registerResource(
+		'entry',
+		new ResourceTemplate('epicme://entries/{id}', {
+			list: undefined,
+			complete: {
+				async id(value) {
+					const entries = await agent.db.getEntries()
+					return entries
+						.map((entry) => entry.id.toString())
+						.filter((id) => id.includes(value))
+				},
+			},
+		}),
+		{
+			title: 'Journal Entry',
+			description: 'A single journal entry with the given ID',
+		},
+		async (uri, { id }) => {
+			const entry = await agent.db.getEntry(Number(id))
+			invariant(entry, `Entry with ID "${id}" not found`)
+			return {
+				contents: [
+					{
+						mimeType: 'application/json',
+						text: JSON.stringify(entry),
+						uri: uri.toString(),
+					},
+				],
+			}
+		},
+	)
+}