TaskGuard MCP

TaskGuard MCP is a Model Context Protocol server that gives AI agents a lightweight task-management and self-verification layer.

It helps agents:

• define clear goals before execution
• break work into measurable checkpoints
• detect scope drift before doing unrelated work
• record decisions, blockers, and verification evidence
• verify final results against explicit done criteria

TaskGuard is designed for coding agents, research agents, automation agents, and any long-running AI workflow where staying focused matters.

Why TaskGuard?

Agents are powerful, but they often fail in predictable ways:

• They expand the scope with “while I’m here...” cleanup.
• They lose track of what the user actually asked for.
• They report progress without evidence.
• They say “done” before acceptance criteria are satisfied.

TaskGuard gives the agent a durable task contract and an audit trail it can consult throughout the run.

Install

npm install -g taskguard-mcp

Or run directly:

npx taskguard-mcp

For local development:

npm install
npm run build
node dist/index.js

MCP client configuration

Published package:

{
  "mcpServers": {
    "taskguard": {
      "command": "npx",
      "args": ["taskguard-mcp"]
    }
  }
}

Local build:

{
  "mcpServers": {
    "taskguard": {
      "command": "node",
      "args": ["/absolute/path/to/taskguard-mcp/dist/index.js"],
      "env": {
        "TASKGUARD_STATE_DIR": "/absolute/path/to/.taskguard"
      }
    }
  }
}

On Windows, use escaped backslashes in JSON paths:

{
  "mcpServers": {
    "taskguard": {
      "command": "node",
      "args": ["C:\\Users\\VK\\Desktop\\mcp-skill\\dist\\index.js"],
      "env": {
        "TASKGUARD_STATE_DIR": "C:\\Users\\VK\\Desktop\\mcp-skill\\.taskguard"
      }
    }
  }
}

State storage

TaskGuard stores local state as JSON.

Default:

${process.cwd()}/.taskguard/taskguard-state.json

Environment overrides:

Variable	Meaning
TASKGUARD_STATE_FILE	Exact state file path
TASKGUARD_STATE_DIR	Directory containing taskguard-state.json

Runtime state is intentionally excluded from git via .gitignore.

Tools

taskguard_define_goal

Call before meaningful work starts. Defines the task contract.

{
  "title": "Implement login form",
  "goal": "Create a login form with validation using existing UI components",
  "nonGoals": ["Do not modify backend APIs"],
  "doneCriteria": [
    { "description": "Login form renders", "required": true },
    { "description": "Validation works", "required": true },
    { "description": "Tests pass", "required": true }
  ]
}

taskguard_add_checkpoint

Adds measurable work steps.

{
  "sessionId": "session_abc123",
  "checkpoints": [
    { "label": "Build form UI" },
    { "label": "Add validation" },
    { "label": "Run tests" }
  ]
}

taskguard_update_checkpoint

Updates checkpoint status and can attach evidence.

{
  "sessionId": "session_abc123",
  "checkpointId": "checkpoint_abc123",
  "status": "completed",
  "evidence": {
    "kind": "test",
    "summary": "Vitest suite passed",
    "command": "npm test"
  }
}

taskguard_check_scope_drift

Checks whether proposed work appears outside the recorded task contract.

{
  "sessionId": "session_abc123",
  "proposedAction": "Also refactor the whole auth backend while here",
  "changedFiles": ["src/server/auth.ts"]
}

Returns in_scope, possible_drift, or out_of_scope with reasons and a suggested next step.

taskguard_add_evidence

Records proof of progress or verification.

{
  "sessionId": "session_abc123",
  "kind": "typecheck",
  "summary": "TypeScript typecheck passed",
  "command": "npm run typecheck",
  "doneCriterionIds": ["criterion_abc123"]
}

taskguard_update_criterion

Marks done criteria as pending, met, not_met, or waived.

{
  "sessionId": "session_abc123",
  "criterionId": "criterion_abc123",
  "status": "met",
  "evidenceIds": ["evidence_abc123"]
}

taskguard_add_blocker / taskguard_update_blocker

Tracks blockers that prevent completion until resolved or waived.

taskguard_verify_done

Call before final response, commit, push, PR, or handoff.

{
  "sessionId": "session_abc123",
  "strict": true
}

Strict mode requires met required criteria to have linked evidence.

taskguard_get_status

Returns the current ledger for one session or all non-archived sessions.

taskguard_reset_session

Archives or deletes a session. Prefer archive for auditability.

Resources

TaskGuard exposes read-only MCP resources:

• taskguard://sessions
• taskguard://sessions/{sessionId}
• taskguard://sessions/{sessionId}/summary
• taskguard://sessions/{sessionId}/done-report

Prompts

TaskGuard includes prompts that guide agents into the recommended workflow:

• taskguard_plan_task
• taskguard_checkpoint_review
• taskguard_done_review

Recommended agent workflow

1. User asks for a task.
2. Agent calls taskguard_define_goal.
3. Agent calls taskguard_add_checkpoint.
4. Before adjacent or broad work, agent calls taskguard_check_scope_drift.
5. After each step, agent calls taskguard_update_checkpoint and records evidence.
6. Before saying “done”, agent calls taskguard_verify_done.
7. If ready is false, agent reports what remains instead of claiming completion.

Development

npm install
npm run lint
npm run typecheck
npm test
npm run build

Privacy and security

TaskGuard is local-first. It does not call external APIs and does not use an LLM internally. State is written to the configured local JSON file.

Do not store secrets, API keys, passwords, or sensitive personal data in TaskGuard evidence or decision logs.

License

MIT