sackville-mcp 0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or Derivative
+          Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Curtis Autery
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,215 @@
+# sackville-mcp
+
+The Sackville MCP server — exposes Sackville's pillars to an LLM agent as MCP tools
+and resources. **`sackville-mcp` is the AGGREGATE server**: one stdio process that
+serves every *enabled* pillar (docs, api, browser, coverage, deps, flake, lsp,
+mutate, verify). Narrow single-pillar bins also ship for minimal deployments
+(`sackville-docs-mcp`, `sackville-api-mcp`, `sackville-browser-mcp`, …).
+
+## Quickstart — the aggregate server
+
+Add one block to your MCP client config (see [`examples/mcp/.mcp.json`](../../examples/mcp/.mcp.json)):
+
+```jsonc
+{
+  "mcpServers": {
+    "sackville-mcp": {
+      "command": "npx",
+      "args": ["-y", "sackville-mcp"],
+      "env": {
+        // Pick which pillars to expose (unset ⇒ the curated default docs+api+deps+verify).
+        "SACKVILLE_TOOLSETS": "api,deps,verify",
+        // Each pillar reads its OWN operator gate; run/write tools appear only when set.
+        "SACKVILLE_API_ALLOWED_HOSTS": "api.example.com"
+      }
+    }
+  }
+}
+```
+
+- **Selecting pillars** — `SACKVILLE_TOOLSETS` is a comma list of pillar names; unset
+  enables the curated read-heavy default. It only *selects* — it never grants a
+  capability (each pillar still reads its own `SACKVILLE_<PILLAR>_*` gate).
+- **Install isolation** — a bare `npm i sackville-mcp` is **native-free**. The heavy
+  engines (`@sackville-mcp/browser` → playwright, `@sackville-mcp/core`/`@sackville-mcp/embed` → the
+  docs index, `@sackville-mcp/flake` → SQLite) are **optional peers**: install the ones whose
+  pillars you enable. A pillar whose engine isn't installed (or, for docs, whose
+  `SACKVILLE_INDEX` is unset) is *loud-disabled* at startup — the server still starts.
+- **Compose, never widen** — in the aggregate the api + verify pillars read the prefixed
+  `SACKVILLE_API_*` / `SACKVILLE_API_SECRET_*` namespace, so no bare flag unlocks two
+  pillars at once. Safety config is always operator-set, never an agent input.
+
+## Docs tools
+
+- **`search_docs`** — **hybrid** search: FTS5/bm25 fused with vector KNN via
+  reciprocal rank fusion. Inputs: `query`, optional `library`/`version`/`type`/
+  `limit` (default 8, max 25). Returns **compact** results (`id`, `title`,
+  `symbol`, `type`, `library`, `version`, `score`, `snippet`, `resourceUri`) as
+  `structuredContent` — never full bodies. The query is embedded in-process with
+  transformers.js (`Xenova/bge-small-en-v1.5`), matching the indexed vectors
+  (ADR 0003); the model (~130 MB) downloads once on first query.
+- **`get_doc`** — inputs: `id`. Returns the full fragment (the one place bodies
+  are returned). Errors if the id is unknown.
+
+## Docs resource
+
+- **`sackville://doc/{id}`** — the same full fragment as `get_doc`, so agents can
+  follow a search hit's `resourceUri` without a tool call.
+
+## API tools (`sackville-api-mcp`)
+
+Over a Bruno `.bru` collection directory (passed as the `dir` tool argument, so
+one server serves many collections):
+
+- **`list_requests`** — `{ dir }` → each request's `name`/`method`/`url`.
+- **`get_request`** — `{ dir, name }` → method/url/headers, counts, and
+  **`requiredSecrets`** — the secret **names** referenced as `{{secret:NAME}}`,
+  never values.
+- **`run_request`** — `{ dir, name, vars?, env? }` → the redacted run result
+  (status, assertions, scriptTests, captured, `bodyHandle`).
+- **`run_collection`** — `{ dir, names[], vars?, env?, stopOnFailure? }` → a
+  compact per-step summary + threaded `captured`.
+- **`validate_response`** — OpenAPI 3.1 (`openapiSpec`,`method`,`path`,`status`,
+  `body`) **or** GraphQL (`graphqlSchema`,`query`,`body`, + optional `variables` to
+  type-check the request variables against the operation's declared types) → contract findings.
+- **`validate_request`** — validate a request's **body + path/query/header params**
+  against an OpenAPI 3.1 operation (`openapiSpec`,`method`,`path`,`body?`,`query?`,
+  `headers?`) → contract findings (message + path redacted). Scalar params, array params
+  (query form/space/pipe-delimited + path/header `simple`, non-string-scalar items), and
+  object params (query `deepObject` + `form/explode=false`); ambiguous serializations
+  (e.g. `form/explode=true` objects, string-item delimited arrays, fractional `multipleOf`
+  numbers) are skipped as uncheckable, never a false finding (ADR 0016). A GraphQL envelope
+  is refused, not schema-failed.
+- Resource **`sackville://run/{runId}/body`** — fetch a stored response body by
+  its handle (bodies are never inlined).
+
+**Safety:** `allowUnsafe` / `allowedHosts` are **operator-controlled** — set on
+the bin via env, never exposed as tool inputs (an agent can't authorize its own
+mutating requests). Mutations dry-run unless both are set (ADR 0004).
+
+## Browser tools (`sackville-browser-mcp`)
+
+Stateful, session-oriented (open → drive → close); all large artifacts by handle:
+
+- **`browser_open_session`** / **`browser_list_sessions`** / **`browser_close_session`**
+  — lifecycle. Open mints a server-side `sessionId` + `runId` (never agent inputs)
+  and reports `capturing` + `sessionCount`/`maxContexts`; close flushes and returns
+  the run artifact handles.
+- **`browser_navigate`** / **`browser_snapshot`** — drive + (re)capture a
+  token-capped ARIA snapshot whose elements carry `[ref=…]` ids.
+- **`browser_click`/`fill`/`fill_form`/`select`/`press`** — interact by ref;
+  mutations **dry-run** (redacted would-be-request preview) unless the operator
+  unlocked execution. `fill` resolves `{{secret:NAME}}` server-side (fail-closed).
+- **`browser_wait_for`** / **`browser_get_text`/`get_value`/`get_attribute`** —
+  read-like; reads are redacted and don't invalidate refs.
+- **`browser_assert`** — evaluate declarative assertions against the live page
+  (a free read). Page sources `url`/`title`/`ariaSnapshot`; element sources
+  `text`/`value`/`visible`/`count` (by ref or role+name); the shared `@sackville-mcp/assert`
+  operator set (`equals`/`contains`/`matches`/`gt`/…). Each **auto-waits** to its
+  timeout; observed values are redacted. Returns `{pass, results}`.
+- **`browser_audit_a11y`** — axe-core audit; compact summary + report by handle.
+- **`browser_perf_audit`** — Lighthouse performance audit of a URL (allowlist-gated;
+  spawns a fresh proxied Chrome, independent of any session). Score + core web-vitals
+  inline; full LHR JSON + HTML by handle. Assert shape/thresholds, never exact scores.
+- **`browser_trace_query`** — parse a captured trace.zip (by `runId`; needs trace
+  capture on) into an action timeline (API calls + timing + errors), console, and an
+  errors list. No live session needed — query after the session closed; the trace is
+  already redacted. `apiFilter`/`errorsOnly`/`limit`/`includeParams` narrow it.
+- **`browser_screenshot`** — operator-gated (off by default; pixels can't be
+  redacted, like the trace.zip); captures a PNG to a `screenshot-s<n>` handle
+  (summary only, never inlined) and does not invalidate refs.
+- **`browser_vision_click`** / **`browser_vision_move`** — drive the pointer at a
+  viewport coordinate (CSS pixels, e.g. from a screenshot) for canvas / non-AX-tree
+  UI the snapshot can't address. Operator-gated **off by default** (`ALLOW_VISION`) —
+  a blind click on a *point* sidesteps the accessible-tree safety story; the click
+  still goes through the mutation gate. Prefer ref-based `browser_click` whenever the
+  element is in the snapshot.
+- **`browser_visual_compare`** — visual regression: capture the current page
+  (animations frozen, caret hidden) and pixel-diff it against a stored baseline (by
+  name) via pixelmatch. Returns pass + diff pixel count/ratio; the diff PNG is stored
+  by `visual-diff-s<n>` handle on a mismatch. `maxDiffPixelRatio`/`maxDiffPixels` set
+  the budget, `mask[]` ignores dynamic regions. Operator-gated (`BASELINE_DIR`);
+  `update:true` records the baseline only when `ALLOW_BASELINE_UPDATE` is set (an
+  agent can't rewrite the golden). Assert on a diff budget, not exact pixels.
+- **`browser_upload`** — set file(s) on a file-input ref. Deny-by-default: requires
+  an operator upload-allowlist dir and confines every path within it (no traversal/
+  absolute escape), so an agent can't upload arbitrary local files.
+- **`browser_downloads`** — collect file downloads since the last call (a free read).
+  Downloads are denied by default (cancelled); with an operator quarantine dir set
+  they're saved there under a sanitized name and reported as filename/path/size —
+  the bytes are never served. `waitMs` waits briefly for a download a click just started.
+- **`browser_save_storage_state`** — operator-gated; writes the password-equivalent
+  storageState to an operator-path artifact (handle + counts only, never inlined).
+- **`browser_replay_har`** — "network heavy mode" replay: serve the session from a
+  recorded HAR instead of the network (`routeFromHAR`, unmatched requests aborted —
+  deterministic, zero egress). Call before navigating. Operator-gated + deny-by-default
+  (requires a replay dir; the HAR must resolve within it). **HAR capture** is the flip
+  side: with an operator `HAR_DIR` set, each session records a full HAR (bodies
+  attached) that `browser_close_session` finalizes — redacted, by `har` handle, with a
+  compact summary.
+- **`browser_list_flows`** / **`browser_run_flow`** — list the persisted `.bru`
+  flows the operator made available (by name + step count) and replay one (by name)
+  on a session. Steps drive through the SAME gate (navigation allowlist + dry-run-vs-
+  execute) and redactor as the live step tools; `{{var}}` values are caller-supplied
+  (non-secret), `{{secret:NAME}}` resolves server-side (fail-closed, never echoed).
+  Operator-gated + deny-by-default (requires a `FLOWS_DIR`; the flow is named, never a
+  caller-supplied path). The human-CLI counterpart is `sackville browser run`.
+- **Video capture** — with an operator `VIDEO_DIR` set, each session records a
+  `.webm`; `browser_close_session` finalizes it (written on context close) and
+  surfaces it by `video` handle. Operator-gated off by default — video is
+  unredactable pixels (same posture as the trace/screenshots); an optional size cap
+  (`VIDEO_WIDTH`/`VIDEO_HEIGHT`) bounds the frame size, the session wall-clock cap
+  bounds duration.
+- Resource **`sackville://browser/run/{runId}/{kind}`** — fetch a stored artifact
+  (`snapshot-s<gen>` / `a11y-s<n>` / `screenshot-s<n>` / `trace` / `console` /
+  `network` / `har` / `video`) by handle; binary kinds (trace.zip, screenshot PNG,
+  HAR .zip, video webm) come back as a base64 blob. The password-equivalent
+  `storage-state` kind is **refused** (operator-path only).
+
+**Safety (all operator-set via `SACKVILLE_BROWSER_*` env, never tool inputs):**
+navigation/mutation deny-by-default (`ALLOW_UNSAFE`, `ALLOWED_HOSTS`); a **mandatory**
+DNS-pinning SSRF proxy (loopback forced through it; `ALLOW_PRIVATE` opt-in);
+service-workers blocked + WebRTC egress neutralized; JS dialogs dismissed by
+default (`ALLOW_DIALOGS` to accept; each recorded, redacted, on the step result);
+downloads cancelled unless an operator quarantine dir (`DOWNLOAD_DIR`) is set;
+uploads confined to an operator allowlist dir (`UPLOAD_DIR`, denied when unset);
+HAR capture off unless an operator output dir (`HAR_DIR`) is set + HAR replay off
+unless a replay dir (`REPLAY_HAR_DIR`) is set, both deny-by-default; persisted-flow
+replay off unless a flows dir (`FLOWS_DIR`) is set; video capture off unless a video
+dir (`VIDEO_DIR`) is set; visual-regression compare off unless a baseline dir
+(`BASELINE_DIR`) is set + baseline writes gated behind `ALLOW_BASELINE_UPDATE`; secret
+redaction across every artifact + the trace.zip + the HAR; `{{secret:NAME}}` fill +
+origin-scoped `httpCredentials` (`HTTP_USERNAME/PASSWORD/ORIGIN`); caps
+`MAX_SESSIONS`/`SESSION_MS`/`MAX_PAGES`/
+`IDLE_TTL_MS`; trace capture + `storageState` capture (`ALLOW_STORAGE_STATE`) +
+screenshot capture (`ALLOW_SCREENSHOTS`) + vision/coordinate input (`ALLOW_VISION`)
+all off unless explicitly enabled.
+
+## Run
+
+```bash
+sackville-mcp <index.sqlite>          # docs; or: SACKVILLE_INDEX=… sackville-mcp
+
+# API testing — mutations dry-run unless explicitly unlocked:
+sackville-api-mcp
+SACKVILLE_ALLOW_UNSAFE=1 SACKVILLE_ALLOWED_HOSTS=api.example.com sackville-api-mcp
+
+# Browser testing — deny-by-default; unlock + allowlist per operator policy:
+SACKVILLE_BROWSER_ALLOWED_HOSTS=app.test,127.0.0.1 sackville-browser-mcp
+```
+
+All three speak MCP over stdio.
+
+### Register with Claude Code
+
+```bash
+claude mcp add sackville         -- sackville-mcp /path/to/index.sqlite
+claude mcp add sackville-api     -- sackville-api-mcp
+claude mcp add sackville-browser -- sackville-browser-mcp
+```
+
+## Token economy
+
+Search returns summaries + resource links, not bodies; the agent fetches full
+text only when it follows a link. This keeps results well under Claude Code's
+~10k-token warning threshold. See `ARCHITECTURE.md` §4.