Margin

Margin is an MCP server that quietly notices what you did today -- commits, notes, document edits -- and offers a short, Scripture-grounded reflection tied to your day. No manual input needed. Just a gentle acknowledgment of the day, verified against real Scripture, woven together with a fact about an unreached people group somewhere in the world.

Built for the Scripture in New Frontiers Kaggle hackathon.

How it works

1. Watchers log a short summary of activity (git commits, file edits) -- never file contents, never verse text.
2. On your chosen schedule (once a day, a few times a day, only on notable milestones, or after every save), Margin infers a theme from the day's events, gets a real verse suggestion and canonical text via Gloo + Canon (which calls the YouVersion Platform API), pulls a fact about an unreached people group, and writes a reflection connecting the day, the verse, and the people group -- all grounded only in what actually happened and what Canon actually returned. When activity is very thin (three words or fewer), the theme is picked from a local seed list rather than calling Gloo; verse selection, Scripture verification, and reflection writing still go through Gloo and Canon.
3. A React frontend polls the server and shows the day's timeline and reflection. Verse text is fetched live on-demand -- never cached to disk.
4. The day closes exactly once -- at 11:59pm local time, or via "Wrap up my day" (with confirmation). The end-of-day reflection always considers everything logged that day.
5. You can save reflections that mean something and revisit past days in an archive.

Setup

Quick start

git clone https://github.com/XcellentProgramming/margin.git
cd margin
./scripts/install.sh

This installs Node.js if it's missing (asks first), installs all dependencies, prompts you for credentials in the terminal (Gloo Client ID/Secret, Gloo Token URL, Canon MCP URL, Canon Auth Token), and starts Margin once everything's filled in. Safe to re-run -- it won't re-prompt for values already set.

Prerequisites

• Node.js 20+
• A Gloo AI Studio account with API credentials
• Access to the Canon MCP server

A note on Canon access: Canon is a server maintained for this project (source available here). To run Margin locally with full functionality, email tech@joshuaproject.net for a Canon access token.

Manual setup

If you'd rather set things up by hand instead of using install.sh:

git clone https://github.com/XcellentProgramming/margin.git
cd margin
npm install
cd frontend && npm install && cd ..
cp .env.example .env

Fill in GLOO_CLIENT_ID, GLOO_CLIENT_SECRET, GLOO_TOKEN_URL, CANON_MCP_URL, and CANON_AUTH_TOKEN in .env. Margin fails honestly if these aren't set -- it never falls back to placeholder Scripture content.

Run

./scripts/dev.sh

Starts the backend (port 3900) and frontend (http://localhost:5173) together. If it needs to stop cleanly, run ./scripts/stop.sh.

Connect the watchers

Git commits -- add to .git/hooks/post-commit in any repo you want watched:

node /path/to/margin/watchers/log-commit.js

Files (note, docs, code):

node watchers/fileWatcher.js /path/to/folder/you/want/watched

Test

./scripts/test.sh

For the watchers specifically:

node scripts/testWatchers.js           # confirms both watchers log events correctly
node scripts/demoFileToReflection.js   # full pipeline demo: edit/commit -> logged event -> real reflection

MCP tools exposed

Tool	Purpose
logActivity	Records an event (called by watchers). Refuses once the day is closed.
getDailyReflection	Generates the reflection. Pass { closeOutDay: true } to archive and lock the day.
getProgressCheck	Mid-day checks. Auto-triggers based on frequency setting (checkpoints or notable-event detection).
getEncouragement	Mid-day encouragement pop-ups.
setPreferences / getPreferences	Frequency and quiet-hours settings.
getHistory	Past days' archived reflections.
saveReflection / unsaveReflection / getSavedReflections	Save/unsave/list kept reflections.
getVerseText	Fetches verse text live from Canon on demand -- never cached.

Design principles

• No verse text is ever cached -- per YouVersion's terms of service.
• No mock or placeholder Scripture content, ever -- unconfigured credentials produce an honest error, not fabricated content.
• Reflections stay honest about what happened -- no inferring unstated actions, no inventing unverified facts about people groups.

LICENSE

MIT

Notice

README.md generated by Claude Sonnet 5 with edits from XcellentProgramming. Last updated: 7/29/26