DEV Community: Fairen

APM vs agkit: is your plugin marketplace a build artifact or a source of truth?

Fairen — Fri, 17 Jul 2026 06:39:25 +0000

Microsoft shipped APM — Agent Package Manager. 3.2k stars, apm.yml, a lockfile, policy files, SBOM export, eight coding agents configured from one manifest. It is a serious piece of work.

I maintain agkit, which scaffolds and manages agent plugin marketplaces. So when APM landed, the honest first reaction was the one you'd expect: is there anything left for mine to do?

Take what follows with the appropriate grain of salt — I am not a neutral party. But I spent a week in APM's docs and issue tracker trying to answer that question properly, and the answer turned out to be more interesting than either "no" or "obviously yes." The two tools overlap almost completely on the surface, and disagree about one thing underneath. That one thing is the whole decision.

The easy answer, and why it's wrong

The comfortable story writes itself: APM installs, agkit publishes. Consumer versus producer. Two halves of the same problem. Everybody shakes hands.

It's wrong, and it's worth killing before it spreads, because APM publishes marketplaces perfectly well:

apm init --marketplace starts a project that will publish its own marketplace
apm marketplace init appends a marketplace: block to your apm.yml and creates .claude-plugin/
there are authoring helpers around it — check, outdated, migrate, package
apm pack builds .claude-plugin/marketplace.json from that block — that is the publishing step, and the file is the artifact
microsoft/apm-action runs the whole release: gate, matrix-pack, sha256 sidecars, marketplace.json drift detection, gh release create

So both tools take skills sitting on your disk and turn them into something other people install by name, at a version. If you want a reason to pick one over the other, "producer versus consumer" is not it.

What they actually disagree about

APM's source of truth is apm.yml plus a .apm/<type>/ tree. marketplace.json is what falls out the other end. apm pack is a compiler, and APM is deliberate about this: the GitHub Action doesn't assume which CLI consumes the output, it just emits whatever your outputs: map declares — claude=marketplace.json, codex=plugins.toml. Vendor-neutral by design. The catalog is a build artifact.

agkit's source of truth is .claude-plugin/marketplace.json itself. There is nothing to compile for Claude Code and Copilot, because they read that file as-is. agkit sync runs the other way entirely: the README plugin table and the AGENTS.md list are derived from the catalog, so they can't drift. The catalog is the source of truth.

Same filename. Opposite direction. Everything else follows from that.

What the compile step buys you

A real abstraction layer earns its keep, and APM's does:

One manifest, many ecosystems. Declare once, deploy across Copilot, Claude Code, Cursor, OpenCode, Codex, Gemini, Windsurf, and Kiro. When a vendor changes its format, that's APM's problem, not yours.
Somewhere to hang governance. You cannot lock, hash, scan, and police a file that people hand-edit. Once the catalog is generated, apm.lock.yaml can pin the resolved tree with integrity hashes, apm-policy.yml can constrain sources with tighten-only inheritance from enterprise to org to repo, and apm lock export can emit CycloneDX or SPDX.
Reproducibility as a contract. git clone && apm install is a promise. A marketplace is only ever an offer.

What it costs you

An abstraction is a thing you have to learn, a build you have to run, and a place bugs can live that couldn't otherwise exist.

APM's own authoring guide is refreshingly blunt about one of these. apm pack is liberal — it collects primitives from both .apm/<type>/ and root convention directories like agents/ or skills/. apm install is stricter, and per-primitive. The consequence is that if you author instructions/ at your plugin root, your bundle packs cleanly and then installs silently incomplete. Their recommendation to marketplace publishers is to use .apm/<type>/ for every primitive, because it's the only layout that's symmetric across both commands.

That's good documentation of a sharp edge. It is also a category of bug that cannot exist when there is no compile step — when the file you edit is the file the agent reads, "packs but doesn't install" isn't a state your project can be in.

What agkit's directness buys you

What's in the repo is what ships. No build, no artifact, no drift between them. git push is the release — no registry, no account, no publish token.
Zero adoption cost. npx agkit init dev-toolkit, Node 22+, nothing installed. Compare with adopting a manifest format, a lockfile, and a release pipeline before your first plugin exists.
The plugin is the unit of release. agkit bump commit-crafter --tag reads only the commits touching that plugin's directory since its last commit-crafter@x.y.z tag, applies conventional-commit rules, writes the manifest version, generates the changelog entry, syncs the derived files, and tags it. Semantic-release, scoped to one plugin, so a busy plugin never drags a quiet one into a release.
Reference without vendoring. agkit add octo-org/changelog-skill changelog --ref v1.2.0 puts someone else's plugin in your catalog without cloning it. Your repo gains one JSON entry; the agent resolves the source at install time.

What it costs you

You inherit the platform's model, including its future. If Anthropic and GitHub change the catalog shape, agkit follows them; it has no layer to absorb the change on your behalf. That's the deal you're signing.

And there's a harder limit. agkit has no lockfile, no integrity hashes, no policy file, no SBOM, and no supply-chain scanning. If your security team needs to say "these are the only sources this organisation will allow" and have it enforced on every install, agkit has nothing to offer them. That isn't a roadmap gap I'm being coy about. It's the wrong tool, and APM is the right one.

They compose — and that's the actual answer

Here is the part I didn't expect to find, and the reason this article isn't a fight.

APM reads marketplace.json as-is — both .github/plugin/marketplace.json and .claude-plugin/marketplace.json. It normalises both dialects: Copilot CLI uses repository and ref fields, Claude Code uses source as a string or an object, and APM maps either onto its canonical dependency representation. It then resolves each entry to a Git URL — at which point plugins installed from that marketplace get the same version locking, security scanning, and governance as any other APM dependency.

Read that from a publisher's chair. An agkit-published marketplace is already an APM dependency. You don't do anything. You published the format the platform defined, and APM speaks it fluently.

So the split was never producer versus consumer. It's this:

You choose how you author. Your users choose how they consume.

Those are two decisions, made by two different people, at two different times — and neither tool forces the other's hand. A solo maintainer publishes a catalog with agkit and git push. A regulated bank three timezones away installs one plugin out of it through apm install commit-crafter@dev-toolkit, with a lockfile, a pinned SHA, a Unicode scan and a policy gate in the way. Nobody had to agree on a toolchain. They agreed on a file format, which is the only thing worth agreeing on.

So which one?

	agkit	APM
Catalog is	the source of truth	a build artifact
You author in	the platform's native format	`apm.yml` + `.apm/<type>/`
Build step	none for Claude Code / Copilot	`apm pack`
Release unit	the plugin (per-plugin semver + changelog + tag)	the package / project
Version bump	computed from conventional commits	you decide, CI releases
Distribution	`git push` to any forge	git, plus release artifacts
Consumption	the agent's native `/plugin install`	`apm install` + lockfile
Governance	none	lockfile, hashes, policy, SBOM, drift detection
Targets	Claude Code, Copilot native · Codex, Cursor via `agkit build`	8 agents from one manifest
Runtime	Node 22+, `npx`-able	Python binary — `curl`, `brew`, `pip`, `scoop`

Reach for agkit when you're publishing: you have skills you want other people to install by name, you want the catalog to be a file you can read, and you want git push to be the whole release pipeline.

Reach for APM when you're consuming or governing: you need every developer and CI runner to end up with a byte-identical agent setup, you need to answer "what reached disk and from where," or someone in your organisation has an opinion about supply chains that comes with a compliance deadline attached.

Reach for both in the obvious configuration: publish with agkit, let the people who need governance put APM in front of it. The catalog doesn't care.

The honest closing

APM is a bigger project than mine, backed by an organisation, moving faster, and solving a problem I'm not solving. Its authoring surface has been growing steadily — and if it eventually converges on treating the catalog as the source rather than the output, agkit's reason to exist gets thin.

I'd take that outcome. I wrote agkit because assembling marketplace.json by hand at 6pm on a Friday is a chore, not because the ecosystem was short an abstraction. If that chore stops existing, the tool has done its job either way.

Until then: the file is the interface. Pick whichever tool gets you to a good one.

agkit — npm · docs · source
APM — github.com/microsoft/apm · docs
Previously: Stop zipping your Claude Code skills: build a plugin marketplace in 15 minutes

Compared against APM v0.25.0 and agkit 0.9.2, July 2026. Both move fast — check the docs before quoting me. agkit is MIT-licensed and unaffiliated with Anthropic, GitHub, Microsoft, OpenAI or Cursor.

Agkit : Stop zipping your Claude Code skills: build a plugin marketplace in 15 minutes

Fairen — Thu, 16 Jul 2026 22:13:04 +0000

You wrote a Claude Code skill. A good one — it turns your staged diff into a proper conventional commit message, and you use it a dozen times a day.

A teammate watches you work and asks the inevitable question: "can you send me that?"

So you zip up a folder. Then someone else asks. Then you improve the skill — and now there are three copies of it in the wild, two of them stale, and nobody knows which one they have.

So you do the obvious thing: you make a repo. team-skills, one folder per skill, everyone clones it and copies what they need into their ~/.claude/. Push a fix and it's available to everybody.

This is better than the zip. It is not a solution — it's the same problem with a git remote in front of it.

The junk drawer problem

A shared repo of skills is a junk drawer, and it fails in four specific ways.

It's all-or-nothing. Clone the repo and you get all fourteen skills, including the eleven that have nothing to do with your work. And skills aren't free: each one's description competes for the agent's attention every session. Your teammate wanted one skill. Their alternative is to hand-pick files out of the clone — which is copying, which is where we came in.

Copying is still copying. The moment those files land in someone's ~/.claude/, they're a fork. No link back to the origin, no update path except "clone again and re-copy, carefully", and no way to answer the question "which version do you have?" — because there are no versions.

There's no unit. team-skills@a3f9c2 tells you nothing about the commit skill specifically. You can't say "I'm on commit-crafter 0.2.0" because commit-crafter isn't a thing that has versions; it's a folder in a repo whose history is fourteen unrelated stories braided together. Every skill's changelog is every other skill's noise.

There's no boundary of ownership. Another team publishes a genuinely good skill. Your drawer's options: copy it in and own the drift forever, or tell everyone to clone a second drawer.

What's missing are two things — and here's the part worth being clear about, because it's the actual point of this article: neither of them is an agkit invention.

The first is the plugin: the unit. A directory with a manifest that gives it an identity — a name, a version, a description, an author. Something that can be installed, updated, and uninstalled as one thing, and versioned independently of its neighbours. This is how Claude Code and GitHub Copilot already model extensions. The separation isn't tooling; it's the shape of the thing.

The second is the marketplace: the catalog. One file listing your plugins, so an agent can show them, install one by name, and know where each of them comes from — including from a repo that isn't yours.

Put those together and "can you send me that?" has a different answer:

/plugin install commit-crafter@dev-toolkit

Your teammate gets one plugin, not fourteen. It has a version. /plugin update brings them your fix. They can uninstall it cleanly. Nothing was copied by hand, and nothing drifted.

So why does anyone still keep a junk drawer? Because writing that catalog by hand — plus a manifest per plugin, plus the versioning, plus the changelogs, plus keeping the docs in step — is exactly the kind of chore that makes zipping a folder look reasonable at 6pm on a Friday.

That's the gap agkit fills. It doesn't reinvent plugins or marketplaces — it removes the reason you didn't bother. Think ng for Angular, but for agent plugin marketplaces: one command scaffolds a push-ready repository, and a handful more cover the rest of the project's life.

In this walkthrough we'll take that commit skill from "a folder on your machine" to "installable by anyone with one line". We'll scaffold a marketplace, add a plugin from a template and make it ours, catalog a second plugin that lives in someone else's repo without ever cloning it, publish to GitHub, then ship an improvement with a real version bump.

Everything below is a real terminal session against agkit 0.9.2.

The one idea to hold onto

agkit is built around a single principle: one canonical catalog.

Your repository has exactly one source of truth, .claude-plugin/marketplace.json, plus your plugins under plugins/<name>/. Claude Code and GitHub Copilot read that file as-is — no build step, no compilation. Push the repo, and it installs.

Everything else — the README plugin table, the AGENTS.md list, the registries for Codex and Cursor — is derived from that catalog. Which means it can't drift, because you never maintain it by hand.

Keep that in mind and the rest of the commands stop looking like a list of tools and start looking like one workflow.

Step 1: scaffold the marketplace

You need Node.js 22+. No install required:

npx agkit init dev-toolkit

It asks a few questions (name, owner, description, git remote, CI), or you can pass them as flags and skip the prompts entirely:

npx agkit init dev-toolkit -y \
  --name dev-toolkit \
  --owner "Jane Doe" \
  --email jane@example.com \
  --description "My personal Claude Code + Copilot plugins" \
  --repo https://github.com/jane/dev-toolkit.git

┌  agkit init _
│
◇  Marketplace scaffolded
│
◇  Next steps ─────────────────────────────────────────────────────╮
│                                                                   │
│  cd dev-toolkit                                                   │
│  git remote add origin https://github.com/jane/dev-toolkit.git    │
│  agkit add skill my-first-skill                                   │
│  agkit validate                                                   │
│  git add -A && git commit -m 'feat: initial marketplace'          │
│  git push -u origin main                                          │
│                                                                   │
│  Target agents: Claude Code, GitHub Copilot CLI                   │
│  Native install (no build): Claude Code, GitHub Copilot CLI       │
│                                                                   │
├───────────────────────────────────────────────────────────────────╯
│
└  Done ✔

Here's what landed:

dev-toolkit/
├── .claude-plugin/marketplace.json   # the catalog
├── plugins/                          # your plugins live here
├── AGENTS.md                         # repo context, read natively by most agents
├── README.md                         # with an install section, already filled in
├── examples/team-settings.json       # drop-in config so teammates get it automatically
├── .github/workflows/validate.yml    # CI gate
└── .gitignore                        # (git init already ran)

The catalog itself is deliberately boring:

{
  "$schema": "https://json.schemastore.org/claude-code-marketplace.json",
  "name": "dev-toolkit",
  "owner": { "name": "Jane Doe", "email": "jane@example.com" },
  "metadata": {
    "description": "My personal Claude Code + Copilot plugins",
    "version": "1.0.0",
    "pluginRoot": "./plugins",
    "targets": ["claude-code", "copilot"]
  },
  "plugins": []
}

Two things worth noticing. targets records which agents you serve — the default is Claude Code and Copilot, both native. And it's already a git repo with a $schema, meaning your editor autocompletes the catalog and CI can validate it from the first commit.

Serving Codex or Cursor too? Pass --agents claude-code,copilot,codex,cursor at init. Those two install from their own registry, which agkit build generates from this same catalog. One repo, four agents, no duplicated plugin content. We'll stay native in this article.

Step 2: add the skill, then make it yours

agkit add takes a template and a name. Five built-in templates ship with the CLI — skill, command, agent, hook, mcp:

agkit add skill commit-crafter -d "Write conventional commit messages from staged changes"

◆  Created plugins/commit-crafter (built-in:skill template) and registered it in marketplace.json
│
●  Edit the generated files, then test locally:
│    claude
│    /plugin marketplace add /path/to/dev-toolkit
│    /plugin install commit-crafter@dev-toolkit

Two files appear, and the catalog gains an entry pointing at them:

{
  "name": "commit-crafter",
  "source": "./plugins/commit-crafter",
  "description": "Write conventional commit messages from staged changes",
  "version": "0.1.0",
  "author": { "name": "Jane Doe" }
}

Note that last hint in the output: /plugin marketplace add /path/to/dev-toolkit. A marketplace is just a directory with a catalog, so you can install from a local path and test your plugin before anything is pushed anywhere. That tightens the loop considerably.

Now the part that matters — the template is a skeleton, not a skill. Open plugins/commit-crafter/skills/commit-crafter/SKILL.md and you get scaffolding with instructions in it:

---
name: commit-crafter
description: "Write conventional commit messages from staged changes ..."
---

# Commit Crafter

Explain the knowledge or procedure this skill provides. Claude loads this
file on demand, so write it as instructions to a competent colleague.

## When to use
- Situation 1
- Situation 2

Replace it with the real thing. The description in the front matter is what Claude reads to decide whether to load the skill at all, so it's worth writing carefully:

---
name: commit-crafter
description: "Writes conventional commit messages from staged changes. Use when the user asks to commit, write a commit message, or says 'commit this'."
---

# Commit Crafter

Turn a staged diff into a Conventional Commits message.

## Instructions

1. Run `git diff --staged` to read what is actually being committed.
2. Pick the type from the change itself: `feat` for new behaviour, `fix` for
   a bug, `refactor` when behaviour is unchanged, `docs`, `test`, `chore`.
3. Scope it with the package or directory touched: `feat(auth): …`
4. Subject line: imperative, lowercase, no trailing period, ≤ 72 chars.
5. If the change breaks a public contract, add a `BREAKING CHANGE:` footer.

## Examples

`feat(parser): support scoped package names`
`fix(auth): refresh the token before expiry, not after`

That's the whole shape of it: agkit gives you a valid, registered, correctly wired plugin; you supply the substance.

If you later hand-edit a manifest — a description, keywords, a homepage — remember that plugins/<name>/.claude-plugin/plugin.json is the source of truth, not the catalog. Edit it, then run agkit sync and the catalog, README table and AGENTS.md all catch up.

Step 3: catalog a plugin that lives in someone else's repo

Here's where a marketplace beats a folder of copies.

There's a public plugin you like — say a changelog generator, published in its own repository. You want it in your toolkit, but you don't want to own its code, copy it in, or track its upstream changes by hand.

So don't. Point at it:

agkit add octo-org/changelog-skill changelog \
  --ref v1.2.0 \
  -d "Generate a release changelog from git history"

◆  Registered changelog as a remote plugin (octo-org/changelog-skill) in marketplace.json — nothing was cloned.
│
●  Claude Code fetches it from the source at install time:
│    /plugin install changelog@dev-toolkit
│  (pass --vendor to clone it into ./plugins instead)

Nothing was cloned. Your repo gained exactly one thing — an entry in the catalog:

{
  "name": "changelog",
  "source": {
    "source": "github",
    "repo": "octo-org/changelog-skill",
    "ref": "v1.2.0"
  },
  "description": "Generate a release changelog from git history"
}

The agent resolves that source when a user installs the plugin. No vendored code, no version to keep in sync, no fork to maintain. The --ref v1.2.0 pins it to a tag so upstream can't move under your users' feet — use --sha <commit> if you want to pin harder.

This is the default for any remote git source, and the spec grammar is flexible: bare owner/repo, gh:/gl: shorthands, or a full git URL for any forge. If the plugin sits in a subdirectory of a bigger repo, point at the folder with //:

agkit add "https://gitlab.com/team/marketplace.git//my-plugin" my-plugin

And when you do want the files copied in — seeding a plugin from a shared template you intend to modify — that's what --vendor is for. It clones the repo, renders it, and drops the result into plugins/<name>/ as your code. The rule of thumb: remote sources are referenced by default; --vendor when you want to own the copy.

Step 4: validate and publish

agkit validate runs local checks — JSON validity, kebab-case names, reserved names, source resolution, manifest presence, version drift — and delegates to claude plugin validate when the Claude Code CLI is installed:

agkit validate

●  Note: relative plugin sources resolve only when the marketplace is added via
   Git (any forge), not via a direct URL to marketplace.json.
◆  claude plugin validate: passed
◆  .claude-plugin/marketplace.json is valid

It exits non-zero on error, which is why the CI workflow that init generated already calls it.

Publishing is the anticlimax — it's just git:

git remote add origin https://github.com/jane/dev-toolkit.git
git add -A
git commit -m "feat: initial marketplace"
git push -u origin main

That's it. That's the distribution step. No registry, no account, no publish token. Your teammate now runs:

/plugin marketplace add jane/dev-toolkit
/plugin install commit-crafter@dev-toolkit

Copilot users get the same repo through copilot plugin marketplace add jane/dev-toolkit. And because distribution is just git push, none of this is GitHub-specific — GitLab, Bitbucket, Gitea and self-hosted forges all work, agkit just emits the git URL form instead of the owner/repo shorthand.

Better still, init wrote an examples/team-settings.json with an extraKnownMarketplaces block. Drop it into .claude/settings.json in your team's repo and teammates get the marketplace automatically when they trust the repository — nobody has to add anything by hand.

Step 5: ship an improvement

This is the step neither the zip nor the drawer could ever do.

You improve the skill — it should now recognise breaking changes and add the footer. Commit it with a conventional message, scoped to the plugin:

git add plugins/commit-crafter
git commit -m "feat(commit-crafter): detect breaking changes and add a BREAKING CHANGE footer"

Preview the release before committing to it:

agkit bump commit-crafter --dry-run

●  2 commit(s) (no previous release tag):
│    minor  feat(commit-crafter): detect breaking changes and add a BREAKING CHANGE footer
│    minor  feat: initial marketplace
│
●  [dry-run] commit-crafter: 0.1.0 -> 0.2.0 (minor) + CHANGELOG.md entry

agkit read the commits that touch that plugin's directory since its last commit-crafter@x.y.z tag — there isn't one yet, hence "no previous release tag" and the initial commit being counted too — and applied conventional-commit rules: a feat means minor, so 0.1.0 → 0.2.0. A fix would be a patch; a feat! or BREAKING CHANGE: would be major. You can always force it: agkit bump commit-crafter major.

Happy with it? Do it for real, and let agkit commit and tag the release:

agkit bump commit-crafter --tag

◆  commit-crafter: 0.1.0 -> 0.2.0 (minor)
◆  Committed and tagged commit-crafter@0.2.0 — push with: git push --follow-tags

In one command it wrote the new version into the plugin manifest, generated a changelog entry from your commit subjects, and ran sync internally so the version flowed everywhere it needs to be:

# Changelog

## 0.2.0 — 2026-07-16

- feat(commit-crafter): detect breaking changes and add a BREAKING CHANGE footer
- feat: initial marketplace

The catalog now says 0.2.0. So does the README table. So does the AGENTS.md list. You updated none of them.

git push --follow-tags

The --follow-tags matters: the tag is the boundary the next bump measures from, so it has to reach the forge. Your teammate runs /plugin update and has your fix. Versions are per plugin, by the way — each one carries its own manifest version, changelog and tags, so a busy plugin never drags a quiet one into a release.

One caveat worth knowing: you can't bump a referenced remote plugin like changelog. Its version is owned upstream and you only hold a reference. To move it forward, re-pin it: agkit add octo-org/changelog-skill changelog --ref v1.3.0.

The loop, condensed

npx agkit init dev-toolkit                    # scaffold a push-ready repo
agkit add skill commit-crafter                # scaffold a plugin, then edit it
agkit add octo-org/changelog-skill changelog --ref v1.2.0   # reference, don't clone
agkit validate && git push -u origin main     # publish

# later:
git commit -m "feat(commit-crafter): …"
agkit bump commit-crafter --tag               # version + changelog + sync + tag
git push --follow-tags

Five commands to go from a folder on your laptop to something a team installs by name and updates on its own.

The genuine shift here isn't the scaffolding — it's that your skills stop being files you hand people and become software you ship: each one a plugin with a name, a version, a changelog and a release history, listed in a catalog, validated in CI. The same repo can serve Claude Code, Copilot, Codex and Cursor, from any git forge, because there's one catalog and everything else derives from it.

And notice how little of that is about agkit. The plugin and the marketplace are the platform's model — they're what let your teammate install one thing instead of fourteen, at a version, and update it without asking you. agkit's contribution is narrower and, honestly, more useful: it makes producing that structure cheap enough that you'll actually do it, instead of pushing another folder into the drawer.

Which, it turns out, was all the zip was ever missing.

agkit is MIT-licensed and unaffiliated with Anthropic, GitHub, OpenAI or Cursor.

npm: agkit
Docs: agent-marketplace-kit.gitbook.io/agkit-docs
Source: github.com/AGent-marketplace-KIT/cli
Website: agent-marketplace-kit.github.io

If you build something with it, I'd love to see the catalog.

Complete Tutorial: Creating an MCP Task Manager Server from Scratch

Fairen — Thu, 06 Nov 2025 16:14:42 +0000

📖 Table of Contents

Introduction to Model Context Protocol (MCP)
Prerequisites and Installation
Project Structure
Basic Configuration
MCP Server Implementation
Endpoints: Tools
Endpoints: Resources
Endpoints: Prompts
Error Handling
Main Server
Code Organization and Patterns
Testing and Validation
Docker Deployment
Additional Resources

