@shopchief/agent-access 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +98 -163
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,200 +1,135 @@
1
1
  # ShopChief Agent Access
2
2
 
3
- Install and maintain the public [ShopChief](https://shopchief.ai) commerce Skill
4
- for Codex and Claude Code. External agents can use a merchant's
5
- authorized products, assets, business Skills and connected tools through
6
- ShopChief's existing MCP or REST interface.
3
+ Connect Codex or Claude Code to your [ShopChief](https://shopchief.ai) workspace.
4
+ Use your AI agent with authorized products, media assets, commerce Skills and
5
+ connected business tools, within the stores and permissions you approve.
7
6
 
8
- This package installs guidance, configures Codex/Claude Code native MCP connections,
9
- and helps diagnose setup. An eligible ShopChief
10
- subscription and an authorized connection are required to use the hosted service.
11
- The MIT license covers the public client files, not access to the hosted service.
7
+ This package installs the ShopChief Skill and helps set up the native MCP
8
+ connection so you can work from your preferred agent.
12
9
 
13
- Requires **Node.js 22 or newer**. Native MCP setup needs no Python or API key.
14
- The optional REST mode requires **Python 3.10 or newer** on PATH.
15
- The package has no npm runtime dependencies and no install/postinstall scripts.
10
+ ## Before you start
16
11
 
17
- ## Status
12
+ - **Node.js 22 or newer**, with npm/npx available in your terminal.
13
+ - **Codex or Claude Code**, with its `codex` or `claude` command available.
14
+ - A **ShopChief account with an eligible subscription** and permission to connect
15
+ the workspace and stores you want to use.
18
16
 
19
- Version 0.1.0 has passed local package acceptance and user-run Codex/Claude Code
20
- Skill loading and read-only MCP checks on macOS. Registry publication
21
- and ownership of the `@shopchief` namespace must be verified before announcing
22
- the registry commands below. Local use requires neither npm login nor payment.
17
+ The default MCP setup uses browser authorization. No Python or API key is needed.
23
18
 
24
- ## Local build, install and debug
19
+ ## Install and authorize
25
20
 
26
- From the repository root:
21
+ Run the command for your client in an interactive terminal.
22
+
23
+ **Codex**
27
24
 
28
25
  ```sh
29
- npm --prefix packages/agent-access run build
30
- node packages/agent-access/bin/shopchief-agent.mjs --help
31
- node packages/agent-access/bin/shopchief-agent.mjs install --client codex --dry-run
26
+ npx @shopchief/agent-access@latest install --client codex
32
27
  ```
33
28
 
34
- To exercise the actual npm artifact on macOS/Linux, use a fresh directory outside
35
- your existing agent configuration. The following paths are deliberately under
36
- the real `/private/tmp` directory on macOS; on Linux use a real temporary path
37
- such as `/tmp/shopchief-agent-access-local` instead.
29
+ **Claude Code**
38
30
 
39
31
  ```sh
40
- mkdir -p /private/tmp/shopchief-agent-access-local
41
- cd packages/agent-access
42
- npm pack --pack-destination /private/tmp/shopchief-agent-access-local
43
- npm install --prefix /private/tmp/shopchief-agent-access-local/runtime \
44
- --no-audit --no-fund \
45
- /private/tmp/shopchief-agent-access-local/shopchief-agent-access-0.1.0.tgz
46
-
47
- /private/tmp/shopchief-agent-access-local/runtime/node_modules/.bin/shopchief-agent \
48
- install --client codex \
49
- --skill-only \
50
- --install-dir /private/tmp/shopchief-agent-access-local/skills/shopchief
32
+ npx @shopchief/agent-access@latest install --client claude
51
33
  ```
52
34
 
53
- For native setup, omit `--skill-only` and use the actual client's Skill directory.
54
- Codex new-server registration requires an interactive terminal because its native
55
- `mcp add` can itself start OAuth. To remove the isolated Skill, use `uninstall
56
- --dry-run` or `uninstall` with the same `--client` and `--install-dir`.
57
- `doctor` checks public deployment
58
- endpoints; it needs network access. To debug source code with Node's inspector:
35
+ The installer adds the Skill and sets up or reuses the `shopchief` MCP connection.
36
+ When prompted, open the browser and approve the workspace, selected stores and
37
+ permissions. An existing authorized connection can be reused.
59
38
 
60
- ```sh
61
- node --inspect-brk bin/shopchief-agent.mjs install --client codex --dry-run
62
- ```
39
+ If authorization remains incomplete, follow the command printed by the installer.
40
+ For Claude Code versions without a terminal login command, open `/mcp` inside
41
+ Claude Code to authorize ShopChief.
42
+
43
+ After setup, open a new agent session so it can discover the Skill and tools.
44
+ Ask the agent:
45
+
46
+ > Load the ShopChief Skill, then call shopchief_account and
47
+ > shopchief_stores_list to verify my connection and list my authorized stores.
48
+ > Only perform these two free read operations.
49
+
50
+ Successful installation and browser authorization are separate from tool access.
51
+ These two calls confirm that your active session can reach your workspace.
52
+ Other operations may use ShopChief credits according to the service's pricing.
53
+
54
+ ## Use ShopChief in your agent
55
+
56
+ Start with a request such as:
57
+
58
+ > Use ShopChief to find the products and existing media assets in my authorized store.
59
+
60
+ You can also ask the agent to discover available commerce Skills and connected
61
+ business tools. Available actions depend on your subscription, approved scopes,
62
+ store access and connected services.
63
63
 
64
- `npm pack` runs static checks and copies an explicit list of MIT-licensed public
65
- assets from `src/modules/external_agents/distribution/`. Generated `dist/assets/`
66
- is ignored by Git. No server implementation, configuration seeds, credentials,
67
- merchant records or dependency directories enter the package. Keep this source
68
- directory in the ShopChief checkout when building; the packed artifact runs
69
- independently of that checkout.
64
+ [Manage your connections and store access in ShopChief](https://shopchief.ai/app/agent-access).
70
65
 
71
- ## Registry usage after publication
66
+ ## Update, check or remove
67
+
68
+ Run the install command again to update the managed Skill files. If you changed a
69
+ managed file yourself, the installer stops so you can review it before updating.
70
+
71
+ Use `claude` instead of `codex` in these commands for Claude Code:
72
72
 
73
73
  ```sh
74
- npx @shopchief/agent-access@latest install --client codex
74
+ # Show setup and authorization instructions
75
75
  npx @shopchief/agent-access@latest guide --client codex
76
+
77
+ # Check installed files, public endpoints and native MCP configuration
76
78
  npx @shopchief/agent-access@latest doctor --client codex
79
+
80
+ # Preview removal, then remove the managed Skill files
77
81
  npx @shopchief/agent-access@latest uninstall --client codex --dry-run
82
+ npx @shopchief/agent-access@latest uninstall --client codex
78
83
  ```
79
84
 
80
- Installing the npm package alone does not install a Skill or configure MCP.
81
- For Codex, explicitly run `install --client codex` in an interactive terminal.
82
- It checks the native CLI's MCP capabilities, reuses a matching `shopchief`
83
- Streamable HTTP server or runs `codex mcp add shopchief --url <endpoint>`, and
84
- uses native OAuth when needed. `mcp add` may perform OAuth itself; saved OAuth
85
- status is checked before starting a separate `codex mcp login shopchief` so that
86
- the wrapper does not immediately repeat authorization. A fresh registration is
87
- refused without a terminal; `--skill-only` still works offline/noninteractively.
88
- An existing registration may be inspected noninteractively; any remaining
89
- login is left as an explicit next command. Different URLs/transports, disabled
90
- servers, bearer-token/header authentication or a header helper stop automatic
91
- configuration and preserve settings. The package never reads Codex's token file.
92
-
93
- Explicitly run `install`. For Claude Code, this checks the installed `claude`
94
- CLI, reuses a matching `shopchief` connection or registers an HTTP server in
95
- user scope, and starts `claude mcp login shopchief` in an interactive terminal
96
- when supported. You review and approve the OAuth grant in your browser.
97
- Existing connected authorization is reused. Existing servers with another URL,
98
- transport, fixed Authorization header, or blocked project approval are preserved
99
- and require review instead of being overwritten.
100
-
101
- Use `--no-login` to defer browser authorization, or `--skill-only` to install
102
- guidance without invoking the native CLI. Noninteractive installation prints the
103
- exact login command instead of opening a browser. Older Claude versions without
104
- the login subcommand use `/mcp` for native authorization. `--no-login` is specific
105
- to Claude: Codex's add command can initiate OAuth and does not expose a matching
106
- skip-login option.
107
-
108
- ## Commands
109
-
110
- | Command | Behavior |
111
- | --- | --- |
112
- | `install` | Install/update unchanged managed Skill files. Codex/Claude MCP modes also register/reuse native HTTP servers and start supported interactive OAuth. Skill copying itself is offline; native setup may access the server. REST reuses the existing Python installer and the deployment's public Skill/helper. |
113
- | `guide` | Print client-specific native configuration, OAuth, reload and free verification steps. No network requests or configuration edits. |
114
- | `doctor` | Verify files/public endpoints and native MCP registration. Codex reports saved credential status, keeping live connection/session verification separate; Claude also reports its native health check. REST mode checks Python/helper integrity; `--check-api` verifies authenticated free reads. |
115
- | `uninstall` | Remove unchanged managed files and their manifest. Preserve unrelated files, REST credentials and native MCP configuration. Modified managed files block the entire uninstall. |
116
-
117
- | Option | Commands | Behavior |
118
- | --- | --- | --- |
119
- | `--client codex\|claude` | All | Default `codex`. Claude Code uses `claude`. |
120
- | `--mode mcp\|rest` | install, guide, doctor | Default `mcp`; REST is opt-in. |
121
- | `--install-dir PATH` | install, doctor, uninstall | Complete Skill directory, not its parent. |
122
- | `--base-url URL` | install, guide, doctor | Default `https://shopchief.ai`; HTTPS required except for localhost development. |
123
- | `--config-dir PATH` | REST install/doctor | Credential directory, default `$XDG_CONFIG_HOME/shopchief` or `~/.config/shopchief`. |
124
- | `--no-input` | REST install | Require `SHOPCHIEF_API_KEY` from the environment. |
125
- | `--check-api` | REST doctor | Read account, tool catalogue and authorized stores. Never execute paid or write tools. |
126
- | `--dry-run` | install, uninstall | Preview without writing, requesting credentials or making network requests. |
127
- | `--skill-only` | MCP install | Install guidance only; skip native MCP configuration/authentication. |
128
- | `--no-login` | Claude MCP install | Register/reuse the MCP server but defer OAuth. Cannot combine with `--skill-only`. |
129
- | `--help`, `-h` | All | Show help. |
130
- | `--version`, `-v` | All | Show package version. |
131
-
132
- Codex defaults to `~/.agents/skills/shopchief`; Claude Code defaults to
133
- `~/.claude/skills/shopchief`. These are installer conventions; override them if
134
- the current client documents a different directory. Use the same directory for
135
- installation, diagnosis and removal. Symlinked paths, including parent
136
- directories, are rejected; supply the actual real path instead.
137
-
138
- Deployment URL precedence is `--base-url`, `SHOPCHIEF_BASE_URL`, the installed
139
- manifest's source (install/doctor), then `https://shopchief.ai`. Explicit
140
- `--base-url` may change the public MCP Skill's source while preserving an existing
141
- REST helper/credentials. Native server conflicts still stop before Skill writes.
142
- An environment-only deployment change or a REST deployment mismatch is refused;
143
- use separate Skill and REST credential directories for different REST deployments.
144
-
145
- Repeated `install` updates only unchanged managed files; local modifications or
146
- unmanaged conflicting files cause a stop. Other files are preserved. A previous
147
- REST helper is preserved when installing the MCP Skill. Do not run concurrent
148
- install/uninstall operations on the same directory.
149
-
150
- `doctor` exit status is 0 when its checks pass and 1 when a check fails.
151
- Public endpoint requests allow 15 seconds per attempt and retry once on transient
152
- network failures. A `RETRY` line reports the reason; a subsequent `PASS` requires
153
- a successful response and valid content. HTTP errors, redirects, invalid content
154
- and certificate errors are not retried. Persistent failures report a safe network
155
- error code when available; they do not prove that MCP authorization failed.
156
- Native MCP configuration is inspected with the selected native CLI. Codex's stored
157
- OAuth status is not a live connection check. Claude also provides a native
158
- health check. OAuth/connection remains unverified when not established;
159
- client Skill discovery and session tool availability always require checks inside the
160
- active client session with `shopchief_account` and `shopchief_stores_list`.
161
- An OAuth callback or installed Skill alone does not establish tool availability.
85
+ Uninstall preserves your native MCP configuration, credentials and unrelated
86
+ files. To revoke access, use [ShopChief Agent access](https://shopchief.ai/app/agent-access).
87
+ Remove the native MCP entry in your client's settings if you no longer need it.
88
+
89
+ ## Troubleshooting
90
+
91
+ - **Client command not found:** make sure `codex` or `claude` works in the same
92
+ terminal, then rerun installation.
93
+ - **Authorization unfinished:** follow the installer's login instructions and
94
+ check that your ShopChief subscription and selected store access are active.
95
+ - **Existing connection conflicts:** review the `shopchief` entry in your client.
96
+ The installer preserves conflicting URLs or authentication settings.
97
+ - **Skill or tools missing:** open a new session and run the two verification
98
+ calls above. `doctor` cannot confirm that the active session loaded the Skill;
99
+ Codex's saved OAuth status alone does not establish a live connection.
100
+ - **Network check failed:** review the `FAIL` line and network/proxy settings.
101
+ `doctor` retries transient network failures once; a failed public endpoint
102
+ check alone does not mean your authorization failed.
103
+ - **Custom or symlinked directory:** use `--install-dir` with the full real Skill
104
+ directory for install, doctor and uninstall. Defaults are
105
+ `~/.agents/skills/shopchief` for Codex and `~/.claude/skills/shopchief` for Claude.
106
+
107
+ To preview installation, add `--dry-run`. To install only the Skill without native
108
+ MCP setup, add `--skill-only`. Claude users can use `--no-login` to defer browser
109
+ authorization; this option is unavailable for Codex. Run
110
+ `npx @shopchief/agent-access@latest --help` for all options.
162
111
 
163
112
  ## Optional REST access
164
113
 
114
+ Choose REST if you need API-key-based access. It requires **Python 3.10 or newer**
115
+ on PATH and an authorized ShopChief API key.
116
+
165
117
  ```sh
166
- shopchief-agent install --client codex --mode rest
167
- shopchief-agent doctor --client codex --mode rest --check-api
118
+ npx @shopchief/agent-access@latest install --client codex --mode rest
119
+ npx @shopchief/agent-access@latest doctor --client codex --mode rest --check-api
168
120
  ```
169
121
 
170
- Enter the API key in the installer's hidden terminal prompt. Never paste it into
171
- agent conversations or pass it as a CLI argument. For automation, inject
172
- `SHOPCHIEF_API_KEY` from a secret manager and use `--no-input`. A supplied
173
- environment key takes precedence over saved credentials. The installer reports
174
- the actual helper and credential paths. Use those paths with the existing
175
- helper commands: `account`, `tools`, `call` and `download`. REST installation
176
- uses network access. MCP `--skill-only` copies bundled guidance offline;
177
- default Codex/Claude MCP setup invokes its native connection/authentication flow.
178
-
179
- On POSIX the REST installer writes credentials with mode `600`. Windows ACLs
180
- are not managed: use a private user directory. Removing the Skill does not
181
- revoke access; revoke connections/keys in ShopChief's Agent access page.
182
- OAuth tokens stay in the native client's credential store and are never read by
183
- this package. Authenticated diagnostics suppress account/tool response bodies.
184
-
185
- ## Maintainer checks and publication
122
+ Enter the key only in the installer's hidden terminal prompt. Do not paste it into
123
+ an agent conversation or pass it as a command argument. For unattended setup, use
124
+ `SHOPCHIEF_API_KEY` from a secret manager with `--no-input`. Keep the reported
125
+ credential directory private; Windows file permissions are managed by you.
186
126
 
187
- ```sh
188
- npm run check
189
- npm pack --dry-run
190
- # After local acceptance, scope ownership and npm authentication are verified:
191
- npm publish --access public
192
- ```
127
+ ## License
193
128
 
194
- Publication is a separate explicit action. Use a new version for each published
195
- artifact. Review the pack file list before publishing. This repository's manual
196
- acceptance record tracks actual platform coverage; macOS acceptance does not
197
- establish Windows/Linux or real client OAuth acceptance.
129
+ The public client files are MIT-licensed. Access to the hosted ShopChief service
130
+ requires an eligible subscription and authorization. This package has no npm
131
+ runtime dependencies and no install/postinstall scripts; run the explicit
132
+ `install` command above to set up your Skill and connection.
198
133
 
199
134
  [ShopChief website](https://shopchief.ai) ·
200
135
  [Agent connection guide](https://shopchief.ai/api/agent-access/guide) ·
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@shopchief/agent-access",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Install, inspect and maintain the ShopChief commerce Skill for external AI agents.",
5
5
  "type": "module",
6
6
  "license": "MIT",