# Capture & Reflect

`capture-reflect-mcp` is the open-source MCP server behind **Capture & Reflect**, a personal capture and reflection system. It lets an AI client capture and retrieve Markdown journal entries and notes, including photo attachments, through natural language while keeping the records in a separate local or GitHub repository.

It is designed to work with the directory conventions used by [`capture-reflect-practice`](https://github.com/sunling/capture-reflect-practice):

```text
journals/{YYYY}/{YYYYMM}/
notes/{YYYY}/{YYYYMM}/
reviews/
```

## Hosted quick start

Before connecting Capture & Reflect, create a dedicated GitHub repository for your records:

1. On GitHub, create a new repository. A **private, empty repository** is recommended for personal records. You do not need to add a README, `.gitignore`, or license; Capture & Reflect can initialize a repository with no commits.
2. Connect your AI client to `https://api.bysunling.com/mcp` and complete OAuth. See the [client-specific instructions](#connect-to-the-hosted-mcp) below.
3. Ask the client to save a journal entry or note. On first use, open the secure GitHub setup link returned by Capture & Reflect.
4. Authorize the Capture & Reflect GitHub App. For the narrowest access, choose **Only select repositories** and select the dedicated records repository.
5. Choose that repository, confirm your time zone, and click **Save & connect**. Capture & Reflect creates the canonical `journals/`, `notes/`, and `reviews/` directories automatically.
6. Try “Dear diary, today...”, “Save this thought: ...”, or “What did I write about moving?”

An existing repository also works, and existing files are not replaced. A dedicated repository is recommended because it keeps personal records separate and limits the GitHub App's access to only the data it needs. Record Markdown and images are written directly to the selected repository; they are not copied into the hosted service's database.

## Your records remain usable without this MCP

**No MCP required. No ID required. No database required.** Markdown files, images, and ordinary relative Markdown links in *your records repository* are the durable assets. Capture & Reflect helps write and explore them; it is not required to keep using them.

- **Keep writing normally.** If the hosted MCP stops working or is discontinued, clone or download the records repository, open it in Obsidian or another Markdown editor, and create/edit `.md` files. You do **not** have to generate an ID by hand or export a proprietary database. Use standard links such as `[related note](another-note.md)` to connect records.
- **IDs are optional metadata.** Capture & Reflect assigns a stable `id: cr_<uuid>` in YAML frontmatter when it creates a new journal, note, or review; appending to an existing journal preserves its ID. Older files and hand-written Markdown without IDs remain valid. An ID does not replace the file path or make ordinary Markdown links immune to renaming.
- **Links are the source of graph relationships.** The read-only `get_record_connections` tool accepts an exact repository-relative `path` or an optional `id` and derives outgoing links, backlinks, and unresolved targets from standard relative Markdown links in record bodies. It does not add reverse links to other files or maintain a graph database. It does not infer relationship types or treat a link as the user's endorsement of an AI suggestion.
- **Reviews preserve evidence separately.** A review's `source_paths` lists the journal and note files consulted for the reviewed period. That is provenance, **not** an assertion that every record shares a meaningful idea. The review body can link specific records beside an observation and explain *why* they matter. The graph tool currently derives edges from body links, not from `source_paths`; no typed relationship schema is required.
- **Indexes are disposable.** `.capture-reflect/` search metadata can be rebuilt from Markdown; graph connections are computed from files at query time. Removing an index never removes the original note or its links.

Current limitations: graph lookup scans all discoverable records and may be slower for large repositories. The MCP record reader currently recognizes date-prefixed record filenames, so manually created journals should follow `YYYYMMDD.md` and notes should follow `YYYYMMDD-short-topic.md` under the canonical folders to be found by MCP search/graph tools; older date-prefixed journal filenames remain supported. Obsidian and other editors do not require these conventions. Standard relative links must be repaired if a file is moved or renamed by a tool that does not update references automatically. The graph parser supports common inline and reference-style Markdown links, not Obsidian-only `[[wikilinks]]` or every advanced Markdown syntax. No automatic backfill of old IDs, automatic AI relationship creation, or relationship-type taxonomy is implemented.

See the [portable knowledge graph design and MCP outage walkthrough](docs/portable-knowledge-graph.md) for examples and the exact boundaries.

## Current scope

The local server exposes seven record, graph, and context tools. The hosted service also exposes secure setup and account-switch tools:

- `capture_journal`: create or append a personal journal entry fragment, with optional photos.
- `capture_note`: save a structured Markdown note preserving the original text, with optional body-only source details, related journals or notes, AI-labeled reflections and possible actions, and photos.
- `get_records_by_date_range`: retrieve journals and notes, or saved reviews with `types: ["review"]` (filtered by save date).
- `save_review`: save a review and validated source links under `reviews/`, without overwriting.
- `search_records`: search journals and notes by default; use `types: ["review"]` for earlier reviews.
- `get_record_connections`: read standard Markdown outgoing links, backlinks, and unresolved targets by exact path or optional ID; does not write records.
- `get_bubble_breaker_context`: read recent journals and notes, current date/time, and the Bubble Breaker workflow; defaults to the last seven calendar days in the configured time zone.
- `get_github_setup_link`: authorize a GitHub App and choose a per-user records repository.
- `get_github_account_switch_link`: open GitHub account selection directly, including when the old authorization has expired.

The MCP server handles access and storage. It publishes four focused Agent Skills through the MCP Skills extension so supported AI clients can discover their instructions and resources:

- `capture-record`: route one journal entry or note, preserve the user's voice, and pass uploaded photos through.
- `review-records`: review a date range and save its sources, patterns, questions, and reflections unless chat-only output is requested.
- `recall-records`: search before answering questions about earlier records.
- `bubble-breaker`: discover one verified unfamiliar resource, record completion with minimal effort, or explore perspectives, blind spots, connections, and questions.

### Note capture workflow

The capture skill passes the user's text verbatim as structured `originalNote`. The server renders an **Original note** section plus optional **Source**, **Related records**, **Further reflection (AI)**, and **Possible actions (AI)** sections, with headings in the note's language. Related records may be journals or notes. Source details are rendered only in the body, not duplicated in YAML.

Before saving, the client starts with one focused `search_records` query across journals and notes and only runs another when the first result is clearly insufficient, with at most three searches total. It reads the results and includes up to three meaningful connections total with verified dates, exact returned paths, and exact excerpts. Search currently matches literal text; it may miss related experiences or ideas expressed differently. Empty sections are omitted, and a failed lookup does not prevent saving the original note. Users can skip enrichment.

Search and connection selection remain a client workflow defined by the bundled skill and tool instructions. `capture_note` accepts structured fields rather than arbitrary Markdown, and the storage layer consistently renders the sections while preserving `originalNote` verbatim.

Capture routing follows the intended subject rather than isolated trigger words. Lived experiences and feelings go to `capture_journal`; technical observations, measurements, product tests, debugging findings, and design decisions go to `capture_note`, even when they discuss journals or the recording workflow itself. An explicit request to save something as a journal overrides the inferred subject.

### Sharded GitHub search index

GitHub-backed repositories use a sharded search index under `.capture-reflect/index/`. The manifest references smaller shards grouped by record type and year; nonstandard paths use deterministic hash buckets. Captures update only the affected shard and the manifest in the same atomic commit as the Markdown record and any images.

The first search creates the index. Later searches validate per-shard digests against the current Git tree and rebuild stale metadata from changed records. Markdown under `journals/`, `notes/`, and `reviews/` remains the source of truth; all `.capture-reflect/` data is rebuildable.

### Bubble Breaker workflow

Ask “Surprise me with something new.” The client explores varied domains and sources with its own web tools, independently of inferred interests. Before recommending one verified resource, it uses `get_bubble_breaker_context` and focused `search_records` queries to filter familiar territory and repeats. History filters candidates; it does not determine every destination. The MCP does not browse or generate recommendations itself. Other modes are `challenge`, `blindspot`, `connect`, and `socratic`.

Recommendations stay in chat. Once you explicitly report completion, the client checks notes for an existing completion and saves a minimal record through `capture_note`, using the single stable `bubble-breaker` tag and no automatic record enrichment or required summary. The generated YAML frontmatter holds the stable ID, factual resource title, resolved date, and tag; structured source details, including a canonical URL when known, appear in the Markdown body. It preserves user-supplied thoughts verbatim, or uses one short localized completion marker because `capture_note.originalNote` cannot be empty. The configured time zone replaces the reference skill's fixed time zone. Search-based duplicate checks are not atomic; existing notes cannot be appended, so an explicitly requested repeat completion can be saved separately. Scheduling requires a supported client.

## Terminology

- `journal entry`, `note`, `review`, and `record` refer to one item.
- `records` refers to a collection of journal entries and notes.
- `journals/`, `notes/`, `reviews/`, and `images/` refer to actual directories. Directory names are always lowercase, plural, wrapped in backticks, and include a trailing slash.
- Skill names follow their operation: `capture-record` writes one record, while `recall-records` and `review-records` may work across multiple records.

## Language support

The interface, tool names, and public metadata are English-first. Record content is multilingual: titles, Markdown bodies, source text, quotations, and filename keywords may use Unicode and keep the user's original language and code-switching. Capture tools do not translate unless the user explicitly asks. Recall and review responses follow the language of the current request while preserving source-language quotations.

New journal filenames use `{YYYYMMDD}.md` without a topic keyword or language-specific weekday. New note filenames retain `{YYYYMMDD}-{keyword}.md`; older journals keep their filenames and receive same-day appends. Filename keywords support Unicode letters, combining marks, and numbers. Image attachments accept an optional `alt` description in the user’s language, falling back to the filename stem or an empty description. See the [file naming guide](docs/file-naming.md).

Example requests include “Dear diary, today...”, “Save this thought: ...”, “What stood out this week?”, and “What did I write about moving?” These are English examples, not a requirement to write records in English.

## Safety boundaries

- The source repository contains no personal records or credentials.
- The server can only read `journals/`, `notes/`, and `reviews/`. Reviews must be requested explicitly and are excluded from default reads and searches.
- New records are written only inside those three directories. Reviews are create-only; source paths must identify existing journals or notes within the reviewed period.
- Existing note files are never silently overwritten.
- If more than one journal file exists for a date, the write stops instead of guessing.
- Each capture accepts up to five image attachments. Images are resized to fit within 2048 × 2048 pixels, metadata is removed, and the processed file must be no larger than 10 MB.
- GitHub credentials are read from the environment and are never written into records.

## Connect to the hosted MCP

The hosted Capture & Reflect MCP is available at:

```text
https://api.bysunling.com/mcp
```

A supported remote MCP client can connect to this endpoint and complete OAuth. On first use, Capture & Reflect provides a secure GitHub setup link so the user can authorize the GitHub App, choose the repository where records should live, and save the detected time zone.

### Account selection during Connect

For GitHub account and repository selection before returning to ChatGPT, enable the optional [Standalone Connect flow](docs/standalone-connect.md). This requires WorkOS configuration, a server API key, a GitHub callback and email permission, and explicit migration of existing identities. Deploying code alone does not enable it. Once activated, disconnecting and reconnecting the plugin starts GitHub account selection; the separate setup tool remains available for repository changes within that account.

### Switch GitHub accounts with the original hosted-auth flow

Ask “Switch the GitHub account for my records”. The client calls `get_github_account_switch_link` and returns a fresh link that opens GitHub's account picker directly. Select or sign into the desired account, then choose a repository and click **Save & connect**. The general `get_github_setup_link` page also shows the current username and **Use a different GitHub account**. Grant the GitHub App access to that repository if needed.

Disconnecting the plugin in ChatGPT does not clear the server's saved GitHub connection. Account switching uses GitHub's account picker and does not require clearing browser cookies. The old connection remains until authorization succeeds; successful reauthorization clears the previous repository selection, so a repository must be selected before captures resume. Existing records stay in their original repository.

### Claude

In Claude:

1. Open **Customize → Connectors**.
2. Choose **Add custom connector**.
3. Name it `Capture & Reflect` and use `https://api.bysunling.com/mcp` as the MCP URL.
4. Connect and complete OAuth.
5. The first time you save a record, follow the GitHub setup link and choose your records repository.

### ChatGPT

In ChatGPT with Developer mode available:

1. Open **Settings → Security and login** and enable **Developer mode**.
2. Open **Plugins** and create a developer plugin connected to the hosted MCP endpoint.
3. Use `https://api.bysunling.com/mcp` as the MCP URL, then complete OAuth and tool scanning.
4. The first time you save a record, follow the GitHub setup link and choose your records repository.

Once connected in either client, try: “Dear diary, today...”, “Save this thought: ...”, “What stood out this week?”, or “What did I write about moving?”

The same hosted MCP can be used by other AI clients that support remote MCP with OAuth.

## Local development with ChatGPT

For local development with ChatGPT, use the local HTTP server plus ChatGPT's Secure MCP Tunnel. This keeps the unauthenticated development endpoint on your own computer.

Requirement: Node.js 22 or later. A local clone of your records repository is needed only for local storage.

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

For backward compatibility, the default local path remains `~/.log-reflect/records`; it is
created on the first write. To use an existing local records repository instead, set its absolute path as
`RECORDS_REPO_PATH` in `.env`.

### Store records directly in GitHub

Create a fine-grained personal access token for only the records repository. Grant it
**Contents: Read and write**; no broader account or organization permissions are needed. Keep
the repository private if the records are personal, and put the following values in `.env`:

```bash
RECORDS_STORAGE=github
RECORDS_GITHUB_REPOSITORY=YOUR_GITHUB_USERNAME/YOUR_RECORDS_REPOSITORY
RECORDS_GITHUB_TOKEN=github_pat_...
RECORDS_GITHUB_BRANCH=main
RECORDS_TIME_ZONE=America/Los_Angeles
```

Each capture creates a GitHub commit immediately. Journal
fragments for the same day are appended to the existing file with conflict retries; an existing
note is never overwritten. Reading and search remain limited to `journals/`, `notes/`, and explicitly requested
`reviews/`.

The GitHub token used by this MCP server is separate from any GitHub connector authorization in
an AI client. Never commit `.env`; it is already excluded by `.gitignore`.

Load the environment and start the Streamable HTTP endpoint:

```bash
set -a
source .env
set +a
npm run start:http
```

Check that it is running:

```bash
curl http://127.0.0.1:3000/health
```

Next, create a tunnel in [OpenAI Platform tunnel settings](https://platform.openai.com/settings/organization/tunnels), run `tunnel-client` on this computer, and configure its HTTP target as:

```text
http://127.0.0.1:3000/mcp
```

Keep both `npm run start:http` and `tunnel-client run --profile <your-profile>` running. Then open **Settings → Security and login → Developer mode** in ChatGPT. On the [ChatGPT Plugins page](https://chatgpt.com/admin/plugins), create an app, choose **Tunnel**, and select or paste your `tunnel_id`. See the [Secure MCP Tunnel guide](https://developers.openai.com/api/docs/guides/secure-mcp-tunnels) for installing and initializing `tunnel-client`.

Once connected, try: “Dear diary, today...”, “Add this photo to today's diary”, “Save this thought: ...”, “What stood out this week?”, or “What did I write about moving?”

### ChatGPT plugin packaging

The first ChatGPT connection creates an app identifier such as `plugin_asdk_app...`. That identifier is intentionally not committed here. It can later be placed in `.app.json` when packaging the final installable plugin.

Official references: [Build an MCP server](https://developers.openai.com/plugins/build/mcp-server), [connect it to ChatGPT](https://developers.openai.com/plugins/deploy/connect-chatgpt), and [package a plugin](https://developers.openai.com/plugins/build/plugins).

## Photo attachments

In a supported AI client, attach one or more images to the message that asks to record a journal entry or save a note. Supported source formats are JPEG, PNG, WebP, HEIC, and AVIF. The client passes a temporary file URL to the plugin, which normalizes the image and stores it beside the Markdown record:

```text
journals/{YYYY}/{YYYYMM}/images/
notes/{YYYY}/{YYYYMM}/images/
```

The record contains relative Markdown image links, so it remains portable when the records repository is cloned or viewed on GitHub. Original EXIF metadata is not retained. Non-image attachments are rejected in this version.

> The local HTTP endpoint uses no authentication and binds to `127.0.0.1` by default. Do not expose it directly to the public internet. The Netlify entrypoint under `netlify/functions/` is the authenticated production endpoint.

## Hosted production deployment

The production architecture uses WorkOS AuthKit for MCP OAuth, a GitHub App for per-user repository access, Supabase for encrypted connection metadata, and Netlify Functions for the public HTTPS endpoint. Journal bodies and images are written directly to the repository selected by the user; they are not copied into Supabase.

1. Create a WorkOS AuthKit project. Enable CIMD and dynamic client registration, set the resource indicator to the stable public origin, and configure that origin as the default resource.
2. Create a public GitHub App with **Contents: Read and write** and **Metadata: Read** repository permissions. Enable expiring user tokens. Set the callback URL to `/github/callback` and setup URL to `/github/installed` on the public origin.
3. Create a dedicated Supabase project and apply `supabase/migrations/20260901051620_create_user_connections.sql`.
4. Create a Netlify site from this repository, attach the stable custom domain, and configure every variable in `.env.production.example` as a secret environment variable.
5. Connect `https://YOUR_DOMAIN/mcp` in a supported AI client, complete any required domain verification, scan the tools and Skills, and run the review test cases.

When a user saves a repository connection, Capture & Reflect initializes any missing canonical directories with harmless `.gitkeep` files:

```text
notes/
journals/
reviews/
```

Git does not track empty directories, so these marker files make the structure visible before the first record. Existing files are never replaced. A repository with no commits is initialized on its default branch.

## Scheduled reviews

The MCP server is passive: it exposes record and review capabilities but does not wake itself up on a schedule. The simplest hosted workflow is a scheduled task in a supported AI client that periodically invokes the `review-records` Skill, reads the chosen date range with `get_records_by_date_range`, and returns the review.

When no period is specified, reviews default to the last seven calendar days including today in the configured time zone (today minus six days through today). User-specified ranges or named periods take precedence. Omit both `from` and `to` on `get_records_by_date_range` to use the server default, or provide both for a custom inclusive range. The response includes the resolved `from`, `to`, and `timeZone`; reuse those dates when saving.

The review skill finishes by calling `save_review` unless the user requests chat-only output. Reviews are saved as `reviews/YYYY/YYYYMM/FROMYYYYMMDD-TOYYYYMMDD-keyword.md`, with the save date, reviewed range, source paths and links, and the full review body. The directory uses the save date; the filename uses the reviewed range and a topic keyword in the user’s language, for example `reviews/2026/202609/20260905-20260911-after-plans-changed.md`. Existing reviews retain their filenames. Source links reference current entries rather than immutable snapshots. User thoughts remain distinct from AI interpretations. Empty periods are not saved; sparse evidence is labeled. Existing reviews are never overwritten. Retrieve earlier reviews with `types: ["review"]`; date filters use the save date, while the reviewed period is stored in `from`/`to` metadata. A self-hosted alternative is a Netlify Scheduled Function plus an AI model call, but that adds model credentials, scheduling, retries, and delivery handling to this service.

Never expose `SUPABASE_SECRET_KEY`, `GITHUB_CLIENT_SECRET`, `TOKEN_ENCRYPTION_KEY`, or `SETUP_TOKEN_SECRET` to a browser. Generate the latter two independently with a cryptographically secure random generator.

## Local stdio setup

Requirements: Node.js 22 or later.

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

Optionally set the absolute path to an existing records repository. If it is omitted, the
server uses `~/.log-reflect/records`:

```bash
RECORDS_REPO_PATH=/absolute/path/to/capture-reflect-practice
```

Build and start the stdio server (for Claude Desktop, Codex, and other local MCP clients):

```bash
npm run build
RECORDS_REPO_PATH=/absolute/path/to/capture-reflect-practice npm run start:stdio
```

## Example client configuration

After building, point an MCP client at the compiled server:

```json
{
  "mcpServers": {
    "capture-reflect": {
      "command": "node",
      "args": ["/absolute/path/to/capture-reflect-mcp/dist/src/server.js"],
      "env": {
        "RECORDS_REPO_PATH": "/absolute/path/to/capture-reflect-practice",
        "RECORDS_TIME_ZONE": "America/Los_Angeles"
      }
    }
  }
}
```

For GitHub-backed stdio, replace `RECORDS_REPO_PATH` in the client environment with
`RECORDS_STORAGE`, `RECORDS_GITHUB_REPOSITORY`, `RECORDS_GITHUB_TOKEN`, and
`RECORDS_GITHUB_BRANCH` as shown above.

## Development

```bash
npm run check
npm test
```

Run the weekly review flow through the built HTTP server:

```bash
npm run test:e2e:review
```

This starts a separate server on a temporary localhost port and uses a scripted MCP client to initialize, capture test notes and a journal, read two date ranges, reproduce source-validation errors, save a corrected review, read it back, and verify overwrite protection. It checks HTTP 200 separately from MCP `isError`, verifies the saved Markdown on disk, and prints per-request timings. The test uses an isolated temporary records directory, does not load `.env`, and stops the server and removes test records afterward. It requires permission to bind a localhost port. It does not exercise AI generation, live GitHub, hosted authentication, or the Netlify runtime.

To run the same HTTP checks with real GitHub records, authenticate `gh` with read access to the repository, then run:

```bash
npm run test:e2e:review -- --github sunling/sunling-os
```

This regression scenario reads journals and notes dated September 1–14, 2026 through `GitHubRecordsStore`, using September 8–14 as the reviewed period and September 1–7 as comparison material. It requires records in both periods. The script copies exact contents and paths into temporary local storage and verifies HTTP reads against the fetched contents. GitHub requests are restricted to reads; all review saves happen locally. It prints counts, sizes, and timings without printing real filenames or bodies on a successful test run. The review body is a test inventory, not an AI-generated personal review. No GitHub credential is passed to the local HTTP server.

To inspect the tools interactively:

```bash
npx @modelcontextprotocol/inspector node dist/src/server.js
```

## Roadmap

- Add MCP resources for reading individual records.
- Complete domain verification, privacy policy, tool scanning, test prompts, and ChatGPT plugin review.
- Add scheduled reflection and automated Bubble Breaker delivery.