1. Introduction to Model Context Protocol (MCP)

What is MCP?

The Model Context Protocol (MCP) is a standardized communication protocol that allows Large Language Models (LLMs) to interact with external systems in a secure and structured manner. It uses JSON-RPC 2.0 for communication.

Main Components

Tools: Actions that the LLM can execute (create, modify, delete)
Resources: Data that the LLM can read (files, databases)
Prompts: Predefined templates to guide interactions

MCP Session Lifecycle

sequenceDiagram
    Client->>Server: initialize
    Server->>Client: capabilities
    Client->>Server: tools/list
    Client->>Server: resources/list
    Client->>Server: prompts/list
    Client->>Server: tools/call | resources/read | prompts/get

2. Prerequisites and Installation

Required Technologies

Node.js 18+ with TypeScript
@modelcontextprotocol/sdk for MCP implementation
Zod for schema validation
Database (SQLite for this tutorial)

Installation

# Create the project
mkdir mcp-task-manager
cd mcp-task-manager

# Initialize Node.js
npm init -y

# Install dependencies
npm install @modelcontextprotocol/sdk zod sqlite3
npm install -D typescript @types/node ts-node nodemon

# TypeScript configuration
npx tsc --init

3. Project Structure

mcp-task-manager/
├── src/
│   ├── server.ts           # MCP server entry point
│   ├── database/
│   │   ├── db.ts          # Database configuration
│   │   └── schema.sql     # Table schema
│   ├── tools/
│   │   ├── index.ts       # Tools export
│   │   ├── create-task.ts
│   │   ├── update-task.ts
│   │   ├── complete-task.ts
│   │   └── delete-task.ts
│   ├── resources/
│   │   ├── index.ts       # Resources export
│   │   ├── task-list.ts
│   │   ├── task-stats.ts
│   │   └── task-detail.ts
│   ├── prompts/
│   │   ├── index.ts       # Prompts export
│   │   ├── weekly-review.ts
│   │   └── sprint-planning.ts
│   ├── types/
│   │   └── task.ts        # TypeScript types
│   └── utils/
│       └── errors.ts      # Error handling
├── Dockerfile             # Multi-stage Docker configuration
├── docker-compose.yml     # Docker orchestration
├── .dockerignore          # Files to ignore for Docker
├── .env.example           # Environment variables example
├── package.json
├── tsconfig.json
└── README.md

4. Basic Configuration

package.json

{
  "name": "mcp-task-manager",
  "version": "1.0.0",
  "description": "MCP server for task management",
  "main": "dist/server.js",
  "scripts": {
    "build": "tsc && mkdir -p dist/database && cp src/database/schema.sql dist/database/",
    "start": "node dist/server.js",
    "dev": "nodemon src/server.ts",
    "test": "jest",
    "docker:build": "docker build -t task-manager-mcp-server .",
    "docker:run": "docker run -d --name task-manager-mcp-server -p 3000:3000 task-manager-mcp-server",
    "docker:stop": "docker stop task-manager-mcp-server && docker rm task-manager-mcp-server",
    "docker:logs": "docker logs task-manager-mcp-server"
  },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.21.0",
    "sqlite3": "^5.1.7",
    "zod": "^3.25.76"
  },
  "devDependencies": {
    "@types/node": "^24.10.0",
    "nodemon": "^3.1.10",
    "ts-node": "^10.9.2",
    "typescript": "^5.9.3"
  }
}

tsconfig.json

{
  // Visit https://aka.ms/tsconfig to read more about this file
  "compilerOptions": {
    // File Layout
    "outDir": "./dist",
    "rootDir": "./src",

    // Environment Settings
    // See also https://aka.ms/tsconfig/module
    "module": "commonjs",
    "target": "ES2022",
    "esModuleInterop": true,
    // For nodejs:
    "lib": ["ES2022"],
    "types": ["node"],
    // and npm install -D @types/node

    // Other Outputs
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,

    // Stricter Typechecking Options
    "noUncheckedIndexedAccess": true,
    "exactOptionalPropertyTypes": true,

    // Style Options
    // "noImplicitReturns": true,
    // "noImplicitOverride": true,
    // "noUnusedLocals": true,
    // "noUnusedParameters": true,
    // "noFallthroughCasesInSwitch": true,
    // "noPropertyAccessFromIndexSignature": true,

    // Recommended Options
    "strict": true,
    "skipLibCheck": true,
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

5. MCP Server Implementation

Basic Types (`src/types/task.ts`)

The system uses Zod for validation and TypeScript type generation:

import { z } from 'zod';

// Main schema with complete validation
export const TaskSchema = z.object({
  id: z.string().optional(),                           // Auto-generated
  title: z.string().min(1).max(200),                  // Required title (1-200 chars)
  description: z.string().optional(),                  // Optional description
  priority: z.enum(['low', 'medium', 'high', 'urgent']).default('medium'),
  status: z.enum(['pending', 'in_progress', 'completed', 'cancelled']).default('pending'),
  due_date: z.string().datetime().optional(),         // ISO 8601 format
  tags: z.array(z.string()).default([]),              // Array of strings
  assignee: z.string().optional(),                    // Assigned user
  created_at: z.string().datetime().optional(),       // Creation timestamp
  updated_at: z.string().datetime().optional(),       // Modification timestamp
  completed_at: z.string().datetime().optional()      // Completion timestamp
});

// TypeScript type automatically inferred
export type Task = z.infer<typeof TaskSchema>;

// Derived schemas for CRUD operations
export const CreateTaskSchema = TaskSchema.omit({ 
  id: true, 
  created_at: true, 
  updated_at: true, 
  completed_at: true 
});

export const UpdateTaskSchema = TaskSchema.partial().extend({
  id: z.string()                                      // Required ID for updates
});

export const CompleteTaskSchema = z.object({
  task_id: z.string(),
  completion_notes: z.string().optional(),
  time_spent: z.number().min(0).optional()           // Time in minutes
});

Advantages of this approach:

Type Safety: Automatic runtime validation
Living documentation: Schemas serve as reference
Reusability: One schema, multiple uses (API, DB, validation)
Explicit errors: Clear error messages for clients

Validation example:

// ✅ Valid
const task = CreateTaskSchema.parse({
  title: "New task",
  priority: "high",
  tags: ["urgent", "feature"]
});

// ❌ Validation error
const invalid = CreateTaskSchema.parse({
  title: "",  // Error: minimum 1 character
  priority: "invalid"  // Error: unauthorized value
});

Database Configuration (`src/database/db.ts`)

import sqlite3 from 'sqlite3';
import path from 'path';
import fs from 'fs';
import { Task } from '../types/task';

export class TaskDatabase {
  private db: sqlite3.Database;

  constructor(dbPath: string = './tasks.db') {
    this.db = new sqlite3.Database(dbPath);
    this.initializeDatabase();
  }

  private async initializeDatabase() {
    const schemaPath = path.join(__dirname, 'schema.sql');
    const schema = fs.readFileSync(schemaPath, 'utf8');

    return new Promise<void>((resolve, reject) => {
      this.db.exec(schema, (err) => {
        if (err) reject(err);
        else resolve();
      });
    });
  }

  async createTask(task: Omit<Task, 'id' | 'created_at' | 'updated_at'>): Promise<string> {
    const sql = `
      INSERT INTO tasks (title, description, priority, status, due_date, tags, assignee)
      VALUES (?, ?, ?, ?, ?, ?, ?)
    `;

    return new Promise((resolve, reject) => {
      this.db.run(sql, [
        task.title,
        task.description || null,
        task.priority,
        task.status || 'pending',
        task.due_date || null,
        JSON.stringify(task.tags || []),
        task.assignee || null
      ], function(err) {
        if (err) reject(err);
        else resolve(`task-${this.lastID}`);
      });
    });
  }

  async getTask(id: string): Promise<Task | null> {
    const sql = 'SELECT * FROM tasks WHERE id = ?';

    return new Promise((resolve, reject) => {
      this.db.get(sql, [id.replace('task-', '')], (err, row: any) => {
        if (err) reject(err);
        else if (!row) resolve(null);
        else {
          resolve({
            id: `task-${row.id}`,
            title: row.title,
            description: row.description,
            priority: row.priority,
            status: row.status,
            due_date: row.due_date,
            tags: JSON.parse(row.tags || '[]'),
            assignee: row.assignee,
            created_at: row.created_at,
            updated_at: row.updated_at,
            completed_at: row.completed_at
          });
        }
      });
    });
  }

  async getAllTasks(): Promise<Task[]> {
    const sql = 'SELECT * FROM tasks ORDER BY created_at DESC';

    return new Promise((resolve, reject) => {
      this.db.all(sql, [], (err, rows: any[]) => {
        if (err) reject(err);
        else {
          const tasks = rows.map(row => ({
            id: `task-${row.id}`,
            title: row.title,
            description: row.description,
            priority: row.priority,
            status: row.status,
            due_date: row.due_date,
            tags: JSON.parse(row.tags || '[]'),
            assignee: row.assignee,
            created_at: row.created_at,
            updated_at: row.updated_at,
            completed_at: row.completed_at
          }));
          resolve(tasks);
        }
      });
    });
  }

  async updateTask(id: string, updates: Partial<Task>): Promise<boolean> {
    const fields = [];
    const values: string[] = [];

    Object.entries(updates).forEach(([key, value]) => {
      if (key !== 'id' && value !== undefined) {
        fields.push(`${key} = ?`);
        values.push(key === 'tags' ? JSON.stringify(value) : String(value));
      }
    });

    if (fields.length === 0) return false;

    fields.push('updated_at = CURRENT_TIMESTAMP');
    const sql = `UPDATE tasks SET ${fields.join(', ')} WHERE id = ?`;
    values.push(id.replace('task-', ''));

    return new Promise((resolve, reject) => {
      this.db.run(sql, values, function(err) {
        if (err) reject(err);
        else resolve(this.changes > 0);
      });
    });
  }

  async completeTask(id: string, notes?: string, timeSpent?: number): Promise<boolean> {
    const sql = `
      UPDATE tasks 
      SET status = 'completed', 
          completed_at = CURRENT_TIMESTAMP,
          completion_notes = ?,
          time_spent = ?,
          updated_at = CURRENT_TIMESTAMP
      WHERE id = ?
    `;

    return new Promise((resolve, reject) => {
      this.db.run(sql, [notes || null, timeSpent || null, id.replace('task-', '')], function(err) {
        if (err) reject(err);
        else resolve(this.changes > 0);
      });
    });
  }

  async deleteTask(id: string): Promise<boolean> {
    const sql = 'DELETE FROM tasks WHERE id = ?';

    return new Promise((resolve, reject) => {
      this.db.run(sql, [id.replace('task-', '')], function(err) {
        if (err) reject(err);
        else resolve(this.changes > 0);
      });
    });
  }

  async getStats(): Promise<any> {
    const sql = `
      SELECT 
        COUNT(*) as total_tasks,
        SUM(CASE WHEN status = 'pending' THEN 1 ELSE 0 END) as pending,
        SUM(CASE WHEN status = 'in_progress' THEN 1 ELSE 0 END) as in_progress,
        SUM(CASE WHEN status = 'completed' THEN 1 ELSE 0 END) as completed,
        SUM(CASE WHEN status = 'cancelled' THEN 1 ELSE 0 END) as cancelled,
        SUM(CASE WHEN priority = 'urgent' THEN 1 ELSE 0 END) as urgent,
        SUM(CASE WHEN priority = 'high' THEN 1 ELSE 0 END) as high,
        SUM(CASE WHEN priority = 'medium' THEN 1 ELSE 0 END) as medium,
        SUM(CASE WHEN priority = 'low' THEN 1 ELSE 0 END) as low,
        AVG(time_spent) as avg_completion_time
      FROM tasks
    `;

    return new Promise((resolve, reject) => {
      this.db.get(sql, [], (err, row: any) => {
        if (err) reject(err);
        else resolve(row);
      });
    });
  }
}

Database Schema (`src/database/schema.sql`)

CREATE TABLE IF NOT EXISTS tasks (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL,
  description TEXT,
  priority TEXT DEFAULT 'medium' CHECK (priority IN ('low', 'medium', 'high', 'urgent')),
  status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'in_progress', 'completed', 'cancelled')),
  due_date TEXT,
  tags TEXT DEFAULT '[]',
  assignee TEXT,
  completion_notes TEXT,
  time_spent INTEGER,
  created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
  completed_at DATETIME
);

