@affset/mcp 0.1.1 → 0.3.0

package/.env.example

@@ -12,6 +12,11 @@ AFFSET_NAMESPACE=your-namespace
 # Optional. Per-request HTTP timeout in milliseconds (1000–300000; default 30000).
 # AFFSET_REQUEST_TIMEOUT_MS=30000
 
+# Optional. Origin the API-reference documentation resources are fetched from
+# (origin only, no path). Defaults to the affset marketing site; override to
+# point at a staging docs host. Fetched anonymously — no API key is sent here.
+# AFFSET_DOCS_URL=https://affset.com
+
 # Optional. Set to true to register only read-only tools (no create/update/delete/
 # cut) — recommended for stats/reporting sessions, especially with an MCP client
 # that auto-approves tool calls. See README Security section. Default false.

package/README.md

@@ -4,38 +4,55 @@ An [MCP](https://modelcontextprotocol.io) server that lets a media buyer run aff
 from a chat client — pull stats, manage campaigns/zones/team, payouts, targeting,
 sub labels, and cut underperforming zones in plain language, no dashboard.
 
-It's a thin wrapper over the existing affset tenant API (`Bearer` token +
-`X-Namespace`). One server instance serves one tenant.
+The tools wrap the existing affset tenant API. Connect through the hosted
+endpoint (OAuth, no API key) or run this package locally (`Bearer` token +
+`X-Namespace`). One connection serves one tenant.
+
+**Fastest way to connect — the hosted endpoint.** Add
+`https://mcp.affset.com/mcp` as a remote MCP server in Claude (web or desktop),
+Cursor, Claude Code, or any client that supports streamable HTTP with OAuth:
+paste the URL, sign in with your affset email, keep **Read-only** (the consent
+default) or grant full access. Every connection shows up on the dashboard
+Integrations page and can be revoked individually. Setup guide:
+[affset.com/integrations](https://affset.com/integrations).
+
+The npm package below is the self-host path: same tool roster, runs on your
+machine with an API key you manage yourself. Stdio defaults to full access
+unless you set `AFFSET_READ_ONLY=true`.
 
 ## Tools
 
-| Tool                    | What it does                                                                                                                                                                                                                                                                                          |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `whoami`                | Show the tenant this server is bound to: namespace, API base, derived dashboard URL, and (when readable) company / timezone / custom API domain. Read-only.                                                                                                                                           |
-| `get_stats`             | Traffic stats grouped by a dimension (date, campaign, zone, country, sub1–5, …). Returns clicks, conversions, CR, payout, media cost and ROI as a table. Sub columns use the tenant's sub labels when configured.                                                                                     |
-| `list_campaigns`        | List campaigns (status / name filter, pagination).                                                                                                                                                                                                                                                    |
-| `list_zones`            | List traffic-source zones (status / name filter, pagination).                                                                                                                                                                                                                                         |
-| `list_team`             | List team members (email, role, manager). **Never returns API tokens.**                                                                                                                                                                                                                               |
-| `create_team_member`    | Invite a team member (owner, manager, publisher, advertiser, publisher_manager, advertiser_manager). A scoped manager key can only create its own managed role, self-assigned. Returns the new API key **once** — `list_team` never shows it again. **Dry-run by default**; `confirm: true` to apply. |
-| `create_campaign`       | Create a campaign from an advertiser email, offer URL, geo, payout and name. Defaults: CPA / rate 0, **paused**, global payout rule, ready tracking link with `source_click_id={clickid}` + sub placeholders. **Dry-run by default**; `confirm: true` to apply.                                       |
-| `set_campaign_status`   | **Run** or **pause** a campaign (`action: "run" \| "pause"`). **Dry-run by default**; `confirm: true` to apply. Running can hit the plan's active-campaign limit.                                                                                                                                     |
-| `update_campaign`       | Partial update (name, offer URL, status, rate, budgets, dates, …). **Dry-run by default**; `confirm: true` to apply. Prefer `set_campaign_status` for run/pause.                                                                                                                                      |
-| `create_zone`           | Create a traffic-source zone (name + optional postback/site/traffic-back URLs). Always created `active`. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                            |
-| `update_zone`           | Partial update (name, status, URLs). **Dry-run by default**; `confirm: true` to apply. Pass `null` to clear a URL.                                                                                                                                                                                    |
-| `get_zone_url`          | The `/serve` URL to paste into a network's campaign settings — rotates across the zone's **active** campaigns. Prefilled sub convention, optional `cost` macro. Warns when no active campaigns are visible.                                                                                           |
-| `get_tracking_link`     | The `/track/click` link for an existing campaign + zone — straight to one active campaign, with no rotation or targeting checks. Re-derives what `create_campaign` echoed on create.                                                                                                                  |
-| `cut_zones`             | Blacklist underperforming zones on a campaign by threshold (CR / spend / ROI). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                      |
-| `list_payout_rules`     | List a campaign's global + per-zone payout rules and its `payout_goal_type`.                                                                                                                                                                                                                          |
-| `set_payout_rule`       | Upsert a global or zone-specific payout. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                            |
-| `delete_payout_rule`    | Delete a global or zone-specific payout rule. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                       |
-| `set_payout_goal`       | Set or clear `payout_goal_type` (goal-based conversions). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                           |
-| `list_targeting_types`  | Catalog of targeting rule types, flagging the seeded ones `/serve` never evaluates.                                                                                                                                                                                                                   |
-| `list_targeting_rules`  | List a campaign's targeting rules, flagging any that have no effect.                                                                                                                                                                                                                                  |
-| `set_targeting_rule`    | Upsert one targeting rule (safe merge), normalised to what `/serve` matches. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                        |
-| `remove_targeting_rule` | Remove one targeting rule by id or type+method. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                     |
-| `list_sub_labels`       | List tenant display names for sub1–sub5.                                                                                                                                                                                                                                                              |
-| `set_sub_labels`        | Set or clear sub labels (partial; `null` clears). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                   |
-| `list_conversions`      | List conversion audit records (payout, spend, pixel type, payload, postback). Optional client-side filters on the current page.                                                                                                                                                                       |
+| Tool                    | What it does                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `whoami`                | Show the tenant this server is bound to: namespace, API base, derived dashboard URL, and (when readable) company / timezone / custom API domain. Read-only.                                                                                                                                                                                                                                                                                                                                                                   |
+| `get_stats`             | Traffic stats grouped by a dimension (date, campaign, zone, country, sub1–5, advertiser, publisher, …), optionally narrowed with `advertiser_email`/`publisher_email` filters (one user, any group_by). Returns clicks, conversions, CR, payout, media cost and ROI as a table. `paid_only` defaults to true (same as the dashboard) so CR excludes informative conversions. Sub columns use the tenant's sub labels when configured. Per-user groupings and filters are owner/manager plus the matching side's manager role. |
+| `list_campaigns`        | List campaigns (status / name filter, pagination).                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `get_campaign`          | One campaign's full record — every field (untruncated offer URL, exact schedule, budgets/pacing, silent flag, payout goal type) plus its targeting rules and payout rules, in one call.                                                                                                                                                                                                                                                                                                                                       |
+| `list_zones`            | List traffic-source zones (status / name filter, pagination, linked source).                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `list_team`             | List team members (email, role, manager). **Never returns API tokens.**                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
+| `create_team_member`    | Invite a team member (owner, manager, publisher, advertiser, publisher_manager, advertiser_manager). A scoped manager key can only create its own managed role, self-assigned. Returns the new API key **once** — `list_team` never shows it again. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                         |
+| `create_campaign`       | Create a campaign from an advertiser email, offer URL, geo, payout and name. Defaults: CPA / rate 0, **paused**, global payout rule, and a ready tracking link (linked source template when configured; otherwise `source_click_id={clickid}` + sub placeholders). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                          |
+| `set_campaign_status`   | **Run** or **pause** a campaign (`action: "run" \| "pause"`). **Dry-run by default**; `confirm: true` to apply. Running can hit the plan's active-campaign limit.                                                                                                                                                                                                                                                                                                                                                             |
+| `update_campaign`       | Partial update (name, offer URL, status, rate, budgets, dates, …). **Dry-run by default**; `confirm: true` to apply. Prefer `set_campaign_status` for run/pause.                                                                                                                                                                                                                                                                                                                                                              |
+| `create_zone`           | Create a traffic-source zone (name + optional postback/site/traffic-back URLs, optional `traffic_source_id` link). Always created `active`. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                 |
+| `update_zone`           | Partial update (name, status, URLs, `traffic_source_id`). **Dry-run by default**; `confirm: true` to apply. Pass `null` to clear a URL or unlink the source.                                                                                                                                                                                                                                                                                                                                                                  |
+| `list_traffic_sources`  | List traffic sources — the networks bought from, each with the tracking/postback templates its linked zones use. API token shown only as set/none.                                                                                                                                                                                                                                                                                                                                                                            |
+| `create_traffic_source` | Create a traffic source, optionally from a network preset (`exoclick`, `trafficstars`, `propellerads`, `adsterra`, `richads`) that copies verified templates into an editable row. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                          |
+| `update_traffic_source` | Partial update (name, templates, api_token, status). Linked zones pick the new tracking template up immediately. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                                            |
+| `get_zone_url`          | The `/serve` URL to paste into a network's campaign settings — rotates across the zone's **active** campaigns. A zone linked to a traffic source renders that source's tracking template; otherwise prefilled sub convention + optional `cost` macro. Warns when no active campaigns are visible.                                                                                                                                                                                                                             |
+| `get_tracking_link`     | The `/track/click` link for an existing campaign + zone — straight to one active campaign, with no rotation or targeting checks. Renders a linked source's template like `get_zone_url`. Re-derives what `create_campaign` echoed on create.                                                                                                                                                                                                                                                                                  |
+| `cut_zones`             | Blacklist underperforming zones on a campaign by threshold (CR / spend / ROI). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                                                                              |
+| `list_payout_rules`     | List a campaign's global + per-zone payout rules and its `payout_goal_type`.                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `set_payout_rule`       | Upsert a global or zone-specific payout. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| `delete_payout_rule`    | Delete a global or zone-specific payout rule. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| `set_payout_goal`       | Set or clear `payout_goal_type` (goal-based conversions). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                                                                                                   |
+| `list_targeting_types`  | Catalog of targeting rule types, flagging the seeded ones `/serve` never evaluates.                                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `list_targeting_rules`  | List a campaign's targeting rules, flagging any that have no effect.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
+| `set_targeting_rule`    | Upsert one targeting rule (safe merge), normalised to what `/serve` matches. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                                                                                |
+| `remove_targeting_rule` | Remove one targeting rule by id or type+method. **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `list_sub_labels`       | List tenant display names for sub1–sub5.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| `set_sub_labels`        | Set or clear sub labels (partial; `null` clears). **Dry-run by default**; `confirm: true` to apply.                                                                                                                                                                                                                                                                                                                                                                                                                           |
+| `list_conversions`      | List conversion audit records (payout, spend, pixel type, payload, postback). `paid_only` filters server-side; other optional filters are client-side on the current page.                                                                                                                                                                                                                                                                                                                                                    |
 
 ### Which URL do I give the network?
 
@@ -64,23 +81,67 @@ URL. Both URL types also require an active zone. Geo whitelist is enforced in `/
 only — the direct tracking link is **not** geo-gated, but it still requires an active,
 currently serviceable campaign.
 
+## Documentation resources
+
+Beyond the tools, the server exposes the affset **API reference** as MCP
+[resources](https://modelcontextprotocol.io/docs/concepts/resources), so an
+assistant can answer "how does conversion tracking work?" or "what does `/serve`
+accept?" from the docs themselves — not just from the tool schemas.
+
+| Resource URI                       | Type               | Content                                                      |
+| ---------------------------------- | ------------------ | ------------------------------------------------------------ |
+| `affset://docs/api-reference`      | `text/markdown`    | The full API reference — endpoints, auth, roles, examples.   |
+| `affset://docs/api-reference.json` | `application/json` | The same reference as structured data, for programmatic use. |
+
+They're the exact content published at [affset.com/docs](https://affset.com/docs),
+generated from one source, and **fetched at read time** from `AFFSET_DOCS_URL`
+(`{origin}/api-reference.md` and `{origin}/api-reference.json`) — so they always
+reflect the currently published docs, not a copy pinned to this package. The
+fetch sends **no credentials** (the docs are public and live on a different
+origin than the tenant API). HTML SPA fallbacks, redirects, invalid JSON, and
+oversized bodies are rejected. Both resources are always available, including
+under `AFFSET_READ_ONLY`.
+
 ## Configuration
 
-All config comes from environment variables (never hard-coded):
+Self-host (stdio) only — hosted connections do not use these variables. All
+config comes from the environment (never hard-coded):
 
-| Variable                    | Description                                                                                                                                                                                                                                                                                         |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AFFSET_BASE_URL`           | Origin of the affset API, e.g. `https://api.affset.com` (no path/query/credentials). Must be `https` unless the host is `localhost`/`127.0.0.1`/`::1` — plain http would send the API key in cleartext.                                                                                             |
-| `AFFSET_API_KEY`            | Tenant API key. Its namespace must match `AFFSET_NAMESPACE`.                                                                                                                                                                                                                                        |
-| `AFFSET_NAMESPACE`          | Tenant namespace (lowercase letters, numbers, hyphens; 3–63 chars — same rules as signup).                                                                                                                                                                                                          |
-| `AFFSET_READ_ONLY`          | Optional, default `false`. Set to `true`/`1` to register only the read-only tools (`whoami`, `get_stats`, every `list_*`, `get_zone_url`, `get_tracking_link`) — every create/update/delete/cut tool is unavailable, not just gated behind confirm. See [Security](#security) for why this matters. |
-| `AFFSET_REQUEST_TIMEOUT_MS` | Optional, default `30000`. Per-request HTTP timeout in milliseconds (`1000`–`300000`).                                                                                                                                                                                                              |
+| Variable                    | Description                                                                                                                                                                                                                                                                                                         |
+| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `AFFSET_BASE_URL`           | Origin of the affset API, e.g. `https://api.affset.com` (no path/query/credentials). Must be `https` unless the host is `localhost`/`127.0.0.1`/`::1` — plain http would send the API key in cleartext.                                                                                                             |
+| `AFFSET_API_KEY`            | Tenant API key. Its namespace must match `AFFSET_NAMESPACE`.                                                                                                                                                                                                                                                        |
+| `AFFSET_NAMESPACE`          | Tenant namespace (lowercase letters, numbers, hyphens; 3–63 chars — same rules as signup).                                                                                                                                                                                                                          |
+| `AFFSET_READ_ONLY`          | Optional, default `false`. Set to `true`/`1` to register only the read-only tools (`whoami`, `get_stats`, `get_campaign`, every `list_*`, `get_zone_url`, `get_tracking_link`) — every create/update/delete/cut tool is unavailable, not just gated behind confirm. See [Security](#security) for why this matters. |
+| `AFFSET_REQUEST_TIMEOUT_MS` | Optional, default `30000`. Per-request HTTP timeout in milliseconds (`1000`–`300000`).                                                                                                                                                                                                                              |
+| `AFFSET_DOCS_URL`           | Optional, default `https://affset.com`. Origin the API-reference [documentation resources](#documentation-resources) are fetched from (origin only, no path). Fetched anonymously — no API key is sent here.                                                                                                        |
 
 See [`.env.example`](.env.example).
 
 ## Install
 
-### From npm (recommended)
+### Hosted (fastest — no install)
+
+Add the remote server in your MCP client and approve access in the browser.
+OAuth is discovered from the endpoint — do not paste an API key, and do not add
+an `Authorization` header.
+
+- **Claude (web or desktop)** — Customize → Connectors → **+** → Add custom connector →
+  `https://mcp.affset.com/mcp`.
+- **Cursor** — Settings → MCP → Add server, transport "streamable HTTP", same URL.
+- **Claude Code** — `claude mcp add --transport http affset https://mcp.affset.com/mcp`
+  then authenticate with `/mcp`.
+
+You sign in with your affset email (magic link). **Read-only** is selected on
+the consent screen unless you switch to **Full access**. The connection gets
+its own scoped credential — your API key is never involved — and appears on
+the dashboard's Integrations page, where it can be revoked at any time. Full
+guide: [affset.com/integrations](https://affset.com/integrations).
+
+The self-host paths below run the same tool roster over stdio and require
+Node.js 22.13 or newer.
+
+### From npm (recommended for self-hosting)
 
 No clone, no build — your MCP client runs it with `npx`. For **Claude Desktop**
 (`claude_desktop_config.json`):
@@ -164,6 +225,8 @@ for `"command": "node"`, `"args": ["/absolute/path/to/affset-mcp/dist/index.js"]
 
 > **list paused campaigns** → `list_campaigns(status: "paused")`
 >
+> **show me everything about campaign 42** → `get_campaign(campaign_id: 42)`
+>
 > **show zones** → `list_zones()`
 >
 > **who's on the team?** → `list_team()`
@@ -172,12 +235,19 @@ for `"command": "node"`, `"args": ["/absolute/path/to/affset-mcp/dist/index.js"]
 >
 > **stats for today by sub1** → `get_stats(group_by: "sub1")`
 >
-> **create a RichAds zone with postback** → `create_zone(name: "RichAds", postback_url: "https://…/{source_click_id}")` (dry-run) → confirm
+> **stats by advertiser** → `get_stats(group_by: "advertiser_email")`
+>
+> **stats for one publisher, grouped by zone** → `get_stats(group_by: "zone_id", publisher_email: "publisher@example.com")`
+>
+> **stats including informative conversions** → `get_stats(paid_only: false)`
+>
+> **set up RichAds end to end** → `create_traffic_source(name: "RichAds", preset: "richads")` (dry-run) → confirm
+> → `create_zone(name: "RichAds push", traffic_source_id: "…")` (dry-run) → confirm → `get_zone_url()`
 >
 > **create a campaign for offer X, advertiser buyer@example.com, geo BR, payout $2**
 > → `create_campaign(user_email: "buyer@example.com", offer_url: "https://offer.example/lp?s={click_id}", geo: ["BR"], payout: 2)` (dry-run) → confirm
 >
-> **what URL do I paste into RichAds?** → `get_zone_url(cost: "{cost}")`
+> **what URL do I paste into RichAds?** → `get_zone_url()` — a zone linked to a traffic source gets the source's template filled in
 >
 > **give me the link for campaign 42 again** → `get_tracking_link(campaign_id: 42)`
 >
@@ -204,14 +274,26 @@ for `"command": "node"`, `"args": ["/absolute/path/to/affset-mcp/dist/index.js"]
 >
 > **show recent conversions** → `list_conversions()`
 >
-> **find $0 payouts (goal miss?)** → `list_conversions(zero_payout: true)`
+> **hide informative conversions (goal-type misses)** → `list_conversions(paid_only: true)`
+>
+> **find $0 payouts (no rule / still on this page)** → `list_conversions(zero_payout: true)`
 >
 > **lookup by source click id** → `list_conversions(source_click_id: "abc123")`
 
 ## Notes & limits
 
 - **`get_stats` groups by one dimension per call.** Drill-down is a sequence of
-  calls, each narrowing with `campaign_ids` / `zone_ids` / `sub1..sub5` filters.
+  calls, each narrowing with `campaign_ids` / `zone_ids` / `sub1..sub5` /
+  `conversion_type` / `advertiser_email` / `publisher_email` / `paid_only` filters. The two email
+  filters select one user's campaigns or zones without changing `group_by`; access
+  is limited to owner/manager or the corresponding scoped manager role. Filtering
+  by `conversion_type` returns conversion rows only (impressions, clicks and media
+  cost are zero). `paid_only` defaults to **true** (the API default is false; this
+  matches the dashboard) so the conversions count and CR drop informative rows
+  recorded with `postback_skipped=non_goal_type` — pixel type missed the campaign's
+  `payout_goal_type`. Silent conversions still count; this is not a payout>0 filter.
+  Set `false` for the raw count. Only recent (unfolded) events are filtered;
+  conversions already in daily archives stay included.
 - **`spend` means `media_cost`** (your traffic cost). ROI / spend thresholds need
   cost data imported for the slice.
 - List endpoints have **no server-side name search** — `name_contains` filters the
@@ -241,9 +323,13 @@ for `"command": "node"`, `"args": ["/absolute/path/to/affset-mcp/dist/index.js"]
   while the campaign kept buying); `list_targeting_types` flags them. Use
   `unique_users` (`visits/hours`) for frequency capping.
 - **`list_conversions`** is the conversion audit trail (not aggregated stats). The API
-  has no campaign/zone/date filters; optional filters apply to the current page only.
-  Rows do not include campaign_id/zone_id. Publisher-side roles do not see `spend` and
-  advertiser-side roles do not see `payout`, so `zero_payout` needs a role that can.
+  has no campaign/zone/date filters; `paid_only` is the one server-side filter (`true`
+  drops rows recorded with `postback_skipped=non_goal_type` — pixel type missed the
+  campaign's `payout_goal_type`; silent conversions and other skip reasons still come
+  back — this is not a payout>0 filter). The other optional filters apply to the current
+  page only. Rows do not include campaign_id/zone_id. Publisher-side roles do not see
+  `spend` and advertiser-side roles do not see `payout`, so `zero_payout` needs a role
+  that can; `paid_only` does not (it keys on `postback_skipped`, not `payout`).
 - **`create_team_member`** creates the API key directly (like the dashboard's "Add Team
   Member") — it does not send an invite email. Hand the returned key to the person
   yourself. Revoking/removing a team member is not yet a tool; use the dashboard's
@@ -257,6 +343,44 @@ for `"command": "node"`, `"args": ["/absolute/path/to/affset-mcp/dist/index.js"]
   startup — so it could not use a tenant it just created. Sign up in the dashboard,
   then point a server instance at the new namespace.
 
+## Using as a library
+
+Since 0.2.0 the package doubles as a runtime-agnostic library: everything the
+stdio server registers (tools, docs resources, read-only stripping) is exposed
+as one helper that runs on any fetch-capable runtime — Node ≥22.13 or Cloudflare
+Workers. The hosted affset MCP gateway (`mcp.affset.com`) consumes
+exactly this surface, so the remote roster can never drift from stdio.
+
+```ts
+import { registerAffsetTools, type Config } from "@affset/mcp/core";
+
+const config: Config = {
+  baseUrl: "https://api.affset.com",
+  docsBaseUrl: "https://affset.com",
+  apiKey: perRequestKey, // e.g. an OAuth grant's backing credential
+  namespace: tenantNamespace,
+  requestTimeoutMs: 30_000,
+  readOnly: scope === "read", // never registers tools without readOnlyHint: true
+};
+
+registerAffsetTools(server, config); // server: your own McpServer instance
+```
+
+`registerAffsetTools` accepts your `McpServer` structurally, so your own
+`@modelcontextprotocol/sdk` install works — no need to match this package's
+copy. Env-var loading (`AFFSET_*`) is deliberately not part of the library
+surface; it belongs to the stdio entrypoint only. A third, optional
+`{ onToolCall }` argument reports only tool name, duration, and success/error
+status for transport-owned audit logging; arguments and output are never
+included.
+
+The library validates and normalizes `config` before registering anything.
+Remote API origins must use HTTPS (plain HTTP is accepted only on loopback),
+origins cannot contain credentials or paths, and invalid namespaces, timeouts,
+API keys, or non-boolean read-only settings fail closed at startup. The public
+declarations do not require Node ambient types, so the same import type-checks
+in Workers and other web-standard runtimes.
+
 ## Development
 
 ```bash
@@ -271,14 +395,23 @@ npm run dev          # watch mode
 
 ## Security
 
-- No secrets in the repo; credentials come from the environment at runtime.
+- **Hosted (`https://mcp.affset.com/mcp`):** OAuth via magic link. Read-only is
+  the consent default (mutating tools are never registered). Full access still
+  dry-runs mutations until `confirm: true`. Revoke from the dashboard
+  Integrations page. Nothing on `mcp.affset.com` / `oauth.affset.com` asks for
+  an API key.
+- **Self-host (stdio):** no secrets in the repo; credentials come from the
+  environment at runtime. Create a **dedicated, least-privilege, expiring API
+  key** rather than reusing an owner key.
 - `AFFSET_BASE_URL` must be `https` unless the host is loopback — no cleartext API key.
+- Tenant API responses are streamed under a 5 MB hard limit; larger bodies are
+  cancelled before parsing or reaching model context.
 - stdout is the JSON-RPC channel — all logs go to stderr.
 - `list_team` redacts API tokens.
 - All mutations (including creates) follow **show → confirm → apply**.
-- Create a **dedicated, least-privilege API key** for the MCP rather than reusing an
-  owner key, and give it an expiry — affset's RBAC roles (owner/manager/publisher/
-  advertiser) apply to MCP tool calls exactly as they do to the dashboard.
+- affset's RBAC roles (owner / manager / publisher / advertiser /
+  advertiser_manager / publisher_manager) apply to MCP tool calls exactly as
+  they do to the dashboard.
 - Pin GitHub installs to a reviewed commit or tag in long-lived environments. A
   floating `main` spec can run newer repository code the next time `npx` resolves it.
 
@@ -298,10 +431,12 @@ Mitigations in place:
 - `confirm: true` on mutating tools is a **model-level** safety net, not a security
   boundary — a model that has been steered by injected content can supply
   `confirm: true` itself. The only real boundary is your MCP client's per-call tool
-  approval and **`AFFSET_READ_ONLY`**.
-
-**Set `AFFSET_READ_ONLY=true`** for any session where you're mainly reading stats/
-conversions, especially with an MCP client that auto-approves tool calls. It removes
-every mutation tool from the server entirely — not hidden behind a prompt, unavailable
-to call. Reserve a read-write instance (or a separate one) for sessions where you're
-actively managing campaigns/zones/payouts and are reviewing each confirm yourself.
+  approval plus **read-only mode** (hosted: consent default; stdio:
+  **`AFFSET_READ_ONLY=true`**).
+
+Prefer read-only for any session where you're mainly reading stats/conversions,
+especially with an MCP client that auto-approves tool calls. It removes every
+mutation tool from the server entirely — not hidden behind a prompt, unavailable
+to call. Reserve full access (hosted) or a read-write stdio instance for sessions
+where you're actively managing campaigns/zones/payouts and are reviewing each
+confirm yourself.

package/dist/client.d.ts

@@ -0,0 +1,43 @@
+import { type Config } from "./runtimeConfig.js";
+/** Thrown when the affset API returns a non-2xx response. */
+export declare class AffsetApiError extends Error {
+    readonly status: number;
+    /** Parsed JSON body when present (e.g. plan-limit details). */
+    readonly body?: unknown | undefined;
+    constructor(status: number, message: string, 
+    /** Parsed JSON body when present (e.g. plan-limit details). */
+    body?: unknown | undefined);
+}
+type Query = Record<string, string | number | undefined>;
+/**
+ * Thin typed HTTP client over the affset tenant API. Injects the Bearer token
+ * and `X-Namespace` header on every request and normalises error handling.
+ */
+export declare class AffsetClient {
+    private readonly config;
+    constructor(config: Config);
+    /** Resolved once per process; the tenant timezone changes about never. */
+    private tenantTimezone?;
+    /**
+     * The tenant's timezone (IANA name). Date ranges must be resolved in it, not
+     * in the host machine's zone, so that a requested window lines up with the
+     * date buckets `/api/stats?group_by=date` returns.
+     *
+     * Falls back to UTC if the setting cannot be read — a stats query with a
+     * slightly-off window beats failing the whole call.
+     */
+    getTenantTimezone(): Promise<string>;
+    /**
+     * Tenant timezone for a write whose meaning depends on local midnight. Unlike
+     * stats reads, silently falling back to UTC here could change a schedule, so
+     * callers get the underlying API error and must stop the mutation.
+     */
+    getRequiredTenantTimezone(): Promise<string>;
+    private readTenantTimezone;
+    get<T>(path: string, query?: Query): Promise<T>;
+    post<T>(path: string, body: unknown): Promise<T>;
+    put<T>(path: string, body: unknown): Promise<T>;
+    delete<T>(path: string, query?: Query): Promise<T>;
+    private request;
+}
+export {};

package/dist/client.js

@@ -1,3 +1,5 @@
+import { readResponseText, ResponseTooLargeError } from "./lib/readBody.js";
+import { normalizeRuntimeConfig } from "./runtimeConfig.js";
 /** Thrown when the affset API returns a non-2xx response. */
 export class AffsetApiError extends Error {
     status;
@@ -11,6 +13,8 @@ export class AffsetApiError extends Error {
         this.name = "AffsetApiError";
     }
 }
+/** Bound upstream memory use before JSON parsing or rendering into model context. */
+const MAX_API_RESPONSE_BYTES = 5_000_000;
 /**
  * Thin typed HTTP client over the affset tenant API. Injects the Bearer token
  * and `X-Namespace` header on every request and normalises error handling.
@@ -18,7 +22,7 @@ export class AffsetApiError extends Error {
 export class AffsetClient {
     config;
     constructor(config) {
-        this.config = config;
+        this.config = normalizeRuntimeConfig(config);
     }
     /** Resolved once per process; the tenant timezone changes about never. */
     tenantTimezone;
@@ -100,7 +104,16 @@ export class AffsetClient {
             }
             throw new AffsetApiError(0, `Network error calling ${method} ${path}: ${err instanceof Error ? err.message : String(err)}`);
         }
-        const text = await res.text();
+        let text;
+        try {
+            text = await readResponseText(res, MAX_API_RESPONSE_BYTES);
+        }
+        catch (err) {
+            if (err instanceof ResponseTooLargeError) {
+                throw new AffsetApiError(res.ok ? 0 : res.status, `Response too large calling ${method} ${path}: ${err.message}.`);
+            }
+            throw err;
+        }
         let data = null;
         if (text) {
             try {

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+import type { Config } from "./runtimeConfig.js";
+export type { Config } from "./runtimeConfig.js";
+/**
+ * Read and validate config from the environment. Throws with an actionable
+ * message listing every missing variable — surfaced to the user at startup.
+ */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -1,31 +1,9 @@
+import { MAX_REQUEST_TIMEOUT_MS, MIN_REQUEST_TIMEOUT_MS, parseOriginUrl, validateApiKey, validateNamespace, } from "./runtimeConfig.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
-const MAX_TIMEOUT_MS = 300_000;
+/** Where the docs feeds live when AFFSET_DOCS_URL is not set. */
+const DEFAULT_DOCS_URL = "https://affset.com";
 const TRUTHY = new Set(["1", "true", "yes", "on"]);
 const FALSY = new Set(["0", "false", "no", "off"]);
-/**
- * Same rules as lite-adserver signup: lowercase alnum + hyphens, 3–63 chars,
- * no leading/trailing hyphen, no consecutive hyphens. Keeps whoami's
- * `https://{namespace}.affset.com` URL from embedding attacker-chosen junk if
- * someone pastes a weird AFFSET_NAMESPACE into their MCP client config.
- */
-const NAMESPACE_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
-/** Loopback hosts allowed to stay on plain http — everything else must be https. */
-function isLoopbackHost(hostname) {
-    return (hostname === "localhost" ||
-        hostname === "127.0.0.1" ||
-        hostname === "::1" ||
-        hostname.endsWith(".localhost"));
-}
-function namespaceError(namespace) {
-    if (namespace.length < 3 || namespace.length > 63) {
-        return "AFFSET_NAMESPACE must be 3–63 characters.";
-    }
-    if (!NAMESPACE_RE.test(namespace) || namespace.includes("--")) {
-        return ("AFFSET_NAMESPACE must be lowercase letters, numbers, and hyphens only " +
-            "(no leading/trailing or consecutive hyphens).");
-    }
-    return null;
-}
 /**
  * Read and validate config from the environment. Throws with an actionable
  * message listing every missing variable — surfaced to the user at startup.
@@ -45,38 +23,20 @@ export function loadConfig(env = process.env) {
         throw new Error(`Missing required environment variable(s): ${missing.join(", ")}. ` +
             `See .env.example for the expected values.`);
     }
-    const nsErr = namespaceError(namespace);
-    if (nsErr)
-        throw new Error(nsErr);
-    const normalized = baseUrl.replace(/\/+$/, "");
-    let parsed;
-    try {
-        parsed = new URL(normalized);
-    }
-    catch {
-        throw new Error(`AFFSET_BASE_URL is not a valid URL: ${baseUrl}`);
-    }
-    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-        throw new Error(`AFFSET_BASE_URL must be http(s), got ${parsed.protocol}`);
-    }
-    if (parsed.username || parsed.password) {
-        throw new Error("AFFSET_BASE_URL must not contain embedded credentials.");
-    }
-    if ((parsed.pathname !== "/" && parsed.pathname !== "") || parsed.search || parsed.hash) {
-        throw new Error("AFFSET_BASE_URL must be an origin only (scheme, host, and optional port; no path, query, or fragment).");
-    }
-    // Plain http sends the Bearer API key in cleartext. Only loopback (local dev /
-    // wrangler dev) is exempt — anything else must be https.
-    if (parsed.protocol === "http:" && !isLoopbackHost(parsed.hostname)) {
-        throw new Error(`AFFSET_BASE_URL must be https for a non-local host (got http://${parsed.hostname}) — ` +
-            `plain http would send the API key in cleartext.`);
-    }
+    validateNamespace(namespace, "AFFSET_NAMESPACE");
+    const parsedApiKey = validateApiKey(apiKey, "AFFSET_API_KEY");
+    // Plain http on AFFSET_BASE_URL sends the Bearer API key in cleartext; the
+    // helper refuses it for non-loopback hosts.
+    const parsed = parseOriginUrl(baseUrl, "AFFSET_BASE_URL", true);
+    // Optional — the docs feeds are public, so this only sets where to fetch them.
+    const docsRaw = env.AFFSET_DOCS_URL?.trim();
+    const docsBaseUrl = parseOriginUrl(docsRaw || DEFAULT_DOCS_URL, "AFFSET_DOCS_URL").origin;
     const timeoutRaw = env.AFFSET_REQUEST_TIMEOUT_MS?.trim();
     let requestTimeoutMs = DEFAULT_TIMEOUT_MS;
     if (timeoutRaw) {
         const n = Number(timeoutRaw);
-        if (!Number.isSafeInteger(n) || n < 1000 || n > MAX_TIMEOUT_MS) {
-            throw new Error(`AFFSET_REQUEST_TIMEOUT_MS must be an integer between 1000 and ${MAX_TIMEOUT_MS}.`);
+        if (!Number.isSafeInteger(n) || n < MIN_REQUEST_TIMEOUT_MS || n > MAX_REQUEST_TIMEOUT_MS) {
+            throw new Error(`AFFSET_REQUEST_TIMEOUT_MS must be an integer between ${MIN_REQUEST_TIMEOUT_MS} and ${MAX_REQUEST_TIMEOUT_MS}.`);
         }
         requestTimeoutMs = n;
     }
@@ -91,7 +51,8 @@ export function loadConfig(env = process.env) {
     }
     return {
         baseUrl: parsed.origin,
-        apiKey: apiKey,
+        docsBaseUrl,
+        apiKey: parsedApiKey,
         namespace: namespace,
         requestTimeoutMs,
         readOnly,

package/dist/core.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Runtime-agnostic library surface of @affset/mcp (REMOTE-MCP-PRD.md §5.6).
+ *
+ * Everything exported here runs on any fetch-capable runtime (Node ≥22.13,
+ * Cloudflare Workers) — no `process.env`, no `node:` imports. The stdio
+ * entrypoint (`dist/index.js`, the `affset-mcp` bin) layers env-var loading on
+ * top of this; the remote MCP gateway imports this surface directly and
+ * supplies per-grant credentials instead.
+ *
+ * `loadConfig` (env-var parsing) is deliberately NOT exported: it is the
+ * stdio entrypoint's concern, and its signature drags Node types into
+ * consumers.
+ */
+export { registerAffsetTools, type AffsetToolServer, type RegisterAffsetToolsOptions, type ToolCallEvent, } from "./registerTools.js";
+export type { Config } from "./runtimeConfig.js";
+export { AffsetClient, AffsetApiError } from "./client.js";
+export { DOCS_FEEDS, fetchDocsFeed, DocsFetchError, type DocsFeed } from "./docs.js";
+export { VERSION } from "./version.js";