convez.ai
MCP ServerProdutividadeIntermediário
pariksheet

Plannen — Planejador IA Local-First

pariksheet/plannen

Planejador IA que aprende suas preferências e vive no seu computador

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que expõe um planejador inteligente com armazenamento local e aprendizado de preferências. Integra-se ao Claude Desktop e Claude Code para acessar eventos, perfil pessoal e histórico de forma persistente, sem enviar dados para a nuvem.

Instalação

$npx convez-ai pariksheet/plannen

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
0
Forks
0
Acompanhando
0
Saúde
100%
Último commit
há 1 mês
Versão
v0.10.6
Issues abertas
8
Contribuidores
1

Casos de uso

  • Planejar eventos e atividades personalizadas com histórico de preferências familiares
  • Integrar agenda inteligente ao Claude Desktop com contexto persistente
  • Transformar eventos em memórias e narrativas com aprendizado contínuo

Veredito

MCP server bem arquitetado que leva a sério privacidade e aprendizado contextual. A abordagem local-first é rara e valiosa; o design de perfil que extrai fatos naturalmente é inovador. Recomendado para quem valoriza controle de dados e planejamento personalizado.

README

A tradução para o português deste README ainda está na fila.

Plannen is a local-first AI planner. It knows your preferences and past events, helps you schedule what's next, and turns memorable moments into stories. Use it through the web app, or just talk to it from Claude Code or Claude Desktop — both surfaces drive the same database via an MCP server.


Why it works

Two pieces do the heavy lifting:

An MCP server. Plannen ships an MCP server that exposes its data layer — events, profile facts, family members, locations, sources, stories — as tools Claude Code and Claude Desktop can call directly. You don't talk to a bespoke chatbot; you talk to Claude in whatever client you already use, and Claude reaches into Plannen via MCP. The web app uses the same service functions, so the two surfaces stay in lockstep.

A profile that learns. Every time you mention something durable about yourself or your family in natural conversation — "my son just turned 6", "we prefer apartments over hotels", "no highway charging when the kids are in the car" — Plannen passively extracts the fact and saves it. The next time Claude plans something, it knows. Suggestions become personal: "his school finishes Wednesday at 12:00, want a sports option that runs 13:00–15:00?" rather than generic "here are some sports classes in Belgium".


Deployment modes

Pick one at init time; switch later by re-running init.

ModeWhat it isWhen to use
local_pgEmbedded Postgres + Plannen's own Hono backend. Node-only, no Docker.Default. Fastest path; everything on your machine.
local_sbLocal Supabase stack (Postgres + Auth + Storage + Edge Functions) via Docker.You want the full Supabase surface locally.
cloud_sbSupabase Cloud project (DB + Storage + Edge Functions + remote MCP).You want browser access from anywhere, or to deploy to Vercel.

Prerequisites

NeedForInstall
Node.js ≥ 20 LTSAll modesbrew install node
Claude Code or Claude DesktopThe AI interfaceclaude.com/claude-code
A container runtime (Docker, Colima, OrbStack)local_sb onlyper-tool docs
Supabase CLI ≥ 2.0local_sb, cloud_sbbrew install supabase/tap/supabase
A Supabase Cloud project + supabase logincloud_sb onlydashboard → new project

Quick start

git clone <repo-url> plannen
cd plannen
npm install
npx plannen init --mode=local_pg --email you@example.com
npx plannen up

Open http://localhost:4321. For the other modes, swap --mode=local_sb or --mode=cloud_sb (the cloud variant is interactive — it picks your project and asks for the DB password).

init is idempotent. Re-run any time. If something gets broken, /plannen-doctor (inside Claude Code) will diagnose and suggest a fix.

CI flags: npx plannen init --help.

Daily workflow

npx plannen up             # db + backend + web dev
npx plannen up --no-dev    # headless: db + backend only (MCP/Claude use case)
npx plannen status         # what's running for the active profile
npx plannen down           # graceful shutdown

All sub-steps are idempotent, so re-running on a live stack is a no-op.

For auto-start at login (macOS LaunchAgent) and per-mode troubleshooting, see docs/OPERATIONS.md.

Profiles

A profile is a named bundle of mode + env settings. plannen init creates one called default and points <repo>/.env at it via symlink. You only need extra profiles when you want to run a second environment (e.g. a staging cloud setup) alongside your daily one.

npx plannen profile list                              # show all profiles, mark active
npx plannen profile create staging --mode=cloud_sb    # second cloud profile
npx plannen profile use staging                       # swap the .env symlink
npx plannen up --profile=default                      # one-off, doesn't change active
npx plannen profile delete staging --yes              # irreversible

Profile state lives under ~/.plannen/profiles/<name>/. The active pointer is ~/.plannen/active, or override per-shell with PLANNEN_PROFILE=<name>.


Deploying to Vercel (cloud_sb)

npm i -g vercel && vercel login
npx plannen deploy

