Skip to main content
Glama
deenesjakoruzh
sunling

log-reflect-mcp

by sunling
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

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 journals 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 log-reflect-practice:

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

Current scope

The local server exposes four record tools. The hosted service also exposes a secure setup tool:

  • capture_journal: create or append a personal journal fragment, with optional photos.

  • capture_note: save a Markdown note, with optional photos.

  • get_records_by_date_range: retrieve journal entries and notes for review.

  • search_records: search record contents.

  • get_github_setup_link: authorize a GitHub App and choose a per-user records repository.

The MCP server handles access and storage. It publishes three focused Agent Skills through the MCP Skills extension so ChatGPT can discover their instructions and resources:

  • capture-records: route a journal entry or note, preserve the user's voice, and pass uploaded photos through.

  • review-records: review a date range using evidence from the stored records.

  • recall-records: search before answering questions about earlier records.

Related MCP server: ai-journal

Language support

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

Examples include “记录一下今天发生的事”, “Save this reflection”, “今日のメモを保存して”, and mixed-language notes.

Safety boundaries

  • The source repository contains no personal records or credentials.

  • The server can only read journals/ and notes/.

  • New records are written only inside those two directories.

  • 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 ChatGPT Developer Mode

The quickest private test uses 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

By default, records are stored under ~/.log-reflect/records, which 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/ and notes/.

The GitHub token used by this MCP server is separate from any GitHub connector authorization in ChatGPT. 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: “帮我记录今天的日记”“把这张照片放进今天的日记”“保存一条笔记”“回看我最近七天的记录” or “搜索我以前关于搬家的记录”.

Photo attachments

In ChatGPT, 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 plugin downloads the temporary ChatGPT file URL, 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 ChatGPT, complete the domain verification challenge, scan the tools and Skills, run the review test cases, and submit the plugin for review. Scan again after every deployed tool or Skill change because ChatGPT imports a snapshot.

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 ChatGPT scheduled task that periodically invokes the review-records Skill, reads the chosen date range with get_records_by_date_range, and returns the review in ChatGPT.

At present, scheduled reviews are read-only and are not written back to the records repository. Persisting them under reviews/ requires a separate, narrowly scoped save_review MCP tool. 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.

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.

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/log-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/log-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/log-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

To inspect the tools interactively:

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

Roadmap

  • Add MCP resources for reading individual records.

  • Add an explicit develop-practice workflow after the review and recall Skills have been exercised in real use.

  • Complete domain verification, privacy policy, tool scanning, test prompts, and ChatGPT plugin review.

  • Add scheduled reflection and information-bubble-breaker workflows.

Available Tools

4 tools
capture_inputC

Save an external input such as an article, book, podcast, video, course, or conversation as a Markdown note.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoYYYY-MM-DD; defaults to today
tagsNo
titleYes
sourceNo
contentYesMarkdown note body
keywordYesFilename keyword without spaces or slashes

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must disclose side effects and expectations. It only says 'Save' without explaining write privileges, overwrite behavior, filing conventions, or response format. The saved note's storage details are entirely omitted, leaving an agent unaware of potential errors or constraints beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence, front-loading the primary action. It avoids redundancy and is easy to scan. It loses a point for omitting any structural hints about optional fields or examples that would aid comprehension.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 6 parameters and no output schema or annotations, the description is far too minimal. It does not explain the purpose of filename keyword constraints, source handling, tag limits, or how the note is persisted. An agent would need additional information to correctly invoke all parameters.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description adds no parameter-specific guidance. Schema coverage is 50% (only date, content, keyword have descriptions), and the tool description fails to clarify the roles of title, source, or tags, or to supplement what the schema does provide. The phrase 'Markdown note' hints at content, but not enough to compensate for the coverage gap.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states a specific verb ('Save'), a resource ('external input'), and the output format ('Markdown note'). It lists example inputs (article, book, podcast) making the purpose unambiguous. However, it does not explicitly distinguish from sibling 'capture_journal', so it loses some differentiation credit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives. The description does not mention capture_journal or any conditions for selecting this over other capture/search tools. An agent would not know whether this is appropriate for a specific scenario without further inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

capture_journalB

Create or append a personal journal fragment. Supply lightly edited content that preserves the user's words and uncertainty.

ParametersJSON Schema
NameRequiredDescriptionDefault
dateNoYYYY-MM-DD; defaults to today
titleYesShort factual fragment heading
contentYesMarkdown journal body without summaries or tags
keywordYesFilename keyword without spaces or slashes

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It does reveal a write operation ('create or append') and a light-editing philosophy, which is genuine behavioral context. However, it does not disclose how the tool decides append vs. create, whether it is idempotent, auth requirements, or what it returns — gaps that matter for a write tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with no filler. The purpose is front-loaded in the first sentence, and the second sentence carries the only substantive addition (editing guidance). Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 4-parameter write tool with no annotations and no output schema, the description is thin but the schema is fully self-documenting. The main gaps are the append-vs-create decision logic and the missing differentiation from capture_input in the sibling set, neither of which the schema can compensate for.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3 even without parameter detail in the description. The description reinforces the content parameter's meaning via 'lightly edited content,' but adds nothing about keyword-as-filename, date defaults, or title that the schema already explains. It does not exceed the baseline.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Create or append a personal journal fragment.' This clearly separates it from the read-oriented siblings get_records_by_date_range and search_records. However, it does not distinguish itself from the near-namesake capture_input, leaving the agent to guess how journal capture differs from general input capture.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The instruction to 'Supply lightly edited content that preserves the user's words and uncertainty' provides useful guidance on how to phrase the content body. But there is no when-to-use guidance versus capture_input, and no conditions under which one should be preferred over the other, so an agent selecting between the two capture tools gets no help.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_records_by_date_rangeA