CREATE INDEX IF NOT EXISTS idx_tasks_status ON tasks(status);
CREATE INDEX IF NOT EXISTS idx_tasks_priority ON tasks(priority);
CREATE INDEX IF NOT EXISTS idx_tasks_assignee ON tasks(assignee);
CREATE INDEX IF NOT EXISTS idx_tasks_due_date ON tasks(due_date);

6. Endpoints: Tools

Task Creation (`src/tools/create-task.ts`)

import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';
import { CreateTaskSchema } from '../types/task.js';
import { McpError, ErrorCode } from '../utils/errors.js';

export const createTaskTool: Tool = {
  name: 'create_task',
  description: 'Create a new task in the system',
  inputSchema: {
    type: 'object',
    properties: {
      title: {
        type: 'string',
        description: 'Task title',
        minLength: 1,
        maxLength: 200
      },
      description: {
        type: 'string',
        description: 'Detailed task description'
      },
      priority: {
        type: 'string',
        enum: ['low', 'medium', 'high', 'urgent'],
        default: 'medium',
        description: 'Priority level'
      },
      due_date: {
        type: 'string',
        format: 'date-time',
        description: 'Due date (ISO 8601)'
      },
      tags: {
        type: 'array',
        items: { type: 'string' },
        description: 'List of associated tags'
      },
      assignee: {
        type: 'string',
        description: 'Person assigned to the task'
      }
    },
    required: ['title'],
    additionalProperties: false
  }
};

export async function handleCreateTask(args: any, db: TaskDatabase) {
  try {
    // Argument validation
    const validatedArgs = CreateTaskSchema.parse(args);

    // Task creation
    const taskId = await db.createTask(validatedArgs);

    return {
      content: [{
        type: 'text',
        text: 'Task created successfully'
      }],
      task_id: taskId,
      created_at: new Date().toISOString(),
      status: 'pending'
    };
  } catch (error) {
    if (error instanceof Error) {
      throw new McpError(ErrorCode.INVALID_PARAMS, `Validation error: ${error.message}`);
    }
    throw new McpError(ErrorCode.INTERNAL_ERROR, 'Internal error during creation');
  }
}

Task Update (`src/tools/update-task.ts`)

import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';
import { UpdateTaskSchema } from '../types/task.js';
import { McpError, ErrorCode } from '../utils/errors.js';

export const updateTaskTool: Tool = {
  name: 'update_task',
  description: 'Update an existing task',
  inputSchema: {
    type: 'object',
    properties: {
      task_id: {
        type: 'string',
        description: 'Task identifier to modify'
      },
      title: {
        type: 'string',
        minLength: 1,
        maxLength: 200
      },
      description: { type: 'string' },
      priority: {
        type: 'string',
        enum: ['low', 'medium', 'high', 'urgent']
      },
      status: {
        type: 'string',
        enum: ['pending', 'in_progress', 'completed', 'cancelled']
      },
      due_date: {
        type: 'string',
        format: 'date-time'
      },
      tags: {
        type: 'array',
        items: { type: 'string' }
      },
      assignee: { type: 'string' }
    },
    required: ['task_id'],
    additionalProperties: false
  }
};

export async function handleUpdateTask(args: any, db: TaskDatabase) {
  try {
    const { task_id, ...updates } = args;

    // Check if task exists
    const existingTask = await db.getTask(task_id);
    if (!existingTask) {
      throw new McpError(ErrorCode.TASK_NOT_FOUND, `Task ${task_id} not found`);
    }

    // Check if task is already completed
    if (existingTask.status === 'completed') {
      throw new McpError(ErrorCode.TASK_ALREADY_COMPLETED, 'Cannot modify a completed task');
    }

    // Update
    const success = await db.updateTask(task_id, updates);

    if (success) {
      const updatedTask = await db.getTask(task_id);
      return {
        content: [{
          type: 'text',
          text: 'Task updated successfully'
        }],
        task: updatedTask
      };
    } else {
      throw new McpError(ErrorCode.INTERNAL_ERROR, 'Update failed');
    }
  } catch (error) {
    if (error instanceof McpError) throw error;
    throw new McpError(ErrorCode.INTERNAL_ERROR, 'Internal error during update');
  }
}

Task Completion (`src/tools/complete-task.ts`)

import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';
import { CompleteTaskSchema } from '../types/task.js';
import { McpError, ErrorCode } from '../utils/errors.js';

export const completeTaskTool: Tool = {
  name: 'complete_task',
  description: 'Mark a task as completed',
  inputSchema: {
    type: 'object',
    properties: {
      task_id: {
        type: 'string',
        description: 'Task identifier to complete'
      },
      completion_notes: {
        type: 'string',
        description: 'Notes about task completion'
      },
      time_spent: {
        type: 'number',
        minimum: 0,
        description: 'Time spent in minutes'
      }
    },
    required: ['task_id'],
    additionalProperties: false
  }
};

export async function handleCompleteTask(args: any, db: TaskDatabase) {
  try {
    const validatedArgs = CompleteTaskSchema.parse(args);

    // Check if task exists
    const existingTask = await db.getTask(validatedArgs.task_id);
    if (!existingTask) {
      throw new McpError(ErrorCode.TASK_NOT_FOUND, `Task ${validatedArgs.task_id} not found`);
    }

    // Check if task is already completed
    if (existingTask.status === 'completed') {
      throw new McpError(ErrorCode.TASK_ALREADY_COMPLETED, 'Task already completed');
    }

    // Complete the task
    const success = await db.completeTask(
      validatedArgs.task_id,
      validatedArgs.completion_notes,
      validatedArgs.time_spent
    );

    if (success) {
      return {
        content: [{
          type: 'text',
          text: 'Task completed successfully'
        }],
        completed_at: new Date().toISOString(),
        total_time: validatedArgs.time_spent
      };
    } else {
      throw new McpError(ErrorCode.INTERNAL_ERROR, 'Completion failed');
    }
  } catch (error) {
    if (error instanceof McpError) throw error;
    throw new McpError(ErrorCode.INTERNAL_ERROR, 'Internal error during completion');
  }
}

Task Deletion (`src/tools/delete-task.ts`)

import { Tool } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';
import { McpError, ErrorCode } from '../utils/errors.js';

export const deleteTaskTool: Tool = {
  name: 'delete_task',
  description: 'Permanently delete a task',
  inputSchema: {
    type: 'object',
    properties: {
      task_id: {
        type: 'string',
        description: 'Task identifier to delete'
      },
      confirm: {
        type: 'boolean',
        description: 'Deletion confirmation (security)',
        default: false
      }
    },
    required: ['task_id', 'confirm'],
    additionalProperties: false
  }
};

export async function handleDeleteTask(args: any, db: TaskDatabase) {
  try {
    const { task_id, confirm } = args;

    // Check confirmation
    if (!confirm) {
      throw new McpError(ErrorCode.INVALID_PARAMS, 'Confirmation required to delete a task');
    }

    // Check if task exists
    const existingTask = await db.getTask(task_id);
    if (!existingTask) {
      throw new McpError(ErrorCode.TASK_NOT_FOUND, `Task ${task_id} not found`);
    }

    // Save information before deletion
    const taskInfo = {
      id: existingTask.id,
      title: existingTask.title,
      status: existingTask.status
    };

    // Delete the task
    const success = await db.deleteTask(task_id);

    if (success) {
      return {
        content: [{
          type: 'text',
          text: `Task "${taskInfo.title}" deleted successfully`
        }],
        deleted_task: taskInfo,
        deleted_at: new Date().toISOString()
      };
    } else {
      throw new McpError(ErrorCode.INTERNAL_ERROR, 'Deletion failed');
    }
  } catch (error) {
    if (error instanceof McpError) throw error;
    throw new McpError(ErrorCode.INTERNAL_ERROR, 'Internal error during deletion');
  }
}

Tools Export (`src/tools/index.ts`)

import { createTaskTool, handleCreateTask } from './create-task.js';
import { updateTaskTool, handleUpdateTask } from './update-task.js';
import { completeTaskTool, handleCompleteTask } from './complete-task.js';
import { deleteTaskTool, handleDeleteTask } from './delete-task.js';

export const tools = [
  createTaskTool,
  updateTaskTool,
  completeTaskTool,
  deleteTaskTool
];

export const toolHandlers = {
  create_task: handleCreateTask,
  update_task: handleUpdateTask,
  complete_task: handleCompleteTask,
  delete_task: handleDeleteTask
};

7. Endpoints: Resources

Task List (`src/resources/task-list.ts`)

import { Resource } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';

export const taskListResource: Resource = {
  uri: 'task://list',
  name: 'Task List',
  description: 'All active tasks in the system',
  mimeType: 'application/json'
};

export async function handleTaskListResource(db: TaskDatabase) {
  try {
    const tasks = await db.getAllTasks();

    return {
      contents: [{
        uri: 'task://list',
        mimeType: 'application/json',
        text: JSON.stringify({
          tasks: tasks.map(task => ({
            id: task.id,
            title: task.title,
            status: task.status,
            priority: task.priority,
            assignee: task.assignee,
            due_date: task.due_date,
            created_at: task.created_at
          })),
          total: tasks.length
        }, null, 2)
      }]
    };
  } catch (error) {
    throw new Error('Error retrieving tasks');
  }
}

Statistics (`src/resources/task-stats.ts`)

import { Resource } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';

export const taskStatsResource: Resource = {
  uri: 'task://stats',
  name: 'Task Statistics',
  description: 'Global statistics of the task system',
  mimeType: 'application/json'
};

export async function handleTaskStatsResource(db: TaskDatabase) {
  try {
    const stats = await db.getStats();
    const tasks = await db.getAllTasks();

    // Calculate overdue tasks
    const now = new Date();
    const overdueTasks = tasks.filter(task => 
      task.due_date && 
      new Date(task.due_date) < now && 
      task.status !== 'completed'
    ).length;

    // Calculate completion rate
    const completionRate = stats.total_tasks > 0 
      ? (stats.completed / stats.total_tasks) * 100 
      : 0;

    const statsData = {
      total_tasks: stats.total_tasks,
      by_status: {
        pending: stats.pending,
        in_progress: stats.in_progress,
        completed: stats.completed,
        cancelled: stats.cancelled
      },
      by_priority: {
        urgent: stats.urgent,
        high: stats.high,
        medium: stats.medium,
        low: stats.low
      },
      overdue_tasks: overdueTasks,
      completion_rate: Math.round(completionRate * 10) / 10,
      average_completion_time: stats.avg_completion_time || 0
    };

    return {
      contents: [{
        uri: 'task://stats',
        mimeType: 'application/json',
        text: JSON.stringify(statsData, null, 2)
      }]
    };
  } catch (error) {
    throw new Error('Error retrieving statistics');
  }
}

Task Detail (`src/resources/task-detail.ts`)

import { Resource } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';
import { McpError, ErrorCode } from '../utils/errors.js';

export const taskDetailResource: Resource = {
  uri: 'task://detail/{id}',
  name: 'Task Detail',
  description: 'Detailed information of a specific task',
  mimeType: 'application/json'
};

export async function handleTaskDetailResource(uri: string, db: TaskDatabase) {
  try {
    // Extract ID from URI
    const match = uri.match(/task:\/\/detail\/(.+)/);
    if (!match) {
      throw new McpError(ErrorCode.INVALID_PARAMS, 'Invalid URI for task detail');
    }

    const taskId = match[1];
    if (!taskId) {
      throw new McpError(ErrorCode.INVALID_PARAMS, 'Missing task ID in URI');
    }

    const task = await db.getTask(taskId);

    if (!task) {
      throw new McpError(ErrorCode.TASK_NOT_FOUND, `Task ${taskId} not found`);
    }

    return {
      contents: [{
        uri: uri,
        mimeType: 'application/json',
        text: JSON.stringify(task, null, 2)
      }]
    };
  } catch (error) {
    if (error instanceof McpError) throw error;
    throw new Error('Error retrieving task detail');
  }
}

