WorkItemsMcp 1.0.2

WorkItemsMCP

A Model Context Protocol (MCP) server for persistent, markdown-based task tracking. Designed to let an AI agent resume each day, read work item files, update tasks based on conversation, and maintain daily logs — all stored as plain markdown files in a local vault.

Installation

Install as a dotnet global tool from NuGet.org:

dotnet tool install -g WorkItemsMcp

Quick start

1. Set the vault environment variable

export TASK_TRACKER_VAULT=/path/to/your/task-vault

2. Run the server

work-items-mcp

3. Register with your MCP client (e.g. Claude Desktop)

{
  "mcpServers": {
    "work-items": {
      "command": "work-items-mcp",
      "env": {
        "TASK_TRACKER_VAULT": "/path/to/your/task-vault"
      }
    }
  }
}

Running from source? Use dotnet run --project src/WorkItemsMcp instead of work-items-mcp, and update "command"/"args" in the MCP client config accordingly.

Vault structure

task-vault/
  .task-tracker/
    index.json        ← task metadata index
    next-id.txt       ← auto-increment ID counter
    config.json       ← vault config
  tasks/
    TASK-0001.md      ← one file per task (YAML front matter + markdown)
    TASK-0002.md
  daily/
    2026-05-21.md     ← one daily note per day
  views/
    active.md         ← auto-generated view: not-started + in-progress
    urgent.md         ← auto-generated view: high + urgent urgency
    blocked.md        ← auto-generated view: blocked tasks
    completed.md      ← auto-generated view: done + cancelled

MCP Tools

Vault management

Daily workflow

Task management

Views

Task format

Each task is a markdown file with YAML front matter:

---
id: TASK-0001
title: "Fix restore cancellation loop"
status: in-progress
urgency: high
created: 2026-05-21
updated: 2026-05-21
deadline:
blocked: false
---

# TASK-0001 - Fix restore cancellation loop

## Description
...

## Current state
Status: In Progress
Urgency: High
Blocked: No

## Next actions
- [ ] Review customer report
- [ ] Identify restore/design-time build loop

## Open questions
- Does this reproduce only with gRPC projects?

## History

### 2026-05-21
Created task.

Valid status values

not-started · in-progress · blocked · done · cancelled

Valid urgency values

low · normal · high · urgent

Agent workflow

1. Agent calls get_vault_status
2. If setup_required → agent asks user where to store the vault
3. Agent calls initialize_vault with chosen path
4. Agent calls resume_day with today's date
5. Agent summarises active / urgent / blocked work to the user
6. User gives updates
7. Agent calls create_task, update_task, or append_task_update as needed
8. Agent calls append_daily_update to log the conversation summary
9. Agent calls rebuild_views
10. Agent summarises what changed

Error responses

All tools return structured JSON. On error:

{
  "status": "error",
  "errorCode": "task_not_found",
  "message": "Task TASK-9999 was not found."
}

Error codes: vault_not_configured · vault_not_initialized · task_not_found · invalid_status · invalid_urgency · invalid_date · io_error

Project structure

src/WorkItemsMcp/
  Program.cs
  Tools/
    VaultTools.cs       ← get_vault_status, initialize_vault
    TaskTools.cs        ← create_task, get_task, update_task, append_task_update, list_tasks, search_tasks
    DailyTools.cs       ← resume_day, append_daily_update
    ViewTools.cs        ← rebuild_views
  Services/
    VaultService.cs
    TaskRepository.cs
    DailyNoteService.cs
    ViewBuilder.cs
    MarkdownTaskSerializer.cs
    TaskIdGenerator.cs
  Models/
    TaskItem.cs
    VaultTypes.cs

Requirements

• .NET 9
• ModelContextProtocol NuGet package (official Microsoft SDK)
• YamlDotNet NuGet package

Releasing a new version

Releases are published to NuGet.org automatically via GitHub Actions when a version tag is pushed:

git tag v1.2.0
git push origin v1.2.0

The workflow will build, pack, and push the .nupkg to NuGet.org using the NUGET_API_KEY repository secret. You can also trigger a publish manually from the Actions tab → Publish to NuGet → Run workflow.