causly-server 0.0.0-stage → 1.5.1

package/.env.example

@@ -0,0 +1,120 @@
+# All tokens below are optional — filesystem, git, shell, Terraform, and Docker
+# tools work with no configuration at all. Add only the ones for services you
+# plan to use. See README.md and the docs site for setup details per service.
+
+# GitHub — repo/issue/PR tools
+# Create at: https://github.com/settings/tokens?type=beta
+# Needs: Contents (read/write), Issues (read/write), Pull requests (read/write),
+# Administration (read/write, only if you want github_create_repo / github_delete_repo)
+GITHUB_TOKEN=
+
+# Vercel — project/deployment tools
+# Create at: https://vercel.com/account/tokens
+VERCEL_TOKEN=
+
+# Supabase — project/SQL tools
+# Create at: https://supabase.com/dashboard/account/tokens
+SUPABASE_ACCESS_TOKEN=
+
+# Slack — channel/message tools
+# Create a Slack app at: https://api.slack.com/apps -> OAuth & Permissions
+# Bot token scopes needed: channels:read, channels:history, groups:read, groups:history,
+# chat:write, channels:manage, groups:write (for private channel creation), users:read
+# (search:read requires a user token, not bot)
+SLACK_BOT_TOKEN=
+
+# Gmail — email tools (OAuth2, not a simple API key)
+# 1. console.cloud.google.com -> new/existing project -> enable "Gmail API"
+# 2. Google Auth Platform -> Branding (app name, support email); Audience -> External, add yourself as a test user
+# 3. Clients -> Create client -> Application type: Desktop app (not "Web application")
+# 4. Put the client id and secret below (or run: causly-server setup), then run:
+#      causly-server login google
+#    It signs you in with the browser and saves the refresh token for you.
+# 5. In Testing status the token expires after 7 days: Audience -> Publish app avoids that.
+GMAIL_CLIENT_ID=
+GMAIL_CLIENT_SECRET=
+GMAIL_REFRESH_TOKEN=
+
+# Google Calendar — event/free-busy tools (same OAuth client as Gmail works)
+# Enable "Google Calendar API" in the same Google Cloud project, then run
+# `causly-server login google`; it saves the refresh token. Client id/secret fall back to GMAIL_CLIENT_*.
+# CALENDAR_CLIENT_ID=
+# CALENDAR_CLIENT_SECRET=
+CALENDAR_REFRESH_TOKEN=
+# Optional IANA timezone for "today"/"tomorrow" and working hours (default: machine zone)
+# CAUSLY_TIMEZONE=Asia/Kolkata
+
+# Telegram — alerts and bot messages. No OAuth, just a bot token.
+# 1. Message @BotFather -> /newbot -> copy the token
+# 2. Send any message to your new bot, then call telegram_get_updates to see your chat id
+TELEGRAM_BOT_TOKEN=
+# Chat that telegram_notify writes to (your own chat id)
+TELEGRAM_CHAT_ID=
+
+# Linear — issue tools
+# Create at: Linear > Settings > Account > Security & access > Personal API keys
+LINEAR_API_KEY=
+
+# Stripe — customers, invoices, payment links, refunds. START WITH TEST MODE.
+# Create at: https://dashboard.stripe.com/test/apikeys (toggle "Test mode" on).
+# A restricted key (rk_test_...) works too; give it only the permissions you need.
+# Live keys (sk_live_/rk_live_) are refused unless STRIPE_ALLOW_LIVE=true.
+STRIPE_API_KEY=
+# STRIPE_ALLOW_LIVE=true
+# Currency used when a tool call does not give one (default usd)
+# STRIPE_DEFAULT_CURRENCY=inr
+
+# Discord — read and post in your servers. Bot token only.
+# 1. discord.com/developers/applications -> New Application -> Bot -> Reset Token
+# 2. Bot page: turn on "Message Content Intent" (needed to read other people's text)
+# 3. OAuth2 > URL Generator: scope "bot", permissions View Channels + Read Message History +
+#    Send Messages; open the URL to invite the bot to your server
+DISCORD_BOT_TOKEN=
+
+# Groq - meeting transcription (Whisper). Free tier at https://console.groq.com/keys
+# Audio is uploaded to Groq only when you confirm a meeting_transcribe call.
+GROQ_API_KEY=
+# GROQ_WHISPER_MODEL=whisper-large-v3-turbo
+# Files above this size need ffmpeg on PATH to be compressed first (default 25)
+# GROQ_MAX_FILE_MB=25
+
+# Notion — page/database/block tools
+# Create at: https://www.notion.so/my-integrations
+# Also required: open each page/database in Notion you want accessible, click
+# "..." -> Connections -> add your integration. The API only sees pages/databases
+# explicitly shared with it, even with a valid token.
+NOTION_API_KEY=
+
+# Terraform — no token needed here. Just install the Terraform CLI and make
+# sure `terraform` is on your PATH. These tools shell out to the CLI directly.
+
+# Docker — no token needed here. Tries `docker` directly first (macOS/Linux/
+# Docker Desktop), falls back to `wsl docker` on Windows if Docker only exists
+# inside WSL.
+
+# Postgres / MySQL — no persistent env var. Pass a connection string directly
+# on each call, e.g. postgres://user:pass@host:5432/dbname or
+# mysql://user:pass@host:3306/dbname
+
+# Secrets manager — local encrypted secret storage, no external service.
+# Generate a key with:
+#   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+SECRETS_MASTER_KEY=
+# Only needed temporarily while rotating the master key (see docs) — remove
+# once rotation is complete.
+# SECRETS_MASTER_KEY_NEW=
+
+# Sentry — error monitoring/issue tools
+# Create at: https://sentry.io/settings/account/api/auth-tokens/
+# Needs at least project:read + event:read; add event:write for
+# sentry_resolve_issue / sentry_ignore_issue / sentry_add_comment
+SENTRY_AUTH_TOKEN=
+
+# BoundaryAttest server receipt POC — optional and disabled by default.
+# The private key must be an operator-controlled Ed25519 PKCS #8 PEM file
+# outside the MCP client. No key or receipt directory is needed when disabled.
+BOUNDARYATTEST_ENABLED=false
+# BOUNDARYATTEST_PRIVATE_KEY=/absolute/path/to/ed25519-private.pem
+# BOUNDARYATTEST_RECEIPT_DIR=/absolute/path/to/receipts
+# Optional subset of the three POC tools (cannot expand beyond this set):
+# BOUNDARYATTEST_TOOLS=ship_change,verify_ci_fix,deploy_project