Resources Export (`src/resources/index.ts`)

import { taskListResource, handleTaskListResource } from './task-list.js';
import { taskStatsResource, handleTaskStatsResource } from './task-stats.js';
import { taskDetailResource, handleTaskDetailResource } from './task-detail.js';

export const resources = [
  taskListResource,
  taskStatsResource,
  taskDetailResource
];

export const resourceHandlers = {
  taskList: handleTaskListResource,
  taskStats: handleTaskStatsResource,
  taskDetail: handleTaskDetailResource
};

8. Endpoints: Prompts

Weekly Review (`src/prompts/weekly-review.ts`)

import { Prompt } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';

export const weeklyReviewPrompt: Prompt = {
  name: 'weekly_review',
  description: 'Generate a weekly review report',
  arguments: [
    {
      name: 'week_number',
      description: 'Week number to analyze',
      required: false
    },
    {
      name: 'team',
      description: 'Filter by specific team',
      required: false
    }
  ]
};

export async function handleWeeklyReviewPrompt(args: any, db: TaskDatabase) {
  try {
    const weekNumber = args.week_number || getCurrentWeekNumber();
    const team = args.team || 'all teams';

    // Retrieve data
    const tasks = await db.getAllTasks();
    const stats = await db.getStats();

    // Filter by team if specified
    const filteredTasks = args.team 
      ? tasks.filter(task => task.assignee?.includes(args.team))
      : tasks;

    const description = `Weekly review ${team} - Week ${weekNumber}`;

    return {
      description,
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `Generate a detailed review for week ${weekNumber} of ${team} with:

📊 **Available Data:**
- Total tasks: ${filteredTasks.length}
- Completed tasks: ${filteredTasks.filter(t => t.status === 'completed').length}
- In progress tasks: ${filteredTasks.filter(t => t.status === 'in_progress').length}
- Pending tasks: ${filteredTasks.filter(t => t.status === 'pending').length}

📋 **Requested Analysis:**
1. **Tasks completed this week**
2. **Tasks in progress with their progression**
3. **Identified blockers and solutions**
4. **Performance metrics**
5. **Recommendations for next week**

Use a structured format with emojis and clear sections.`
          }
        },
        {
          role: 'assistant',
          content: {
            type: 'text',
            text: `I will analyze the data for week ${weekNumber} for ${team} and generate a comprehensive report...`
          }
        }
      ]
    };
  } catch (error) {
    throw new Error('Error generating weekly review prompt');
  }
}

function getCurrentWeekNumber(): number {
  const now = new Date();
  const start = new Date(now.getFullYear(), 0, 1);
  const days = Math.floor((now.getTime() - start.getTime()) / (24 * 60 * 60 * 1000));
  return Math.ceil((days + start.getDay() + 1) / 7);
}

Sprint Planning (`src/prompts/sprint-planning.ts`)

import { Prompt } from '@modelcontextprotocol/sdk/types.js';
import { TaskDatabase } from '../database/db.js';

export const sprintPlanningPrompt: Prompt = {
  name: 'sprint_planning',
  description: 'Assist with sprint planning with velocity analysis',
  arguments: [
    {
      name: 'sprint_duration',
      description: 'Sprint duration in days (default: 14)',
      required: false
    },
    {
      name: 'team_capacity',
      description: 'Team capacity in person-days',
      required: false
    }
  ]
};

export async function handleSprintPlanningPrompt(args: any, db: TaskDatabase) {
  try {
    const sprintDuration = args.sprint_duration || 14;
    const teamCapacity = args.team_capacity;

    const tasks = await db.getAllTasks();
    const stats = await db.getStats();

    // Analyze priority tasks
    const highPriorityTasks = tasks.filter(t => 
      ['urgent', 'high'].includes(t.priority) && 
      t.status === 'pending'
    );

    // Calculate average velocity
    const completedTasks = tasks.filter(t => t.status === 'completed');
    const avgCompletionTime = stats.avg_completion_time || 0;

    return {
      description: `Sprint planning - ${sprintDuration} days`,
      messages: [
        {
          role: 'user',
          content: {
            type: 'text',
            text: `Help me plan the next sprint with this data:

🏃‍♂️ **Sprint Parameters:**
- Duration: ${sprintDuration} days
- Team capacity: ${teamCapacity || 'not specified'}

📊 **Task Analysis:**
- Priority tasks (urgent/high): ${highPriorityTasks.length}
- Pending tasks: ${tasks.filter(t => t.status === 'pending').length}
- Average completion time: ${avgCompletionTime} minutes
- Current completion rate: ${((stats.completed / stats.total_tasks) * 100).toFixed(1)}%

🎯 **Request:**
1. **Suggest optimal task distribution**
2. **Identify critical dependencies**
3. **Propose realistic timeline**
4. **Anticipate potential risks**
5. **Recommend tracking metrics**

Generate a detailed plan with clear milestones.`
          }
        },
        {
          role: 'assistant',
          content: {
            type: 'text',
            text: `Let's analyze the data to create an optimal sprint plan...`
          }
        }
      ]
    };
  } catch (error) {
    throw new Error('Error generating sprint planning prompt');
  }
}

Prompts Export (`src/prompts/index.ts`)

import { weeklyReviewPrompt, handleWeeklyReviewPrompt } from './weekly-review.js';
import { sprintPlanningPrompt, handleSprintPlanningPrompt } from './sprint-planning.js';

export const prompts = [
  weeklyReviewPrompt,
  sprintPlanningPrompt
];

export const promptHandlers = {
  weekly_review: handleWeeklyReviewPrompt,
  sprint_planning: handleSprintPlanningPrompt
};

9. Error Handling

Error Codes (`src/utils/errors.ts`)

export enum ErrorCode {
  // Standard JSON-RPC errors
  PARSE_ERROR = -32700,
  INVALID_REQUEST = -32600,
  METHOD_NOT_FOUND = -32601,
  INVALID_PARAMS = -32602,
  INTERNAL_ERROR = -32603,

  // Task Manager specific errors
  TASK_NOT_FOUND = -32000,
  PERMISSION_DENIED = -32001,
  TASK_ALREADY_COMPLETED = -32002,
  INVALID_DATE_FORMAT = -32003,
  QUOTA_EXCEEDED = -32004
}

export class McpError extends Error {
  constructor(
    public code: ErrorCode,
    message: string,
    public data?: any
  ) {
    super(message);
    this.name = 'McpError';
  }

  toJsonRpc() {
    return {
      code: this.code,
      message: this.message,
      ...(this.data && { data: this.data })
    };
  }
}

export function getErrorMessage(code: ErrorCode): string {
  switch (code) {
    case ErrorCode.TASK_NOT_FOUND:
      return 'Task not found';
    case ErrorCode.PERMISSION_DENIED:
      return 'Permission denied';
    case ErrorCode.TASK_ALREADY_COMPLETED:
      return 'Task already completed';
    case ErrorCode.INVALID_DATE_FORMAT:
      return 'Invalid date format';
    case ErrorCode.QUOTA_EXCEEDED:
      return 'Quota exceeded';
    default:
      return 'Internal error';
  }
}

10. Main Server

Hybrid HTTP/STDIO Architecture

The TaskManagerServer supports two communication modes:

1. HTTP Mode (Recommended)

private createHttpServer() {
  return http.createServer(async (req, res) => {
    // CORS configuration for web integration
    res.setHeader('Access-Control-Allow-Origin', '*');
    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');

    // Handle OPTIONS requests (CORS preflight)
    if (req.method === 'OPTIONS') {
      res.writeHead(200);
      res.end();
      return;
    }

    // Health check endpoint
    if (req.method === 'GET' && req.url === '/health') {
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ 
        status: 'healthy', 
        timestamp: new Date().toISOString() 
      }));
      return;
    }

    // Main MCP endpoint
    if (req.method === 'POST' && req.url === '/mcp') {
      // JSON-RPC request processing
      // ...
    }
  });
}

HTTP Mode Advantages:

✅ Simplified integration with Claude Desktop
✅ Easy debugging with curl, Postman, etc.
✅ Health check for monitoring
✅ CORS enabled for web applications
✅ Scalability for multiple clients

2. STDIO Mode (Legacy)

if (process.env.MCP_TRANSPORT === 'stdio') {
  const transport = new StdioServerTransport();
  await this.server.connect(transport);
  console.error('Task Manager MCP Server started (stdio)');
}

MCP Request Handling

The server implements a JSON-RPC translation layer:

private async handleMcpRequest(request: any) {
  const { method, params } = request;

  switch (method) {
    case 'initialize':
      return {
        jsonrpc: '2.0',
        id: request.id,
        result: {
          protocolVersion: '1.0',
          serverInfo: { name: 'task-manager-server', version: '1.0.0' },
          capabilities: { tools: {}, resources: {}, prompts: {} }
        }
      };

    case 'tools/list':
      return { jsonrpc: '2.0', id: request.id, result: { tools } };

    case 'tools/call':
      // Validation and tool execution
      const { name, arguments: args } = params;
      if (!toolHandlers[name as keyof typeof toolHandlers]) {
        throw new McpError(ErrorCode.METHOD_NOT_FOUND, `Tool ${name} not found`);
      }
      const result = await toolHandlers[name as keyof typeof toolHandlers](args, this.database);
      return { jsonrpc: '2.0', id: request.id, result };

    // Other methods...
  }
}

Centralized Error Handling

try {
  const request = JSON.parse(body);
  const response = await this.handleMcpRequest(request);

  res.writeHead(200, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify(response));
} catch (error) {
  res.writeHead(500, { 'Content-Type': 'application/json' });
  res.end(JSON.stringify({ 
    error: 'Internal server error', 
    message: error instanceof Error ? error.message : 'Unknown error' 
  }));
}

Main Entry Point (`src/server.ts`)

import { Server } from '@modelcontextprotocol/sdk/server/index.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { 
  ListToolsRequestSchema,
  CallToolRequestSchema,
  ListResourcesRequestSchema,
  ReadResourceRequestSchema,
  ListPromptsRequestSchema,
  GetPromptRequestSchema
} from '@modelcontextprotocol/sdk/types.js';
import * as http from 'http';
import { TaskDatabase } from './database/db.js';
import { tools, toolHandlers } from './tools/index.js';
import { resources, resourceHandlers } from './resources/index.js';
import { prompts, promptHandlers } from './prompts/index.js';
import { McpError, ErrorCode } from './utils/errors.js';

class TaskManagerServer {
  private server: Server;
  private database: TaskDatabase;
  private httpServer?: http.Server;

  constructor() {
    this.database = new TaskDatabase();
    this.server = new Server(
      {
        name: 'task-manager-server',
        version: '1.0.0'
      },
      {
        capabilities: {
          tools: {},
          resources: {},
          prompts: {}
        }
      }
    );

    this.setupHandlers();
  }

  private setupHandlers() {
    // Handler for tools with MCP schemas
    this.server.setRequestHandler(ListToolsRequestSchema, async () => ({
      tools
    }));

    this.server.setRequestHandler(CallToolRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;

      if (!toolHandlers[name as keyof typeof toolHandlers]) {
        throw new McpError(ErrorCode.METHOD_NOT_FOUND, `Tool ${name} not found`);
      }

      try {
        return await toolHandlers[name as keyof typeof toolHandlers](args, this.database);
      } catch (error) {
        if (error instanceof McpError) {
          throw error;
        }
        throw new McpError(ErrorCode.INTERNAL_ERROR, 'Internal server error');
      }
    });

    // Handler for resources
    this.server.setRequestHandler(ListResourcesRequestSchema, async () => ({
      resources
    }));

    this.server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
      const { uri } = request.params;

