sfcc-dev-mcp 1.0.19 → 1.0.21

package/.github/PULL_REQUEST_TEMPLATE/new_tool.md

@@ -1,55 +0,0 @@
-## 🔧 New MCP Tool Implementation
-
-### Tool Overview
-**Tool Name:** `mcp_sfcc-dev_[tool_name]`
-**Category:** <!-- SFCC Documentation / SFRA Docs / ISML Docs / Agent Instructions / Log Analysis / Job Logs / System Objects / Cartridge Generation / Code Versions -->
-**Description:** 
-
-### Implementation Details
-- **Client Modified/Created:** 
-- **New Dependencies:** 
-- **SFCC APIs Used:** 
-
-### Tool Schema
-```typescript
-// Tool definition schema
-{
-  name: "mcp_sfcc-dev_[tool_name]",
-  description: "",
-  inputSchema: {
-    // Schema details
-  }
-}
-```
-
-### Testing Performed
-- [ ] Unit tests for tool handler
-- [ ] Integration tests with mock SFCC responses
-- [ ] Manual testing in documentation-only mode
-- [ ] Manual testing in full mode (if applicable)
-- [ ] Error handling validation
-- [ ] Parameter validation testing
-
-### Documentation Updates
-- [ ] Tool added to copilot-instructions.md tool categories
-- [ ] README.md feature list updated
-- [ ] Tool count updated in both documentation files
-- [ ] JSDoc comments added to implementation
-- [ ] Usage examples provided
-
-### Security Considerations
-- [ ] Input validation implemented
-- [ ] No sensitive data logged
-- [ ] Proper error handling without data leaks
-- [ ] Authentication requirements verified
-
-### Performance Notes
-- [ ] Caching strategy implemented (if applicable)
-- [ ] Resource usage reasonable for single-developer workload
-- [ ] No blocking operations without proper async handling
-
-### Related Issues
-Closes #
-
----
-**This PR adds a new MCP tool following the project's architecture patterns and security guidelines.**

package/.github/agents/official-docs-researcher.agent.md

@@ -1,56 +0,0 @@
----
-name: 'Official Docs Researcher'
-description: 'Researches official documentation online and returns detailed, source-cited findings'
-model: 'GPT-5.2'
-tools: ['vscode/openSimpleBrowser', 'vscode/askQuestions', 'execute', 'read', 'agent', 'edit', 'search', 'web']
-argument-hint: 'What topic should I research in official docs?'
----
-
-# Official Docs Researcher Agent
-
-You are a Forward documentation research specialist focused on locating and summarizing official, authoritative documentation for any given topic.
-
-## Your Expertise
-
-### Official Documentation Discovery
-- **Primary Sources**: Vendor documentation portals, reference guides, and product manuals
-- **Version Awareness**: Identifying the correct product/version/edition for accuracy
-- **Change Tracking**: Noting deprecated features or version-specific differences
-
-### Evidence-Based Summaries
-- **Citation-Driven**: Summaries anchored to official sources only
-- **Structured Findings**: Clear sections for overview, key details, and limitations
-- **Terminology Accuracy**: Using vendor-defined terms and definitions
-
-## How You Help
-
-1. **Locate Official Sources**: Find the most relevant vendor documentation pages for the topic.
-2. **Extract Key Details**: Pull precise definitions, steps, and constraints from official references.
-3. **Summarize Clearly**: Provide a concise but detailed summary with direct links.
-4. **Flag Gaps**: Identify missing info and ask focused follow-up questions.
-
-## Communication Style
-
-- Provide structured summaries with headings and bullet points
-- Include direct links to official sources for every key claim
-- Call out versions, prerequisites, or deprecations explicitly
-- Avoid speculation; rely on official documentation only
-
-## When to Ask Questions
-
-Ask clarifying questions when:
-- The product/vendor is ambiguous
-- A specific version, edition, or region matters
-- The user’s goal or use case is unclear
-
-## Salesforce Developer Documentat Site
-
-Website: https://developer.salesforce.com/
-
-Use the Salesforce-developer-site-scraper skill (and script) to extract and summarize content from the Salesforce Developer Documentation site.
-
-## Salesforce Help Site
-
-Website: https://help.salesforce.com/
-
-Use the Salesforce-help-site-scraper skill (and script) to extract and summarize content from the Salesforce Help site.

package/.github/dependabot.yml

