TheGuidingPrincipels/Task-Tracking-MCP

Task Tracking MCP

Modern MCP server for strategic task planning and goal tracking. The project uses SQLite (via better-sqlite3) and a unified baseline migration to keep development, CI, and production environments consistent.

Prerequisites

• Node.js 20+
• npm 10+
• SQLite CLI (sqlite3) available on your PATH

Installation & Local Setup

npm ci
npm run build
npm run db:migrate   # applies migrations/1000_baseline_schema.sql to data/tasks.db

Common database workflows:

• npm run db:fresh – rebuilds data/tasks.db from the baseline.
• npm run db:stamp – records the baseline as applied (useful when the file already matches migrations/1000_baseline_schema.sql).
• npm run db:status – shows applied/pending migrations.

Maintenance & Seed Utilities

• scripts/maintenance/dedup-monthly-goals.ts — deduplicate (month, title) combinations while preserving references.
• scripts/seeds/seed-pattern-defaults.ts — backfill enhanced pattern columns with sane defaults.
• scripts/seed-today-demo.mjs — populate demo data for local exploration.

Run any of the scripts with npx tsx <script> (or DATABASE_PATH=... npx tsx ... against a custom database file).

Testing

npm test

The suite exercises the entire goal lifecycle, baseline migrations, and regression scenarios.

Benchmark Research Workflow

Server-side web research is disabled by default (TASK_PLANNER_ENABLE_SERVER_RESEARCH=false). When get_task_forecast returns web_research_desired: true, orchestrate research client-side:

1. Call get_task_forecast and inspect workflow_status.
   • needs_research means the forecast is incomplete; follow the entry in required_actions[0] (typically exa:web_search_exa).
   • low_confidence means the forecast is usable only after collecting more historical data (no research required yet).
2. Use your preferred web-search MCP/server to gather durations and citations when research is required.
3. Call ingest_benchmark_evidence with the extracted observations; it returns the DB cache_key and next steps for verification.
4. Run get_task_forecast again to confirm workflow_status changes to complete and benchmark_available becomes true (cache TTL defaults to 30 days, configurable via TASK_PLANNER_BENCHMARK_TTL_DAYS).
   • Transparency fields help you audit adjustments:
     • benchmark_raw shows unadjusted P50/P80/P90 from cache
     • adjustment_factors shows multipliers (velocity, complexity, time-of-day) and net_multiplier
     • benchmark_source reveals provider of the cached row

Set TASK_PLANNER_ENABLE_SERVER_RESEARCH=true only if you intentionally want the MCP server to perform web requests itself.

Test Isolation & Cache Management

• Use purge_benchmark_cache to delete a cached benchmark before a test run:
  • Args: { "archetype": "Implement OAuth2 authentication", "source_provider": "web_research_exa" } (optional source filter)
  • Deletes both the aggregate and evidence rows for the matching key(s).

Logging in MCP (Important)

• By default, runtime logs are silenced in MCP mode to avoid contaminating stdout/stderr with non‑JSON text that some clients try to parse as NDJSON.
• To enable logs in development, set TASK_PLANNER_LOG_LEVEL=debug (or any non‑silent value) and run via npm run dev. Avoid enabling logs when connected to an MCP client unless the client safely ignores non‑JSON lines.

Continuous Integration

GitHub Actions (.github/workflows/ci.yml) checks every push and pull request:

1. Installs dependencies and builds the TypeScript sources.
2. Applies the baseline migration.
3. Compares the schema produced by DatabaseManager against migrations/1000_baseline_schema.sql to guard against drift.
4. Runs npm test.

Any schema change must update both src/database.ts and regenerate migrations/1000_baseline_schema.sql.

Further References

• – original consolidation proposal.
• – phased execution log, including verification results.
• – SMART/WOOP data model, new tables/fields, and UI integration tips.
• TASK_PLANNER_BENCHMARK_TTL_DAYS — how long (in days) automatic web benchmarks stay in the cache. Default 30 keeps behaviour balanced; drop to 14 for fast-changing topics, or bump to 60–90 for very stable work.