(vercel link is run automatically by plannen deploy if .vercel/ doesn't exist.)

Post-deploy checklist (custom SMTP, custom domain, Google OAuth callback) lives in docs/VERCEL.md.


AI provider (web-app features only)

Open /settings and pick one:

  • Claude Code CLI (local_pg only). If claude is in your PATH, the backend auto-detects it and routes AI calls through your subscription. No API key required.
  • Anthropic API key (BYOK). Paste a key from console.anthropic.com. Stored locally, never leaves your machine. Works on all modes.

Skip this if you only drive Plannen via Claude Code or Claude Desktop — MCP slash commands work without anything in /settings.


Slash commands (in Claude Code)

After the plugin is installed:

CommandWhat it does
/plannen-doctorDiagnose env, DB, MCP, plugin, AI key, Google keys.
/plannen-setupRe-config .env (email, Supabase URL/keys, Google OAuth).
/plannen-write-story <event>Compose a story from event memories and photos.
/plannen-organise-photos <event>Drive the Google Photos picker for an event.
/plannen-discover <query>Find events from saved sources + web search.
/plannen-check-watchesForce-process the watch queue now.
/plannen-backupRun scripts/export-seed.sh.

The plugin also bundles always-on workflow skills (event-creation intent gate, profile extraction, source analysis, etc.) — see plugin/skills/.

For plugin scope (user vs project) and Claude Desktop registration, see docs/PLUGIN.md.

Connect Plannen to claude.ai (web, Desktop, mobile, Chrome)

Tier 2 installs can register the Plannen MCP as a claude.ai custom connector:

  1. npx plannen cloud oauth enable --profile prod (provision runs this automatically for new installs)
  2. claude.ai → Settings → Connectors → Add custom connector → paste the printed URL
  3. Click Connect — log in with your Plannen account and approve

The connector then works across claude.ai web, Claude Desktop, mobile, and Claude in Chrome. The Claude Code plugin is unaffected — it keeps its plnnn_ token from plugin.json.

MCP server modes

  • stdio (default) — mcp/src/ Node process. Used by local_pg and local_sb.
  • HTTP (default on cloud_sb) — supabase/functions/mcp/ Deno Edge Function, personal-access-token auth.

Switch with bash scripts/mcp-mode.sh stdio|http. The HTTP MCP does not include transcribe_memory (needs local Whisper). Use stdio if you need audio transcription.

MCP Personal Access Tokens

Each user has their own PAT — like a GitHub PAT, but for Plannen. PATs scope every MCP call to the issuing user; RLS handles the rest.

Admin / dev (you have DB access)

npx plannen token create --label "MacBook"

Mints a plnnn_… token, writes it to your active profile's env, and rewires plugin/.claude-plugin/plugin.json. Reload the plannen plugin in Claude Code.

Inviting another user (they don't have DB access)

  1. Share your deployment's SUPABASE_URL + anon key.
  2. They run npx plannen profile create --mode cloud_sb and sign in via magic link at the deployment's web URL.
  3. /settings → "Personal access tokens" → Generate, save the plaintext.
  4. npx plannen token activate <PAT> — wires their plugin.

Verbs

VerbWhat it does
plannen token create --label <name>Mint a new PAT, wire it into active profile + plugin.json
plannen token listShow your tokens (no plaintext)
plannen token revoke <id>Revoke a token
plannen token activate <PAT>Wire a PAT from /settings into active profile + plugin.json
plannen token rotateRevoke current PAT, mint a fresh one

Backups

bash scripts/export-seed.sh

Writes supabase/seed.sql + supabase/seed-photos.tar.gz (both gitignored). To restore: drop both into supabase/, run npx plannen init again, then bash scripts/restore-photos.sh.

Never run supabase db reset on local_sb — it wipes the database. Use supabase migration up instead.


Optional integrations

Google Calendar / Photos / Drive setup (Cloud Console + OAuth callback per mode) is in docs/INTEGRATIONS.md.


Project layout

plannen/
├── src/                  # React app (Vite + TypeScript)
├── mcp/                  # MCP server (pg.Pool + withUserContext)
├── backend/              # Hono backend (used by local_pg)
├── plugin/               # Claude Code plugin (skills + commands)
├── cli/                  # `plannen` CLI (init, up, down, status, profile)
├── supabase/
│   ├── migrations/       # Main schema (source of truth)
│   ├── functions/        # Edge functions
│   └── seed*.{sql,tar.gz}  # Personal data backups (gitignored)
├── scripts/              # Lower-level helpers the CLI delegates to
└── docs/                 # Design docs and architecture notes

Tips

These aren't Plannen-specific — general practice for anyone using Claude or running a local-first app with personal data.

Don't share your Claude sessions for model training. API keys are excluded by Anthropic's commercial policy. If you sign Claude Code into a claude.ai subscription instead, open claude.ai/settings/privacy and turn "Help improve Claude" off.

Cap your Anthropic spend. console.anthropic.com → Workspaces → create one → set a monthly spend limit → generate a key scoped to that workspace. If a key leaks, blast radius is bounded.

Back up your data. bash scripts/export-seed.sh writes the two seed files; copy them somewhere safe. Encrypt if you upload to a cloud provider.

Ver o original no GitHub

Bom para

Relacionados