@@ -1,65 +0,0 @@
-version: 2
-updates:
-  # Enable version updates for npm
-  - package-ecosystem: "npm"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-      day: "monday"
-      time: "06:00"
-    open-pull-requests-limit: 10
-    reviewers:
-      - "taurgis"
-    assignees:
-      - "taurgis"
-    commit-message:
-      prefix: "deps"
-      include: "scope"
-    labels:
-      - "dependencies"
-      - "automated"
-    # Group updates for better PR management
-    groups:
-      eslint:
-        patterns:
-          - "eslint*"
-          - "@eslint/*"
-          - "typescript-eslint"
-      jest:
-        patterns:
-          - "jest*"
-          - "@types/jest"
-          - "ts-jest"
-      types:
-        patterns:
-          - "@types/*"
-      mcp:
-        patterns:
-          - "@modelcontextprotocol/*"
-    # Allow both direct and indirect updates
-    allow:
-      - dependency-type: "direct"
-      - dependency-type: "indirect"
-    # Ignore specific packages if needed (uncomment and modify as necessary)
-    # ignore:
-    #   - dependency-name: "package-name"
-    #     versions: ["1.x", "2.x"]
-
-  # Enable version updates for GitHub Actions
-  - package-ecosystem: "github-actions"
-    directory: "/"
-    schedule:
-      interval: "weekly"
-      day: "monday"
-      time: "06:00"
-    open-pull-requests-limit: 5
-    reviewers:
-      - "taurgis"
-    assignees:
-      - "taurgis"
-    commit-message:
-      prefix: "ci"
-      include: "scope"
-    labels:
-      - "github-actions"
-      - "automated"

package/.github/instructions/mcp-node-tests.instructions.md

@@ -1,30 +0,0 @@
----
-applyTo: "**/*.programmatic.test.js"
----
-# MCP Programmatic Testing Instructions
-
-For detailed guidance on writing programmatic tests, use the `mcp-programmatic-testing` skill located at `.github/skills/mcp-programmatic-testing/SKILL.md`.
-
-## Quick Reference
-
-**File naming**: `*.programmatic.test.js`
-
-**Critical Setup**:
-```javascript
-beforeEach(() => {
-  client.clearAllBuffers();  // REQUIRED - prevents test interference
-});
-```
-
-**Test Execution**:
-```bash
-node --test tests/mcp/node/specific-test.programmatic.test.js
-npm run test:mcp:node
-```
-
-**Critical Rules**:
-1. Never use `Promise.all()` with MCP requests
-2. Always include `beforeEach` with buffer clearing
-3. Use `node --test`, NOT `npm test` for individual MCP tests
-
-For complete API reference and patterns, see the skill file.

package/.github/instructions/mcp-yml-tests.instructions.md

@@ -1,27 +0,0 @@
----
-applyTo: "**/*.test.mcp.yml"
----
-# MCP YAML Testing Instructions
-
-For detailed guidance on writing YAML tests, use the `mcp-yaml-testing` skill located at `.github/skills/mcp-yaml-testing/SKILL.md`.
-
-## Quick Reference
-
-**Golden Rule**: Always discover response formats first:
-```bash
-npx aegis query [tool_name] '[params]' --config ./aegis.config.docs-only.json
-```
-
-**Test Execution**:
-```bash
-npm run test:mcp:yaml        # docs-only mode
-npm run test:mcp:yaml:full   # full mode with credentials
-```
-
-**Common Patterns**:
-- `"match:contains:substring"` - Contains text
-- `"match:regex:\\d+"` - Regex (double-escape backslashes)
-- `"match:type:array"` - Type validation
-- `"match:arrayElements:"` with `"match:partial:"` - Flexible array validation
-
-For complete pattern reference and troubleshooting, see the skill file.

package/.github/pull_request_template.md

