@atoms-tech/atoms-mcp 0.4.2 → 0.5.0

package/README.md

@@ -134,12 +134,121 @@ Add to your `claude_desktop_config.json`:
 
 Add to your MCP configuration with `command: "npx"` and `args: ["@atoms-tech/atoms-mcp"]`. Refer to your editor's MCP documentation for the exact config file location.
 
+## Org-Controlled Policy
+
+Org admins can set guardrails (read-only mode, allowed toolsets, project scope, required confirmations) for every member of their org through **Org Settings → MCP Access Policy** in the ATOMS web app. Both this stdio package and the hosted MCP server (`https://<project>.supabase.co/functions/v1/mcp-server`) read the same `mcp_policy` table at session init, so an admin's policy applies regardless of how a user connects.
+
+**Tenancy:** every policy row is scoped by `org_id`. Org A admins cannot read or modify Org B's policy — Row-Level Security enforces this at the database.
+
+**Resolution order** (each layer can only narrow the previous, never widen):
+
+1. Role baseline (admin / editor / viewer)
+2. Org-default policy for that role
+3. Optional per-user override
+4. Operator env-var ceiling (this package, see below)
+
+The operator env vars below are layered **on top** of the org policy. They're useful for stdio installs (per-machine lockdown) and CI bots; they don't replace the admin-set policy and they cannot widen it.
+
+## Environment Variables
+
+Tool exposure can be narrowed at startup so you only register what an agent needs. Both filters apply at server-init time — disabled tools never appear in the MCP tool list.
+
+### `ATOMS_MCP_READ_ONLY`
+
+Set to `1` (or `true`) to drop every mutating tool. Useful for analyst agents, CI summaries, or any context where writes shouldn't be possible.
+
+```json
+{
+  "mcpServers": {
+    "atoms-mcp": {
+      "command": "npx",
+      "args": ["@atoms-tech/atoms-mcp"],
+      "env": { "ATOMS_MCP_READ_ONLY": "1" }
+    }
+  }
+}
+```
+
+Affected tools (12): `atoms_create_item`, `atoms_update_item`, `atoms_delete_item`, `atoms_link_items`, `atoms_bulk_import`, `atoms_record_test_result`, `atoms_create_variable`, `atoms_update_variable`, `atoms_delete_variable`, `atoms_create_domain`, `atoms_update_domain`, `atoms_delete_domain`.
+
+### `ATOMS_MCP_TOOLSETS`
+
+Comma-separated list of toolsets to enable. When set, only tools in the named toolsets register (plus the always-on tools below). Unknown names are ignored.
+
+| Toolset | Tools |
+|---|---|
+| `items` | list, get, search, browse, history, create, update, delete, bulk_import |
+| `traceability` | trace, link_items, export_mermaid, impact_analysis |
+| `coverage` | get_coverage, record_test_result, project_summary |
+| `variables` | list/get/create/update/delete variables |
+| `domains` | list/create/update/delete domains |
+
+Always-on regardless of `ATOMS_MCP_TOOLSETS`: `atoms_status`, `atoms_list_projects`.
+
+```json
+{ "env": { "ATOMS_MCP_TOOLSETS": "coverage,traceability" } }
+```
+
+Combine with `ATOMS_MCP_READ_ONLY=1` for a tightly scoped read-only agent — e.g., a coverage-reporting CI job that can't accidentally mutate state.
+
+### `ATOMS_MCP_REQUIRE_CONFIRMATION`
+
+Force a two-step confirm flow on destructive tools so a runaway agent (or a prompt-injected tool argument) can't delete in a single call.
+
+When set, the first call returns `{ status: "confirmation_required", preview, confirmation_token }` without performing the operation. The agent must then re-call with the issued `confirmation_token` to execute. Tokens are HMAC-SHA256 signed, expire in 60 seconds, and bind to the exact (tool, project, target) — they can't be reused or swapped between calls.
+
+Accepted values:
+
+| Value | Effect |
+|---|---|
+| `1`, `true`, `all` | Confirmation required for every supported destructive tool |
+| `atoms_delete_item,atoms_bulk_import` | Comma-separated allowlist of tools that require it |
+| unset | No confirmation required (default — preserves backward compatibility) |
+
+Currently supported on: `atoms_delete_item`, `atoms_delete_variable`, `atoms_delete_domain`, `atoms_bulk_import`.
+
+For `atoms_bulk_import` the token also binds to a hash of the items array — modifying any item between preview and confirm invalidates the token.
+
+```json
+{ "env": { "ATOMS_MCP_REQUIRE_CONFIRMATION": "atoms_delete_item,atoms_bulk_import" } }
+```
+
+Optional: set `ATOMS_MCP_CONFIRMATION_SECRET` (≥16 chars) to make tokens survive process restarts. Otherwise the secret is regenerated each launch and tokens issued before a restart become invalid.
+
+### `ATOMS_MCP_ORG_ID`
+
+When you belong to multiple orgs, picks which one's MCP policy applies for this stdio session. Set to an org UUID. If unset, the package falls back to your earliest-joined org membership.
+
+### `ATOMS_MCP_PROJECT_ID`
+
+Bind the session to a single project. Every tool call's `project_id` argument must match — mismatches are rejected before the handler runs. `atoms_list_projects` filters its response to just the scoped project. Set to a project UUID; invalid values are ignored with a warning.
+
+```json
+{ "env": { "ATOMS_MCP_PROJECT_ID": "11111111-2222-3333-4444-555555555555" } }
+```
+
+Useful when an agent should only ever touch one project — for example, a CI bot dedicated to a single product line. Defense-in-depth on top of RLS, since it catches accidents (or prompt injections) that pass a different project_id.
+
+### `ATOMS_RATE_LIMIT_RPM`
+
+Override the default 60 requests/minute per-user rate limit. Set to a positive integer.
+
+### `ATOMS_CLIENT_NAME`
+
+Identifier persisted to the audit log so you can see which client (e.g., `cursor`, `claude-desktop`, `ci-coverage-bot`) made each call.
+
 ## Security
 
