@kavinga/commerce-tools 0.1.2 → 0.1.6

package/README.md

@@ -0,0 +1,135 @@
+# commerce-tools
+
+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.
+
+## Features
+
+- **New Relic MCP Server** — executes NRQL queries via NerdGraph and maps Adobe Commerce project IDs to New Relic account IDs
+- **Commerce & Security Prompts** — built-in specialist prompts for APM monitoring, performance analysis, and attack detection (brute force, SQLi, XSS, DDoS, scraping, carding)
+- **Agent Framework** — automatic tool-use loop with conversation history management and configurable iteration limits
+- **Pluggable Providers** — abstract provider interface supports Claude and other LLM backends
+- **Hook System** — event-driven extensibility with `before-tool`, `after-tool`, `before-generate`, and `after-generate` hooks
+- **Composable CLI** — command, skill, and agent registries for building and extending tools
+
+## Project Structure
+
+```
+commerce-tools/
+├── agents/        # Agent implementations (extend BaseAgent)
+├── commands/      # CLI command registry
+├── core/          # Runtime: router, tool-runner, session, hooks
+├── mcps/          # MCP servers (New Relic NRQL)
+├── providers/     # AI provider implementations and base types
+├── skills/        # Skill registry and loaders
+├── dist/          # Compiled output (generated)
+├── .env.example   # Environment variable template
+└── .mcp.json      # MCP server config for Claude Code
+```
+
+## Getting Started
+
+### Prerequisites
+
+- Node.js 18+
+- A New Relic account with a [NerdGraph API key](https://docs.newrelic.com/docs/apis/nerdgraph/get-started/introduction-new-relic-nerdgraph/)
+
+### Installation
+
+```bash
+npm install
+```
+
+### Configuration
+
+Copy `.env.example` to `.env` and fill in your credentials:
+
+```bash
+cp .env.example .env
+```
+
+| Variable | Description |
+|---|---|
+| `NEW_RELIC_API_KEY` | NerdGraph API key |
+| `NEW_RELIC_REGION` | `us` or `eu` (default: `us`) |
+| `NEW_RELIC_ACCOUNT_ID` | Optional default account ID |
+| `MCP_TRANSPORT` | Transport mode (default: `stdio`) |
+
+### Build
+
+```bash
+npm run build
+```
+
+### Run the New Relic MCP server
+
+```bash
+npm start
+# or directly:
+node dist/mcps/newrelic/server.js
+```
+
+## Using with Claude Code
+
+The `.mcp.json` file configures the New Relic MCP server for use with Claude Code. To register it:
+
+```bash
+claude mcp add newrelic -- node /path/to/commerce-tools/dist/mcps/newrelic/server.js
+```
+
+Or reference the existing `.mcp.json` in your Claude Code project settings. Once connected, Claude can:
+
+- Run NRQL queries against any New Relic account
+- Resolve Adobe Commerce project IDs to account IDs
+- Analyze logs, transactions, APM metrics, Redis, MySQL, and Elasticsearch data
+- Detect and investigate security attacks
+
+## Architecture
+
+### Core
+
+| Module | Purpose |
+|---|---|
+| `core/router.ts` | Resolves provider names to implementations |
+| `core/tool-runner.ts` | Registers and dispatches tool handlers |
+| `core/session.ts` | Manages conversation sessions and message history |
+| `core/hooks.ts` | Event hooks for tool and generation lifecycle |
+
+### Agents
+
+`agents/_base.ts` implements the agentic loop:
+
+1. Call `provider.generate()` with current messages and tools
+2. Append assistant response to history
+3. If stop reason is `tool_use`, extract and execute tool calls
+4. Append tool results to history
+5. Repeat up to `maxIterations` (default: 10)
+
+Subclass `BaseAgent` and implement `handleToolCall()` to build custom agents.
+
+### New Relic MCP Tools
+
+| Tool | Description |
+|---|---|
+| `execute_nrql` | Run a NRQL query against a New Relic account via NerdGraph |
+| `get_account_id_by_project_id` | Resolve an Adobe Commerce project ID to a New Relic account ID |
+
+### New Relic MCP Prompts
+
+| Prompt | Description |
+|---|---|
+| `newrelic_commerce` | NRQL specialist for Adobe Commerce monitoring and investigation |
+| `newrelic_security` | Extends commerce prompt with attack detection and security analysis |
+
+## Development
+
+```bash
+# Watch mode
+npx tsc --watch
+
+# Type check only
+npx tsc --noEmit
+```
+
+## License
+
+MIT

package/dist/mcps/newrelic/prompts/commerce.js

@@ -1,23 +1,23 @@
 export const commercePrompt = `
-You are a New Relic specialist. You run NRQL queries and resolve Adobe Commerce project IDs to account IDs using the New Relic MCP tools.
+Reference for querying New Relic with NRQL for Adobe Commerce projects, using the New Relic MCP tools \`get_account_id_by_project_id\` and \`execute_nrql\`.
 
-**Critical:** Do not use any attribute name in NRQL unless it was returned by a \`SELECT * FROM <entity> ... LIMIT 1\` query you already ran for that entity. Run that discovery query first; then use only the keys from the result. Never guess or invent field names.
+**Critical:** Do not use any attribute name in NRQL unless it was returned by a \`SELECT * FROM <entity> ... LIMIT 1\` query already run for that entity. Run that discovery query first; then use only the keys from the result. Never guess or invent field names.
 
-## When invoked
+## Workflow
 
-1. **If the user provides an Adobe Commerce project ID** (and no account ID):
+1. **Resolve the account.** If an Adobe Commerce project ID is given (and no account ID):
    - Call the New Relic MCP tool \`get_account_id_by_project_id\` with that project ID.
    - Use the returned \`accountId\` from the first matching entity for all NRQL execution.
-   - If no entities are found, tell the user and suggest checking the project ID or NEW_RELIC_API_KEY.
+   - If no entities are found, report it and suggest checking the project ID or NEW_RELIC_API_KEY.
 
-2. **Before writing any NRQL that uses specific field names** (in SELECT, WHERE, FACET, etc.):
-   - You **must** first run \`SELECT * FROM <entity> ... LIMIT 1\` (with the correct WHERE for that entity and a SINCE clause).
+2. **Discover fields before writing any NRQL that uses specific field names** (in SELECT, WHERE, FACET, etc.):
+   - First run \`SELECT * FROM <entity> ... LIMIT 1\` (with the correct WHERE for that entity and a SINCE clause).
    - Inspect the JSON result and note the **exact attribute names** (keys) returned.
    - **Only use those attribute names** in subsequent queries. Do not assume, guess, or invent field names.
 
-3. **Build NRQL** from the user's intent and the standard Adobe Commerce patterns below. Use the project ID in filters as shown. For any non-\`SELECT *\` query, use only fields you obtained in step 2.
+3. **Build NRQL** from the request and the standard Adobe Commerce patterns below. Use the project ID in filters as shown. For any non-\`SELECT *\` query, use only fields obtained in step 2.
 
-4. **Execute NRQL** with the MCP tool \`execute_nrql\`, passing the \`account_id\` from step 1 (or the user's account ID if they provided it). Use a sensible \`timeout_seconds\` (e.g. 30) for large result sets.
+4. **Execute NRQL** with the MCP tool \`execute_nrql\`, passing the \`account_id\` from step 1 (or the account ID given directly). Use a sensible \`timeout_seconds\` (e.g. 30) for large result sets.
 
 5. **Summarize results** clearly: row count, key fields, and any errors or empty result sets.
 

package/dist/mcps/newrelic/prompts/security.d.ts

@@ -1,2 +1,12 @@
+/**
+ * Self-contained MCP prompt: embeds the full commerce reference because MCP
+ * prompt consumers cannot load the newrelic-commerce skill.
+ */
 export declare const securityPrompt: string;
+/**
+ * Subagent system prompt for the Claude Code / Cursor plugins: persona plus
+ * the security workflow, deferring the full entity/filter reference to the
+ * newrelic-commerce skill instead of duplicating it.
+ */
+export declare const securityAgentPrompt: string;
 //# sourceMappingURL=security.d.ts.map

package/dist/mcps/newrelic/prompts/security.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../../../mcps/newrelic/prompts/security.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,cAAc,QAgEnB,CAAC"}
+{"version":3,"file":"security.d.ts","sourceRoot":"","sources":["../../../../mcps/newrelic/prompts/security.ts"],"names":[],"mappings":"AAmEA;;;GAGG;AACH,eAAO,MAAM,cAAc,QAQJ,CAAC;AAExB;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAaT,CAAC"}

package/dist/mcps/newrelic/prompts/security.js

@@ -1,12 +1,11 @@
 import { commercePrompt } from './commerce.js';
-export const securityPrompt = `${commercePrompt}
-
----
-
-## Security & Attack Analysis
-
-You are also a security analyst. In addition to the general NRQL and Adobe Commerce capabilities above, you detect and investigate attacks against Adobe Commerce projects using New Relic data.
-
+/**
+ * Security-analysis knowledge shared by the MCP prompt and the plugin agent.
+ * Keep this self-contained apart from the entity filters / field-discovery
+ * rules, which the consumers supply (commercePrompt or the newrelic-commerce
+ * skill).
+ */
+const securityCore = `
 ### Attack categories to investigate
 
 | Category | Primary entities | Key signals |
@@ -23,7 +22,7 @@ You are also a security analyst. In addition to the general NRQL and Adobe Comme
 
 ### Investigation workflow
 
-1. **Resolve account** — same as the base prompt: call \`get_account_id_by_project_id\` if only a project ID is given.
+1. **Resolve account** — call \`get_account_id_by_project_id\` if only a project ID is given.
 
 2. **Discover fields** — run \`SELECT * FROM <entity> WHERE <filter> LIMIT 1 SINCE 1 hour ago\` for each entity you plan to query. Only use field names from those results.
 
@@ -64,4 +63,36 @@ You are also a security analyst. In addition to the general NRQL and Adobe Comme
 - When evidence is ambiguous, state it clearly and suggest additional queries rather than asserting an attack occurred.
 - If the user asks to block an IP or apply a WAF rule, note that those actions must be taken outside New Relic (e.g. in the Fastly or CDN console) and are not performed by this tool.
 `.trim();
+/**
+ * Self-contained MCP prompt: embeds the full commerce reference because MCP
+ * prompt consumers cannot load the newrelic-commerce skill.
+ */
+export const securityPrompt = `${commercePrompt}
+
+---
+
+## Security & Attack Analysis
+
+In addition to the general NRQL and Adobe Commerce guidance above, detect and investigate attacks against Adobe Commerce projects using New Relic data.
+
+${securityCore}`.trim();
+/**
+ * Subagent system prompt for the Claude Code / Cursor plugins: persona plus
+ * the security workflow, deferring the full entity/filter reference to the
+ * newrelic-commerce skill instead of duplicating it.
+ */
+export const securityAgentPrompt = `
+You are a security analyst for Adobe Commerce projects on New Relic. You detect and investigate attacks by running NRQL queries with the New Relic MCP tools \`get_account_id_by_project_id\` and \`execute_nrql\`.
+
+For the full entity → filter table and field-discovery rules, use the \`newrelic-commerce\` skill. Essentials:
+
+- **Log and infrastructure samples** (ProcessSample, SystemSample, Mysql/Redis/Elasticsearch/Rabbitmq samples): \`apmApplicationNames = '|<project id>|'\` (literal pipe characters around the project ID).
+- **Fastly (CDN) logs:** \`cache_status IS NOT NULL AND project_id = '<project id>'\`.
+- **APM events** (Transaction, TransactionError, PageView, ErrorTrace): \`appName = '<project id>'\` (no pipes).
+- **Never use a field name** that was not returned by a \`SELECT * FROM <entity> ... LIMIT 1\` discovery query you already ran for that entity.
+- Always add a \`SINCE ...\` clause when querying Log data.
+
+## Security & Attack Analysis
+
+${securityCore}`.trim();
 //# sourceMappingURL=security.js.map

package/dist/mcps/newrelic/prompts/security.js.map

@@ -1 +1 @@
-{"version":3,"file":"security.js","sourceRoot":"","sources":["../../../../mcps/newrelic/prompts/security.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAgE9C,CAAC,IAAI,EAAE,CAAC"}
+{"version":3,"file":"security.js","sourceRoot":"","sources":["../../../../mcps/newrelic/prompts/security.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAE/C;;;;;GAKG;AACH,MAAM,YAAY,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAyDpB,CAAC,IAAI,EAAE,CAAC;AAET;;;GAGG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,GAAG,cAAc;;;;;;;;EAQ7C,YAAY,EAAE,CAAC,IAAI,EAAE,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;;;;;;;;;;;;;EAajC,YAAY,EAAE,CAAC,IAAI,EAAE,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kavinga/commerce-tools",
-  "version": "0.1.2",
+  "version": "0.1.6",
   "description": "Multi-provider AI tooling platform with MCPs, agents, skills, and commands",
   "type": "module",
   "bin": {
@@ -10,7 +10,8 @@
     "dist/"
   ],
   "scripts": {
-    "build": "tsc",
+    "build": "tsc && npm run build:plugins",
+    "build:plugins": "tsx plugins/build.ts",
     "dev:newrelic": "tsx mcps/newrelic/server.ts",
     "start:newrelic": "node dist/mcps/newrelic/server.js"
   },
@@ -26,5 +27,8 @@
   },
   "engines": {
     "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
   }
 }