# Task Manager — MCP Server + Next.js

A small but complete example that demonstrates **every core Model Context Protocol
(MCP) concept**, wired to a Next.js web app that shares the same data.

An AI client (e.g. Claude Desktop) talks to the MCP server to read and change tasks;
the Next.js UI shows those same tasks and updates live.

```
┌────────────────┐   MCP (stdio / JSON-RPC)   ┌───────────────────────┐
│  AI client     │ ─────────────────────────► │  mcp-server/server.ts │
│ (Claude etc.)  │   tools · resources ·      │  Resources / Tools /  │
└────────────────┘   prompts                  │  Prompts / Transport  │
                                              └──────────┬────────────┘
                                                         │  reads/writes
                                                         ▼
                                              ┌───────────────────────┐
┌────────────────┐    HTTP / REST             │   lib/store.ts        │
│  Web browser   │ ─────────────────────────► │   data/tasks.json     │
│ (Next.js UI)   │   /api/tasks               │  (shared file store)  │
└────────────────┘                            └───────────────────────┘
```

## MCP concepts demonstrated

| Concept       | Where                  | Examples                                                                     |
| ------------- | ---------------------- | ---------------------------------------------------------------------------- |
| **Resources** | `mcp-server/server.ts` | `tasks://all`, `tasks://stats`, `tasks://{id}` (templated)                    |
| **Tools**     | `mcp-server/server.ts` | `create_task`, `update_task`, `complete_task`, `delete_task`, `search_tasks` |
| **Prompts**   | `mcp-server/server.ts` | `summarize_tasks`, `daily_plan` (parameterized)                              |
| **Transport** | `mcp-server/server.ts` | stdio (Claude Desktop compatible)                                            |

## Project structure

```
lib/store.ts                # Shared, file-backed task store (single source of truth)
mcp-server/server.ts        # The MCP server: resources + tools + prompts + stdio
mcp-server/smoke-test.ts    # End-to-end MCP client test (uses the official SDK Client)
app/page.tsx                # Task manager web UI
app/api/tasks/route.ts      # REST: GET (list/search) + POST (create)
app/api/tasks/[id]/route.ts # REST: GET / PATCH / DELETE one task
claude_desktop_config.json  # Example config to connect Claude Desktop
```

## Run it

### 1. The web app

```bash
npm run dev
# open http://localhost:3000
```

### 2. The MCP server (standalone)

```bash
npm run mcp            # runs the server over stdio
npm run mcp:inspect    # opens the MCP Inspector UI to click through tools/resources/prompts
```

### 3. End-to-end smoke test

```bash
npx tsx mcp-server/smoke-test.ts
```

Exercises the full MCP surface: lists tools/resources/templates/prompts, calls a
tool, reads resources, and fetches a prompt.

## Connect to Claude Desktop

Add the `mcpServers` block from `claude_desktop_config.json` to your Claude Desktop
config (macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`),
adjusting `cwd` to this project's absolute path. Restart Claude Desktop, then ask it
to "create a task" or "summarize my tasks" — the changes appear in the web UI too.

## How the two sides stay in sync

Both the MCP server process and the Next.js API import the same `lib/store.ts`, which
persists to `data/tasks.json`. Anything the AI does through MCP is immediately visible
in the browser (the UI polls every 3s), and vice-versa — verified across separate
processes.