Read journal and input records within an inclusive date range.

ParametersJSON Schema
NameRequiredDescriptionDefault
toYesInclusive end date in YYYY-MM-DD
fromYesInclusive start date in YYYY-MM-DD
typesNo

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full behavioral disclosure burden. It states the operation is a read and that the date range is inclusive, but it does not mention return format, pagination, default behavior when 'types' is omitted, or error handling.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence with no filler. The verb and resource appear immediately, and every word ('inclusive', 'date range') adds relevant meaning.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no annotations and no output schema, the description leaves the return shape and default behavior unstated, and the relationship to search_records is unexplored. Still, for a straightforward date-range read, the schema plus description provides a minimally viable definition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema already documents from/to with inclusive YYYY-MM-DD formats. The description adds that records are journal/input, which aligns with the optional types enum, but does not clarify the default filtering behavior when types is omitted. With 67% schema coverage, the description partially compensates but not fully.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a clear verb ('Read') and resource ('journal and input records') with a date-range scope, making the tool's query purpose obvious. It distinguishes itself from the capture_* siblings by being a read operation, though it does not explicitly contrast with search_records.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use the tool: when records need to be read within an inclusive date range. However, it provides no explicit exclusions or alternatives, leaving the choice between this tool and search_records to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_recordsC

Search journal and input Markdown files for matching text.

ParametersJSON Schema
NameRequiredDescriptionDefault
toNo
fromNo
limitNo
queryYes
typesNo

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden of behavioral disclosure. It only states the tool searches for matching text but does not disclose case sensitivity, exact vs. fuzzy matching, result ordering, pagination, or any side effects. The agent is left without critical runtime behavior information.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that is front-loaded with the core action and target. It is efficient in word count, but it omits essential details, so while it is concise, it is not comprehensive. It earns a 4 for brevity without waste, but lacks the structural depth expected for a tool with multiple parameters.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 5 parameters, no output schema, and no annotations, the description is grossly incomplete. It fails to explain how to form a query, what valid input types are, the semantics of date filters, or the response format. An agent would struggle to invoke this tool correctly without further information.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 0% description coverage, and the description does not explain any of the five parameters. It does not clarify what 'query' means, how 'from'/'to' are formatted, what 'limit' controls, or how 'types' restricts the search. The only loose hint is 'journal and input' which vaguely maps to the types enum, but this is not explicit.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool searches journal and input Markdown files for matching text, specifying both the action and the resource types. However, it does not differentiate from sibling tools like get_records_by_date_range, which could also involve searching or retrieving records, so it lacks distinguishing context.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no guidance on when to use this tool versus alternatives. It does not mention any conditions, prerequisites, or scenarios where this search tool is preferred over capture or date-range retrieval tools. The agent receives no help in selecting the correct tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.4/5.0
Disambiguation5/5

Each tool has a unique, non-overlapping purpose: capturing journal entries vs. external inputs, and reading by date vs. searching by text. The boundaries are clear, and an agent would rarely misselect between them.

Naming Consistency5/5

All tools use a consistent snake_case verb_noun pattern. 'get_records_by_date_range' is slightly longer but still follows the same style as 'capture_journal' and 'search_records', with no mixed conventions.

Tool Count5/5

With 4 tools, the server is well-scoped for its purpose of logging and retrieving reflections. Each tool serves a necessary function, and the count is neither too thin nor bloated.

Completeness4/5

The set covers the core capture and retrieval workflows for journaling and external inputs. Minor gaps exist (e.g., no explicit update/delete, no single-record get by ID), but agents can work around these via search and date-range queries.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • ai-journal

    solentlabs
    A
    license
    Not graded
    quality
    B
    maintenance
    A local MCP server for journaling, organizing, and recalling your work. It captures entries as plain markdown files, indexes them for full-text and structured search, and enables querying via natural language.
    1
    MIT

  • mcp-ltm

    kvas-it
    A
    license
    Not graded
    quality
    D
    maintenance
    Provides persistent long-term memory for AI assistants with tag-based retrieval, wiki-style linking, and source references, storing memories as markdown files with SQLite index.
    1
    MIT

  • txt-to-md-mcp

    ASTLY123
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables writing text content to Markdown files with folder organization and overwrite control, and listing recent Markdown files.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/sunling/capture-reflect-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server