MCP Task Server

A practical Model Context Protocol (MCP) server built with TypeScript, the MCP SDK, Prisma, and PostgreSQL.

This project demonstrates the core MCP server concepts through a simple task management system:

Tools — execute operations such as creating, updating, deleting, and listing tasks.

Resources — expose task data and server information through MCP resource URIs.

Resource Templates — expose individual tasks through dynamic URIs such as task://{id}.

Prompts — provide reusable prompt templates for task review workflows.

MCP Client — a small client used to connect to and test the MCP server.

The project is primarily a hands-on learning project for understanding how MCP works internally and how an MCP server can be connected to a real database.

Tech Stack

TypeScript

Node.js

Model Context Protocol SDK 1.30.0

Prisma 7.10.0

PostgreSQL

Zod

tsx

Related MCP server: Personal Task Manager MCP

Project Structure

src/
├── client/
│   ├── create-task.ts
│   ├── list-tasks.ts
│   ├── get-task.ts
│   ├── update-task.ts
│   ├── delete-task.ts
│   ├── read-server-info.ts
│   └── read-tasks.ts
│
├── db/
│   └── prisma.ts
│
├── generated/
│   └── prisma/
│
├── prompts/
│   └── review-task.ts
│
├── resources/
│   ├── server-info.ts
│   ├── tasks.ts
│   └── task.ts
│
├── services/
│   └── task-service.ts
│
├── tools/
│   ├── create-task.ts
│   ├── list-tasks.ts
│   ├── get-task.ts
│   ├── update-task.ts
│   └── delete-task.ts
│
├── client.ts
└── server.ts

MCP Concepts

Tools

Tools are callable operations exposed by the MCP server.

The client can request an operation and receive its result.

Implemented tools:

createTask
listTasks
getTask
updateTask
deleteTask

For example:

Client
  ↓
callTool("createTask")
  ↓
MCP Server
  ↓
Task Service
  ↓
PostgreSQL
  ↓
Result

Tools can perform both read and write operations. They are not limited to database mutations.

Resources

Resources expose read-only data through MCP resource URIs.

This project contains:

server://info
tasks://all
task://{id}

Examples:

server://info

returns information about the MCP server.

tasks://all

returns the current tasks.

task://{id}

returns a specific task.

Resource Templates

task://{id} is implemented as a resource template.

The {id} part is dynamic:

task://cda5d771-1adb-4d0c-a9bb-0d55c3c2e6f9

The server also implements the template list callback, allowing clients to discover concrete task resources.

Prompts

Prompts are reusable prompt templates for specific workflows.

This project includes:

review-task

The prompt accepts a task ID, loads the task from PostgreSQL, and generates a structured review prompt.

For example:

Review this task:

Title: Learn MCP

Please analyze the task and suggest improvements.

Prompts are optional; they are useful when an MCP server wants to provide standardized workflows or instructions rather than only data and operations.

Database

The project uses PostgreSQL with Prisma.

The database contains a simple Task model:

model Task {
  id        String   @id @default(uuid())
  title     String
  completed Boolean  @default(false)
  createdAt DateTime @default(now())
  updatedAt DateTime @updatedAt
}

Environment Variables

Create a .env file:

DATABASE_URL="postgresql://USER:PASSWORD@HOST:5432/DATABASE"

Do not commit .env to the repository.

Installation

Clone the repository and install dependencies:

npm install

Generate the Prisma client:

npx prisma generate

Run migrations:

npx prisma migrate dev

Running the MCP Server

The server uses the MCP stdio transport.

Start it with:

npx tsx src/server.ts

The server communicates through standard input/output, so normal application logs are written to stderr.

Running the Test Client

The project includes a small MCP client for testing the server.

Run:

npx tsx src/client.ts

The client connects to the server through StdioClientTransport and demonstrates:

connecting to the MCP server

listing tools

calling tools

listing resources

reading resources

listing prompts

retrieving prompts

MCP Architecture

The overall architecture looks like this:

                  ┌──────────────────┐
                  │    MCP Client    │
                  └────────┬─────────┘
                           │
                           │ stdio
                           ▼
                  ┌──────────────────┐
                  │    MCP Server    │
                  ├──────────────────┤
                  │      Tools       │
                  │    Resources     │
                  │     Prompts      │
                  └────────┬─────────┘
                           │
                           ▼
                  ┌──────────────────┐
                  │   Task Service   │
                  └────────┬─────────┘
                           │
                           ▼
                  ┌──────────────────┐
                  │    PostgreSQL    │
                  └──────────────────┘

What This Project Demonstrates

The goal of this repository is not to build a full production task management application.

The goal is to understand the MCP protocol and its main server primitives by implementing them against a real database.

The project covers:

MCP server initialization

MCP client initialization

stdio transport

MCP tools

tool arguments with Zod

MCP resources

dynamic resources

resource templates

resource template listing

MCP prompts

prompt arguments

database integration

Prisma

PostgreSQL

client/server communication

License

This project is for learning and demonstration purposes.