      // Route to appropriate handler based on URI
      if (uri === 'task://list') {
        return await resourceHandlers.taskList(this.database);
      } else if (uri === 'task://stats') {
        return await resourceHandlers.taskStats(this.database);
      } else if (uri.startsWith('task://detail/')) {
        return await resourceHandlers.taskDetail(uri, this.database);
      } else {
        throw new McpError(ErrorCode.METHOD_NOT_FOUND, `Resource ${uri} not found`);
      }
    });

    // Handler for prompts
    this.server.setRequestHandler(ListPromptsRequestSchema, async () => ({
      prompts
    }));

    this.server.setRequestHandler(GetPromptRequestSchema, async (request) => {
      const { name, arguments: args } = request.params;

      if (!promptHandlers[name as keyof typeof promptHandlers]) {
        throw new McpError(ErrorCode.METHOD_NOT_FOUND, `Prompt ${name} not found`);
      }

      return await promptHandlers[name as keyof typeof promptHandlers](args || {}, this.database);
    });
  }

  async start() {
    const port = process.env.PORT || 3000;

    if (process.env.MCP_TRANSPORT === 'stdio') {
      const transport = new StdioServerTransport();
      await this.server.connect(transport);
      console.error('Task Manager MCP Server started (stdio)');
    } else {
      this.httpServer = this.createHttpServer();
      this.httpServer.listen(port, () => {
        console.error(`Task Manager MCP Server started on port ${port} (HTTP)`);
      });
    }
  }

  async stop() {
    if (this.httpServer) {
      this.httpServer.close();
    }
  }
}

// Start the server
const server = new TaskManagerServer();
server.start().catch(console.error);

Advanced Error Handling Pattern

// src/utils/error-handling.ts
export class TaskManagerError extends Error {
  constructor(
    public code: string,
    message: string,
    public details?: any
  ) {
    super(message);
    this.name = 'TaskManagerError';
  }
}

export function createErrorResponse(error: unknown, id: number | string) {
  if (error instanceof TaskManagerError) {
    return {
      jsonrpc: '2.0',
      id,
      error: {
        code: -32000,
        message: error.message,
        data: { code: error.code, details: error.details }
      }
    };
  }

  return {
    jsonrpc: '2.0',
    id,
    error: {
      code: -32603,
      message: 'Internal error',
      data: { originalError: error instanceof Error ? error.message : String(error) }
    }
  };
}

Resource Caching Pattern

// src/utils/cache.ts
export class ResourceCache {
  private cache = new Map<string, { data: any; timestamp: number; ttl: number }>();

  set(key: string, data: any, ttlMs: number = 60000) {
    this.cache.set(key, {
      data,
      timestamp: Date.now(),
      ttl: ttlMs
    });
  }

  get(key: string): any | null {
    const entry = this.cache.get(key);
    if (!entry) return null;

    if (Date.now() - entry.timestamp > entry.ttl) {
      this.cache.delete(key);
      return null;
    }

    return entry.data;
  }

  clear() {
    this.cache.clear();
  }
}

// Usage in resources
export async function handleTaskListResource(database: TaskDatabase): Promise<Resource> {
  const cacheKey = 'task-list';
  const cached = resourceCache.get(cacheKey);

  if (cached) {
    return {
      contents: [{
        type: 'text',
        text: cached
      }]
    };
  }

  const tasks = await database.getAllTasks();
  const result = JSON.stringify({ tasks, total: tasks.length, cached: false }, null, 2);

  resourceCache.set(cacheKey, result, 30000); // 30 seconds TTL

  return {
    contents: [{
      type: 'text',
      text: result
    }]
  };
}

Applied patterns:

✅ Promisification of SQLite callbacks
✅ Data transformation (ID prefixing)
✅ Explicit null handling
✅ Type safety with TypeScript

11. Code Organization and Patterns

Structuring Pattern

The project follows a clear modular architecture:

src/
├── server.ts          # Entry point and orchestration
├── database/          # Persistence layer
│   ├── db.ts         # Database logic
│   └── schema.sql    # Table structure
├── tools/            # MCP Actions (Create, Update, Delete)
├── resources/        # MCP Data (Read-only)
├── prompts/          # LLM interaction templates
├── types/            # TypeScript schemas and types
└── utils/            # Cross-cutting utilities

Export Pattern

Each module exposes a consistent pattern:

// tools/index.ts
export const tools = [createTaskTool, updateTaskTool, ...];
export const toolHandlers = {
  create_task: handleCreateTask,
  // ...
};

Benefits:

✅ Centralized imports from main server
✅ Automatic discovery of new tools
✅ Type safety with object keys
✅ Simplified maintenance

Validation Pattern

Layered validation with Zod:

export async function handleCreateTask(args: any, db: TaskDatabase) {
  try {
    // 1. Schema validation
    const validatedArgs = CreateTaskSchema.parse(args);

    // 2. Business logic validation
    if (validatedArgs.due_date && new Date(validatedArgs.due_date) < new Date()) {
      throw new McpError(ErrorCode.INVALID_PARAMS, 'Due date cannot be in the past');
    }

    // 3. Database operation
    const task = await db.createTask(validatedArgs);

    return {
      task_id: `task-${task.id}`,
      status: task.status,
      created_at: task.created_at
    };
  } catch (error) {
    if (error instanceof z.ZodError) {
      throw new McpError(ErrorCode.INVALID_PARAMS, `Validation failed: ${error.message}`);
    }
    throw error;
  }
}

Database Pattern

Encapsulation with promisification:

async getTask(id: string): Promise<Task | null> {
  const sql = 'SELECT * FROM tasks WHERE id = ?';
  return new Promise((resolve, reject) => {
    this.db.get(sql, [id.replace('task-', '')], (err, row) => {
      if (err) reject(err);
      else if (!row) resolve(null);
      else resolve({
        ...row,
        id: `task-${row.id}`,
        tags: row.tags ? JSON.parse(row.tags) : []
      });
    });
  });
}

Applied patterns:

✅ Promisification of SQLite callbacks
✅ Data transformation (ID prefixing)
✅ Explicit null handling
✅ Type safety with TypeScript

12. Testing and Validation

Jest Configuration (`jest.config.js`)

module.exports = {
  preset: 'ts-jest',
  testEnvironment: 'node',
  roots: ['<rootDir>/src', '<rootDir>/tests'],
  testMatch: ['**/__tests__/**/*.ts', '**/?(*.)+(spec|test).ts'],
  transform: {
    '^.+\\.ts$': 'ts-jest',
  },
  collectCoverageFrom: [
    'src/**/*.ts',
    '!src/**/*.d.ts',
  ],
  moduleFileExtensions: ['ts', 'js', 'json'],
};

Integration Tests (`tests/integration.test.ts`)

import { TaskDatabase } from '../src/database/db';
import { handleCreateTask } from '../src/tools/create-task';
import { handleTaskListResource } from '../src/resources/task-list';

describe('Task Manager Integration Tests', () => {
  let db: TaskDatabase;

  beforeEach(() => {
    // Use in-memory database for tests
    db = new TaskDatabase(':memory:');
  });

  test('Creating and retrieving a task', async () => {
    // Create a task
    const result = await handleCreateTask({
      title: 'Test Task',
      description: 'Task for testing',
      priority: 'high',
      tags: ['test', 'automation']
    }, db);

    expect(result.task_id).toBeDefined();
    expect(result.status).toBe('pending');

    // Retrieve task list
    const listResult = await handleTaskListResource(db);
    const tasks = JSON.parse(listResult.contents[0].text);

    expect(tasks.tasks).toHaveLength(1);
    expect(tasks.tasks[0].title).toBe('Test Task');
    expect(tasks.tasks[0].priority).toBe('high');
  });

  test('Error handling - non-existent task', async () => {
    const task = await db.getTask('task-999');
    expect(task).toBeNull();
  });
});

Manual Test Script (`scripts/test-mcp.js`)

#!/usr/bin/env node

const { spawn } = require('child_process');

function testMcpServer() {
  console.log('🧪 Testing MCP Task Manager server...\n');

  const server = spawn('npm', ['run', 'dev']);

  // Initialization test
  const initMessage = {
    jsonrpc: '2.0',
    id: 1,
    method: 'initialize',
    params: {
      protocolVersion: '1.0',
      clientInfo: { name: 'test-client', version: '1.0.0' }
    }
  };

  server.stdin.write(JSON.stringify(initMessage) + '\n');

  server.stdout.on('data', (data) => {
    try {
      const response = JSON.parse(data.toString());
      console.log('✅ Response received:', response);
    } catch (error) {
      console.log('📝 Output:', data.toString());
    }
  });

  server.stderr.on('data', (data) => {
    console.error('❌ Error:', data.toString());
  });

  // Stop after 5 seconds
  setTimeout(() => {
    server.kill();
    console.log('\n🏁 Test completed');
  }, 5000);
}

testMcpServer();

13. Docker Deployment

Multi-stage Dockerfile

Create an optimized Dockerfile with multi-stage build:

# Task Manager MCP Server Dockerfile
# Multi-stage build for optimized production image

# Stage 1: Build stage
FROM node:20-alpine AS builder

# Set working directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install dependencies (including dev dependencies for building)
RUN npm ci

# Copy source code
COPY src/ ./src/
COPY tsconfig.json ./

# Build the application
RUN npm run build

# Stage 2: Production stage
FROM node:20-alpine AS production

# Install dumb-init for proper signal handling
RUN apk add --no-cache dumb-init

# Create app user for security
RUN addgroup -g 1001 -S mcpuser && \
    adduser -S mcpuser -u 1001

# Set working directory
WORKDIR /app

# Copy package files
COPY package*.json ./

# Install only production dependencies
RUN npm ci --only=production && \
    npm cache clean --force

# Copy built application from builder stage
COPY --from=builder /app/dist ./dist

# Create data directory for SQLite database
RUN mkdir -p /app/data && \
    chown -R mcpuser:mcpuser /app

USER mcpuser

# Expose the port for MCP server (HTTP mode by default)
EXPOSE 3000

# Set environment variables for HTTP mode
ENV MCP_TRANSPORT=http
ENV PORT=3000

# Health check for HTTP MCP server
HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
    CMD wget --no-verbose --tries=1 --spider http://localhost:3000/health || exit 1

# Use dumb-init to handle signals properly
ENTRYPOINT ["dumb-init", "--"]

# Start the MCP server
CMD ["node", "dist/server.js"]

.dockerignore File

The .dockerignore file optimizes Docker build context by excluding unnecessary files:

node_modules
npm-debug.log
.git
.gitignore
README.md
.env
.env.local
.env.development.local
.env.test.local
.env.production.local
dist
coverage
*.md
.nyc_output
tasks.db

Why these exclusions?

node_modules/: Will be installed in the container
dist/: Will be generated during build
tasks.db: Local development database
.env* files: Prevents accidental inclusion of secrets
*.md: Documentation not needed in production

Docker Scripts in package.json

{
  "scripts": {
    "build": "tsc && mkdir -p dist/database && cp src/database/schema.sql dist/database/",
    "start": "node dist/server.js",
    "dev": "nodemon src/server.ts",
    "test": "jest",
    "docker:build": "docker build -t task-manager-mcp-server .",
    "docker:run": "docker run -d --name task-manager-mcp-server -p 3000:3000 task-manager-mcp-server",
    "docker:stop": "docker stop task-manager-mcp-server && docker rm task-manager-mcp-server",
    "docker:logs": "docker logs task-manager-mcp-server"
  }
}

HTTP API Endpoints

The server exposes the following endpoints:

Health Check

GET /health

Returns the server health status.

MCP Communication

POST /mcp
Content-Type: application/json

Example call to list tools:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

Example call to create a task:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_task",
      "arguments": {
        "title": "New task",
        "description": "Task description",
        "priority": "high"
      }
    }
  }'

Deployment Commands

# Build Docker image
npm run docker:build

# Launch container
npm run docker:run

# View logs
npm run docker:logs

# Stop container
npm run docker:stop

# Build and run in one command
npm run docker:build && npm run docker:run

Production Configuration

Environment Variables

The .env.example file defines configuration variables:

NODE_ENV=production
MCP_TRANSPORT=http
PORT=3000
DB_PATH=/app/data/tasks.db
LOG_LEVEL=info

Variable descriptions:

NODE_ENV: Runtime environment (development/production)
MCP_TRANSPORT: Transport mode (http/stdio)
PORT: HTTP server listening port
DB_PATH: Path to SQLite database
LOG_LEVEL: Logging level (debug/info/warn/error)

Usage:

# Copy and customize
cp .env.example .env.production

# Use with Docker
docker run --env-file .env.production task-manager-mcp-server

Transport Mode

The server supports two modes:

HTTP (default): Communication via REST endpoints
STDIO: Communication via stdin/stdout (for direct integration)

Volume for Data Persistence

