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:

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 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.

Related MCP server: ai-journal

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 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.

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:

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. 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.

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:

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:

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

Check that it is running:

curl http://127.0.0.1:3000/health

Next, create a tunnel in OpenAI Platform tunnel settings, run tunnel-client on this computer, and configure its HTTP target as:

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, create an app, choose Tunnel, and select or paste your tunnel_id. See the Secure MCP Tunnel guide 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, connect it to ChatGPT, and package a plugin.

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:

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:

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.

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:

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

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

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:

{
  "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

npm run check
npm test

Run the weekly review flow through the built HTTP server:

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:

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:

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.