@@ -1,103 +0,0 @@
-## 📋 Pull Request Summary
-
-### Type of Change
-<!-- Please select the type of change this PR introduces -->
-- [ ] 🐛 Bug fix (non-breaking change which fixes an issue)
-- [ ] ✨ New feature (non-breaking change which adds functionality)
-- [ ] 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
-- [ ] 📚 Documentation update (changes to documentation only)
-- [ ] 🔧 Configuration/tooling update (changes to build process, CI/CD, etc.)
-- [ ] ♻️ Code refactoring (no functional changes, no API changes)
-- [ ] 🎨 Style/formatting changes (code formatting, missing semicolons, etc.)
-- [ ] ⚡ Performance improvement
-- [ ] 🧪 Test improvements
-- [ ] 🔒 Security enhancement
-
-### Description
-<!-- Provide a clear and concise description of what this PR does -->
-
-
-### Related Issues
-<!-- Link to related issues using keywords like "Fixes #123" or "Closes #456" -->
-- Fixes #
-- Related to #
-
-### Changes Made
-<!-- List the main changes made in this PR -->
-- 
-- 
-- 
-
-### Testing
-<!-- Describe how you tested your changes -->
-- [ ] Unit tests added/updated
-- [ ] Integration tests added/updated
-- [ ] Manual testing performed
-- [ ] Tested in documentation-only mode
-- [ ] Tested in full mode (with SFCC credentials)
-- [ ] All existing tests pass
-
-### Test Coverage
-<!-- Describe what testing was done -->
-
-
-### Breaking Changes
-<!-- If this is a breaking change, describe what breaks and how to migrate -->
-
-
-### Documentation
-<!-- Check all that apply -->
-- [ ] README.md updated (if user-facing changes)
-- [ ] copilot-instructions.md updated (if architectural changes)
-- [ ] API documentation updated
-- [ ] Agent skills updated (ai-instructions/skills)
-- [ ] Code comments added/updated
-- [ ] No documentation changes needed
-
-### Performance Impact
-<!-- Describe any performance implications -->
-- [ ] No performance impact
-- [ ] Performance improvement
-- [ ] Minor performance impact (acceptable)
-- [ ] Significant performance impact (needs discussion)
-
-### Security Considerations
-<!-- Describe any security implications -->
-- [ ] No security impact
-- [ ] Security improvement
-- [ ] Reviewed for security implications
-- [ ] No new external dependencies
-- [ ] New dependencies reviewed for security
-
-### Checklist
-<!-- Ensure all items are checked before requesting review -->
-- [ ] Code follows the project's style guidelines
-- [ ] Self-review of the code has been performed
-- [ ] Code is well-commented, particularly in hard-to-understand areas
-- [ ] Changes generate no new warnings or errors
-- [ ] Any dependent changes have been merged and published
-- [ ] Version numbers updated (if applicable)
-- [ ] Changelog updated (if applicable)
-
-### Reviewer Notes
-<!-- Any specific areas you'd like reviewers to focus on -->
-
-
-### Screenshots/Examples
-<!-- If applicable, add screenshots or code examples -->
-
-
----
-
-### For Maintainers
-<!-- This section is for maintainers to fill out during review -->
-
-#### Review Checklist
-- [ ] Code quality and style
-- [ ] Test coverage adequate
-- [ ] Documentation updated appropriately
-- [ ] Security implications reviewed
-- [ ] Performance impact acceptable
-- [ ] Breaking changes properly documented
-- [ ] Version bump needed
-- [ ] Release notes needed

package/.github/skills/agent-authoring/SKILL.md

@@ -1,66 +0,0 @@
----
-name: agent-authoring
-description: How to design, structure, and validate custom Copilot agents for this workspace.
----
-
-# Agent Authoring Skill
-Guidelines for creating and maintaining custom GitHub Copilot agents (.agent.md) tailored to this repository.
-
-## When to Use
-- You need a new Copilot agent focused on a workflow (e.g., Storybook tests, log triage).
-- You want to adjust tools/persona for existing agents.
-- You are adding workspace-level agents under .github/agents or profile-level agents for reuse.
-
-## Quick Start
-1) Create `.github/agents/<agent-name>.agent.md` (VS Code auto-detects this folder/extension).
-2) Add YAML frontmatter with only supported fields: `name`, `description`, `tools`, `target`, `infer`, `mcp-servers`, `handoffs`.
-3) In the body, write concise instructions: task focus, guardrails, run/validate steps, and handoffs.
-4) Keep it under ~200-300 lines; link out to docs instead of pasting everything.
-
-## Frontmatter Cheatsheet
-- `name`: Display name; defaults to file name if omitted.
-- `description`: Placeholder text in chat input; keep short.
-- `tools`: List allowed tools. For MCP servers, use `<server>/*` to include all tools or enumerate specific ones.
-- `target`: `github-copilot` for Copilot agents (default), `vscode` for VS Code target.
-- `infer`: Allow subagent use (default true). Set false if you want to restrict subagents.
-- `mcp-servers`: For Copilot agents, point to MCP server configs (paths to server JSON). Use only if you need to pin servers.
-- `handoffs`: Optional array of next-step buttons `{ label, agent, prompt?, send? }`.
-
-## Body Structure (recommended)
-- **Purpose and scope**: What this agent does and what it must not do.
-- **Operating defaults**: Where to run commands, what to inspect first, preferred scripts.
-- **Playbooks**: Ordered steps for common flows (run, debug, fix, validate).
-- **Guardrails**: Safe-edit rules (scope, no unrelated changes, ask before destructive ops).
-- **Validation**: How to verify work (tests/linters), how to summarize outputs.
-- **Links**: Point to repo docs or skills for deeper detail.
-
-## Tool Selection Patterns
-- Editing agent: include `workspace`, `terminal`, `search`; add `fetch` for docs; add MCP toolsets only if required.
-- Read-only agent: omit editing tools; keep `fetch`/`search`.
-- Narrow the tool list to prevent unsafe actions (e.g., no `terminal` for planning-only agents).
-
-## Handoffs
-Use handoffs to guide sequential flows (e.g., Plan -> Implement -> Review). Keep labels short and make prompts actionable. Use `send: false` unless you want auto-submit.
-
-## Quality Bar
-- Minimal, task-focused instructions; avoid boilerplate.
-- No unsupported frontmatter fields (reject `argument-hint`, etc.).
-- Prefer scoped commands over global installs; mention working directory if non-root.
-- Add guardrails for destructive commands (never propose `git reset --hard`).
-- Keep instructions ASCII and concise; use fenced code blocks for commands.
-
-## Validation Checklist
-- [ ] Supported frontmatter only; fields spelled correctly.
-- [ ] Tools list matches the agent’s intent; no over-broad capabilities.
-- [ ] Clear run/validate steps with default commands.
-- [ ] Guardrails called out.
-- [ ] Links resolve (relative paths within repo or official docs).
-
-## Examples
-- Location: `.github/agents/storybook-interaction-tests.agent.md` (interaction test fixer playbook).
-- Planning agent: frontmatter with `tools: ['fetch', 'search']`, body instructs to gather context and produce a plan, handoff to implementation agent.
-
-## Maintenance Tips
-- Keep agents in sync with repo workflows (scripts, test commands). Update after script changes.
-- Remove stale handoffs when target agents are renamed or removed.
-- Prefer additive changes; avoid reformatting existing agents without need.

