Steady MCP

# Steady MCP (local) This is a **local MCP server** that submits Steady check-ins by driving Steady’s **web form** (there is **no official Steady API**). It’s built for the workflow: > You tell the AI: **team + check-in fields** (previous / next / blockers) → AI calls the MCP tool → Steady check-in is submitted. --- ## What this supports - **Email + password login** (two-step flow from [`/signin`](https://app.steady.space/signin)) via `steady_login` - **Cookie-based auth** via `steady_set_cookies` (fallback for non-standard auth flows) - **Team discovery** via `steady_list_teams` - **Submitting a check-in for one team** via `steady_submit_checkin` ### How it works (important) Steady rotates the `_sthr_session` cookie when you load the daily edit page (`/check-ins/YYYY-MM-DD/edit`). So **this server uses a curl cookie jar** (`cookiejar.txt`) to preserve the updated session cookie between the GET and POST. --- ## Requirements - **Node.js 18+** - **Cursor** (or another MCP client) with support for running local MCP servers over stdio - Access to Steady web app (`https://app.steady.space`) --- ## Install ```bash cd tools/steady-mcp npm install ``` --- ## Configure Cursor (MCP) Add a server entry to your Cursor MCP config. ### Where is `mcp.json`? Common locations: - **macOS / Linux**: `~/.cursor/mcp.json` - **Windows**: `%USERPROFILE%\\.cursor\\mcp.json` If you don’t see it, use Cursor’s UI settings for MCP servers (recommended), or search for `mcp.json` on your machine. ### Quickstart: macOS (recommended) 1) **Install Node.js 18+** - If you use Homebrew: ```bash brew install node node -v ``` 2) **Install dependencies** ```bash cd <ABS_PATH_TO_REPO>/tools/steady-mcp npm install ``` 3) **Add `steady-mcp` to `~/.cursor/mcp.json`** (example below) 4) **Restart Cursor** (quit + reopen) 5) In Cursor, run: - `steady_login` - `steady_submit_checkin` ### Quickstart: Windows 1) **Install Node.js 18+** - If you use `winget`: ```powershell winget install OpenJS.NodeJS.LTS node -v ``` 2) **Install dependencies** ```powershell cd <ABS_PATH_TO_REPO>\tools\steady-mcp npm install ``` 3) **Add `steady-mcp` to `%USERPROFILE%\.cursor\mcp.json`** 4) **Restart Cursor** (fully quit + reopen) 5) In Cursor, run: - `steady_login` - `steady_submit_checkin` ### Example `mcp.json` snippet > Replace `<ABS_PATH_TO_REPO>` and your email. ```json { "mcpServers": { "steady-mcp": { "command": "node", "args": [ "<ABS_PATH_TO_REPO>/tools/steady-mcp/src/index.js" ], "env": { "STEADY_BASE_URL": "https://app.steady.space", "STEADY_EMAIL": "you@company.com", "STEADY_PASSWORD": "<YOUR_PASSWORD>", "STEADY_MCP_DEBUG": "0" } } } } ``` ### Windows path tip (important) In JSON, Windows backslashes require escaping. Easiest option: use forward slashes in the `args` path: ```json { "mcpServers": { "steady-mcp": { "command": "node", "args": [ "C:/Users/<YOU>/path/to/repo/tools/steady-mcp/src/index.js" ], "env": { "STEADY_BASE_URL": "https://app.steady.space", "STEADY_EMAIL": "you@company.com", "STEADY_PASSWORD": "<YOUR_PASSWORD>" } } } } ``` ### Security note - `STEADY_PASSWORD` in `mcp.json` is the simplest setup, but it’s **not** ideal for security. - Prefer `STEADY_PASSWORD_COMMAND` (password retrieved at runtime) whenever possible. --- ## Credentials / Secrets (cross-platform) The server reads credentials from environment variables provided by your MCP client. ### Option A (simple): plaintext env password - `STEADY_EMAIL` - `STEADY_PASSWORD` ### Option B (recommended): password command - `STEADY_EMAIL` - `STEADY_PASSWORD_COMMAND` — command that prints the password to stdout (no prompts) Examples: - **macOS Keychain** (recommended on macOS) 1) Store once: ```bash security add-generic-password -a "you@company.com" -s "steady-mcp" -w "<YOUR_PASSWORD>" -U ``` 2) In MCP env: - `STEADY_PASSWORD_COMMAND=security find-generic-password -w -s steady-mcp -a you@company.com` - **Windows**: use a password manager CLI (e.g. 1Password CLI / Bitwarden CLI) or a small local script that prints the password. - **Any OS**: use your password manager’s CLI, or a small script you keep outside git. ### Option C (macOS-only fallback): Keychain lookup without a command If you have a Keychain entry, the server can read it automatically on macOS: - `STEADY_EMAIL=you@company.com` - optionally `STEADY_KEYCHAIN_SERVICE=steady-mcp` - optionally `STEADY_KEYCHAIN_ACCOUNT=you@company.com` --- ## Authentication options ### 1) Login automation (email → password) Use: - `steady_login` This will log in and write: - `cookies.txt` (Cookie header string) - `cookiejar.txt` (curl jar; used internally to handle session rotation) ### 2) Cookie-based auth (fallback) If login automation doesn’t work for your Steady account, you can set cookies from your browser: 1) In Steady (browser): DevTools → Application/Storage → Cookies → `https://app.steady.space` 2) Copy these cookies: - `_sthr_session` - `remember_user_token` (if present) 3) Build a Cookie header string: ```text _sthr_session=...; remember_user_token=... ``` 4) Call: - `steady_set_cookies` with `{ "cookies": "_sthr_session=...; remember_user_token=..." }` --- ## File locations (where cookies are stored) Defaults (can be overridden via env): - **macOS** - cookies: `~/Library/Application Support/steady-mcp/cookies.txt` - jar: `~/Library/Application Support/steady-mcp/cookiejar.txt` - **Windows** - cookies: `%APPDATA%\\steady-mcp\\cookies.txt` - jar: `%APPDATA%\\steady-mcp\\cookiejar.txt` - **Linux** - cookies: `$XDG_CONFIG_HOME/steady-mcp/cookies.txt` (or `~/.config/steady-mcp/cookies.txt`) - jar: `$XDG_CONFIG_HOME/steady-mcp/cookiejar.txt` (or `~/.config/steady-mcp/cookiejar.txt`) Overrides: - `STEADY_COOKIES_PATH` - `STEADY_COOKIE_JAR_PATH` --- ## Usage (day-to-day) ### Step 0: Restart Cursor After adding/updating MCP config, fully restart Cursor (quit + reopen). ### Step 1: Login (refresh cookies) Call: - `steady_login` Then verify: - `steady_ping` → should return `{ "ok": true }` ### Step 2: List team names (optional) Call: - `steady_list_teams` ### Step 3: Submit today’s check-in for one team Call: - `steady_submit_checkin` Example: ```json { "team": "Everest AI", "previous": "Wrapped up CI fixes and reviewed PRs.", "text": "Next: finalize the MCP schema changes and update docs.", "blockers": "No blockers.", "mood": "calm" } ``` Success is typically: - `status_code: 302` --- ## Tools (API surface) - **`steady_login`**: log in and save cookies locally - **`steady_set_cookies`**: save browser cookies manually - **`steady_ping`**: validate auth - **`steady_list_teams`**: list team names/ids from the daily edit page - **`steady_submit_checkin`**: submit for one team --- ## Troubleshooting Start here: `docs/TROUBLESHOOTING.md` Common issues: - **Tool not found in Cursor** - fully restart Cursor - verify the `mcp.json` entry path is correct and absolute - verify `npm install` was run in `tools/steady-mcp` - **HTTP 422** - usually means the submission was rejected (already checked in / stale session / insufficient permission) - run `steady_login` again and retry - confirm the team is actually pending on Steady’s daily page - **Need debug** - set `STEADY_MCP_DEBUG=1` (warning: debug output may include sensitive cookies)