# Launch with persistent volume
docker run -d \
  --name task-manager-mcp-server \
  -p 3000:3000 \
  -v task-manager-data:/app/data \
  task-manager-mcp-server

Docker Compose (optional)

The docker-compose.yml file simplifies deployment and container management:

version: '3.8'

services:
  task-manager-mcp:
    build: .
    container_name: task-manager-mcp-server
    ports:
      - "3000:3000"
    volumes:
      - task-manager-data:/app/data
    environment:
      - NODE_ENV=production
      - MCP_TRANSPORT=http
      - PORT=3000
      - DB_PATH=/app/data/tasks.db
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://localhost:3000/health"]
      interval: 30s
      timeout: 10s
      retries: 3

volumes:
  task-manager-data:
    driver: local

Docker Compose advantages:

Data persistence: Named volume for SQLite database
Automatic restart: restart: unless-stopped
HTTP health check: Automatic monitoring via /health
Centralized configuration: Environment variables defined
Simplified management: docker-compose up -d to start everything

Claude Desktop Integration

HTTP Configuration (recommended)

Modify Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "task-mcp": {
      "type": "http",
      "url": "http://localhost:3000"
    }
  }
}

Docker Configuration

To use the server via Docker:

{
  "mcpServers": {
    "task-mcp": {
      "type": "http",
      "url": "http://localhost:3000"
    }
  }
}

Then launch the container:

npm run docker:build
npm run docker:run

STDIO Configuration (alternative)

If you prefer to use stdio communication:

{
  "mcpServers": {
    "task-manager": {
      "command": "node",
      "args": ["/path/to/mcp-task-manager/dist/server.js"],
      "env": {
        "NODE_ENV": "production",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Monitoring and Maintenance

Monitoring with Health Check

The /health endpoint provides status information:

# Simple check
curl http://localhost:3000/health

# Response
{
  "status": "healthy",
  "timestamp": "2025-11-05T16:25:58.230Z"
}

Container Logs

# View logs in real-time
docker logs -f task-manager-mcp-server
npm run docker:logs

# View last lines
docker logs --tail 100 task-manager-mcp-server

Docker Metrics

# Container statistics
docker stats task-manager-mcp-server

# Complete inspection
docker inspect task-manager-mcp-server

Updates

# Method 1: NPM Scripts
npm run docker:stop
npm run docker:build
npm run docker:run

# Method 2: Docker Compose
docker-compose down
docker-compose build
docker-compose up -d

Data Backup

# Create volume backup
docker run --rm -v task-manager-data:/data -v $(pwd):/backup alpine tar czf /backup/tasks-backup.tar.gz -C /data .

# Restore backup
docker run --rm -v task-manager-data:/data -v $(pwd):/backup alpine tar xzf /backup/tasks-backup.tar.gz -C /data

Debug and Troubleshooting

# Access container
docker exec -it task-manager-mcp-server sh

# Check processes
docker exec task-manager-mcp-server ps aux

# Test connectivity
docker exec task-manager-mcp-server wget -qO- http://localhost:3000/health

14. Additional Resources

MCP Documentation

Development Tools

MCP Inspector - Debug tool
Postman MCP Collection - API tests

Possible Extensions

Authentication: JWT, OAuth 2.0
Webhooks: Real-time notifications
Integrations: Slack, Teams, GitHub Issues
Analytics: Advanced metrics, dashboards
REST API: Complementary HTTP interface

Practical Usage Examples

API Testing with curl

# 1. Start server
npm run docker:run

# 2. Check health
curl http://localhost:3000/health

# 3. List available tools
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# 4. Create a task
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "create_task",
      "arguments": {
        "title": "Implement authentication",
        "description": "Add JWT auth to MCP server",
        "priority": "high",
        "tags": ["security", "backend"],
        "assignee": "john.doe@example.com"
      }
    }
  }'

# 5. List tasks
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "resources/read",
    "params": {
      "uri": "task://list"
    }
  }'

# 6. View statistics
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "resources/read",
    "params": {
      "uri": "task://stats"
    }
  }'

Script Integration

#!/bin/bash
# create-task.sh - Script to create tasks via API

TITLE="$1"
DESCRIPTION="$2"
PRIORITY="${3:-medium}"

if [ -z "$TITLE" ]; then
  echo "Usage: $0 <title> [description] [priority]"
  exit 1
fi

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d "{
    \"jsonrpc\": \"2.0\",
    \"id\": 1,
    \"method\": \"tools/call\",
    \"params\": {
      \"name\": \"create_task\",
      \"arguments\": {
        \"title\": \"$TITLE\",
        \"description\": \"$DESCRIPTION\",
        \"priority\": \"$PRIORITY\"
      }
    }
  }" | jq '.'

Usage Examples

# Local development
npm run dev

# Build and test Docker image
npm run docker:build
npm run docker:run
npm run docker:logs

# With docker-compose
docker-compose up -d
docker-compose logs -f

# Production with persistent volume
docker run -d \
  --name task-manager-mcp-server \
  -v $(pwd)/data:/app/data \
  task-manager-mcp-server

🎯 Conclusion

This tutorial has guided you through creating a complete professional MCP Task Manager server. You now have:

✅ Complete MCP Architecture

4 Tools: Create, update, complete, delete tasks
3 Resources: List, statistics, task details
2 Prompts: Weekly review, sprint planning
Zod Validation: Type safety and robust validation

✅ Production-Ready Infrastructure

Hybrid HTTP/STDIO server with REST endpoints
SQLite database with optimized schema
Multi-stage Docker with non-root user
Health checks and integrated monitoring
CORS and error handling professional-grade

✅ Automated Deployment

NPM scripts for Docker (build, run, stop, logs)
Docker Compose with persistent volumes
Configurable environment variables
HTTP health checks for monitoring

✅ Claude Desktop Configuration

{
  "mcpServers": {
    "task-mcp": {
      "type": "http",
      "url": "http://localhost:3000"
    }
  }
}

🚀 Implemented Features

Tools (Actions)

create_task: Creation with complete validation
update_task: Modification with completed task protection
complete_task: Finalization with notes and time tracking
delete_task: Secure deletion with confirmation

Resources (Data)

task://list: Overview with metadata
task://stats: Dashboards and metrics
task://detail/{id}: Detailed information per task

Prompts (LLM Templates)

weekly_review: Weekly performance analysis
sprint_planning: Task planning and distribution

🔧 Extensibility

The modular architecture facilitates adding new features:

// New tool in src/tools/
export const archiveTaskTool: Tool = { /* ... */ };
export async function handleArchiveTask(args: any, db: TaskDatabase) { /* ... */ }

// New resource in src/resources/
export const taskCalendarResource: Resource = { /* ... */ };
export async function handleTaskCalendarResource(db: TaskDatabase) { /* ... */ }

// New prompt in src/prompts/
export const standupPrompt: Prompt = { /* ... */ };
export async function handleStandupPrompt(args: any, db: TaskDatabase) { /* ... */ }

🛠 Suggested Next Steps

Authentication and Authorization

   // JWT middleware to secure API
   import jwt from 'jsonwebtoken';

   const authMiddleware = (req, res, next) => {
     const token = req.headers.authorization?.split(' ')[1];
     if (!token || !jwt.verify(token, process.env.JWT_SECRET)) {
       return res.status(401).json({ error: 'Unauthorized' });
     }
     next();
   };

External Integrations

   // Webhooks for notifications
   export const webhookTool: Tool = {
     name: 'setup_webhook',
     description: 'Configure external notifications',
     // ...
   };

   // Calendar synchronization
   export const calendarSyncTool: Tool = {
     name: 'sync_calendar',
     description: 'Synchronize with Google Calendar/Outlook',
     // ...
   };

Web Interface (Optional)

   # React/Vue frontend for administration
   npm create vite@latest task-manager-ui -- --template react-ts
   cd task-manager-ui
   npm install axios @tanstack/react-query

Advanced Database

   // Migration to PostgreSQL for production
   import { Pool } from 'pg';

   export class PostgresTaskDatabase extends TaskDatabase {
     private pool: Pool;
     // ...
   }

Analytics and Monitoring

   // Prometheus metrics
   import prometheus from 'prom-client';

   const taskCreationCounter = new prometheus.Counter({
     name: 'tasks_created_total',
     help: 'Total number of tasks created'
   });

The MCP Task Manager server is now ready for production use and can serve as a solid foundation for more complex task management and productivity applications!

📚 Reference Documentation

Conventional Changelog support

Fairen — Mon, 31 Aug 2020 12:43:09 +0000

Photo by Daniel McCullough on Unsplash

Introduction

This post takes place in a series aiming to show how to build an Angular application from scratch.

We will see how to scaffold an enterprise-scale angular application with all the assets needed to easily develop and maintain it.

This post will show you how to add support for conventional changelog generation for your application on Gitlab and add it to your CI tool chain.

Our goal will be to automate changelog generation on the master branch and generate a tag with the changelog updated :

[Manual] Merge develop to master (by Pull Request).
[Manual] Tag master with prerelease-X.Y.Z (on Gitlab or with git cli).
[Automatic] CI triggered to update CHANGELOG.md and package.json + remove prerelease-X.Y.Z tag.
[Automatic] Push to master and add tag X.Y.Z, release ready.

Git Workflow

git checkout develop
git pull
# Retrieve the last develop version

git checkout -b feature/changelog
# Feature Branch creation

Make your repository Comitizen friendly

First, install the Commitizen cli tools:

npm install commitizen --save --save-exact --save-dev

Next, initialize your project to use the cz-conventional-changelog adapter by typing:

commitizen init cz-conventional-changelog --save-dev --save-exact

The above command does three things for you.

Installs the cz-conventional-changelog adapter npm module.
Saves it to package.json's dependencies or devDependencies.
Adds the config.commitizen key to the root of your package.json as shown here:

...
    "devDependencies": {
        ....
        "cz-conventional-changelog": "^3.1.0",
    }
...
    "config": {
        "commitizen": {
            "path": "./node_modules/cz-conventional-changelog"
        }
    }
...

This just tells Commitizen which adapter we actually want our contributors to use when they try to commit to this repo.

Use Comitizen

Add comitizen script to your package.json.

    "scripts": {
        ...
        "commit": "git-cz"
        ...
    },

Use npm run commit instead of git commit to enjoy!

When you're working in a Commitizen friendly repository, you'll be prompted to fill in any required fields and your commit messages will be formatted according to the standards you defined above.

Use Conventional Changelog

Install the Conventional Changelog CLI :

npm install conventional-changelog-cli --save --save-exact --save-dev

Update your package.json to include the followings script :

"scripts": {
    ...
    "init-changelog": "conventional-changelog -p angular -i CHANGELOG.md -s -r 0",
    "version": "conventional-changelog -p angular -i CHANGELOG.md -s && git add CHANGELOG.md"
    ...
}

Initialise the Changelog :

npm run init-changelog

Update your Node configuration

With the new npm script version, we will add some logic to the npm versionlife-cyle. The .npmrc file helps us to define some variables used when npm version is called.

Update your .npmrc file or create one with :

tag-version-prefix=""
message="chore(release): Version %s"

For more informations about the npm versionlife-cycle, refer to :
https://docs.npmjs.com/cli/version

Update your CI

Generate your GitLab access token

Go to your Gitlab, User Settings > Access Token and create a new token named GIT_ACCESS_TOKEN with the api scope checked.
Your new personal access token will be prompt, save it :

Now, go to your project Settings > CI/CD panel

Expand the Variable panel and click on Add Variable.

Name the variable GIT_ACCESS_TOKEN and past the personal access token saved from before, make sure protected and masked are unchecked.

The variable $GIT_ACCESS_TOKEN can now be accessed from your CI jobs and enable credential to write/read your git repository.

Update your CI jobs

Update your .gitlab-ci.yml to add a publish-version step.
This step will be triggered when tagging your code with prerelease-X.Y.Z tags (ie. prerelease-1.0.0).

It will :

Retrieve the current prerelease-X.Y.Z tag.
Update your application version (in package.json, package-lock.json and npm-shrinkwrap.json) to the X.Y.Z value.
Run the npm version command and commit and tag in git.
Under the hood, run the version script defined above to update the CHANGELOG.md and add it to the commit.
Remove the prerelease-X.Y.Z tag from your repository.
Add the updated file to git and push the modifications to the master branch and tag it as X.Y.Z.

