@kavinga/commerce-tools 0.1.1 → 0.1.3
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.
- package/README.md +135 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
# commerce-tools
|
|
2
|
+
|
|
3
|
+
A modular AI tooling platform for Adobe Commerce operations, monitoring, and security analysis. Provides a New Relic MCP server for NRQL query execution, plus a composable framework of agents, skills, commands, and providers for building AI-powered Commerce workflows.
|
|
4
|
+
|
|
5
|
+
## Features
|
|
6
|
+
|
|
7
|
+
- **New Relic MCP Server** — executes NRQL queries via NerdGraph and maps Adobe Commerce project IDs to New Relic account IDs
|
|
8
|
+
- **Commerce & Security Prompts** — built-in specialist prompts for APM monitoring, performance analysis, and attack detection (brute force, SQLi, XSS, DDoS, scraping, carding)
|
|
9
|
+
- **Agent Framework** — automatic tool-use loop with conversation history management and configurable iteration limits
|
|
10
|
+
- **Pluggable Providers** — abstract provider interface supports Claude and other LLM backends
|
|
11
|
+
- **Hook System** — event-driven extensibility with `before-tool`, `after-tool`, `before-generate`, and `after-generate` hooks
|
|
12
|
+
- **Composable CLI** — command, skill, and agent registries for building and extending tools
|
|
13
|
+
|
|
14
|
+
## Project Structure
|
|
15
|
+
|
|
16
|
+
```
|
|
17
|
+
commerce-tools/
|
|
18
|
+
├── agents/ # Agent implementations (extend BaseAgent)
|
|
19
|
+
├── commands/ # CLI command registry
|
|
20
|
+
├── core/ # Runtime: router, tool-runner, session, hooks
|
|
21
|
+
├── mcps/ # MCP servers (New Relic NRQL)
|
|
22
|
+
├── providers/ # AI provider implementations and base types
|
|
23
|
+
├── skills/ # Skill registry and loaders
|
|
24
|
+
├── dist/ # Compiled output (generated)
|
|
25
|
+
├── .env.example # Environment variable template
|
|
26
|
+
└── .mcp.json # MCP server config for Claude Code
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Getting Started
|
|
30
|
+
|
|
31
|
+
### Prerequisites
|
|
32
|
+
|
|
33
|
+
- Node.js 18+
|
|
34
|
+
- A New Relic account with a [NerdGraph API key](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/)
|
|
35
|
+
|
|
36
|
+
### Installation
|
|
37
|
+
|
|
38
|
+
```bash
|
|
39
|
+
npm install
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
### Configuration
|
|
43
|
+
|
|
44
|
+
Copy `.env.example` to `.env` and fill in your credentials:
|
|
45
|
+
|
|
46
|
+
```bash
|
|
47
|
+
cp .env.example .env
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
| Variable | Description |
|
|
51
|
+
|---|---|
|
|
52
|
+
| `NEW_RELIC_API_KEY` | NerdGraph API key |
|
|
53
|
+
| `NEW_RELIC_REGION` | `us` or `eu` (default: `us`) |
|
|
54
|
+
| `NEW_RELIC_ACCOUNT_ID` | Optional default account ID |
|
|
55
|
+
| `MCP_TRANSPORT` | Transport mode (default: `stdio`) |
|
|
56
|
+
|
|
57
|
+
### Build
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
npm run build
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
### Run the New Relic MCP server
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npm start
|
|
67
|
+
# or directly:
|
|
68
|
+
node dist/mcps/newrelic/server.js
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
## Using with Claude Code
|
|
72
|
+
|
|
73
|
+
The `.mcp.json` file configures the New Relic MCP server for use with Claude Code. To register it:
|
|
74
|
+
|
|
75
|
+
```bash
|
|
76
|
+
claude mcp add newrelic -- node /path/to/commerce-tools/dist/mcps/newrelic/server.js
|
|
77
|
+
```
|
|
78
|
+
|
|
79
|
+
Or reference the existing `.mcp.json` in your Claude Code project settings. Once connected, Claude can:
|
|
80
|
+
|
|
81
|
+
- Run NRQL queries against any New Relic account
|
|
82
|
+
- Resolve Adobe Commerce project IDs to account IDs
|
|
83
|
+
- Analyze logs, transactions, APM metrics, Redis, MySQL, and Elasticsearch data
|
|
84
|
+
- Detect and investigate security attacks
|
|
85
|
+
|
|
86
|
+
## Architecture
|
|
87
|
+
|
|
88
|
+
### Core
|
|
89
|
+
|
|
90
|
+
| Module | Purpose |
|
|
91
|
+
|---|---|
|
|
92
|
+
| `core/router.ts` | Resolves provider names to implementations |
|
|
93
|
+
| `core/tool-runner.ts` | Registers and dispatches tool handlers |
|
|
94
|
+
| `core/session.ts` | Manages conversation sessions and message history |
|
|
95
|
+
| `core/hooks.ts` | Event hooks for tool and generation lifecycle |
|
|
96
|
+
|
|
97
|
+
### Agents
|
|
98
|
+
|
|
99
|
+
`agents/_base.ts` implements the agentic loop:
|
|
100
|
+
|
|
101
|
+
1. Call `provider.generate()` with current messages and tools
|
|
102
|
+
2. Append assistant response to history
|
|
103
|
+
3. If stop reason is `tool_use`, extract and execute tool calls
|
|
104
|
+
4. Append tool results to history
|
|
105
|
+
5. Repeat up to `maxIterations` (default: 10)
|
|
106
|
+
|
|
107
|
+
Subclass `BaseAgent` and implement `handleToolCall()` to build custom agents.
|
|
108
|
+
|
|
109
|
+
### New Relic MCP Tools
|
|
110
|
+
|
|
111
|
+
| Tool | Description |
|
|
112
|
+
|---|---|
|
|
113
|
+
| `execute_nrql` | Run a NRQL query against a New Relic account via NerdGraph |
|
|
114
|
+
| `get_account_id_by_project_id` | Resolve an Adobe Commerce project ID to a New Relic account ID |
|
|
115
|
+
|
|
116
|
+
### New Relic MCP Prompts
|
|
117
|
+
|
|
118
|
+
| Prompt | Description |
|
|
119
|
+
|---|---|
|
|
120
|
+
| `newrelic_commerce` | NRQL specialist for Adobe Commerce monitoring and investigation |
|
|
121
|
+
| `newrelic_security` | Extends commerce prompt with attack detection and security analysis |
|
|
122
|
+
|
|
123
|
+
## Development
|
|
124
|
+
|
|
125
|
+
```bash
|
|
126
|
+
# Watch mode
|
|
127
|
+
npx tsc --watch
|
|
128
|
+
|
|
129
|
+
# Type check only
|
|
130
|
+
npx tsc --noEmit
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
## License
|
|
134
|
+
|
|
135
|
+
Private — Adobe internal tooling.
|