package/CHANGELOG.md

@@ -0,0 +1,126 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [1.5.1]
+
+### Changed
+- New README for the npm package: install-first quick start, architecture diagram, demo GIF, tool pack tables, configuration, Google setup, security and privacy, troubleshooting and FAQ.
+- `.env.example`: the Google setup comments now describe the `causly-server login google` flow.
+
+## [1.5.0]
+
+### Added
+- **npm package and CLI**: `npm install -g causly-server`, then `causly-server init | setup | keys | doctor [--test] | status | toolsets | backup | restore | login google | remove`. `init` adds the server to Claude Desktop, Cursor and Windsurf.
+- **Lazy tool packs**: files, directory, command and project load first; other packs load on demand. `search_tools`, `load_toolset` and `use_tool` let an agent find and call any tool without restarting the editor. `toolsets` controls which packs load at startup.
+- **Co-founder packs**: research (2 tools), leads (3), SEO and content (4, including Search Console), pipeline (9, local SQLite), calendar (8), Telegram (5), Linear (7), meetings (9: Groq Whisper transcription, action items, deal and calendar links, call prep) and reminders (3, delivered to Telegram).
+- **Safety and local data**: opt-in workspace limit (`init --workspace`), approval gate for risky actions, and a local SQLite store under `~/.causly` with `backup` and `restore`.
+- **Google sign-in**: `causly-server login google` for Gmail, Calendar and Search Console.
+- Opt-in BoundaryAttest Interop Profile v0.2 `server_attested` receipts for the `ship_change`, `verify_ci_fix`, and `deploy_project` workflow boundary, with RFC 8785/JCS redacted evidence hashes, independent expected-key verification, and focused tests. BoundaryAttest v0.1 remains legacy-only.
+- **Notion — new category, 15 tools**: search, page/database CRUD, block append/read/update/delete, comments, users. All live-tested against a real shared Notion page.
+- **Terraform — new category, 20 tools**: full lifecycle (init/validate/fmt/plan/apply/destroy/show/output/workspace), state management (state_list/show/mv/rm/pull/import/taint/untaint), graph/providers, and a CI/CD hook (`terraform_plan_comment` — posts a plan summary as a GitHub PR comment). 17/20 live-tested.
+- **Docker — new category, 18 tools**: ps/images/build/run/stop/start/restart/rm/rmi/logs/inspect/exec/stats/push/pull/compose up-down. Cross-platform — tries `docker` directly first, falls back to `wsl docker` on Windows-only-WSL setups, with automatic Windows-path-to-WSL-path translation for build context, volumes, and compose working directory. 17/18 live-tested.
+- **Generic Postgres/MySQL — new category, 8 tools**: query/list_tables/describe_table/test_connection for each engine, connection-string based. All 8 live-tested against throwaway Docker containers.
+- **Local encrypted secrets manager — new category, 6 tools**: set/get/list/delete/rotate_key/generate_key. AES-256-GCM, local file store, no external service required. All 6 live-tested including a full key-rotation cycle.
+- **Sentry monitoring — new category, 8 tools**: list_projects/list_issues/search_issues/get_issue/resolve_issue/ignore_issue/get_project_stats/add_comment. 5/8 live-tested.
+
+Total: 230+ tools, up from 106.
+
+### Changed
+- The central wrapper now owns each operation ID and supplies it to the existing audit logger so an optional receipt and normal audit event share one correlation identity. Approval and security semantics are unchanged.
+- **License: PolyForm Noncommercial 1.0.0 → MIT.** Added `"license": "MIT"` to `package.json`.
+- Removed the temporary `register/` staging folder now that all tool registrations live directly in `index.js`.
+- Removed the legacy `setup.js` helper (`causly-server init` replaces it) and moved the docs site and landing code out of this repo.
+- Updated `CONTRIBUTING.md` and `ROADMAP.md` to reflect the new tool categories and the current Azure/GCP/AWS-deferred stance.
+
+### Fixed
+- Docker: Windows-style paths (`D:\...`) passed to `docker_build`/`docker_run`/`docker_compose_*` broke when the WSL fallback path was used — added automatic path translation to WSL form (`/mnt/d/...`).
+- Secrets manager: default secrets-store path was anchored to `process.cwd()` (the server's launch directory) instead of the repo root, causing an `EPERM` in some launch configurations — now anchored via `import.meta.url`.
+- Sentry: bare `/issues/{id}/` lookups 404'd on the default API host for EU-region (data-residency) organizations even though org/project-scoped endpoints worked fine there — added automatic regional-host fallback on 404.
+
+## [1.4.0]
+
+### Added
+- **Gmail — new category, 8 tools** (OAuth2 refresh-token based): `gmail_get_profile`, `gmail_search`, `gmail_list_messages`, `gmail_get_message`, `gmail_get_thread`, `gmail_send`, `gmail_reply`, `gmail_forward`. Send/reply/forward classified `HIGH` risk (require `confirm: true`); reads classified `READ`.
+- Setup wizard and `.env.example` now document the Gmail OAuth2 flow (Google Cloud Console + OAuth Playground) and prompt for `GMAIL_CLIENT_ID` / `GMAIL_CLIENT_SECRET` / `GMAIL_REFRESH_TOKEN`
+
+### Fixed
+- `slack_list_channels` silently returning only the first page in large workspaces — now paginates via `response_metadata.next_cursor` up to the requested `limit`
+- `.env.example` Slack scope list was missing `groups:write`, required for `slack_create_channel` with `is_private: true`
+
+### Known limitation
+- Gmail tools require OAuth2 credentials (not a simple API key) — one-time setup via Google Cloud Console. All 8 tools tested working live against a real Gmail account.
+
+## [1.3.0]
+
+### Added
+- **Slack — new category, 8 tools** (Web API, bot-token based): `slack_get_user`, `slack_list_channels`, `slack_get_channel`, `slack_read_messages`, `slack_search_messages`, `slack_send_message`, `slack_reply_thread`, `slack_create_channel`. Send/reply/create-channel classified `HIGH` risk (require `confirm: true`); reads classified `READ`.
+- Setup wizard and `.env.example` now prompt for `SLACK_BOT_TOKEN`
+
+### Fixed
+- `slack_get_user` failing with `missing_scope` — Slack app was missing the `users:read` bot scope; documented required scopes in `.env.example`
+
+### Known limitation
+- `slack_search_messages` requires a Slack **user token**, not a bot token — bot tokens return `not_allowed_token_type`. All other Slack tools tested working with a bot token against a live workspace.
+
+## [1.2.0]
+
+### Added
+- **Git — 11 new tools**, completing the primitive layer (20/20): `git_create_branch`, `git_checkout`, `git_merge`, `git_reset`, `git_stash`, `git_show`, `git_remote`, `git_tag`, `git_changed_files`, `git_diff_stat`, `git_check_clean`
+- **GitHub — 18 new tools**, completing PR lifecycle + Actions/CI (27/27): repo/issue get+update, PR get/update/merge, PR files/diff/comments/reviews, branch get/list, workflow list/runs/jobs/logs/rerun
+- **Vercel — 4 new tools**, completing the deployment-verification set (11/11): `vercel_get_deployment_logs`, `vercel_get_deployment_events`, `vercel_cancel_deployment`, `http_check`
+- **Project Intelligence — new category, 7 tools**: `project_detect`, `project_info`, `project_health`, `run_tests`, `run_lint`, `run_typecheck`, `run_build` — auto-detects language/framework/package manager and resolves the right commands instead of guessing
+- **Workflow tools — new category, 4 tools**: `ship_change` (branch → checks → commit → push → PR, one call), `fix_ci` (diagnose a failing CI run with real logs), `verify_ci_fix` (commit/push/poll until green), `deploy_project` (health → tests+build → deploy → poll → HTTP-verify)
+- **Security layer**: permission-level classification (`READ`/`LOW`/`MEDIUM`/`HIGH`/`DESTRUCTIVE`) with an approval gate (`confirm: true`) for risky tools; secret redaction on every log line; graded command-risk classification (force-push, `DROP TABLE`, curl-pipe-bash, etc.); path protection against writing/deleting inside system directories
+- **Structured audit logging** — `logs/activity.log` is now JSONL (one JSON object per line) with operation ID, risk level, redacted input, and duration per call
+- **MCP Resources**: `causly://project/{path}/health`, `/info`, `/git` for direct context reads
+- **MCP Prompts**: `ship-feature`, `fix-ci`, `deploy-project`, `review-changes`
+- `CODE_OF_CONDUCT.md`, `BUILD_LOG.md`, `ROADMAP.md`
+
+### Changed
+- License: MIT → PolyForm Noncommercial 1.0.0
+- README rewritten to reflect the full 78-tool / 8-category surface and the security model
+
+### Fixed
+- `npm run <script>` (and any command relying on Windows' extension-less resolution — `node`, `where`, etc.) failing with `'node' is not recognized`, specifically inside nested `cmd.exe` processes. Root cause: the raw `PATHEXT` env var Claude Desktop passes in had a leading semicolon, producing an empty extension entry that silently broke resolution one process-layer down even though `PATHEXT` looked correct when echoed at the top level. `buildEnv()` now splits/filters/rejoins `PATH` and `PATHEXT` instead of string-concatenating, and resolves the real casing of each key (`Path` vs `PATH`) instead of risking a duplicate.
+- `ship_change` failing outright when its target branch already existed instead of checking it out
+
+## [1.1.3]
+
+### Fixed
+- `vercel_create_deployment` failing with `gitSource missing required property repoId` — Vercel's API requires the numeric GitHub repo ID, not an "owner/repo" string. Now resolves the ID automatically via the GitHub API before calling Vercel.
+
+## [1.1.2]
+
+### Fixed
+- `run_command` occasionally failed with `spawn powershell.exe ENOENT` on Windows because it relied on PATH lookup to find PowerShell, and Claude Desktop's spawned environment doesn't always have a reliable PATH. Now resolves PowerShell via its standard absolute System32 path first, with automatic fallback to a PATH-based lookup and finally `cmd.exe` if PowerShell truly cannot be found.
+
+## [1.1.1]
+
+### Fixed
+- `run_command` was failing to find `node`, `npm`, and other executables on Windows — Claude Desktop launches the server with a stripped-down environment where `PATHEXT` arrives missing standard extensions (`.EXE`, `.CMD`, `.BAT`, etc.), so PowerShell couldn't resolve commands even though they existed and their folder was in `PATH`. Now restores a sane default `PATHEXT` when spawning commands on Windows.
+
+## [1.1.0]
+
+### Added
+- GitHub tools: authenticated user, create/delete/list repos, create/list issues, create/list pull requests, add comment
+- Vercel tools: authenticated user, list/get projects, list/get deployments, create deployment, delete project
+- Supabase tools: list organizations, list/get projects, create/delete project, run raw SQL
+- Interactive setup wizard (`npm run setup`) — configures `.env` tokens and Claude Desktop config automatically
+- `.env.example` template
+- CONTRIBUTING.md, issue/PR templates, CI workflow
+
+### Fixed
+- `move_file` / `copy_file` / `write_file` / `create_file` failing with `EPERM` when the destination directory was a drive root on Windows (e.g. `D:\`)
+- Removed the `dotenv` dependency — its stdout banner was corrupting the MCP stdio JSON-RPC stream, causing "Unexpected token" errors. Replaced with a small dependency-free `.env` parser.
+- `run_command` was running through `cmd.exe` on Windows by default, which can't handle multi-statement scripts or many PowerShell-style commands. Now runs through `powershell.exe` on Windows.
+
+## [1.0.0]
+
+### Added
+- Initial release
+- File tools: read, read multiple, create, write, edit, delete, move, copy, get info
+- Directory tools: list, tree, create, delete, search
+- Git tools: init, status, add, commit, push, pull, log, diff, branch
+- Shell execution tool (`run_command`) with a blocklist of destructive command patterns
+- Local activity logging (`logs/activity.log`)

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kumar Nihal (Causly)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,377 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Causly Server
+
+**The open-source MCP server that turns any AI agent into your technical co-founder.**
+
+<p>
+  <a href="https://www.npmjs.com/package/causly-server"><img src="https://img.shields.io/npm/v/causly-server.svg?color=FF9A1F" alt="npm version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT license"></a>
+  <a href="https://github.com/KNIHAL/causly-server/actions/workflows/ci.yml"><img src="https://github.com/KNIHAL/causly-server/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <img src="https://img.shields.io/badge/node-%E2%89%A5%2020-339933.svg" alt="Node 20 or newer">
+  <a href="./CONTRIBUTING.md"><img src="https://img.shields.io/badge/PRs-welcome-brightgreen.svg" alt="PRs welcome"></a>
+</p>
+
+Most agents can write text. Causly Server gives them hands: they ship code, hunt for clients, track deals, take meeting notes, handle your calendar and remind you on Telegram, all from one conversation, all on your own machine.
+
+```bash
+npm install -g causly-server
+causly-server init
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/KNIHAL/causly-server/master/docs/images/demo.gif" alt="Install, init and doctor in under ten seconds" width="85%">
+</p>
+
+## Contents
+
+- [Why Causly Server](#why-causly-server)
+- [Quick start](#quick-start)
+- [What you can ask](#what-you-can-ask)
+- [How it works](#how-it-works)
+- [Tool packs](#tool-packs)
+- [Workflow tools](#workflow-tools)
+- [Configuration](#configuration)
+- [Google setup](#google-setup-gmail-calendar-search-console)
+- [Works with](#works-with)
+- [Security and privacy](#security-and-privacy)
+- [Command reference](#command-reference)
+- [Troubleshooting](#troubleshooting)
+- [FAQ](#faq)
+- [Compatibility](#compatibility)
+- [Contributing, roadmap, license](#contributing-roadmap-license)
+
+## Why Causly Server
+
+A founder's week is not only code. It is also finding clients, following up, remembering what was promised in a call, and shipping without breaking things. Causly Server puts all of that behind one MCP server.
+
+- **One server for build, sell, operate and grow.** Git, GitHub, CI and deploys, but also leads, a sales pipeline, meeting notes, calendar, reminders and SEO.
+- **Memory that survives the chat.** Your pipeline, meetings and reminders live in a local SQLite file, so the agent can pick up tomorrow where it stopped today.
+- **Local-first.** Keys and data stay on your machine. There is no Causly cloud in the loop.
+- **Safe by default.** Risky actions need explicit confirmation, file access can be limited to one folder, and secrets are redacted from logs.
+- **Light on your agent's context.** Tools load in packs on demand instead of flooding the agent with hundreds of definitions.
+- **One command setup.** `init` finds Claude Desktop, Cursor and Windsurf and wires them up.
+
+## Quick start
+
+Requires Node.js 20 or newer.
+
+**1. Install**
+
+```bash
+npm install -g causly-server
+```
+
+**2. Connect your editors**
+
+```bash
+causly-server init
+```
+
+`init` adds Causly Server to Claude Desktop, Cursor and Windsurf, whichever you have. It also prints the one-line command for Claude Code. Restart the editor afterwards.
+
+**3. Check everything**
+
+```bash
+causly-server doctor
+```
+
+**4. Add keys for the services you use (optional)**
+
+```bash
+causly-server setup
+```
+
+Files, git, shell, Docker and Terraform work with no keys at all. Add keys only for the services you want. Each key is checked live as you enter it.
+
+Useful `init` options:
+
+```bash
+causly-server init --client cursor                    # pick editors instead of auto-detecting
+causly-server init --workspace D:\my-project          # limit file tools to one folder
+causly-server init --toolsets research,pipeline,meetings   # choose which packs load at startup
+```
+
+## What you can ask
+
+- "Find companies hiring React developers and add the best three to my pipeline."
+- "Save notes from my call with Acme: they want a demo next week, follow up on Friday."
+- "What is due this week? Include meeting action items and reminders."
+- "Prep me for my next meeting." (needs Google Calendar)
+- "Transcribe this recording and list the action items." (needs a Groq key)
+- "Ship this change: run the checks, open a pull request, tell me when CI is green."
+- "Audit this page for SEO and suggest keywords."
+- "Find a free slot on Thursday and create the event."
+
+## How it works
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/KNIHAL/causly-server/master/docs/images/architecture.png" alt="Architecture: your AI agent talks MCP to Causly Server, which has a tool router, a safety layer, tool packs and a local store, and calls your services over their APIs." width="100%">
+</p>
+
+Your agent talks to Causly Server over MCP (stdio). Inside the server:
+
+1. **Tool router.** `search_tools`, `load_toolset` and `use_tool` let the agent find a tool and call it by name. Packs load on demand, and `use_tool` works even in editors that do not refresh their tool list mid-chat, so you do not need to restart.
+2. **Safety layer.** Permission levels, confirmation for risky actions, an optional workspace limit, secret redaction and an activity log.
+3. **Tool packs.** About 230 tools grouped into packs (below).
+4. **Local store.** SQLite for pipeline, meetings and reminders in `~/.causly`, encrypted secrets, and your API keys in `~/.causly/.env`.
+5. **Your services.** GitHub, Vercel, Docker, Terraform, Postgres, Slack, Notion, Linear, Gmail, Google Calendar, Telegram and more, reached with your own keys.
+
+## Tool packs
+
+These packs load at startup by default:
+
+| Pack | Tools | What it does |
+| --- | --- | --- |
+| files | 9 | Read, write, edit, copy, move and inspect files |
+| directory | 5 | List, create and delete directories; search file names |
+| command | 1 | Run shell commands with safety checks |
+| project | 7 | Detect project type and health; run build, tests, lint and typecheck |
+| research | 2 | Search the web and read pages as clean text |
+| leads | 3 | Find companies hiring (Hacker News, remote job boards) and public company contact details |
+| pipeline | 9 | Local sales pipeline: leads, deals, contacts, activity log, report, CSV export |
+| meetings | 9 | Transcribe recordings, save summaries, track action items, link to deals and calendar, prep for calls |
+| reminders | 3 | Follow-ups saved locally; ask what is due |
+
+These load on demand, or you can add them to startup with `causly-server toolsets add <name>`:
+
+| Pack | Tools | What it does |
+| --- | --- | --- |
+| calendar | 8 | Google Calendar: events, free/busy, find meeting slots, create, update, delete |
+| gmail | 8 | Search, read, send, reply and forward |
+| telegram | 5 | Alert yourself, read messages sent to your bot |
+| seo | 4 | Keyword ideas, page audit, draft check, Search Console |
+| git | 20 | Status, diff, commit, branch, merge, stash, tags, remotes |
+| github | 27 | Repos, issues, pull requests, reviews, Actions |
+| workflow | 4 | `ship_change`, `fix_ci`, `verify_ci_fix`, `deploy_project` |
+| vercel | 11 | Projects, deployments, HTTP health checks |
+| docker | 18 | Build, run, logs, images, exec, Compose |
+| terraform | 20 | Init, plan, apply, state, workspaces, PR plan comments |
+| database | 8 | Postgres and MySQL queries and schema inspection |
+| supabase | 6 | Projects, organizations and SQL |
+| slack | 8 | Channels, messages and threads |
+| notion | 15 | Pages, databases, blocks and comments |
+| linear | 7 | List, read, create, update and comment on issues |
+| sentry | 8 | Projects and issues |
+| secrets | 6 | Encrypted local secrets store |
+
+Manage startup packs:
+
+```bash
+causly-server toolsets                      # show what loads at startup
+causly-server toolsets add github,gmail
+causly-server toolsets remove seo
+causly-server toolsets reset                # back to the defaults
+```
+
+## Workflow tools
+
+Single tools are building blocks. These combine them into verified outcomes:
+
+- **`ship_change`**: inspects changes, creates a branch, runs project checks, commits, pushes and opens a pull request.
+- **`fix_ci`**: finds a failing GitHub Actions run and fetches the real failure output.
+- **`verify_ci_fix`**: commits and pushes the fix, polls the workflow and confirms CI is green.
+- **`deploy_project`**: checks health, runs tests and build, deploys, polls, and HTTP-verifies the live URL.
+
+```mermaid
+flowchart TD
+    A["You describe a task"] --> B["Agent edits files"]
+    B --> C["ship_change runs checks"]
+    C --> D["Commit, push, open PR"]
+    D --> E{"CI passes?"}
+    E -- "No" --> F["fix_ci gets failure logs"]
+    F --> G["Agent fixes the code"]
+    G --> H["verify_ci_fix pushes and confirms CI"]
+    H --> E
+    E -- "Yes" --> I["deploy_project deploys"]
+    I --> J["HTTP verification"]
+    J --> K["Shipped"]
+```
+
+## Configuration
+
+Settings live in `~/.causly/.env` (on Windows, `C:\Users\<you>\.causly\.env`). Manage them with the CLI instead of editing by hand:
+
+```bash
+causly-server setup            # step by step, each key checked live
+causly-server keys list        # which keys are set (never the full value)
+causly-server keys set NAME    # hidden prompt
+causly-server keys unset NAME
+causly-server doctor --test    # check every configured service live
+```
+
+Changes are picked up without restarting your editor.
+
+| Service | Variables | Notes |
+| --- | --- | --- |
+| GitHub | `GITHUB_TOKEN` | Fine-grained token: contents, issues, pull requests |
+| Vercel | `VERCEL_TOKEN` | Project must be Git-linked for deploys |
+| Supabase | `SUPABASE_ACCESS_TOKEN` | Management API |
+| Slack | `SLACK_BOT_TOKEN` | `search:read` needs a user token |
+| Notion | `NOTION_API_KEY` | Share each page or database with the integration |
+| Linear | `LINEAR_API_KEY` | Personal API key |
+| Sentry | `SENTRY_AUTH_TOKEN` | Add `event:write` to resolve or comment |
+| Gmail | `GMAIL_CLIENT_ID`, `GMAIL_CLIENT_SECRET`, `GMAIL_REFRESH_TOKEN` | Run `causly-server login google` |
+| Google Calendar | `CALENDAR_REFRESH_TOKEN` | Same Google client as Gmail |
+| Telegram | `TELEGRAM_BOT_TOKEN`, `TELEGRAM_CHAT_ID` | Create a bot with @BotFather, message it, then find your chat id with `telegram_get_updates` |
+| Groq (meeting transcription) | `GROQ_API_KEY` | Free tier available. Audio is uploaded to Groq only when you confirm a transcription |
+| Secrets manager | `SECRETS_MASTER_KEY` | 32-byte hex key you generate and keep |
+| Timezone (optional) | `CAUSLY_TIMEZONE` | IANA name, e.g. `Asia/Kolkata`; defaults to your machine's zone |
+
+Docker and Terraform need no key, only the CLI on your `PATH`. Postgres and MySQL take a connection string on each call. Transcribing recordings over 25 MB needs `ffmpeg` on your `PATH`.
+
+## Google setup (Gmail, Calendar, Search Console)
+
+Google needs a one-time OAuth client that you own. It takes about five minutes.
+
+1. Open [Google Cloud Console](https://console.cloud.google.com) and create or pick a project.
+2. Enable the APIs you want: **Gmail API**, **Google Calendar API**, and optionally **Google Search Console API**.
+3. Open **Google Auth Platform**. Under **Branding**, fill in the app name and your support email. Under **Audience**, choose **External** and add your own Google account as a test user.
+4. Under **Clients**, choose **Create client** and pick **Desktop app**. A "Web application" client fails with `redirect_uri_mismatch`. Copy the client ID and secret.
+5. Save them in Causly: run `causly-server setup`, or `causly-server keys set GMAIL_CLIENT_ID` and `causly-server keys set GMAIL_CLIENT_SECRET`.
+6. Sign in once in your browser:
+
+```bash
+causly-server login google            # Gmail and Calendar
+causly-server login google all        # also Search Console
+```
+
+**Avoid the 7-day expiry.** While your Google app is in *Testing*, Google expires the sign-in token every 7 days. Renew it any time with `causly-server login google`, or stop the expiry for good: in **Google Auth Platform → Audience**, click **Publish app** (In production). The Branding page from step 3 must be filled in first. For personal use you do not need Google verification; at sign-in you will see an "unverified app" warning, which is expected for your own client: choose **Advanced**, then continue.
+
+## Works with
+
+| Client | Setup |
+| --- | --- |
+| Claude Desktop | `causly-server init` |
+| Cursor | `causly-server init` |
+| Windsurf | `causly-server init` |
+| Claude Code | `init` prints the command: `claude mcp add causly-server -- node <path>/index.js` |
+| Any MCP client or agent framework | Spawn `causly-server` over stdio |
+
+Tested with Claude Desktop, Cursor and Windsurf (the same `use_tool` call on a real repository in each), a plain JavaScript MCP client, and LangChain (JS) through `@langchain/mcp-adapters`.
+
+A minimal custom agent in JavaScript:
+
+```js
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+
+const client = new Client({ name: "my-agent", version: "1.0.0" });
+// Find the install folder with: npm root -g
+await client.connect(new StdioClientTransport({
+  command: "node",
+  args: ["<npm-root>/causly-server/index.js"],
+}));
+
+const { tools } = await client.listTools();           // search_tools, load_toolset, use_tool, ...
+const result = await client.callTool({
+  name: "use_tool",
+  arguments: { tool: "git_status", arguments: { repo_path: "." } },
+});
+console.log(result.content[0].text);
+```
+
+## Security and privacy
+
+Causly can touch your files, repositories and infrastructure, so the controls live in the server itself. See [SECURITY.md](./SECURITY.md) to report a vulnerability.
+
+- **Permission levels.** Every tool is `READ`, `LOW`, `MEDIUM`, `HIGH` or `DESTRUCTIVE`. `HIGH` and `DESTRUCTIVE` actions (deploys, merges, shell commands, deletes, raw SQL, Terraform apply and destroy, Docker removal) need an explicit `confirm: true`.
+- **Workspace limit.** `causly-server init --workspace <folder>` restricts file and command tools to one folder.
+- **Command risk checks.** Drive wipes, formatting and shutdown commands are blocked. Force-pushes, `DROP TABLE`, `curl | bash` and `sudo` are flagged.
+- **Path protection.** Writes and deletes inside protected system directories are blocked.
+- **Secret redaction.** Tokens, passwords and API keys are redacted before anything is written to logs.
+- **Local encrypted secrets.** The built-in secrets manager uses AES-256-GCM with a key you control. No external vault needed.
+- **Activity log.** Every call is recorded in `logs/activity.log` as structured JSONL (timestamp, operation ID, risk level, status, redacted input, duration).
+
+**Privacy.** Causly Server has no Causly cloud and no Causly account. Your pipeline, meetings and reminders are stored in a local SQLite file, and your keys stay in `~/.causly/.env`. Data leaves your machine only when you use a service you configured, for example GitHub, Gmail, Telegram, or Groq for transcription, and only to that service.
+
+Optional BoundaryAttest receipts for `ship_change`, `verify_ci_fix` and `deploy_project` are described in [the docs](https://agenv.causly.in/docs/server/tools/boundaryattest).
+
+## Command reference
+
+```text
+causly-server                          Start the MCP server (your editor runs this)
+causly-server init                     Set up Claude Desktop, Cursor and Windsurf
+    --client claude|cursor|windsurf|all
+    --workspace <folder>
+    --toolsets <list>
+    --no-setup
+causly-server status                   One screen: editors, keys, pipeline, reminders, backup, updates
+causly-server doctor [--test]          Check your setup; --test also checks every key live
+causly-server setup [service]          Add API keys step by step
+causly-server keys list | set NAME | unset NAME | open
+causly-server login google [gmail,calendar,gsc|all]
+causly-server toolsets [add|remove|reset]
+causly-server backup [file]            Save a copy of your pipeline, meetings and reminders
+causly-server restore <file> [--yes]   Put a backup back (current data is kept as a copy)
+causly-server remove [--client <name>] Remove it from your editors
+causly-server --version
+```
+
+## Troubleshooting
+
+Start with `causly-server doctor`. It tells you what is missing.
+
+| Problem | Fix |
+| --- | --- |
+| `causly-server` is not recognized after install | Open a new terminal so your `PATH` refreshes. Check that your npm global folder (`npm config get prefix`) is on `PATH`. |
+| Editor does not show the tools after `init` | Quit the editor completely (including the system tray) and open it again. |
+| The agent cannot see a tool that is not loaded | Ask it to call the tool with `use_tool`, or run `causly-server toolsets add <pack>`. |
+| Gmail or Calendar stopped working | Your Google token expired (7 days in Testing mode). Run `causly-server login google`. |
+| `redirect_uri_mismatch` during Google sign-in | Your OAuth client is a "Web application". Create a **Desktop app** client instead. |
+| A reminder never reached Telegram | Set both `TELEGRAM_BOT_TOKEN` and `TELEGRAM_CHAT_ID`, then run `causly-server doctor --test`. |
+| Transcription fails on a large file | Install `ffmpeg` and make sure it is on your `PATH`. Files above 25 MB are compressed first. |
+| `restore` cannot replace the data file | Quit Claude Desktop, Cursor and any app using Causly Server, then run it again. |
+| A file or command is refused | A workspace limit may be on. Check `causly-server doctor`, or re-run `init` with the folder you want. |
+
+## FAQ
+
+**Is it free?** Yes. It is MIT licensed, including for commercial use. The services you connect have their own pricing.
+
+**Does my data go to Causly?** No. There is no Causly cloud in the loop. See [Security and privacy](#security-and-privacy).
+
+**Do I need every key?** No. Add keys only for the services you use.
+
+**Which agents work with it?** Any MCP client. It is tested with Claude Desktop, Cursor, Windsurf, a plain JavaScript client and LangChain (JS).
+
+**Why is my agent not calling a tool?** It may be in a pack that is not loaded. Tell the agent to use `use_tool`, or add the pack with `causly-server toolsets add <pack>`.
+
+**How do I update?** `npm update -g causly-server`. `status` and `doctor` tell you when a new version is out.
+
+**How do I back up my data?** `causly-server backup` saves your pipeline, meetings and reminders to a file. `causly-server restore <file>` puts it back.
+
+**How do I remove it?** `causly-server remove` takes it out of your editors. Then `npm uninstall -g causly-server`.
+
+**Is there a hosted version?** Causly Hosted is in development. [Join the waitlist](https://tally.so/r/NpZkpW).
+
+## Compatibility
+
+| | Status |
+| --- | --- |
+| Node.js | 20 or newer |
+| Windows | Tested |
+| macOS and Linux | Expected to work; not yet tested on real machines. Reports welcome. |
+| Editors | Claude Desktop, Cursor, Windsurf (tested); Claude Code (command printed by `init`) |
+
+## Known limitations
+
+- `vercel_create_deployment` and `deploy_project` need the Vercel project to be Git-linked already.
+- `supabase_run_sql` uses the Supabase Management API; some personal access tokens get a `403` for SQL.
+- `slack_search_messages` needs a Slack user token with the `search:read` scope.
+- `docker_push` needs registry authentication already configured on the host.
+- Sentry `resolve_issue`, `ignore_issue` and `add_comment` need a token with the `event:write` scope.
+
+## Contributing, roadmap, license
+
+- Docs: [agenv.causly.in/docs/server](https://agenv.causly.in/docs/server/intro)
+- [CONTRIBUTING.md](./CONTRIBUTING.md) explains how to add a tool pack and the manual testing checklist. Please read the [Code of Conduct](./CODE_OF_CONDUCT.md) too.
+- [ROADMAP.md](./ROADMAP.md) has what is planned next. [CHANGELOG.md](./CHANGELOG.md) has release history.
+- License: [MIT](./LICENSE).
+
+## Want something custom built on this?
+
+Need a custom MCP server, a specific integration, or a related service for your product or team? Reach out: **nihal@causly.in**
+
+## Causly Hosted
+
+Do not want to run Causly Server yourself? Causly Hosted is a managed version, currently in development.
+
+[Join the Causly Hosted waitlist](https://tally.so/r/NpZkpW)