@revfleet/hscli 0.9.7 → 0.10.0

package/docs/INTERNAL_ENDPOINTS.md

@@ -58,7 +58,7 @@ read-like surfaces into JSON backup assets:
 | `permission-access` | App users, teams, permission sets, assignment maps, roles, seats, templates, FLP, and access-audit RPCs |
 | `datasets-reporting` | Data Studio datasets, reportable sources, joins, formulas, previews, async resolve calls, and async result polling |
 | `reports-dashboards` | Report definitions, favorites, report audit/history, record-view metadata, report permissions, report template discovery, dashboard layouts, widgets, dashboard grants, and report-list views |
-| `workflows-hybrid` | Workflow inventories, hybrid action graphs, validation, output fields, action catalog, CRM object context, canvas errors, access checks, filter-description previews, and card-position RPCs |
+| `workflows-hybrid` | Workflow inventories, current hybrid action graphs, full revision history, validation previews, output fields, action catalog, CRM object context, canvas errors, access checks, filter-description previews, and card-position RPCs |
 | `properties-metadata` | Internal property metadata, legacy v1/v2 fallbacks, property groups, grouped-property listings, named property reads, recycled properties, quotas, fill rates, validation, dynamic options, and conditional options |
 | `crm-search` | Read-only CRM search, CRM GraphQL, object preview, and single-object UI payload helpers used by report builders, help desk, quotes, and object indexes |
 | `object-metadata` | Schema metadata, framework-builder metadata, portal-scoped object types, event object types, and object-type batch reads |
@@ -107,6 +107,24 @@ for research and migration design, but they are not included in
 be implemented as explicit product commands with policy checks, dry-run,
 `--force`, and audit trails.
 
+The sole promoted workflow write adapter is
+`hscli workflows update-internal <flowId>`. It targets the undocumented
+`POST /api/automationplatform/v1/hybrid/batch` editor endpoint and is never
+part of `internal capture` or MCP. It is plan-only by default and adds stronger
+gates than normal writes: one disabled flow, matching requested/input/live ID,
+same-session portal proof, live-version optimistic locking, validation,
+owner-only snapshot, one request with retries disabled, and post-save proof
+from both current state and revision history. Operators must also provide a
+change ticket, sealed action contract, explicit experimental opt-in, `--force`,
+and an ID-bound acknowledgement.
+
+Record-card writes are similarly promoted only through
+`crm record-layouts update-card`. The command reads the live card, replaces
+only `configuration.propertyNames`, snapshots the full before/after payload,
+uses one non-retried `PUT /api/crm-record-cards/v4/crm-cards/{cardId}`, and
+verifies the exact ordered property list. It is not available to generic
+capture or MCP.
+
 ## Browser Session Auth Pattern
 
 Most internal endpoints require the HubSpot browser cookies plus the modern
@@ -189,9 +207,9 @@ commands. hscli exposes only the allowlisted reads below through
 | Reports | `/api/dashboard/v2/reports/*`, `/reporting-migration/v2/reports/migrate` |
 | Reporting data | `/api/reporting/v3/dataset/resolve/async` |
 | Datasets | `/sql-reporting/v1/datasets/*`, `/sql-reporting/v1/extended-reportable-options/*` |
-| Workflows | `/api/automationplatform/v1/hybrid/{flowId}`, validation, output fields, action catalog |
+| Workflows | `/api/automationplatform/v1/flows/{flowId}`, `/api/automationplatform/v1/hybrid/{flowId}`, `/api/automationplatform/v1/hybrid/revisions/{flowId}`, validation, canvas errors, output fields, action catalog; guarded CLI-only full replacement via `/api/automationplatform/v1/hybrid/batch` |
 | Properties | `/api/properties/v4/{typeId}`, `/api/properties/v4/groups/{typeId}`, v2 fallbacks |
-| Lists / segments | Legacy contacts lists, ILS segments, list search, and UI list views |
+| Lists / segments | Legacy contacts lists, ILS segments, list search, UI list views, and `/api/inbounddb-lists/v1/lists/{listId}` complete filter trees |
 | Sales content | `/api/templates/v1`, `/api/sales-content/v1`, `/api/sales-content-libraries/v2` |
 | Sequences | `/api/salescontentsearch/v2/search`, `/api/sequences/v3/sequences/{id}` |
 | Playbooks | Chirp RPC `com.hubspot.playbooks.rpc.PlaybooksRpc` |
@@ -206,7 +224,7 @@ commands. hscli exposes only the allowlisted reads below through
 | Social and ads | `/api/broadcast/v2/*` plus read-only `com.hubspot.ads.rpc.*` Chirp RPCs |
 | CRM search and previews | `/api/crm-search/*`, `/api/graphql/crm`, and `/inbounddb-objects/v1/*` |
 | Conditional properties | `/api/conditional-properties/v2/rules/*` plus unified RPC reads |
-| Record cards | `/api/crm-record-cards/v4/container-views/*` |
+| Record cards | `/api/crm-record-cards/v4/container-views/search`, `/get-view/CRM_RECORD_PAGE/{layoutId}`, `/api/crm-record-cards/v4/crm-cards/all`, and `/crm-cards/{cardId}` |
 | Conversations / help desk | Custom views and Chirp RPC help desk services |
 | Chatflows | Chirp RPC `com.hubspot.chatflows.rpc.*` |
 | Payments / quotes / forecast | Feature-gated internal setup and eligibility endpoints |

package/docs/MCP.md

