-
Notifications
You must be signed in to change notification settings - Fork 2
@W-20591366 Add Tool Adapter Layer for MCP Tools #29
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 3 commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
c80c3c3
@W-20591366 add tool adapter layer
yhsieh1 b6f0e3f
update readme.md
yhsieh1 26b6a67
update jsdoc
yhsieh1 a3228f8
update jsdoc
yhsieh1 97c2308
Merge main into tool-adapter branch
yhsieh1 6fa7245
fix lint
yhsieh1 c058a6f
remove comments
yhsieh1 80558eb
fix lint
yhsieh1 00bdd8e
refactor and use MrtCommand and InstanceCommand baseFlags
yhsieh1 c7ecfb4
update service remove get from process env
yhsieh1 File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -22,6 +22,13 @@ Since the package is not yet published to npm, see the [Development](#developmen | |
| | `--tools` | Comma-separated individual tools to enable (case-insensitive) | | ||
| | `--allow-non-ga-tools` | Enable experimental (non-GA) tools | | ||
|
|
||
| #### Auth Flags | ||
|
|
||
| | Flag | Env Variable | Description | | ||
| |------|--------------|-------------| | ||
| | `--mrt-api-key` | `SFCC_MRT_API_KEY` | MRT API key for Managed Runtime operations | | ||
| | `--mrt-cloud-origin` | `SFCC_MRT_CLOUD_ORIGIN` | MRT cloud origin URL (default: https://cloud.mobify.com). See [Environment-Specific Config Files](#environment-specific-config-files) | | ||
|
|
||
| #### Global Flags (inherited from SDK) | ||
|
|
||
| | Flag | Description | | ||
|
|
@@ -48,6 +55,13 @@ Since the package is not yet published to npm, see the [Development](#developmen | |
| // Explicit config file path | ||
| "args": ["--toolsets", "all", "--config", "/path/to/dw.json"] | ||
|
|
||
| // MRT tools with API key | ||
| "args": ["--toolsets", "MRT", "--mrt-api-key", "your-api-key"] | ||
|
|
||
| // Or use environment variable in mcp.json | ||
| "args": ["--toolsets", "MRT"], | ||
| "env": { "SFCC_MRT_API_KEY": "your-api-key" } | ||
|
|
||
| // Enable experimental tools (required for placeholder tools) | ||
| "args": ["--toolsets", "all", "--allow-non-ga-tools"] | ||
|
|
||
|
|
@@ -229,30 +243,134 @@ echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"cartridge_ | |
|
|
||
| > **Note:** Configuration is not currently required as all tools are placeholder implementations. This section will be relevant once tools are fully implemented. | ||
|
|
||
| Tools that interact with B2C Commerce instances (e.g., MRT, SCAPI, cartridge deployment) require credentials, which can be provided via **environment variables**, a **`.env` file**, a **`dw.json` file**, or the **`--config`** flag. Local tools (e.g., scaffolding, development guidelines) work without configuration. | ||
| Different tools require different types of configuration: | ||
|
|
||
| | Tool Type | Configuration Required | | ||
| |-----------|----------------------| | ||
| | **MRT tools** (e.g., `mrt_bundle_push`) | MRT API key | | ||
| | **B2C instance tools** (e.g., `cartridge_deploy`, SCAPI) | dw.json config | | ||
| | **Local tools** (e.g., scaffolding) | None | | ||
|
|
||
| #### MRT API Key | ||
|
|
||
| MRT (Managed Runtime) operations require an API key from the [Runtime Admin](https://runtime.commercecloud.com/) dashboard. | ||
|
|
||
| **Priority order** (highest to lowest): | ||
|
|
||
| 1. Environment variables (`SFCC_*`) — includes `.env` file if present (shell env vars override `.env`) | ||
| 2. `dw.json` file (auto-discovered or via `--config`) | ||
| 1. `--mrt-api-key` flag | ||
| 2. `SFCC_MRT_API_KEY` environment variable | ||
| 3. `~/.mobify` config file (or `~/.mobify--[hostname]` if `--mrt-cloud-origin` is set) | ||
|
|
||
| #### Option 1: Environment Variables | ||
| **Option A: Flag or environment variable** | ||
|
|
||
| Set environment variables directly or create a `.env` file in your project root: | ||
| ```json | ||
| // mcp.json - using flag | ||
| { | ||
| "mcpServers": { | ||
| "b2c-dx": { | ||
| "command": "b2c-dx-mcp", | ||
| "args": ["--toolsets", "MRT", "--mrt-api-key", "your-api-key"] | ||
| } | ||
| } | ||
| } | ||
|
|
||
| ```bash | ||
| # .env file or shell exports | ||
| SFCC_HOSTNAME="your-sandbox.demandware.net" | ||
| SFCC_USERNAME="your.username" | ||
| SFCC_PASSWORD="your-access-key" | ||
| SFCC_CLIENT_ID="your-client-id" | ||
| SFCC_CLIENT_SECRET="your-client-secret" | ||
| SFCC_CODE_VERSION="version1" | ||
| // mcp.json - using env var | ||
| { | ||
| "mcpServers": { | ||
| "b2c-dx": { | ||
| "command": "b2c-dx-mcp", | ||
| "args": ["--toolsets", "MRT"], | ||
| "env": { | ||
| "SFCC_MRT_API_KEY": "your-api-key" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| **Option B: ~/.mobify file (legacy)** | ||
|
|
||
| If you already use the `b2c` CLI for MRT operations, you may have a `~/.mobify` file configured: | ||
|
|
||
| ```json | ||
| { | ||
| "username": "[email protected]", | ||
| "api_key": "your-api-key" | ||
| } | ||
| ``` | ||
|
|
||
| The MCP server will automatically use this file as a fallback if no flag or environment variable is set. | ||
|
|
||
| ##### Environment-Specific Config Files | ||
|
|
||
| When using `~/.mobify` config files (i.e., no `--mrt-api-key` flag or `SFCC_MRT_API_KEY` env var), you can use `--mrt-cloud-origin` to select an environment-specific config file: | ||
|
|
||
| ```json | ||
| // mcp.json - uses ~/.mobify--cloud-staging.mobify.com for API key | ||
| { | ||
| "mcpServers": { | ||
| "b2c-dx-staging": { | ||
| "command": "b2c-dx-mcp", | ||
| "args": ["--toolsets", "MRT", "--mrt-cloud-origin", "https://cloud-staging.mobify.com"] | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| | Cloud Origin | Config File | | ||
| |--------------|-------------| | ||
| | (default) | `~/.mobify` | | ||
| | `https://cloud-staging.mobify.com` | `~/.mobify--cloud-staging.mobify.com` | | ||
| | `https://cloud-dev.mobify.com` | `~/.mobify--cloud-dev.mobify.com` | | ||
|
|
||
| > **Note:** `--mrt-cloud-origin` is only relevant when the API key is resolved from a config file. If `--mrt-api-key` or `SFCC_MRT_API_KEY` is provided, this flag is ignored. | ||
|
|
||
| #### B2C Instance Config (dw.json) | ||
|
|
||
| Tools that interact with B2C Commerce instances (e.g., `cartridge_deploy`, SCAPI tools) require instance credentials. | ||
|
|
||
| **Priority order** (highest to lowest): | ||
|
|
||
| 1. Environment variables (`SFCC_*`) | ||
| 2. `dw.json` file (via `--config` flag or auto-discovery) | ||
|
|
||
| **Option A: Environment variables** | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "b2c-dx": { | ||
| "command": "b2c-dx-mcp", | ||
| "args": ["--toolsets", "CARTRIDGES"], | ||
| "env": { | ||
| "SFCC_HOSTNAME": "your-sandbox.demandware.net", | ||
| "SFCC_USERNAME": "your.username", | ||
| "SFCC_PASSWORD": "your-access-key", | ||
| "SFCC_CLIENT_ID": "your-client-id", | ||
| "SFCC_CLIENT_SECRET": "your-client-secret", | ||
| "SFCC_CODE_VERSION": "version1" | ||
| } | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| **Option B: dw.json with explicit path** | ||
|
|
||
| ```json | ||
| { | ||
| "mcpServers": { | ||
| "b2c-dx": { | ||
| "command": "b2c-dx-mcp", | ||
| "args": ["--toolsets", "CARTRIDGES", "--config", "/path/to/dw.json"] | ||
| } | ||
| } | ||
| } | ||
| ``` | ||
|
|
||
| #### Option 2: dw.json File | ||
| **Option C: dw.json with auto-discovery** | ||
|
|
||
| Create a `dw.json` file in your project root (auto-discovered by searching upward from current working directory): | ||
| Create a `dw.json` file in your project root. The MCP server will auto-discover it by searching upward from the current working directory: | ||
|
|
||
| ```json | ||
| { | ||
|
|
@@ -265,7 +383,7 @@ Create a `dw.json` file in your project root (auto-discovered by searching upwar | |
| } | ||
| ``` | ||
|
|
||
| > **Note:** Environment variables take precedence over `dw.json` values. | ||
| > **Note:** Environment variables override values from `dw.json`. You can use env vars to override specific fields (e.g., secrets) while using dw.json for other settings. | ||
|
|
||
| ## License | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Note you can get and spread these flags from
...MrtCommand.baseFlagsThere was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@clavery That sounds good! For MCP tools, it might need different API keys, do you consider rename
api-keytomrt-api-key?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
perhaps. although we do want to maximum compatibility with existing conventions (like pwa-kit-dev, etc) which uses --api-key. I'll think about this. Right now we don't have any auth needs that conflict with api-key (all other auths use distinct naming).
One thing that's important is the env variables are the same (which in this case is unambiguous (SFCC_MRT_API_KEY)). So if you don't want to spread from the base command make sure we're keeping those consistent. The idea is that folks can set their configuration once (.env files, dw.json, etc) and ALL of our tools respond in the same way
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@clavery I updated to spread from the command and it works well. One thing to note, if config Cursor MCP with .env instead of "env" attribute in mcp.json,
.envneeds to be under home directory (~) because Cursor runs MCP servers with cwd = home directory.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Both .env and env attribute in mcp.json will be supported.
Yeah I know about cursors weird behavior there. Here's what I told Shaurye a few months ago: Once we move this MCP out of PWA kit we'll want to use a more generic env var AND we should support this as an argument as well (i.e. --project ${workspaceFolder}). Again falling back to cwd when not specified (edited)
Basically we should default everything to assuming the current working directory is our project but allow for a --project (or similar) flag to root (or change our directory) to. The
${workspaceFolder}expansion works in cursorI think this might be a useful flag at the BaseCommand too rather than just being an MCP concern.
All that being said if they don't configure it that way then we don't know where the project is and configuration will just load what it can (And many tools may be useful but others useless)