{"id":51115518,"url":"https://github.com/johnfire/notes-world","last_synced_at":"2026-06-24T21:31:03.416Z","repository":{"id":343945505,"uuid":"1179813017","full_name":"johnfire/notes-world","owner":"johnfire","description":"an app for your computer that  holds notes, organizes them and has an MCP, so it interfaces to AI","archived":false,"fork":false,"pushed_at":"2026-06-22T15:01:55.000Z","size":2484,"stargazers_count":1,"open_issues_count":17,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-22T15:25:26.078Z","etag":null,"topics":["docker","mcp-server","notes-app","notes-application","notes-keeper-organization-tool","notes-management-system","notes-tool"],"latest_commit_sha":null,"homepage":"https://www.christopherrehm.de","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/johnfire.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-03-12T12:07:24.000Z","updated_at":"2026-06-22T15:02:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/johnfire/notes-world","commit_stats":null,"previous_names":["johnfire/notes-world"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/johnfire/notes-world","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnfire%2Fnotes-world","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnfire%2Fnotes-world/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnfire%2Fnotes-world/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnfire%2Fnotes-world/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/johnfire","download_url":"https://codeload.github.com/johnfire/notes-world/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/johnfire%2Fnotes-world/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34750952,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-24T02:00:07.484Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["docker","mcp-server","notes-app","notes-application","notes-keeper-organization-tool","notes-management-system","notes-tool"],"created_at":"2026-06-24T21:31:02.562Z","updated_at":"2026-06-24T21:31:03.411Z","avatar_url":"https://github.com/johnfire.png","language":"TypeScript","funding_links":["https://paypal.me/christopherrehm001"],"categories":[],"sub_categories":[],"readme":"# notes-world\n\nA personal productivity dashboard that consolidates notes, ideas, tasks, and reminders into a single structured view with tags, priorities, and dependencies.\n\n## Quickstart\n\n```bash\n# 1. Bootstrap\n./scripts/setup.sh\n\n# 2. Edit .env — set POSTGRES_PASSWORD\n# 3. Run migrations\nnpm run migrate\n\n# 4. Start development servers\nnpm run dev\n# → API:    http://localhost:3001\n# → Client: http://localhost:5173\n```\n\n## Production (Docker)\n\n```bash\ncp .env.example .env\n# set POSTGRES_PASSWORD in .env\ndocker compose up --build\n# → http://\u003cyour-machine-ip\u003e:3001\n```\n\n## Tech Stack\n\n| Layer    | Tech                             |\n| -------- | -------------------------------- |\n| Frontend | React 18 + TypeScript + Vite     |\n| Styling  | Tailwind CSS (dark theme)        |\n| Backend  | Node 20 + Express 4 + TypeScript |\n| Database | PostgreSQL 16 (raw SQL)          |\n| Deploy   | Docker Compose                   |\n\n## Structure\n\n```\nnotes-world/\n├── src/\n│   ├── client/          # React frontend\n│   ├── server/          # Node/Express backend\n│   │   └── src/\n│   │       ├── domains/ # items, relationships, views\n│   │       ├── db/      # migrations, client\n│   │       └── events/  # in-process event bus\n│   └── mcp/             # MCP server for AI agent access\n├── scripts/             # setup, migrate\n├── config/              # environment configs\n├── tests/               # unit, integration, e2e\n└── *.ispec *.policy     # domain specs (source of truth)\n```\n\n## Database Backups\n\nThe Docker Compose stack includes automatic daily database backups via [postgres-backup-local](https://github.com/prodrigestivill/docker-postgres-backup-local).\n\n**Retention policy:**\n\n- 7 daily backups\n- 4 weekly backups\n- 3 monthly backups\n\nBackups are stored in `./backups/` as compressed `.sql.gz` files.\n\n### Manual backup\n\n```bash\ndocker compose exec db-backup /backup.sh\n```\n\n### Restore from backup\n\n```bash\n# 1. Stop the app (keep db running)\ndocker compose stop app\n\n# 2. Decompress the backup\ngunzip -k backups/daily/notes_world-YYYYMMDD-HHMMSS.sql.gz\n\n# 3. Restore into the database\ndocker compose exec -T db psql -U notes_world -d notes_world \u003c backups/daily/notes_world-YYYYMMDD-HHMMSS.sql\n\n# 4. Restart\ndocker compose up -d app\n```\n\n### Set backup timezone\n\nAdd `TZ` to your `.env` file (defaults to UTC):\n\n```\nTZ=America/Chicago\n```\n\n## MCP Server\n\nAn MCP (Model Context Protocol) server lets AI agents (Claude Code, Claude Desktop, Cursor, etc.) interact with your notes-world data directly.\n\n### Setup\n\n```bash\n# Build the MCP server\ncd src/mcp \u0026\u0026 npm run build\n```\n\nThe MCP server connects to the notes-world REST API, so the main app must be running.\n\n### Configure for Claude Code\n\nAdd to `.claude/settings.json` or `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"notes-world\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/notes-world/src/mcp/dist/index.js\"],\n      \"env\": {\n        \"NOTES_WORLD_API_URL\": \"http://localhost:3001\"\n      }\n    }\n  }\n}\n```\n\n### Configure for Claude Desktop\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `~/.config/Claude/claude_desktop_config.json` (Linux):\n\n```json\n{\n  \"mcpServers\": {\n    \"notes-world\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/notes-world/src/mcp/dist/index.js\"],\n      \"env\": {\n        \"NOTES_WORLD_API_URL\": \"http://localhost:3001\"\n      }\n    }\n  }\n}\n```\n\n### Available tools\n\n| Tool                | Description                                     |\n| ------------------- | ----------------------------------------------- |\n| `create_item`       | Create a new item                               |\n| `get_item`          | Get item by ID                                  |\n| `update_item`       | Update title, body, or color                    |\n| `promote_item`      | Promote untyped item to Task/Idea/Note/Reminder |\n| `archive_item`      | Archive (soft delete) an item                   |\n| `restore_item`      | Restore from archive                            |\n| `get_recent_items`  | List recently updated items                     |\n| `get_trash`         | List archived items                             |\n| `search_items`      | Full-text search across items                   |\n| `list_tasks`        | List all tasks with status/priority             |\n| `start_task`        | Move task to In Progress                        |\n| `complete_task`     | Mark task as done                               |\n| `block_task`        | Mark task as blocked                            |\n| `list_ideas`        | List ideas by maturity                          |\n| `list_notes`        | List all notes                                  |\n| `list_tags`         | List tags with usage counts                     |\n| `create_tag`        | Create a new tag                                |\n| `tag_item`          | Add a tag to an item                            |\n| `untag_item`        | Remove a tag from an item                       |\n| `get_items_for_tag` | Get items with a specific tag                   |\n| `get_tags_for_item` | Get tags on an item                             |\n| `rename_tag`        | Rename a tag                                    |\n| `delete_tag`        | Delete a tag                                    |\n| `export_tag`        | Export tag's items as markdown                  |\n| `export_untagged`   | Export untagged items as markdown               |\n\n## HTTPS / Reverse Proxy\n\nIn production, run behind a reverse proxy for TLS termination. Example with Caddy (auto-HTTPS):\n\n```\n# Caddyfile\nnotes.example.com {\n    reverse_proxy localhost:3001\n}\n```\n\nOr with nginx:\n\n```nginx\nserver {\n    listen 443 ssl;\n    server_name notes.example.com;\n\n    ssl_certificate     /etc/letsencrypt/live/notes.example.com/fullchain.pem;\n    ssl_certificate_key /etc/letsencrypt/live/notes.example.com/privkey.pem;\n\n    location / {\n        proxy_pass http://localhost:3001;\n        proxy_set_header Host $host;\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-Forwarded-Proto $scheme;\n    }\n}\n```\n\nThe app includes rate limiting (200 req/min per IP) and security headers via Helmet.\n\n## Development\n\n```bash\nnpm run dev              # start both servers\nnpm test                 # run all tests\nnpm run lint             # lint all code\nnpm run migrate          # apply pending migrations\n```\n\n## License\n\nProprietary — copyright © 2026 Christopher Rehm, all rights reserved. The source\nis public for transparency only; it is **not** open source and may not be used,\ncopied, modified, hosted, or deployed without prior written permission. See\n[LICENSE](LICENSE). The only authorized deployment is the hosted service at\nhttps://notes-world.christopherrehm.de. Licensing inquiries:\nchristopher.rehm.63@protonmail.com\n\n## Support\n\nIf you find this useful, a small donation helps keep projects like this going:\n[Donate via PayPal](https://paypal.me/christopherrehm001)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnfire%2Fnotes-world","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnfire%2Fnotes-world","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnfire%2Fnotes-world/lists"}