+- **Org-isolated policy** — Every config knob set by Org A's admin lives in a row scoped to Org A's `org_id` and is invisible to Org B. RLS on the `mcp_policy` table is the boundary; the admin UI is purely a hide.
 - **Row Level Security (RLS)** — All queries run with the user's JWT. The server never uses a service role key. You can only access projects your organization has granted you access to.
 - **Role enforcement** — Write tools check your org role (viewer, editor, admin) before making changes. Viewers are blocked from mutations.
 - **Audit logging** — Every tool call is logged with tool name, parameters, duration, and session ID. Write operations log to `change_history` with `actor: "mcp_claude"`.
-- **Rate limiting** — Built-in per-user rate limiter prevents abuse.
+- **Rate limiting** — Built-in per-user sliding-window rate limiter (default 60 req/min, configurable).
+- **Tool annotations** — Every tool declares `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint` per the MCP spec, so capable hosts can surface accurate consent prompts.
+- **Input caps** — Every string field has an explicit upper bound (body 50k, summary 2k, names 64, etc.) to prevent embedding-cost and memory-exhaustion attacks.
+- **Output sanitization** — Error messages strip ASCII control, zero-width, and bidi-format characters from echoed user input, closing a reflected prompt-injection vector.
+- **Confirmation tokens** — Destructive tools (`atoms_delete_*`, `atoms_bulk_import`) can be configured to require a two-step confirm flow with HMAC-signed tokens — see `ATOMS_MCP_REQUIRE_CONFIRMATION` above.
+- **Project scoping** — `ATOMS_MCP_PROJECT_ID` binds a session to a single project and rejects tool calls referencing any other one — defense-in-depth on top of RLS.
 - **No secrets in the package** — The Supabase anon key is a publishable client key (like a Firebase API key). It grants zero data access without a valid user JWT.
 
 ## Requirements