@@ -18,6 +18,11 @@ hscli mcp                                      # minimal: essential CRM reads
 hscli mcp --surface crm                        # curated CRM reads + writes
 hscli mcp --surface migration                  # cross-product migration tools
 hscli mcp --surface full                       # all tools, including raw API
+hscli --json mcp manifest --surface minimal    # protocol + transport + tool metadata
+hscli --profile prod --json mcp doctor         # local profile and safety diagnostics
+hscli --profile prod --json mcp doctor --all   # external checks, clearly marked not live-run
+hscli --profile prod --json mcp setup --client codex  # plan only; no credential/config write
+hscli --json mcp matrix                        # intended use + trust boundaries
 ```
 
 The default `minimal` surface keeps agent context and write exposure small.
@@ -26,10 +31,12 @@ pass command arguments.
 
 ## Profile isolation and safety defaults
 
-- **Profile isolation**: set `HSCLI_MCP_PROFILE=<profile>` to hard-lock the MCP server to one auth profile.
+- **Profile isolation**: `hscli --profile <profile> mcp serve` hard-locks the server to that startup profile by default.
   - If a tool call requests a different profile, the server rejects it.
+  - Cross-profile selection is available only with the operator-controlled `--allow-cross-profile` startup flag.
 - **Write tools are dry-run by default**:
-  - `force: true` is required to execute actual writes.
+  - `force: true` on the tool call is necessary but not sufficient.
+  - The operator must also start the server with `--allow-writes` (or explicitly set `HSCLI_MCP_ALLOW_WRITES=1`).
   - Without `force`, write tools return a dry-run payload (`{ dryRun: true, method, path, body }`).
 - **Lifecycle coverage for CRM objects**:
   - standard object tools now include delete, merge, batch read/upsert/archive.
@@ -39,6 +46,20 @@ pass command arguments.
   - Pipeline object types: `deals`, `tickets`
 - **Secrets redaction**:
   - Token-like fields and bearer strings are redacted in MCP tool outputs and errors.
+- **Conservative tool annotations**:
+  - Every registered tool publishes `readOnlyHint`, `destructiveHint`,
+    `idempotentHint`, and `openWorldHint`.
+  - Unknown or mixed-operation tools default to write/destructive metadata.
+  - `manage_crm_objects` and raw `hub_api_request` are destructive because
+    their runtime arguments can select delete operations.
+- **Stable diagnostic schemas**:
+  - `hscli_mcp_manifest` and `hscli_mcp_doctor` publish MCP `outputSchema`
+    declarations and return validated structured content.
+  - The 11-tool HubSpot name-compatible subset also publishes object-level
+    output schemas so clients can rely on structured content without assuming
+    HubSpot Remote MCP authorization or transport equivalence.
+  - Raw HubSpot tools deliberately do not claim stable output schemas because
+    their response shapes vary by endpoint, product tier, and portal state.
 
 ## Claude Desktop setup
 
@@ -84,14 +105,29 @@ If your client accepts env vars, set:
 - `HSCLI_HOME` to the auth profile directory containing `auth.json`
 - `HSCLI_MCP_PROFILE` to force strict profile isolation
 
+## Three-server setup
+
+The products are complementary and should be configured side by side:
+
+| Server | Transport / auth | Best use |
+|---|---|---|
+| HubSpot Remote MCP | Streamable HTTP, OAuth 2.1 + PKCE, HubSpot user permissions | User-authorized CRM, activities, content, and marketing operations |
+| HubSpot Developer MCP | stdio via HubSpot CLI 8.2+ | HubSpot app and CMS development (`hs mcp setup`) |
+| hscli MCP | local stdio, hscli profile | Bulk operations, migrations, backups, internal adapters, policy, tickets, audit evidence |
+
+Run `hscli --profile <name> --json mcp setup --client <client>` for a
+secret-free plan. The command does not perform OAuth, write client config, or
+store credentials. Run `mcp doctor --all` afterward; external checks remain
+`external-check-required` until the owning client completes them.
+
 ## Tool surfaces
 
 | Surface | Tools | Intended use | Raw API |
 |---|---:|---|---|
-| `minimal` | 29 | Agent discovery and essential CRM reads | No |
-| `crm` | 136 | CRM objects, schemas, properties, associations, imports | No |
-| `migration` | 179 | Curated cross-product backup and migration work | No |
-| `full` | 180 | Explicit operator access to every registered tool | Yes |
+| `minimal` | 31 | Agent diagnostics, discovery, and essential CRM reads | No |
+| `crm` | 138 | CRM objects, schemas, properties, associations, imports | No |
+| `migration` | 181 | Curated cross-product backup and migration work | No |
+| `full` | 182 | Explicit operator access to every registered tool | Yes |
 
 The exact catalog is generated from runtime registration metadata, including
 domain, inferred risk, surfaces, and description:
@@ -107,5 +143,11 @@ npm run docs:mcp:check
 ## Notes
 
 - MCP transport is stdio only in this implementation.
+- The packaged SDK currently negotiates MCP `2025-11-25`. Streamable HTTP,
+  MCP Tasks, MCP Apps, and explicit `2026-07-28` opt-in are not enabled.
+  They require a separate SDK-v2 migration and transport compatibility gate.
 - Existing auth + HTTP core logic is reused (`getToken`, `HubSpotClient`, `maybeWrite`, redaction).
 - `hub_api_request` is exposed only by `--surface full`.
+- MCP writes use the startup write gate, dry-run, force, policy, portal-pin, and change-ticket gates,
+  but are not yet bound to sealed `hscli agent contract` prepare/apply/verify
+  workflows. `mcp doctor` reports this limitation explicitly.