causly-server 0.0.0-stage → 1.5.0

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,121 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+## [Unreleased]
+
+### Added
+- 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.
+
+### 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.
+
+## [1.5.0]
+
+### Added
+- **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: 181 tools, up from 106.
+
+### Changed
+- **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`.
+- Simplified `setup.js` — dropped interactive token prompting (tokens are documented/edited directly in `.env`), kept the cross-platform Claude Desktop config auto-update.
+- 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,205 @@
-# 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 — Turn Any AI Agent Into Your Technical Co-Founder
+
+[![npm](https://img.shields.io/npm/v/causly-server.svg)](https://www.npmjs.com/package/causly-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)
+[![CI](https://github.com/KNIHAL/causly-server/actions/workflows/ci.yml/badge.svg)](https://github.com/KNIHAL/causly-server/actions/workflows/ci.yml)
+[![PRs welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](./CONTRIBUTING.md)
+
+**An open-source MCP server that gives your AI agent the tools of a co-founder: ship code, find leads, track deals, take meeting notes, handle email and your calendar, all from one conversation.**
+
+Your agent stops being a chatbot that writes text and starts doing the work: it reads your repo, opens the pull request, finds companies that are hiring, logs them in your pipeline, books the follow-up, and reminds you on Telegram.
+
+Everything runs on your machine. Your keys, your data, your approval for anything risky.
+
+## See It In Action
+
+[Working Demo](https://github.com/user-attachments/assets/7f4f33e8-2cd4-4c99-ada0-35653bbaa4c4)
+
+<img width="1920" height="1020" alt="Causly Server screenshot" src="https://github.com/user-attachments/assets/e9fb7c22-0a0b-4109-a44d-d2106912389f" />
+
+## What You Can Ask
+
+Once it is installed, just talk to your agent:
+
+- "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."
+- "Ship this change: run the checks, open a pull request, and tell me when CI is green."
+- "Audit this page for SEO and suggest keywords."
+- "Find a free slot with this lead on Thursday and send the invite."
+
+## Install
+
+Requires Node.js 20 or newer.
+
+```bash
+npm install -g causly-server
+causly-server init
+```
+
+`init` finds Claude Desktop, Cursor and Windsurf on your machine and adds Causly Server to each. Restart your editor and you are done. Using Claude Code instead? `init` prints the one-line command for it.
+
+Useful 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 startup packs
+```
+
+### Add your API keys
+
+You only need keys for the services you actually use.
+
+```bash
+causly-server setup            # step by step, each key is checked live
+causly-server doctor --test    # verify every configured service
+causly-server status           # one screen: editors, keys, pipeline, reminders, updates
+```
+
+Keys are stored in `~/.causly/.env` (hidden prompt, never printed back) and picked up without a restart.
+
+## 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), create or pick a project.
+2. Enable the APIs you want: **Gmail API**, **Google Calendar API**, and optionally **Google Search Console API**.
+3. Go to **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. Go to **Clients → Create client** and choose **Desktop app** as the application type. (A "Web application" client fails with `redirect_uri_mismatch`.) Copy the client ID and secret.
+5. Save them in Causly: `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 token expiry: Publish the app
+
+While the Google app is in **Testing** status, Google expires the sign-in token every 7 days. You can renew it any time with `causly-server login google`.
+
+To stop that for good, go to **Google Auth Platform → Audience** and click **Publish app** (set it to *In production*). This needs the Branding page from step 3 to 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.
+
+## Tool Packs
+
+Tools are grouped in packs and loaded lazily, so your agent is never flooded with hundreds of tool definitions. The packs below load at startup:
+
+| Pack | What it does |
+| --- | --- |
+| **files, directory, command, project** | Read, write, edit and search files; run commands with safety checks; detect your stack and run build, test, lint and typecheck |
+| **research** | Search the web and read pages as clean text |
+| **leads** | Find companies hiring (Hacker News, remote job boards) and public company contact details |
+| **pipeline** | Local sales pipeline: leads, deals, contacts, activity log, report, CSV export |
+| **meetings** | Transcribe recordings, save summaries, track action items, link them to deals and calendar events, prep for calls |
+| **reminders** | Follow-ups saved locally; ask what is due |
+| **seo** | Keyword ideas, page audit, draft check, Search Console |
+
+More packs are one command away and load on demand:
+
+| Pack | What it does |
+| --- | --- |
+| **calendar, gmail** | Events, free/busy, find meeting slots; search, read, send, reply, forward |
+| **telegram** | Alert yourself, read messages sent to your bot |
+| **git, github, workflow** | Full Git; repos, issues, pull requests, reviews, Actions; `ship_change`, `fix_ci`, `verify_ci_fix`, `deploy_project` |
+| **vercel, docker, terraform** | Deployments and health checks; containers and Compose; plan, apply, state |
+| **database, supabase** | Postgres and MySQL queries and schema; Supabase projects and SQL |
+| **slack, notion, linear** | Channels and threads; pages and databases; issues |
+| **sentry, secrets** | Issue triage; encrypted local secrets store |
+
+That is 230+ tools in total. Choose which packs load at startup:
+
+```bash
+causly-server toolsets                 # show what loads at startup
+causly-server toolsets add github,gmail
+causly-server toolsets remove seo
+causly-server toolsets reset
+```
+
+### No restart needed: `use_tool`
+
+Some editors do not refresh their tool list mid-chat. `use_tool` lets your agent call any tool by name, even one that is not loaded yet; the pack loads automatically and every safety check still applies.
+
+## 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, 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, 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"]
+```
+
+## Works With
+
+Tested with Claude Desktop, Cursor, Windsurf, a plain JavaScript MCP client, and LangChain (JS) through `@langchain/mcp-adapters`. Any MCP-compatible client or agent framework can connect to the same stdio server.
+
+## Security
+
+Causly can touch your files, repositories and infrastructure, so the controls live in the server itself.
+
+- **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:** `init --workspace <folder>` restricts file and command tools to one folder.
+- **Approval for outside actions:** anything that emails real people, such as calendar invites with guests, needs confirmation first.
+- **Secret redaction:** tokens, passwords and API keys are redacted before anything is written to logs.
+- **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.
+- **Local encrypted secrets:** AES-256-GCM with a key you control, no external vault.
+- **Activity log:** every call is recorded in `logs/activity.log` as structured JSONL (timestamp, operation ID, risk, status, redacted input, duration).
+- **Your data stays local:** the pipeline, meetings and reminders live in a local SQLite file. `causly-server backup` and `restore` keep it safe.
+
+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 init | status | doctor [--test] | setup [service]
+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] | restore <file> [--yes]
+causly-server remove [--client <name>]
+```
+
+## 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.
+- On Windows, if `npm install` fails with `'node' is not recognized` in a postinstall script, retry with `npm install --ignore-scripts` ([issue #2](https://github.com/KNIHAL/causly-server/issues/2)).
+
+## Documentation, Roadmap, Contributing
+
+- Detailed docs: [agenv.causly.in/docs/server](https://agenv.causly.in/docs/server/intro)
+- [ROADMAP.md](./ROADMAP.md), [CONTRIBUTING.md](./CONTRIBUTING.md), [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md), [CHANGELOG.md](./CHANGELOG.md)
+
+## License
+
+[MIT](./LICENSE): free to use, modify and distribute, including commercially.
+
+## 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)