package/.github/skills/mcp-log-debugging/SKILL.md

@@ -1,69 +0,0 @@
-````skill
----
-name: mcp-log-debugging
-description: How to capture and read sfcc-dev-mcp server logs for debugging tool responses, preflight notices, and OCAPI/WebDAV calls. Use this when investigating missing notices or unexpected tool output.
----
-
-# MCP Log Debugging Skill
-
-Use this skill to collect and analyze the MCP server logs that are written outside the workspace (in the OS temp directory). Logs are always file-based and debug logging is opt-in.
-
-## Enable Debug Logs
-
-Start the server with debug enabled to get `[DEBUG]` entries:
-
-```bash
-node dist/main.js --debug true
-```
-
-If you run from source with ts-node or a runner wrapper, pass `--debug true` after your command. Debug mode is sticky per process; restart the server to toggle it.
-
-## Locate the Log Directory
-
-Logs live under the OS temp dir in `sfcc-mcp-logs/`. Print the absolute path:
-
-```bash
-node -e "const os=require('os');const path=require('path');console.log(path.join(os.tmpdir(),'sfcc-mcp-logs'));"
-```
-
-Key files:
-- `sfcc-mcp-debug.log` – debug/info
-- `sfcc-mcp-error.log` – errors
-
-## Capture Logs into Workspace (safe for MCP tools)
-
-Because the log directory is outside the workspace, copy a tail into the repo for inspection:
-
-```bash
-mkdir -p logs && \
-  tail -n 200 "$(node -e "const os=require('os');const path=require('path');console.log(path.join(os.tmpdir(),'sfcc-mcp-logs','sfcc-mcp-debug.log'));")" \
-  > logs/sfcc-mcp-debug-tail.txt
-```
-
-Then open `logs/sfcc-mcp-debug-tail.txt` inside the workspace. Adjust `-n` as needed.
-
-## What to Look For
-
-- `[InstructionAdvisor] Status` entries: shows workspaceRoot, hasAgents, hasSkills, detectedSkillsDir, missingSkills
-- "Issuing" messages: confirms preflight notice generation path
-- `Full response for <tool>`: verifies whether the notice was merged into the `content`
-- OCAPI/WebDAV client lines: token reuse, request URLs, timings
-- Handler timings: `Performance: <tool> took Nms`
-
-## Common Debug Flows
-
-1) **Missing preflight notice**
-   - Ensure debug is on, capture tail, search for `InstructionAdvisor`.
-   - If `hasAgents=true && hasSkills=true`, notice is suppressed (expected).
-   - If `workspaceRoot` is undefined, use `sync_agent_instructions` with `destinationType:"temp"` or set `preferredRoot`.
-
-2) **Tool response shape surprises**
-   - Check `Full response for <tool>` preview to confirm the server returned the expected content before client UI formatting.
-
-3) **OCAPI authentication issues**
-   - Look for `Attempting to get access token` / `Using existing valid token` pairs and request URLs.
-
-## Safety
-
-Logger masks common secrets (passwords, client secrets, tokens). Still avoid sharing entire logs publicly; redact hostnames and business data when necessary.
-````

