@virtocommerce/mcp-onx 1.0.1 → 1.0.2

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 (3) hide show
  1. package/LICENSE +22 -22
  2. package/README.md +126 -126
  3. package/package.json +62 -61
package/LICENSE CHANGED
@@ -1,22 +1,22 @@
1
- MIT License
2
-
3
- Copyright (c) 2026 VirtoCommerce
4
-
5
- Permission is hereby granted, free of charge, to any person obtaining a copy
6
- of this software and associated documentation files (the "Software"), to deal
7
- in the Software without restriction, including without limitation the rights
8
- to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
- copies of the Software, and to permit persons to whom the Software is
10
- furnished to do so, subject to the following conditions:
11
-
12
- The above copyright notice and this permission notice shall be included in all
13
- copies or substantial portions of the Software.
14
-
15
- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
- SOFTWARE.
22
-
1
+ MIT License
2
+
3
+ Copyright (c) 2026 VirtoCommerce
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+
package/README.md CHANGED
@@ -1,126 +1,126 @@
1
- # @virtocommerce/mcp-onx
2
-
3
- VirtoCommerce adapter for the Commerce Operations Foundation (COF) MCP Server. Connects VirtoCommerce Platform to AI assistants via the Model Context Protocol (MCP), enabling order management, customer lookup, product catalog, inventory, fulfillment, and returns operations.
4
-
5
- ## Supported Operations
6
-
7
- | Category | Tools |
8
- | -------- | ----- |
9
- | **Orders** | `create-sales-order`, `update-order`, `cancel-order`, `get-orders` |
10
- | **Fulfillment** | `fulfill-order`, `get-fulfillments` |
11
- | **Customers** | `get-customers` |
12
- | **Products** | `get-products`, `get-product-variants` |
13
- | **Inventory** | `get-inventory` |
14
- | **Returns** | `create-return`, `get-returns` |
15
-
16
- ## Quick Start
17
-
18
- ### Option A: Via npx (no local clone needed)
19
-
20
- Add to your Claude Desktop config (`claude_desktop_config.json`):
21
-
22
- ```json
23
- {
24
- "mcpServers": {
25
- "cof-mcp": {
26
- "command": "npx",
27
- "args": [
28
- "--package=@virtocommerce/cof-mcp",
29
- "--package=@virtocommerce/mcp-onx",
30
- "--yes",
31
- "cof-mcp"
32
- ],
33
- "env": {
34
- "ADAPTER_TYPE": "npm",
35
- "ADAPTER_PACKAGE": "@virtocommerce/mcp-onx",
36
- "ADAPTER_CONFIG": "{\"apiUrl\":\"https://your-vc-instance.com\",\"apiKey\":\"YOUR_API_KEY\",\"workspace\":\"your-store-id\"}",
37
- "LOG_LEVEL": "info"
38
- }
39
- }
40
- }
41
- }
42
- ```
43
-
44
- ### Option B: From source
45
-
46
- ```bash
47
- git clone https://github.com/VirtoCommerce/mcp-onx.git
48
- cd mcp-onx
49
-
50
- # Build server first (adapter depends on it)
51
- cd server && npm install && npm run build && cd ..
52
-
53
- # Build adapter
54
- cd virtocommerce-adapter && npm install && npm run build && cd ..
55
- ```
56
-
57
- Then add to Claude Desktop config:
58
-
59
- ```json
60
- {
61
- "mcpServers": {
62
- "cof-mcp": {
63
- "command": "node",
64
- "args": ["/absolute/path/to/server/dist/index.js"],
65
- "env": {
66
- "ADAPTER_TYPE": "local",
67
- "ADAPTER_PATH": "/absolute/path/to/virtocommerce-adapter/dist/index.js",
68
- "ADAPTER_CONFIG": "{\"apiUrl\":\"https://your-vc-instance.com\",\"apiKey\":\"YOUR_API_KEY\",\"workspace\":\"your-store-id\"}",
69
- "LOG_LEVEL": "info"
70
- }
71
- }
72
- }
73
- }
74
- ```
75
-
76
- ## Configuration
77
-
78
- | Option | Type | Required | Default | Description |
79
- | ------ | ---- | -------- | ------- | ----------- |
80
- | `apiUrl` | `string` | Yes | — | VirtoCommerce Platform URL |
81
- | `apiKey` | `string` | Yes | — | API key (`api_key` header) |
82
- | `workspace` | `string` | No | — | Store ID — scopes orders/shipments, auto-detects catalog |
83
- | `catalogId` | `string` | No | — | Catalog ID for product searches (auto-detected from store if `workspace` is set) |
84
- | `timeout` | `number` | No | `30000` | Request timeout in milliseconds |
85
- | `retryAttempts` | `number` | No | `3` | Max retry attempts for failed requests |
86
- | `debugMode` | `boolean` | No | `false` | Log all API requests/responses to stderr |
87
-
88
- ## VirtoCommerce Permissions
89
-
90
- The adapter requires the following VirtoCommerce API permissions:
91
-
92
- - **Order**: Read, Search, Create, Update
93
- - **Shipment**: Search
94
- - **Customer/Members**: Read, Search
95
- - **Catalog**: Search
96
- - **Inventory**: Search
97
- - **Platform**: Read (countries list)
98
- - **Store**: Read (when `workspace` is set)
99
- - **Pricing**: Evaluate (optional — for automatic price lookup during order creation)
100
-
101
- See [docs/PERMISSIONS.md](docs/PERMISSIONS.md) for detailed permission mappings.
102
-
103
- ## Documentation
104
-
105
- - [Quick Start Guide](docs/QUICKSTART.md) — step-by-step setup with screenshots
106
- - [Configuration Reference](docs/CONFIGURATION.md) — all options, environment variables, retry logic
107
- - [API Reference](docs/API.md) — endpoint mappings, status maps, filter/search mappings
108
- - [Permissions](docs/PERMISSIONS.md) — required VirtoCommerce permissions per operation
109
- - [Known Limitations](docs/LIMITATIONS.md) — unimplemented features and workarounds
110
-
111
- ## Development
112
-
113
- ```bash
114
- cd virtocommerce-adapter
115
-
116
- npm run build # tsc → dist/
117
- npm run dev # tsc --watch
118
- npm test # Jest with --experimental-vm-modules
119
- npm run lint # ESLint
120
- ```
121
-
122
- > **Note**: Build the server (`cd server && npm run build`) before building the adapter — it depends on `@cof-org/mcp` via `file:../server`.
123
-
124
- ## License
125
-
126
- See [LICENSE](../LICENSE) in the repository root.
1
+ # @virtocommerce/mcp-onx
2
+
3
+ VirtoCommerce adapter for the Commerce Operations Foundation (COF) MCP Server. Connects VirtoCommerce Platform to AI assistants via the Model Context Protocol (MCP), enabling order management, customer lookup, product catalog, inventory, fulfillment, and returns operations.
4
+
5
+ ## Supported Operations
6
+
7
+ | Category | Tools |
8
+ | -------- | ----- |
9
+ | **Orders** | `create-sales-order`, `update-order`, `cancel-order`, `get-orders` |
10
+ | **Fulfillment** | `fulfill-order`, `get-fulfillments` |
11
+ | **Customers** | `get-customers` |
12
+ | **Products** | `get-products`, `get-product-variants` |
13
+ | **Inventory** | `get-inventory` |
14
+ | **Returns** | `create-return`, `get-returns` |
15
+
16
+ ## Quick Start
17
+
18
+ ### Option A: Via npx (no local clone needed)
19
+
20
+ Add to your Claude Desktop config (`claude_desktop_config.json`):
21
+
22
+ ```json
23
+ {
24
+ "mcpServers": {
25
+ "cof-mcp": {
26
+ "command": "npx",
27
+ "args": [
28
+ "--package=@virtocommerce/cof-mcp",
29
+ "--package=@virtocommerce/mcp-onx",
30
+ "--yes",
31
+ "cof-mcp"
32
+ ],
33
+ "env": {
34
+ "ADAPTER_TYPE": "npm",
35
+ "ADAPTER_PACKAGE": "@virtocommerce/mcp-onx",
36
+ "ADAPTER_CONFIG": "{\"apiUrl\":\"https://your-vc-instance.com\",\"apiKey\":\"YOUR_API_KEY\",\"workspace\":\"your-store-id\"}",
37
+ "LOG_LEVEL": "info"
38
+ }
39
+ }
40
+ }
41
+ }
42
+ ```
43
+
44
+ ### Option B: From source
45
+
46
+ ```bash
47
+ git clone https://github.com/VirtoCommerce/mcp-onx.git
48
+ cd mcp-onx
49
+
50
+ # Build server first (adapter depends on it)
51
+ cd server && npm install && npm run build && cd ..
52
+
53
+ # Build adapter
54
+ cd virtocommerce-adapter && npm install && npm run build && cd ..
55
+ ```
56
+
57
+ Then add to Claude Desktop config:
58
+
59
+ ```json
60
+ {
61
+ "mcpServers": {
62
+ "cof-mcp": {
63
+ "command": "node",
64
+ "args": ["/absolute/path/to/server/dist/index.js"],
65
+ "env": {
66
+ "ADAPTER_TYPE": "local",
67
+ "ADAPTER_PATH": "/absolute/path/to/virtocommerce-adapter/dist/index.js",
68
+ "ADAPTER_CONFIG": "{\"apiUrl\":\"https://your-vc-instance.com\",\"apiKey\":\"YOUR_API_KEY\",\"workspace\":\"your-store-id\"}",
69
+ "LOG_LEVEL": "info"
70
+ }
71
+ }
72
+ }
73
+ }
74
+ ```
75
+
76
+ ## Configuration
77
+
78
+ | Option | Type | Required | Default | Description |
79
+ | ------ | ---- | -------- | ------- | ----------- |
80
+ | `apiUrl` | `string` | Yes | — | VirtoCommerce Platform URL |
81
+ | `apiKey` | `string` | Yes | — | API key (`api_key` header) |
82
+ | `workspace` | `string` | No | — | Store ID — scopes orders/shipments, auto-detects catalog |
83
+ | `catalogId` | `string` | No | — | Catalog ID for product searches (auto-detected from store if `workspace` is set) |
84
+ | `timeout` | `number` | No | `30000` | Request timeout in milliseconds |
85
+ | `retryAttempts` | `number` | No | `3` | Max retry attempts for failed requests |
86
+ | `debugMode` | `boolean` | No | `false` | Log all API requests/responses to stderr |
87
+
88
+ ## VirtoCommerce Permissions
89
+
90
+ The adapter requires the following VirtoCommerce API permissions:
91
+
92
+ - **Order**: Read, Search, Create, Update
93
+ - **Shipment**: Search
94
+ - **Customer/Members**: Read, Search
95
+ - **Catalog**: Search
96
+ - **Inventory**: Search
97
+ - **Platform**: Read (countries list)
98
+ - **Store**: Read (when `workspace` is set)
99
+ - **Pricing**: Evaluate (optional — for automatic price lookup during order creation)
100
+
101
+ See [docs/PERMISSIONS.md](docs/PERMISSIONS.md) for detailed permission mappings.
102
+
103
+ ## Documentation
104
+
105
+ - [Quick Start Guide](docs/QUICKSTART.md) — step-by-step setup with screenshots
106
+ - [Configuration Reference](docs/CONFIGURATION.md) — all options, environment variables, retry logic
107
+ - [API Reference](docs/API.md) — endpoint mappings, status maps, filter/search mappings
108
+ - [Permissions](docs/PERMISSIONS.md) — required VirtoCommerce permissions per operation
109
+ - [Known Limitations](docs/LIMITATIONS.md) — unimplemented features and workarounds
110
+
111
+ ## Development
112
+
113
+ ```bash
114
+ cd virtocommerce-adapter
115
+
116
+ npm run build # tsc → dist/
117
+ npm run dev # tsc --watch
118
+ npm test # Jest with --experimental-vm-modules
119
+ npm run lint # ESLint
120
+ ```
121
+
122
+ > **Note**: Build the server (`cd server && npm run build`) before building the adapter — it depends on `@cof-org/mcp` via `file:../server`.
123
+
124
+ ## License
125
+
126
+ See [LICENSE](../LICENSE) in the repository root.
package/package.json CHANGED
@@ -1,61 +1,62 @@
1
- {
2
- "name": "@virtocommerce/mcp-onx",
3
- "version": "1.0.1",
4
- "description": "Commerce Operations Foundation adapter for VirtoCommerce Fulfillment",
5
- "repository": {
6
- "type": "git",
7
- "url": "https://github.com/VirtoCommerce/vc-onX-adapter"
8
- },
9
- "bugs": {
10
- "url": "https://github.com/VirtoCommerce/vc-onX-adapter/issues"
11
- },
12
- "homepage": "https://github.com/VirtoCommerce/vc-onX-adapter#readme",
13
- "type": "module",
14
- "main": "dist/index.js",
15
- "types": "dist/index.d.ts",
16
- "exports": {
17
- ".": {
18
- "import": "./dist/index.js",
19
- "types": "./dist/index.d.ts"
20
- }
21
- },
22
- "files": [
23
- "dist",
24
- "README.md",
25
- "LICENSE"
26
- ],
27
- "scripts": {
28
- "build": "tsc",
29
- "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
30
- "test:integration": "npm run build && node test-integration.js",
31
- "lint": "eslint .",
32
- "prepublishOnly": "npm run build",
33
- "dev": "tsc --watch"
34
- },
35
- "keywords": [
36
- "cof",
37
- "fulfillment",
38
- "adapter",
39
- "mcp",
40
- "virtocommerce"
41
- ],
42
- "author": "VirtoCommerce <support@virtocommerce.com>",
43
- "license": "MIT",
44
- "devDependencies": {
45
- "@eslint/js": "^9.8.0",
46
- "@types/jest": "^29.5.14",
47
- "@types/node": "^20.19.29",
48
- "@typescript-eslint/eslint-plugin": "^8.7.0",
49
- "@typescript-eslint/parser": "^8.7.0",
50
- "eslint": "^9.8.0",
51
- "eslint-plugin-import": "^2.29.1",
52
- "jest": "^29.7.0",
53
- "ts-jest": "^29.1.1",
54
- "typescript": "^5.3.3",
55
- "typescript-eslint": "^8.7.0"
56
- },
57
- "dependencies": {
58
- "@virtocommerce/cof-mcp": "^0.5.2-alpha.0",
59
- "axios": "^1.6.0"
60
- }
61
- }
1
+ {
2
+ "name": "@virtocommerce/mcp-onx",
3
+ "version": "1.0.2",
4
+ "description": "Commerce Operations Foundation adapter for VirtoCommerce Fulfillment",
5
+ "repository": {
6
+ "type": "git",
7
+ "url": "https://github.com/VirtoCommerce/vc-onX-adapter"
8
+ },
9
+ "bugs": {
10
+ "url": "https://github.com/VirtoCommerce/vc-onX-adapter/issues"
11
+ },
12
+ "homepage": "https://github.com/VirtoCommerce/vc-onX-adapter#readme",
13
+ "type": "module",
14
+ "main": "dist/index.js",
15
+ "types": "dist/index.d.ts",
16
+ "exports": {
17
+ ".": {
18
+ "import": "./dist/index.js",
19
+ "types": "./dist/index.d.ts"
20
+ }
21
+ },
22
+ "files": [
23
+ "dist",
24
+ "README.md",
25
+ "LICENSE"
26
+ ],
27
+ "scripts": {
28
+ "build": "tsc",
29
+ "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
30
+ "test:integration": "npm run build && node test-integration.js",
31
+ "lint": "eslint .",
32
+ "prepublishOnly": "npm run build",
33
+ "dev": "tsc --watch"
34
+ },
35
+ "keywords": [
36
+ "cof",
37
+ "fulfillment",
38
+ "adapter",
39
+ "mcp",
40
+ "virtocommerce"
41
+ ],
42
+ "author": "VirtoCommerce <support@virtocommerce.com>",
43
+ "license": "MIT",
44
+ "devDependencies": {
45
+ "@eslint/js": "^9.8.0",
46
+ "@types/jest": "^29.5.14",
47
+ "@types/node": "^20.19.29",
48
+ "@typescript-eslint/eslint-plugin": "^8.7.0",
49
+ "@typescript-eslint/parser": "^8.7.0",
50
+ "eslint": "^9.8.0",
51
+ "eslint-import-resolver-typescript": "^4.4.4",
52
+ "eslint-plugin-import": "^2.29.1",
53
+ "jest": "^29.7.0",
54
+ "ts-jest": "^29.1.1",
55
+ "typescript": "^5.3.3",
56
+ "typescript-eslint": "^8.7.0"
57
+ },
58
+ "dependencies": {
59
+ "@virtocommerce/cof-mcp": "^0.5.2-alpha.0",
60
+ "axios": "^1.6.0"
61
+ }
62
+ }