Project Manager MCP Server

A small MCP (Model Context Protocol) server for a project-management domain — create_task, list_tasks, update_task — backed by SQLite, integrated with Claude Code, and deployable to Railway or Render over SSE.

How this maps to the assignment

Objective	Where
MCP server exposing tools for an external system	src/ — SQLite-backed task tracker
Configure Claude Code to use the server	.mcp.json, .claude/settings.json
CLAUDE.md + commands leveraging the tools	CLAUDE.md, .claude/commands/*.md
End-to-end workflow demo	WALKTHROUGH.md

Learning goal	Where it shows up
MCP architecture (host, client, server, transport)	Two transports implemented: src/index.ts (stdio) and src/sse.ts (SSE). Claude Code is the host/client in both cases.
Tool definitions with JSON Schema	src/tools.ts — TOOL_DEFINITIONS
Integrate via .mcp.json	.mcp.json (stdio) and .mcp.sse.json.example (SSE, for the deployed server)
Deploy with SSE transport	Dockerfile, railway.json, render.yaml, src/sse.ts

Project layout

src/
  types.ts    Task/Priority/Status types
  db.ts       SQLite persistence (better-sqlite3)
  tools.ts    Tool JSON Schemas + tools/call handler
  server.ts   Shared MCP Server factory (tools + resources)
  index.ts    stdio entry point (local Claude Code use)
  sse.ts      SSE/HTTP entry point (cloud deployment)
.claude/
  settings.json       auto-approves this project's MCP tools
  commands/
    create-task.md
    list-tasks.md
    update-task.md
    task-report.md    bonus: reads back a status summary
CLAUDE.md              project context Claude Code reads automatically
.mcp.json              local stdio server registration
.mcp.sse.json.example  swap-in config for the deployed SSE server
Dockerfile             build for Railway/Render
railway.json           Railway build/deploy config
render.yaml             Render Blueprint config
WALKTHROUGH.md          scripted demo + how to record your own

The three tools

Tool	Required args	Optional args	Behavior
create_task	title	description, priority (low/medium/high)	Inserts a row, status starts at pending
list_tasks	—	status, priority	Filters, newest first
update_task	task_id, status	—	Errors if task_id doesn't exist

There's also a read-only resource, tasks://summary, returning counts of tasks by status — used by the /task-report command.

Run it locally

npm install
npm run build
npm start           # stdio server, for manual testing outside Claude Code

Or skip the build step during development:

npm run dev          # runs src/index.ts directly via tsx

Data is stored in tasks.db in the project root by default; override with DB_PATH=/some/path/tasks.db.

Wire it up to Claude Code

1. Open this project directory in a terminal: cd project-manager-mcp.
2. Make sure it's built: npm run build (the committed .mcp.json points at dist/index.js).
3. Start claude from this directory. Claude Code reads .mcp.json automatically and will ask you to approve the project-scoped project-manager server the first time — approve it.
4. .claude/settings.json pre-allows the three tools so you won't get a permission prompt per-call; CLAUDE.md gives Claude the context on when to use each one.
5. Try it:
   • "Create a task called 'Set up CI' with medium priority" → calls create_task
   • /list-tasks → calls list_tasks
   • /update-task task_xxx in_progress → calls update_task
   • /task-report → summarizes status counts

If you'd rather not build first, you can point .mcp.json at the dev command instead:

{
  "mcpServers": {
    "project-manager": {
      "command": "npx",
      "args": ["tsx", "src/index.ts"]
    }
  }
}

Deploy to Railway

npm install -g @railway/cli   # if you don't have it
railway login
railway init
railway up

Railway detects railway.json and builds the Dockerfile. Once deployed:

1. In the Railway dashboard, add a volume mounted at /app/data so tasks.db (at DB_PATH=/app/data/tasks.db) survives redeploys.
2. Grab the public URL Railway assigns (Settings → Networking → Generate Domain if it's not already public).
3. Verify it's up: curl https://<your-app>.up.railway.app/ should return a small JSON status blob.

Deploy to Render

1. Push this repo to GitHub.
2. In Render, "New" → "Blueprint", point it at the repo — it picks up render.yaml automatically (Docker build, persistent disk at /app/data, PORT/DB_PATH env vars already set).
3. Once live, verify with curl https://<your-app>.onrender.com/.

Point Claude Code at the deployed server

Replace (or add an entry to) .mcp.json with the SSE config — see .mcp.sse.json.example for the exact shape:

{
  "mcpServers": {
    "project-manager": {
      "type": "sse",
      "url": "https://<your-deployed-app>/sse"
    }
  }
}

Restart Claude Code and re-run the same natural-language requests and slash commands — same tools, same data, now over the network instead of a local subprocess.

Design notes

• Two transports, one server: src/server.ts exports a createServer() factory used by both index.ts (stdio) and sse.ts (SSE), so the tool logic in tools.ts/db.ts is written once. The SSE entry point creates one Server instance per connection (matching the official MCP SDK examples) so concurrent clients don't share request state; they all read and write the same underlying SQLite file, though.
• SQLite over in-memory: the original example (src/index.ts you may have seen elsewhere) kept tasks in a Map, which resets on every restart. This version persists to SQLite via better-sqlite3 so state survives restarts and redeploys (given a persistent volume).
• Validation: tools.ts checks required fields and enum values before touching the database and returns isError: true with a plain-language message on bad input, rather than throwing.