image: node:latest

stages:
  - CodeQuality
  - Release

test:
  stage: CodeQuality
  script: 
    - npm ci
    - npm run ci:test

lint:
  stage: CodeQuality
  script:
    - npm ci
    - npm run ci:lint

publish-version:
  image: node:12.16.1
  stage: Release
  rules:
     - if: '$CI_COMMIT_TAG =~ /^prerelease-\d+.\d+.\d+/'
  before_script:
    - npm ci
    - npm config set unsafe-perm true
  script:
    - TAG_VERSION=`echo $CI_COMMIT_TAG | sed "s/.*prerelease-\([^ ]*\).*/\1/"`
    - git config --global user.name "$GITLAB_USER_NAME"
    - git config --global user.email "$GITLAB_USER_EMAIL"
    - git remote set-url origin "https://gitlab-ci-token:$GIT_ACCESS_TOKEN@$CI_SERVER_HOST/$CI_PROJECT_PATH.git"
    - git tag -d $CI_COMMIT_TAG
    - git push origin --delete $CI_COMMIT_TAG
    - npm version $TAG_VERSION
    - git push origin HEAD:master --tags

Push your modifications.

git add package.json package-lock.json .gitlab-ci.yml CHANGELOG.md .npmrc

# Use the magic !!
npm run commit

git push -u origin feature/changelog

Each time you tag your master branch with a tag prerelease-X.Y.Z, the CI will take care of updating your application version and generating the corresponding Changelog.

Setup a basic CI

Fairen — Wed, 29 Jul 2020 09:48:49 +0000

Photo by Daniel McCullough on Unsplash

Introduction

This post takes place in a series aiming to show how to build an angular application from scratch.

We will see how to scaffold an enterprise-scale angular application with all the assets needed to easily develop and maintain it.

This post will show you how to setup a basic CI toolchain (test and lint your code) for your application on Gitlab.

Git Workflow

git checkout master
git pull
# Retrieve the last master version

git checkout -b develop
# Branch develop creation

Setup tests scripts

We will need to adapt our testing environment to work on the Gitlab CI environment.

Add the follwing lines to your package.json :

"scripts": {
    ...
    "ci:test": "ng test --browsers PhantomJS --watch=false",
    "ci:lint": "ng lint",
    ...
}

Add PhantomJs support :

npm install karma-phantomjs-launcher phantomjs core-js --save --save-exact

Update `karma.conf.js` :

plugins: [
    ...,
    require('karma-phantomjs-launcher')
],

Update `polyfill.ts` :

# Add core-js imports
import 'core-js/es/symbol';
import 'core-js/es/object';
import 'core-js/es/function';
import 'core-js/es/parse-int';
import 'core-js/es/parse-float';
import 'core-js/es/number';
import 'core-js/es/math';
import 'core-js/es/string';
import 'core-js/es/date';
import 'core-js/es/array';
import 'core-js/es/regexp';
import 'core-js/es/map';
import 'core-js/es/weak-map';
import 'core-js/es/set';

# Uncomment zone polyfills
(window as any).__Zone_disable_requestAnimationFrame = true; // disable patch requestAnimationFrame
(window as any).__Zone_disable_on_property = true; // disable patch onProperty such as onclick
(window as any).__zone_symbol__BLACK_LISTED_EVENTS = ['scroll', 'mousemove']; // disable patch specified eventNames
(window as any).__Zone_enable_cross_context_check = true;

Update your `tsconfig.json` :

{
  "compileOnSave": false,
  "compilerOptions": {
    "baseUrl": "./",
    "outDir": "./dist/out-tsc",
    "sourceMap": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "declaration": false,
    "module": "es2015",
    "moduleResolution": "node",
    "target": "es5",
    "typeRoots": [
      "node_modules/@types"
    ],
    "lib": [
      "es2017",
      "es2019",
      "dom",
      "esnext.asynciterable"
    ],
    "resolveJsonModule": true
  }
}

Write your CI configuration file

Create a file .gitlab-ci.yml with the following content :

image: node:latest

stages:
  - CodeQuality

test:
  stage: CodeQuality
  script: 
    - npm ci
    - npm run ci:test

lint:
  stage: CodeQuality
  script:
    - npm ci
    - npm run ci:lint

Each time someone commit on a branch, the CodeQuality stages above will be triggerred.

From the NPM documentation about npm ci:
This command is similar to npm install, except it’s meant to be used in automated environments such as test platforms, continuous integration, and deployment – or any situation where you want to make sure you’re doing a clean install of your dependencies. It can be significantly faster than a regular npm install by skipping certain user-oriented features. It is also more strict than a regular install, which can help catch errors or inconsistencies caused by the incrementally-installed local environments of most npm users.

Push your modifications

git add .gitlab-ci.yml package.json package-lock.json karma.conf.js src/polyfills.ts tsconfig.json
git commit -m "core(ci): Add gitlab CI file and scripts"
git push -u origin develop

Check your CI

For now, your CI will run

npm run ci:test

and

npm run ci:lint

You can now follow the state of your CI on Gitlab.
Go to CI/CD > Pipelines :

Click on the corresponding pipeline to show the stages details :

Create your repository

Fairen — Tue, 28 Jul 2020 12:35:21 +0000

Photo by Daniel McCullough on Unsplash

Introduction

This post takes place in a series aiming to show how to build an angular application from scratch.
We will see how to scaffold an enterprise-scale angular application with all the assets needed to easily develop and maintain it.

This post doesn't dive deep into how git nor gitlab works. For more informations about them, refer to their documentations.

This post will show you how to setup a gitlab repository and push your application created before.

Create your project on Gitlab

Create a new project :

Setup the project configuration :

Upload your first commit

To upload your existing files generated by angular cli use the instructions bellow.

Git global setup

git config --global user.name "<your_gitlab_username>" 
git config --global user.email "<your_gitlab_email>"

Push an existing folder

cd ng-shadow
git remote add origin https://gitlab.com/<your_gitlab_username>/ng-shadow.git
git push -u origin master

Create an Angular application

Fairen — Mon, 27 Jul 2020 14:17:01 +0000

Photo by Daniel McCullough on Unsplash

Introduction

This post is a first of a series aiming to show how to build an angular application from scratch.
We will see how to scaffold an enterprise-scale angular application with all the assets needed to easily develop and maintain it.

This first post doesn't dive deep into how git, node nor angular-cli works. It paraphrases their documentations and gather the informationinto one post. For more informations about them, refer to their documentations.

Getting Started

Start by creating a new angular workspace and application using git & angular-cli.

Install Git

Follow the instruction here.

Install Nodejs and Npm

Install Nodejs and Npm here.

You can find a lot of great article on dev.to to help you install Nodejs and Npm if you have any trouble with the official documentation.

Install NVM (Linux only, sorry not sorry :p)

NVM helps you install and change the node version used according to the directory/project you are working in.

To install or update nvm, you should run the install script. To do that, you may either download and run the script manually, or use the following cURL or Wget command:

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash

wget -qO- https://raw.githubusercontent.com/nvm-sh/nvm/v0.35.3/install.sh | bash

Running either of the above commands downloads a script and runs it. The script clones the nvm repository to ~/.nvm, and attempts to add the source lines from the snippet below to the correct profile file (~/.bash_profile, ~/.zshrc, ~/.profile, or ~/.bashrc).

export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

To use it :

nvm install 10 # only install a version once
nvm use 10 # nvm use 8, adapt on the project your work

Install the latest Angular CLI

Install the Angular CLI globally.
To install the CLI using npm, open a terminal/console window and enter the following command:

npm install -g @angular/cli

Create a workspace and initial application

You develop apps in the context of an Angular workspace.
To create a new workspace and initial starter app:
Run the CLI command ng new and provide the application name (ie. ng-shadow), as shown here:

ng new ng-shadow

The ng new command prompts you for information about features to include in the initial app. Accept the defaults (except for stylesheet by chosing SCSS) by pressing the Enter or Return key.
The Angular CLI installs the necessary Angular npm packages and other dependencies. This can take a few minutes.
The CLI creates a new workspace and a simple Welcome app, ready to run.

Run the application

The Angular CLI includes a server, so that you can easily build and serve your app locally.
Go to the workspace folder (ie. ng-shadow).
Launch the server by using the CLI command ng serve, with the --open option.

cd ng-shadow
ng serve --open

The ng serve command launches the server, watches your files, and rebuilds the app as you make changes to those files.

The --open (or just -o) option automatically opens your browser to http://localhost:4200/.

DEV Community: Fairen

APM vs agkit: is your plugin marketplace a build artifact or a source of truth?

The easy answer, and why it's wrong

What they actually disagree about

What the compile step buys you

What it costs you

What agkit's directness buys you

What it costs you

They compose — and that's the actual answer

So which one?

The honest closing

Agkit : Stop zipping your Claude Code skills: build a plugin marketplace in 15 minutes

The junk drawer problem

The one idea to hold onto

Step 1: scaffold the marketplace

Step 2: add the skill, then make it yours

Step 3: catalog a plugin that lives in someone else's repo

Step 4: validate and publish

Step 5: ship an improvement

The loop, condensed

Complete Tutorial: Creating an MCP Task Manager Server from Scratch

📖 Table of Contents

1. Introduction to Model Context Protocol (MCP)

What is MCP?

Main Components

MCP Session Lifecycle

2. Prerequisites and Installation

Required Technologies

Installation

3. Project Structure

4. Basic Configuration

package.json

tsconfig.json

5. MCP Server Implementation

Basic Types (src/types/task.ts)

Database Configuration (src/database/db.ts)

Database Schema (src/database/schema.sql)

6. Endpoints: Tools

Task Creation (src/tools/create-task.ts)

Task Update (src/tools/update-task.ts)

Task Completion (src/tools/complete-task.ts)

Task Deletion (src/tools/delete-task.ts)

Tools Export (src/tools/index.ts)

7. Endpoints: Resources

Task List (src/resources/task-list.ts)

Statistics (src/resources/task-stats.ts)

Task Detail (src/resources/task-detail.ts)

Resources Export (src/resources/index.ts)

8. Endpoints: Prompts

Weekly Review (src/prompts/weekly-review.ts)

Sprint Planning (src/prompts/sprint-planning.ts)

Prompts Export (src/prompts/index.ts)

9. Error Handling

Error Codes (src/utils/errors.ts)

10. Main Server

Hybrid HTTP/STDIO Architecture

1. HTTP Mode (Recommended)

2. STDIO Mode (Legacy)

MCP Request Handling

Centralized Error Handling

Main Entry Point (src/server.ts)

Advanced Error Handling Pattern

Resource Caching Pattern

11. Code Organization and Patterns

Structuring Pattern

Export Pattern

Validation Pattern

Database Pattern

12. Testing and Validation

Jest Configuration (jest.config.js)

Integration Tests (tests/integration.test.ts)

Manual Test Script (scripts/test-mcp.js)

13. Docker Deployment

Multi-stage Dockerfile

.dockerignore File

Docker Scripts in package.json

HTTP API Endpoints

Health Check

MCP Communication

Deployment Commands

Basic Types (`src/types/task.ts`)

Database Configuration (`src/database/db.ts`)

Database Schema (`src/database/schema.sql`)

Task Creation (`src/tools/create-task.ts`)

Task Update (`src/tools/update-task.ts`)

Task Completion (`src/tools/complete-task.ts`)

Task Deletion (`src/tools/delete-task.ts`)

Tools Export (`src/tools/index.ts`)

Task List (`src/resources/task-list.ts`)

Statistics (`src/resources/task-stats.ts`)

Task Detail (`src/resources/task-detail.ts`)

Resources Export (`src/resources/index.ts`)

Weekly Review (`src/prompts/weekly-review.ts`)

Sprint Planning (`src/prompts/sprint-planning.ts`)

Prompts Export (`src/prompts/index.ts`)

Error Codes (`src/utils/errors.ts`)

Main Entry Point (`src/server.ts`)

Jest Configuration (`jest.config.js`)

Integration Tests (`tests/integration.test.ts`)

Manual Test Script (`scripts/test-mcp.js`)

Update `karma.conf.js` :

Update `polyfill.ts` :

Update your `tsconfig.json` :