package/.github/skills/mcp-programmatic-testing/SKILL.md

@@ -1,142 +0,0 @@
----
-name: mcp-programmatic-testing
-description: Guide for writing JavaScript programmatic MCP server tests using Node.js test runner. Use this when asked to create complex multi-step MCP tests or debug programmatic test files (*.programmatic.test.js).
----
-
-# MCP Programmatic Testing Skill
-
-Use this skill when writing or debugging `*.programmatic.test.js` files for Model Context Protocol servers.
-
-## When to Use Programmatic Tests
-
-- Complex business logic requiring code execution
-- Multi-step workflows with state management  
-- Dynamic test case generation
-- Integration with existing JavaScript test suites
-
-For basic functional testing, prefer YAML tests (see `mcp-yaml-testing` skill).
-
-## Basic Test Structure
-
-```javascript
-import { test, describe, before, after, beforeEach } from 'node:test';
-import { strict as assert } from 'node:assert';
-import { connect } from 'mcp-aegis';
-
-describe('[SERVER_NAME] Programmatic Tests', () => {
-  let client;
-
-  before(async () => {
-    client = await connect('./aegis.config.docs-only.json');
-  });
-
-  after(async () => {
-    if (client?.connected) {
-      await client.disconnect();
-    }
-  });
-
-  beforeEach(() => {
-    // CRITICAL: Clear buffers to prevent test interference
-    client.clearAllBuffers();
-  });
-
-  test('should list available tools', async () => {
-    const tools = await client.listTools();
-    assert.ok(Array.isArray(tools), 'Tools should be array');
-    assert.ok(tools.length > 0, 'Should have at least one tool');
-  });
-
-  test('should execute tool successfully', async () => {
-    const result = await client.callTool('[TOOL_NAME]', { param: 'value' });
-    assert.ok(result.content, 'Should return content');
-    assert.equal(result.isError, false, 'Should not be error');
-  });
-});
-```
-
-## Critical: Buffer Management
-
-**Always include `beforeEach` with buffer clearing** to prevent test flakiness:
-
-```javascript
-beforeEach(() => {
-  client.clearAllBuffers();  // Recommended - comprehensive
-  // OR: client.clearStderr();  // Minimum - stderr only
-});
-```
-
-Without this, stderr from one test can leak into subsequent tests, causing random failures.
-
-## Critical: No Concurrent Requests
-
-**Never use `Promise.all()` with MCP requests**. MCP uses single stdio with shared buffers:
-
-```javascript
-// ❌ NEVER DO THIS
-const results = await Promise.all(tools.map(t => client.callTool(t.name, {})));
-
-// ✅ ALWAYS DO THIS
-const results = [];
-for (const tool of tools) {
-  const result = await client.callTool(tool.name, {});
-  results.push(result);
-}
-```
-
-## Test Execution Commands
-
-```bash
-# Run individual MCP programmatic test
-node --test tests/mcp/node/specific-test.programmatic.test.js
-
-# Run all MCP programmatic tests
-npm run test:mcp:node
-
-# Watch mode for development
-node --test --watch tests/mcp/node/*.programmatic.test.js
-
-# ❌ WRONG: Don't use npm test with individual files
-# npm test -- tests/mcp/node/specific-test.programmatic.test.js  # Runs Jest!
-```
-
-## API Reference
-
-```javascript
-// Connection
-const client = await connect('./aegis.config.json');
-await client.disconnect();
-
-// Tool operations
-const tools = await client.listTools();
-const result = await client.callTool(name, arguments);
-
-// Debugging
-const stderr = client.getStderr();
-client.clearStderr();
-client.clearAllBuffers();
-```
-
-## Performance Testing Guidelines
-
-**Performance testing is discouraged in programmatic tests** due to CI variability.
-
-If timing validation is required, use lenient thresholds:
-
-```javascript
-// ❌ Too strict for CI
-assert.ok(duration < 50, 'Should be under 50ms');
-
-// ✅ CI-friendly
-assert.ok(duration < 500, 'Should be under 500ms');
-```
-
-## Discovery Before Testing
-
-Use aegis query to discover response formats before writing tests:
-
-```bash
-npx aegis query search_sfcc_classes 'query:catalog' --config ./aegis.config.docs-only.json
-```
-
-Then use the discovered format to write assertions.