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

Related MCP server: tpm-mcp

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

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.