Dayflow Search MCP
README.md
# Dayflow Search MCP
A local, strictly read-only [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI agents search the full detail of a [Dayflow](https://dayflow.so) work journal: timeline cards, their detailed write-ups, the observations underneath them, and daily standups, over any date range.
It reads Dayflow's local database directly. It never modifies Dayflow, creates migrations, reads screenshots or recordings, or exposes arbitrary SQL.
This is an independent project. It is not made by or affiliated with Dayflow.
## How it differs from Dayflow's own MCP server
Dayflow ships its own MCP server, and it's the better choice for summaries, time breakdowns, weekly rollups and today's standup. This server is for deeper history questions, such as "what exactly did I do on this three weeks ago, and how do you know?"
| | Dayflow's MCP server | Dayflow Search MCP |
| --- | --- | --- |
| Search covers | Activity titles and one-line summaries | Titles, summaries, detailed write-ups, observations and standups |
| Search results | The 50 most recent matches | Ranked and paginated, up to 5,000 per search |
| Date scope | Timeline is one day at a time | Any day or exact time window, for timeline and search |
| Activity detail | The detailed write-up | The write-up plus the observations from the same stretch of time |
| Match explanation | Not reported | Each result reports its match mode, score and source |
| Writes | Reports whether edits are enabled | No write path at all |
| Time breakdowns and weekly rollups | Yes | No |
Comparison checked against Dayflow 2.9.0 on November 11, 2026.
Because this server reads Dayflow's database rather than an official API, a Dayflow update that changes the schema can break it until it's updated. It has been tested with Dayflow 2.9.0 on macOS.
## Prerequisites
- macOS with Dayflow installed and initialized
- Node.js 22 or newer
- A local Dayflow database at the default location:
`~/Library/Application Support/Dayflow/chunks.sqlite`
## Install and build
```bash
git clone https://github.com/morgancrozier/dayflow-search-mcp.git
cd dayflow-search-mcp
npm ci
npm run build
```
## Connect it to an agent
The server speaks MCP over stdio, so the client launches it as a child process. Use the absolute path to `dist/server.js`. GUI apps may not see your shell's `PATH`, so if `node` isn't found, use the full path from `which node`.
**Claude Code**
```bash
claude mcp add --scope user dayflow-search -- node /absolute/path/to/dayflow-search-mcp/dist/server.js
```
Run `claude mcp list` or `/mcp` inside Claude Code to check it's connected.
**Claude Desktop**, in `claude_desktop_config.json`:
```json
{
"mcpServers": {
"dayflow-search": {
"command": "node",
"args": ["/absolute/path/to/dayflow-search-mcp/dist/server.js"]
}
}
}
```
**Codex**, in `~/.codex/config.toml`:
```toml
[mcp_servers.dayflow-search]
command = "node"
args = ["/absolute/path/to/dayflow-search-mcp/dist/server.js"]
```
**ChatGPT** needs a network-reachable server. See [Using it from ChatGPT](docs/secure-mcp-tunnel.md) for an optional Secure MCP Tunnel setup.
Then try questions like:
- "What did I work on between the 3rd and the 10th? Group it by project."
- "When did I last work on the export bug, and what was blocking it?"
- "Show me the observations behind that activity."
## Run it yourself
```bash
npm start # built server over stdio
npm run dev # without a build step
```
Override the database location for testing or a non-default Dayflow installation:
```bash
DAYFLOW_DB_PATH="/absolute/path/to/chunks.sqlite" npm start
```
The override must identify an existing SQLite file with the expected Dayflow tables.
## Privacy
The server runs locally and sends nothing anywhere itself. But whatever a tool returns becomes visible to the AI client and model provider that called it, and a Dayflow journal records everything on screen, including personal messages. Keep result limits narrow, and scope searches by date or source when you can.
## Safety guarantees
- Opens SQLite with `readonly: true` and `fileMustExist: true`.
- Enables `PRAGMA query_only=ON` and a 3-second `busy_timeout`.
- Uses the normal SQLite WAL locking path, so committed live WAL data is visible while Dayflow runs.
- Does not use `immutable=1` or `nolock=1`.
- Contains only fixed, parameterized `SELECT` queries.
- Does not checkpoint, change journal mode, vacuum, attach, migrate, or expose SQL execution.
- Does not query `llm_calls`, `screenshots`, `batch_screenshots`, or screenshot paths.
- Does not open files referenced by database records and never reads `recordings/`.
- Filters timeline cards with `is_deleted = 0`.
- Keeps each database operation to a short read statement.
## Tools
### `dayflow_get_timeline`
Read active timeline cards chronologically. Supply a Dayflow journal date or an exact datetime range, but not both.
```json
{"date":"2026-08-09","include_detailed_summary":false,"limit":25}
```
```json
{"start":"2026-08-09T14:00:00+07:00","end":"2026-08-09T16:00:00+07:00","limit":25}
```
Date queries use Dayflow's local 4:00 AM to 4:00 AM journal boundary. Exact ranges return activities that overlap the range. Results are chronological and use an opaque `next_cursor` when another page exists.
### `dayflow_search`
Deterministic local lexical search across active timeline cards, detailed observations, and standups. Each Evidence source is normalized through the same local pipeline before phrase matching, term coverage, ranking, and snippet anchoring. Exact normalized phrases rank above all-term matches, which rank above meaningful partial-term matches.
For an Observation evidence result, the observation's own text is the only searchable and scored evidence. After matching, the server may associate it with an overlapping active timeline card. That association reads only the card identity, batch, interval, and display title. The result keeps the observation ID, batch, and interval as its evidence provenance and adds the associated activity ID and display title when available. Card summaries, detailed summaries, categories, metadata, apps, sites, and distractions are neither read for this association nor used to make or rank an observation match. One representative observation is returned per associated activity; matching observations without active provenance remain separate results.
```json
{"query":"GardenPlanner","sources":["timeline","observations","standups"],"limit":25}
```
An optional `date` or `start`/`end` pair narrows the search. Results are compact and include `match_mode`, `relevance_score`, `retrieval_version`, and activity IDs when an observation can be associated with an active card. `relevance_score` is an opaque diagnostic that is comparable only within the same normalized query and retrieval version. Its exact numeric value is not a compatibility promise.
Search has one total order: relevance score descending, evidence timestamp descending, the fixed source order `observations`, `standups`, `timeline`, observation supporting count descending when both results are observations, and finally the source-specific evidence ID descending. Timeline and observation IDs are compared numerically; validated standup `YYYY-MM-DD` IDs are compared by ASCII code-unit order. Supporting count never affects a cross-source comparison, and evidence IDs are never compared across sources. The unique result identity is `(source, relevant_id)`.
Search pagination uses an opaque, versioned live keyset. A cursor stores the complete ranking position, retrieval version, query/source/range scope, and the count already emitted in that chain. `limit` is not part of the scope, so page size may change between requests. A legacy, malformed, wrong-query, wrong-source, wrong-range, invalid, or wrong-version cursor is rejected with an instruction to restart the search without a cursor.
Each continuation searches the corpus visible to that request and resumes strictly after the cursor's stored ranking position. It is not a snapshot: new or updated results ahead of the cursor require a fresh search, later results may appear in the continuation, deleted results disappear, and a previously returned record can reappear if Dayflow changes it enough to move behind the cursor. An unchanged corpus can be traversed without gaps or duplicates, but completeness and deduplication are not unconditional promises while Dayflow is mutating. A cursor chain emits at most 5,000 results even when page size changes. `pagination_hard_limit_reached` becomes true only when 5,000 results have been emitted and at least one later result exists; that response has no next cursor.
Source selection constrains database access: standup-only search does not read timeline cards or observations, timeline-only search reads only active cards in scope, and observation search reads scoped observations before requesting minimal active provenance that overlaps matching evidence. Search reads the selected local Dayflow records live on each request; it intentionally has no FTS index, vector index, embeddings, cache, or write path.
Lexical normalization has deliberately narrow limits:
- Compatibility-equivalent Unicode text and locale-independent full Unicode case folding form Literal matches. Diacritics and combining marks are preserved: `café` does not match `cafe`, and Turkish dotted `İ` is not promised to match ASCII `i`.
- Punctuation, underscores, and whitespace separate tokens. A trailing `+` or `#` remains part of a technology token, so `C++`, `C#`, and `C` stay distinct.
- `exact_phrase` is a Literal match at token boundaries. A substring inside a larger token is not an exact phrase, and a Variant match can never create one.
- Literal tokens are retained. Variant matches only add a lower-weight regular plural alternative: ordinary `s`, selected `es` after `ss`, `x`, `z`, `ch`, and `sh` (plus `bus` and `status`), or `ies` after a consonant plus `y`. `new` is excluded so it never becomes equivalent to `news`.
- There is no generic suffix stripping, derivational or irregular-English stemming, accent removal, phonetic matching, fuzzy matching, or edit distance. Irregular pairs such as `person`/`people` remain literal-only.
The full-case-fold table comes from the exact lockfile-pinned `unicode-case-folding` package. The package performs no runtime I/O; updating its Unicode data is an explicit dependency upgrade rather than a network or platform-locale change at search time.
### `dayflow_get_activity`
Read one active timeline card plus overlapping observations from the same analysis batch.
```json
{"activity_id":242,"include_observations":true}
```
No screenshot data or paths are returned.
### `dayflow_get_standup`
Read one already-existing standup. This tool never generates or updates a standup.
```json
{"date":"2026-08-09"}
```
## Test and validate
```bash
npm test
npm run typecheck
npm run build
```
After building, run all four tools against the live default Dayflow database through an actual MCP stdio client:
```bash
npm run smoke:live
```
The smoke output abbreviates personal text. To test individual argument objects, use an MCP client or the MCP Inspector and call the examples above.
## Limits in V1
- Search performs live in-memory lexical scoring over selected, time-scoped Evidence source rows and may become slower as history grows; no FTS or vector index is maintained. Observation provenance is fetched only after matching and is bounded to active cards that can overlap the matching observation intervals.
- Dayflow has no first-class project table. Project answers are inferred by the calling AI from card text, observations, categories, apps, and sites.
- Search pagination uses a capped live ranking keyset; timeline pagination uses a chronological keyset cursor.
- Existing active activity IDs can later disappear if Dayflow reprocesses a period and soft-deletes the old generated cards.
- Screenshots, recordings, LLM call logs, journal mutation, embeddings, remote access, and HTTP transport are intentionally out of scope.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessOutdated data