Office Recorder and its MCP server

Implementation guide for version 0.1.0, verified against the project source on September 8, 2026.

What Office Recorder does

Office Recorder is a local activity recorder for engineering work. A background daemon writes timestamped events, and the office-history Model Context Protocol (MCP) server lets an AI client query that history and add explicit notes.

The purpose is to make it easier to resume a project: identify recent work, find changed paths, review Git activity, and recover decisions or checkpoints saved by an AI session.

How it works

The daemon observes configured activity sources.
Events are appended to daily JSONL files in a local data directory.
The MCP server reads the same event store and returns events, summaries, or a context bundle.
An AI or script can add a manual event through record_event.

The daemon and MCP server are separate processes. Starting the MCP server alone does not start automatic recording. Configure both to use the same data directory.

Recorded activity

Source	Recorded information
Windows foreground window	Window title and process metadata when the observed foreground-window state changes
File watching	Changed paths under configured roots, with the filesystem event type; changes are debounced per path
Git polling	Initial repository state and subsequent changes to branch, HEAD, and working-tree status
Project classification	Project associations from configured path and window-title rules, plus transitions between classified foreground projects
Manual events	Notes, decisions, checkpoints, or AI-session summaries supplied through MCP
Recorder operations	Daemon start/stop events and supported watcher/window errors

Automatic events carry an ID, timestamp, machine name, type, and source, plus optional project, path, text, and metadata. File-change events record paths and event metadata; they do not contain file-content snapshots.

Setup and execution

From a local checkout with Node.js and npm available:

powershell
npm install
npm run build
Copy-Item office-recorder.config.example.json office-recorder.config.json

For initial setup, edit the copied configuration to use your own paths. The example shipped with this version contains machine-specific paths that must be replaced. Preserve an existing configuration when updating an installation.

A portable starting configuration is:

json
{
  "pollIntervalMs": 5000,
  "gitScanIntervalMs": 30000,
  "fileDebounceMs": 1500,
  "maxGitDepth": 4,
  "watchRoots": ["C:/work/example-project"],
  "ignorePathParts": [
    ".git", "node_modules", "dist", ".vs", "Debug", "Release", "x64"
  ],
  "projectRules": [
    {
      "name": "Example Project",
      "paths": ["C:/work/example-project"],
      "titlePatterns": ["example-project"]
    }
  ]
}

Omitting dataDir uses ~/.office-recorder unless the OFFICE_RECORDER_DATA_DIR environment variable overrides it. Events live in events/YYYY-MM-DD.jsonl beneath that directory.

Run the daemon from the checkout:

powershell
npm run daemon -- --config C:/work/office-recorder/office-recorder.config.json

Use --root PATH to override configured watched roots; repeat the option for multiple roots. --data-dir PATH overrides the storage location. OFFICE_RECORDER_CONFIG can select the configuration file.

Keep watched roots focused on relevant projects. The defaults poll foreground-window state every 5 seconds, poll Git every 30 seconds, and debounce file events for 1.5 seconds.

Connecting the MCP server

The server uses stdio. After building, configure an MCP-capable client to launch Node with the compiled CLI:

json
{
  "mcpServers": {
    "office-history": {
      "command": "node",
      "args": [
        "C:/work/office-recorder/dist/cli.js",
        "mcp",
        "--config",
        "C:/work/office-recorder/office-recorder.config.json"
      ]
    }
  }
}

Replace the example paths with the checkout location. This illustrates the command and arguments; the enclosing configuration format depends on the client.

For direct execution from the checkout:

powershell
npm run mcp -- --config C:/work/office-recorder/office-recorder.config.json

MCP tool reference

Tool	Purpose	Inputs
`recorder_status`	Show storage location, number of event files, and latest event	None
`list_projects`	Show configured watch roots and project rules	None
`recent_activity`	Return recent events	Optional `project`, `since`, `limit`
`search_activity`	Search the serialized event JSON; every query word must match	Required `query`; optional `project`, `since`, `until`, `limit`
`activity_between`	Return events within a time range	Required `start`, `end`; optional `project`, `limit`
`files_touched`	Return unique event paths and the number of matched events used	Optional `project`, `since`, `until`, `limit`
`what_was_i_doing`	Return a compact work diary	Optional `project`, `since`, `until`, `limit`
`reclaim_context`	Build a project context bundle with a summary and event lines	Optional `project`, `query`, `since`, `limit`
`record_event`	Append a manual event with source `mcp`	Required `type`; optional `project`, `path`, `text`, `metadata`

The server also registers the text resource office-history://today, which summarizes up to 200 events since the start of the current UTC date.

Query behavior

Results are ordered newest first.
The usual default limit is 100 events; tool limits accept integers from 1 to 1,000.
reclaim_context defaults to 200 events and includes at most 100 formatted event lines.
Project filtering is an exact, case-insensitive name match.
Search uses case-insensitive substring matching for every whitespace-separated query word across the event JSON.
Time boundaries are inclusive. Use ISO timestamps with an explicit timezone for precise ranges.
A date-only end value represents midnight at the start of that date.
files_touched uses event paths, which can include repository paths; its results are bounded by the event limit.

Example workflow

Ask an AI client connected to the server:

“Show recent activity for Example Project.”
“What was I doing on this project yesterday?”
“Find activity mentioning the driver.”
“Build a context bundle so I can resume Example Project.”

Before ending a work session, save a useful checkpoint with record_event:

json
{
  "type": "checkpoint",
  "project": "Example Project",
  "text": "Completed the parser update. Next step: verify malformed-input handling.",
  "metadata": {
    "next_step": "Run the malformed-input cases and review error messages."
  }
}

This is a synthetic example, not a published activity record.

Current limits and data handling

This version records mechanical observations and user-supplied notes. Its diary and context tools summarize recorded events; they do not independently infer the reasoning behind changes. Explicit checkpoints preserve that reasoning.

Foreground-window capture is Windows-specific, and recursive file watching is enabled on Windows in this implementation. Polling and debouncing can miss or combine short-lived changes. recorder_status shows stored history, so a successful response alone does not prove the daemon is currently running.

Storage is local, while information returned through MCP becomes available to the connected client. Events can contain window titles, paths, machine names, and manual notes. This guide uses generic paths and synthetic examples.

Verification and source basis

The connected office-history server successfully answered recorder_status on September 8, 2026, and returned an existing event store with a recent daemon event.

This guide was checked against the local project's README.md, package.json, and the implementation in src/mcp.ts, src/config.ts, src/daemon.ts, src/store.ts, and src/cli.ts. It describes the observed version 0.1.0 implementation. No public source repository URL was established during this review.