{ "response_cache_ttl": 3600, "truncate_threshold": 51200, "regions": { "US": { "production": { "consumer_id": "your-consumer-id", "private_key": "./keys/us/prod.pem", "private_key_version": "1", "bearer_token": "your-bearer-token", "base_urls": { "sponsored": "https://developer.api.us.walmart.com/api-proxy/service/sp/api-sams/v1" } }, "sandbox": { "consumer_id": "your-sandbox-consumer-id", "private_key": "./keys/us/sandbox.pem", "private_key_version": "1", "bearer_token": "your-sandbox-bearer-token", "base_urls": { "sponsored": "https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1" } } } } } ``` **3. Place your RSA private key PEM files in `~/.config/mcp-samsclub-ads/keys/`** Key paths in the config are resolved relative to the config directory, so `./keys/us/prod.pem` resolves to `~/.config/mcp-samsclub-ads/keys/us/prod.pem`. | Config field | Description | |---|---| | `response_cache_ttl` | Seconds to keep truncated responses in memory (default `3600`) | | `truncate_threshold` | Response byte limit before truncation (default `51200`) | | `regions...consumer_id` | Your Sam's Club consumer ID | | `regions...private_key` | Path to RSA private key PEM (relative to config dir or absolute) | | `regions...private_key_version` | Key version string (default `"1"`) | | `regions...bearer_token` | OAuth bearer token | | `regions...base_urls.sponsored` | Sponsored Ads API base URL | Each request is signed with `WM_CONSUMER.ID`, `WM_SEC.AUTH_SIGNATURE` (Base64 RSA-SHA256), `WM_SEC.KEY_VERSION`, and `WM_CONSUMER.INTIMESTAMP` (Unix epoch ms), plus `Authorization: Bearer ` — all injected automatically by the client. ### Base URLs - **Production:** `https://developer.api.us.walmart.com/api-proxy/service/sp/api-sams/v1` - **Sandbox:** `https://developer.api.us.stg.walmart.com/api-proxy/service/sp/api-sams/v1` Paths in the spec begin `/api/v1/...` (or `/api/v2/...`), so the effective URL is `/api/v1/`. ## Tools ### `list_endpoints` List operations from the bundled OpenAPI spec for an `ad_type`, with optional filters. | Parameter | Required | Description | |---|---|---| | `ad_type` | yes | `sponsored` | | `query` | no | Case-insensitive substring match on operationId, path, or summary | | `tag` | no | Filter to operations whose OpenAPI tags include this value | | `method` | no | Filter by HTTP verb | ### `describe_endpoint` Return one operation plus the `components.schemas` reachable from it (its `$ref` closure), so request bodies and responses can be built without the full spec. | Parameter | Required | Description | |---|---|---| | `ad_type` | yes | `sponsored` | | `operation_id` | yes | Spec operation id (from `list_endpoints`) | ### `call_endpoint` Execute any Sam's Club Sponsored Ads API endpoint. Identify it by `operation_id`, or by raw `method` + `path`. Raw method+path also reaches endpoints not yet in the bundled spec. The server handles RSA-SHA256 signing. | Parameter | Required | Description | |---|---|---| | `region` | yes | e.g. `US` | | `env` | yes | `production` or `sandbox` | | `ad_type` | yes | `sponsored` | | `operation_id` | no* | Spec operation id; resolves `method`+`path` | | `method` | no* | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` | | `path` | no* | e.g. `/api/v1/campaigns` | | `params` | no | Query string parameters (JSON object) | | `body` | no | JSON request body for POST/PUT (object or array) | \* Provide either `operation_id`, or both `method` and `path`. ### `refresh_specs` Re-fetch the bundled OpenAPI spec from its committed `source_url` into a user cache (`~/.cache/mcp-samsclub-ads/specs/`) that takes precedence over the bundled copy — ship fixes without a release. | Parameter | Required | Description | |---|---|---| | `spec_id` | no | One spec to refresh (e.g. `sponsored/sponsored-ads`); omit to refresh all | ## MCP resources Endpoint schemas come from the bundled OpenAPI spec via `list_endpoints` / `describe_endpoint` (see [Tools](#tools)), not from static resources. ### Dynamic resources | Resource URI | Description | |---|---| | `sca://config` | Available regions, environments, and ad types from your config | | `sca://responses/{request_id}` | Full body of a truncated API response (cached in memory, TTL from config) | | `sca://curl/{request_id}` | Reproducible cURL command for a previous API request | ## Spec coverage The bundled OpenAPI spec is **hand-authored from the [developer.samsclub.com](https://developer.samsclub.com/API/overview/) docs and is partial by design.** It covers the core ads surface: Campaigns, Statistics, Ad Groups, Ad Items, Catalog Item Search, Keywords (+ suggestions/analytics), Negative Keywords, Placements, Bid Multipliers, and Snapshot Reports v1/v2 + Latest Report Date. Endpoints not yet modeled (SBA profiles, media, reviews, api-usage, entity/audit snapshots, alerts & recommendations) are still reachable via `call_endpoint` with a raw `method`+`path`. ## Status & blocker **Partner credentials are the long pole.** Access requires emailing an RSA public key to `partner-support@samsclub.com` and receiving a consumer id + auth token + key version. Without sandbox credentials the server runs and its discovery/signing are verified offline, but calls cannot be exercised end-to-end. ## Spec drift detection [`scripts/build_spec.py`](scripts/build_spec.py) scrapes the docs into a *candidate* spec at [`spec-candidate/`](spec-candidate/) — offline, never at runtime. The [`Spec drift`](.github/workflows/spec-drift.yml) workflow runs it on a schedule and opens a PR when the docs change; a reviewer then ports real changes into the hand-authored canonical spec. The candidate is intentionally flat and is never shipped or loaded. ```bash uv run --group spec-build python scripts/build_spec.py # write candidate uv run --group spec-build python scripts/build_spec.py --check # exit 1 on drift ``` Still deferred: flipping a spec's `auth` flag to fetch the authenticated live Swagger backend once partner credentials exist. ## MCP host examples ### Cursor Add to `.cursor/mcp.json`: ```json { "mcpServers": { "samsclub-ads": { "command": "uvx", "args": ["mcp-samsclub-ads"] } } }

mcp-samsclub-ads

Installation