# TechnoTracker

An MCP-UI and OpenAI Apps SDK application that turns explicitly selected work
context into a deterministic schedule, confirmed actuals, and a reconciled
timesheet. Its onboarding
asks about the user's job, approved work tools and connection status, company
time policy, and preferred workflow before rendering the workday plan.

## Architecture

```text
src/
  server.ts          Streamable HTTP MCP server and dual-host UI resources
  contracts.ts       Zod schemas and domain types
  plan-workday.ts    Explicit-input planning use case
  planner/           Priority, scheduling, timesheet, and reconciliation logic
  widget/            React onboarding, planner, and reconciliation UI
```

There is no standalone API, dashboard, database, connector adapter, or
application credential store. ChatGPT retrieves context through separately
approved apps and passes only selected data to `generate_workday_plan`.
TechnoTracker never asks for app passwords, access tokens, or tenant-wide
Microsoft permissions.

## MCP tools

- `show_technotracker_onboarding` renders the interactive setup flow.
- `save_technotracker_configuration` validates app-submitted configuration. It
  is app-only, idempotent, and does not write to an external system.
- `generate_workday_plan` accepts normalized work items, meetings, messages,
  and the validated configuration, then renders the plan.
- `adjust_schedule_item` moves a single planned work block to a new time
  without regenerating the whole plan, deterministically rebalancing the
  timesheet. Meetings are immutable and cannot be adjusted.
- `prepare_workday_reconciliation` turns the original rundown and refreshed
  context into app-derived actual-work suggestions that require confirmation.
- `finalize_workday_reconciliation` is an idempotent pure transform that
  returns deviations, warnings, carryover, approval state, and the reconciled
  timesheet. It performs no submission or external write.

The widget keeps versioned, non-sensitive preferences and dated reconciliation
drafts in ChatGPT widget state and browser storage. Drafts expire after 14 days.
It also keeps a per-day activity timeline (plan generated, schedule adjusted,
reconciliation prepared/finalized, reminders sent) in the same storage, so the
widget stays in sync across every view without waiting on another chat turn.
Activity entries expire after 14 days.
It sends concise context to the conversation at prepare/finalize boundaries.
Durable cross-device profiles would require an authenticated storage service
and are intentionally out of scope.

The same bundled React UI is published in two forms:

- An MCP Apps resource (`text/html;profile=mcp-app`) generated by
  `@mcp-ui/server` and embedded in relevant tool results.
- A ChatGPT Apps SDK template (`text/html+skybridge`) with the MCP-UI Apps SDK
  adapter, referenced through `openai/outputTemplate`.

## Behavior

- Onboarding supports Jira, Azure DevOps, Linear, Asana, ClickUp, Monday,
  Trello, GitHub, Notion, HubSpot, Confluence, Google Drive, Figma, Supabase,
  Vercel, Xcode, Outlook, Google Calendar, Teams, Slack, and email.
- Each selected app records whether it is connected in ChatGPT, still needs a
  connection, or will use manual capture/import. OAuth remains controlled by
  ChatGPT and the user's workspace administrator.
- The questionnaire captures time basis, entry cadence, submission timing,
  approval requirements, description style, overtime policy, and whether the
  user wants a morning plan, end-of-day reconciliation, or weekly summary.
- Work item prefix labels and timesheet codes are configurable. Defaults remain
  `HUB-* => HUBSPOT | HUB-*` and `DTC-* => DTC | DTC-*`.
- Meeting and internal codes are configurable and default to `INT-58`.
- Target hours are configurable from 1 to 16 hours in quarter-hour increments;
  the default is exactly 8 hours.
- Entries can be rounded to 1, 5, 6, 10, 15, or 30 minutes.
- Meetings are immutable busy intervals.
- Generated work blocks are free and never overlap meetings.
- Work blocks receive a 15-minute meeting buffer.
- Work blocks are 90 minutes by default and shrink in 15-minute steps to fit
  meeting-fragmented gaps of at least 30 minutes.
- Work blocks can be nudged earlier or later in 15-minute increments directly
  from the widget; the move is rejected if it would overlap a meeting (with
  buffer), another work block, or the configured workday hours.
- Planned timesheets exactly match the configured daily target.
- Reconciliation supports completed, partial, skipped, replaced, and unplanned
  work with editable duration, issue key, timesheet code, and notes.
- Fixed-day, project-budget, and billable-split policies balance short days.
  Actual-time policies never add balancing time.
- Overtime can be capped deterministically, included as actual, or preserved
  with a review requirement.
- Partial, skipped, and replaced planned work is returned as carryover.
- **Remind me** sends a follow-up request to ChatGPT; TechnoTracker does not
  perform background scans.
- MCP tools perform no external writes.

## Local development

Requirements: Node.js 22+ and npm 11+.

```bash
cp .env.example .env
npm install
npm run dev
```

The MCP endpoint is `http://localhost:8000/mcp`.

- Onboarding preview: `http://localhost:8000/preview?preview=1`
- Plan preview: `http://localhost:8000/preview?preview=plan`
- Reconciliation preview: `http://localhost:8000/preview?preview=reconcile`

## Connect to ChatGPT

1. Run `npm run dev`.
2. Expose port `8000` through an HTTPS development tunnel.
3. Enable developer mode in ChatGPT.
4. Add `https://<tunnel-host>/mcp` as an app.
5. Ask ChatGPT to run `show_technotracker_onboarding`.
6. Select work apps and record their connection state. Use **Open ChatGPT Apps**
   for anything marked **Needs connection**, then complete its OAuth flow if
   permitted by the workspace.
7. Answer the company time-policy and workflow questions.
8. Choose **Build today's plan**. ChatGPT gathers relevant context through
   approved apps and calls `generate_workday_plan`.
9. At the end of the day, choose **Reconcile day** or ask ChatGPT to update the
   reconciliation in chat. Confirm every suggestion before finalizing.

The planner app does not inherit credentials from those apps and requires no
OpenAI API key. It receives only tool arguments selected for the current call.

## Validation

```bash
npm test
npm run typecheck
npm run build
npm audit --omit=dev
```

Tests cover default and custom prefix rules, onboarding/tool metadata, priority
scoring, overlap detection, meeting buffers, gap-fitted focus blocks, free/busy
behavior, single
schedule-item rescheduling, reconciliation confirmation, carryover, rounding,
meeting exclusion, target balancing, overtime policies, draft and activity-log
expiry, and idempotent finalization.

Implementation follows the
[MCP-UI Apps SDK guide](https://mcpui.dev/guide/apps-sdk),
[OpenAI Apps SDK documentation](https://developers.openai.com/apps-sdk), and
[official Apps SDK examples](https://github.com/openai/openai-apps-sdk-examples).