# 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

```bash
npm install -g taskguard-mcp
```

Or run directly:

```bash
npx taskguard-mcp
```

For local development:

```bash
npm install
npm run build
node dist/index.js
```

## MCP client configuration

Published package:

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

Local build:

```json
{
  "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:

```json
{
  "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:

```text
${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.

```json
{
  "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.

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

### `taskguard_update_checkpoint`

Updates checkpoint status and can attach evidence.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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`.

```json
{
  "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.

```json
{
  "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

```bash
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