Skip to content

Commit de8d40b

Browse files
claveryclavery
authored
Add MCP tools for log inspection and Script API/XSD docs (#420)
* Add MCP tools for log inspection and Script API/XSD docs - Logs: logs_list_files, logs_get_recent, plus a watch lifecycle (logs_watch_start/poll/stop/list) that buffers entries between polls via a new LogWatchRegistry on ServerContext, so agents don't miss entries produced between request/response turns. - Docs: docs_search/read/list and docs_schema_search/read/list over the bundled Script API and XSD corpora; no instance auth required. - Adds a new DIAGNOSTICS toolset that groups the script debugger and log tools; existing debug-* tools also re-tagged. - Promotes log filter helpers (parseSinceTime, filterBy*, matchesLevel, matchesSearch) from the CLI to @salesforce/b2c-tooling-sdk so the MCP package can reuse them. * Fix dead links in new MCP tool docs * Harden log watch tools and make DIAGNOSTICS always-on Review fixes for the MCP log watch lifecycle: - Stop the underlying tail if a concurrent logs_watch_start loses the hostname race at registerWatch, instead of orphaning a background poll. - Make logs_watch_stop truly idempotent (matches its documented contract) rather than throwing on a second stop. - Drain files_discovered per poll (report each file once) while keeping the cumulative list for logs_watch_list. - Bound the entry buffer by bytes as well as count so a few multi-MB stack traces can't blow past the intended memory bound. - Default logs_watch_start last_entries to 0 so a fresh watch captures only new entries, matching the "start before triggering" workflow. Make DIAGNOSTICS a base toolset alongside SCAPI so the debugger, log, and docs tools are auto-enabled for every project type. Document the DIAGNOSTICS toolset and the poll response field shapes; expand tests for all of the above.
1 parent b723939 commit de8d40b

42 files changed

Lines changed: 2461 additions & 153 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.changeset/mcp-logs-and-docs-tools.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
---
2+
'@salesforce/b2c-dx-mcp': minor
3+
'@salesforce/b2c-tooling-sdk': minor
4+
---
5+
6+
Add MCP tools for log inspection and documentation lookup. Logs: `logs_list_files`, `logs_get_recent`, and a `logs_watch_start` / `logs_watch_poll` / `logs_watch_stop` / `logs_watch_list` lifecycle that buffers entries between polls so agents don't miss logs produced between tool calls. Docs: `docs_search`, `docs_read`, `docs_list`, `docs_schema_search`, `docs_schema_read`, `docs_schema_list` for the bundled Script API and XSD schema corpora. Adds a new `DIAGNOSTICS` toolset that groups the script debugger and log tools; like `SCAPI`, it is always enabled (auto-discovered for every project type). SDK now also exports the log filter helpers (`parseSinceTime`, `filterBySince`, `filterByLevel`, `filterBySearch`, `matchesLevel`, `matchesSearch`) for reuse.
7+
8+
The log watch buffers `logs_watch_start` defaults to `last_entries: 0` (capture only new entries, matching the "start before triggering" workflow), bounds the entry buffer by bytes as well as count, reports each discovered file only once per poll, stops the underlying tail if a concurrent-start hostname race loses registration, and makes `logs_watch_stop` truly idempotent.

‎docs/.vitepress/config.mts‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -174,7 +174,15 @@ const referenceSidebar = [
174174
{
175175
text: 'Diagnostics',
176176
collapsed: true,
177-
items: [{text: 'Script Debugger', link: '/mcp/tools/diagnostics'}],
177+
items: [
178+
{text: 'Script Debugger', link: '/mcp/tools/diagnostics'},
179+
{text: 'Logs', link: '/mcp/tools/logs'},
180+
],
181+
},
182+
{
183+
text: 'Documentation',
184+
collapsed: true,
185+
items: [{text: 'Script API & Schemas', link: '/mcp/tools/docs'}],
178186
},
179187
],
180188
},

‎docs/mcp/tools/docs.md‎

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
---
2+
description: MCP tools for searching B2C Commerce Script API and XSD schema documentation.
3+
---
4+
5+
# Documentation Tools
6+
7+
MCP tools for searching and reading the bundled B2C Commerce Script API documentation and XSD schemas. These tools read data shipped with the SDK — they do **not** require any instance configuration or authentication. Available in **every toolset**.
8+
9+
## When to use which tool
10+
11+
- Look up a class or module — search first to confirm the id, then read.
12+
- `docs_search` (fuzzy) → `docs_read` (full markdown).
13+
- Look up an XSD schema for an import file (e.g., `system-objecttype-extensions.xml`) — same pattern.
14+
- `docs_schema_search` → `docs_schema_read`.
15+
- Browse all available entries — `docs_list` / `docs_schema_list`.
16+
17+
> **Note:** `docs_read` and `docs_schema_read` content can be large (full markdown files / full XSD bodies). Prefer `docs_search`/`docs_schema_search` to narrow down before reading.
18+
19+
---
20+
21+
## Script API
22+
23+
### docs_search
24+
25+
Fuzzy-search Script API documentation by class, module, or partial name.
26+
27+
| Parameter | Type | Required | Default | Description |
28+
|-----------|------|----------|---------|-------------|
29+
| `query` | string | Yes | | Search query (e.g., `"ProductMgr"`, `"dw.catalog"`, `"Status"`) |
30+
| `limit` | number | No | `20` | Maximum number of results |
31+
32+
**Returns:** `{query, results: [{entry: {id, title, filePath, preview?}, score}]}`. Lower `score` = better match.
33+
34+
### docs_read
35+
36+
Read full markdown documentation for a Script API class or module.
37+
38+
| Parameter | Type | Required | Description |
39+
|-----------|------|----------|-------------|
40+
| `query` | string | Yes | Exact id (e.g., `"dw.catalog.ProductMgr"`) or fuzzy query |
41+
42+
**Returns:** `{entry: {id, title, filePath, preview?}, content: string}`. Returns an error result with a hint to use `docs_search` if no match is found.
43+
44+
### docs_list
45+
46+
List every available Script API documentation entry.
47+
48+
No parameters.
49+
50+
**Returns:** `{count, entries: [{id, title, filePath, preview?}]}`. Output is large; prefer `docs_search` for targeted lookups.
51+
52+
---
53+
54+
## XSD Schemas
55+
56+
### docs_schema_search
57+
58+
Fuzzy-search XSD schema ids.
59+
60+
| Parameter | Type | Required | Default | Description |
61+
|-----------|------|----------|---------|-------------|
62+
| `query` | string | Yes | | Schema name or partial match (e.g., `"catalog"`, `"order"`) |
63+
| `limit` | number | No | `20` | Maximum number of results |
64+
65+
**Returns:** `{query, results: [{entry: {id, filePath}, score}]}`.
66+
67+
### docs_schema_read
68+
69+
Read the contents of an XSD schema (raw XML) plus the on-disk path.
70+
71+
| Parameter | Type | Required | Description |
72+
|-----------|------|----------|-------------|
73+
| `query` | string | Yes | Exact id or fuzzy query |
74+
75+
**Returns:** `{entry: {id, filePath}, content: string, path: string}`. Returns an error result with a hint to use `docs_schema_search` if no match.
76+
77+
### docs_schema_list
78+
79+
List every available XSD schema id.
80+
81+
No parameters.
82+
83+
**Returns:** `{count, entries: [{id, filePath}]}`.
84+
85+
---
86+
87+
## See also
88+
89+
- [Docs CLI commands](/cli/docs) — `b2c docs search` / `read` / `schema`

‎docs/mcp/tools/logs.md‎

Lines changed: 127 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,127 @@
1+
---
2+
description: MCP tools for fetching and tailing logs on B2C Commerce instances.
3+
---
4+
5+
# Log Tools
6+
7+
MCP tools for inspecting runtime logs on a B2C Commerce instance via WebDAV. Use them to investigate errors after triggering a request, monitor a job run, or audit recent failures. Available in the **CARTRIDGES**, **DIAGNOSTICS**, and **SCAPI** toolsets.
8+
9+
## Authentication
10+
11+
All log tools that read from the instance (`logs_list_files`, `logs_get_recent`, `logs_watch_start`) require WebDAV-capable credentials.
12+
13+
**Required:**
14+
- **Basic Auth** preferred: `hostname`, `username`, and `password` (WebDAV access key) for a Business Manager user with WebDAV log read permission.
15+
- OAuth (client-credentials / implicit) is also supported as a fallback for WebDAV.
16+
17+
**Configuration priority:** Flags → Environment variables → `dw.json` config file
18+
19+
`logs_watch_poll`, `logs_watch_stop`, and `logs_watch_list` operate on server-side state only and do not require fresh credentials per call.
20+
21+
See [Configuration](../configuration) for credential setup.
22+
23+
## When to use which tool
24+
25+
- Quick lookup of recent errors → **`logs_get_recent`**.
26+
- Discover what log prefixes are active on the instance → **`logs_list_files`**.
27+
- Monitor logs across a multi-step action you trigger (storefront request, job, debug session) → start a watch with **`logs_watch_start`**, then drain it with **`logs_watch_poll`**, and finish with **`logs_watch_stop`**. The watch buffers entries between calls so nothing is lost between agent turns.
28+
29+
## Recovery from orphaned watches
30+
31+
Log watches are stateful and live in the MCP server process. Only one watch is allowed per hostname. If an agent loses track of an active watch:
32+
33+
1. **List active watches** — call `logs_watch_list` (no args). It returns all watches with their `watch_id`, `hostname`, `prefixes`, and buffered counts.
34+
2. **Stop orphaned watches** — call `logs_watch_stop` with the `watch_id` to release the underlying tail.
35+
3. **Idle cleanup** — watches inactive for 30 minutes are automatically destroyed.
36+
4. **Restart the MCP server** — last resort; destroys all watch state.
37+
38+
---
39+
40+
## One-shot tools
41+
42+
### logs_list_files
43+
44+
List log files on the instance via WebDAV.
45+
46+
| Parameter | Type | Required | Default | Description |
47+
|-----------|------|----------|---------|-------------|
48+
| `prefixes` | string[] | No | all | Filter by log prefix (e.g., `["error", "customerror"]`) |
49+
| `sort_by` | `"date" \| "name" \| "size"` | No | `date` | Sort field |
50+
| `sort_order` | `"asc" \| "desc"` | No | `desc` | Sort order |
51+
52+
**Returns:** `{count, files: [{name, prefix, size, lastModified, path}]}`.
53+
54+
### logs_get_recent
55+
56+
Fetch recent log entries in a single request/response. Filters (`since`, `level`, `search`) are applied client-side after fetching.
57+
58+
| Parameter | Type | Required | Default | Description |
59+
|-----------|------|----------|---------|-------------|
60+
| `prefixes` | string[] | No | `["error", "customerror"]` | Log prefixes to read |
61+
| `count` | number | No | `50` | Maximum entries to return |
62+
| `since` | string | No | | Relative time (`"5m"`, `"1h"`, `"2d"`) or ISO 8601 |
63+
| `level` | string[] | No | | Filter by level (ERROR, WARN, INFO, DEBUG, FATAL, TRACE) |
64+
| `search` | string | No | | Case-insensitive substring filter |
65+
66+
**Returns:** `{count, entries: [{file, level, timestamp, message, raw}]}`.
67+
68+
---
69+
70+
## Watch lifecycle
71+
72+
### logs_watch_start
73+
74+
Start a background log watch. Returns a `watch_id` immediately. Buffers entries in memory until `logs_watch_poll` drains them.
75+
76+
> **Workflow:** call `logs_watch_start` **before** triggering the action that should produce logs. Otherwise startup may emit only existing entries (controlled by `last_entries`) and miss what you wanted to capture.
77+
78+
| Parameter | Type | Required | Default | Description |
79+
|-----------|------|----------|---------|-------------|
80+
| `prefixes` | string[] | No | `["error", "customerror"]` | Log prefixes to watch |
81+
| `last_entries` | number | No | `0` | Pre-existing entries per file to emit on startup. `0` (default) captures only new entries; set >0 for recent context. |
82+
| `poll_interval_ms` | number | No | `3000` | How often the underlying tail polls WebDAV |
83+
| `level` | string[] | No | | Drop entries not matching level before buffering |
84+
| `search` | string | No | | Drop entries not matching substring before buffering |
85+
86+
**Returns:** `{watch_id, hostname, prefixes, started_at}`.
87+
88+
### logs_watch_poll
89+
90+
Drain buffered entries. If the buffer is empty, blocks up to `timeout_ms` waiting for new entries.
91+
92+
| Parameter | Type | Required | Default | Description |
93+
|-----------|------|----------|---------|-------------|
94+
| `watch_id` | string | Yes | | Watch id from `logs_watch_start` |
95+
| `timeout_ms` | number | No | `5000` | Max time to block when buffer is empty. `0` returns immediately. |
96+
| `max_entries` | number | No | `200` | Maximum entries returned per call |
97+
98+
**Returns:** `{watch_id, entries, files_discovered, files_rotated, errors, truncated, buffered_remaining, dropped_entries, stopped}`. When `truncated` is `true`, call again to drain the rest.
99+
100+
- `entries`: `[{file, level, timestamp, message, raw}]` — buffered since the last poll.
101+
- `files_discovered` / `files_rotated`: `[{name, prefix, size, lastModified, path}]` — each file is reported once, on the poll after it is discovered/rotated.
102+
- `errors`: `[{message, at}]` where `at` is an ISO 8601 timestamp of when the tail error occurred.
103+
- `dropped_entries`: count of entries evicted (buffer cap) since the last poll; resets to `0` after each poll.
104+
105+
### logs_watch_stop
106+
107+
Stop a watch and release its underlying tail.
108+
109+
| Parameter | Type | Required | Description |
110+
|-----------|------|----------|-------------|
111+
| `watch_id` | string | Yes | Watch id from `logs_watch_start` |
112+
113+
**Returns:** `{watch_id, stopped_at, total_entries_seen}`.
114+
115+
### logs_watch_list
116+
117+
List active watches. Use to recover orphaned watches or inspect buffered counts.
118+
119+
No parameters.
120+
121+
**Returns:** `{watches: [{watch_id, hostname, prefixes, buffered_entries, total_entries_seen, dropped_entries, files_discovered, stopped, created_at, last_activity_at}]}`.
122+
123+
---
124+
125+
## See also
126+
127+
- [Logs CLI commands](/cli/logs) — `b2c logs tail` / `get` / `list`

‎docs/mcp/toolsets.md‎

Lines changed: 37 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,10 @@
11
---
2-
description: Available toolsets and tools in the B2C DX MCP Server for SCAPI, CARTRIDGES, MRT, PWAV3, and STOREFRONTNEXT development.
2+
description: Available toolsets and tools in the B2C DX MCP Server for SCAPI, CARTRIDGES, DIAGNOSTICS, MRT, PWAV3, and STOREFRONTNEXT development.
33
---
44

55
# Toolsets & Tools
66

7-
The B2C DX MCP Server provides five toolsets with specialized tools for different B2C Commerce development workflows.
7+
The B2C DX MCP Server provides six toolsets with specialized tools for different B2C Commerce development workflows.
88

99

1010
## Overview
@@ -13,12 +13,13 @@ Toolsets are collections of related tools that work together to support specific
1313

1414
**Available toolsets:**
1515
- [CARTRIDGES](#cartridges) - Cartridge deployment and code version management
16+
- [DIAGNOSTICS](#diagnostics) - Script debugger, log inspection, and bundled documentation
1617
- [MRT](#mrt) - Managed Runtime bundle operations
1718
- [PWAV3](#pwav3) - PWA Kit v3 development tools
1819
- [SCAPI](#scapi) - Salesforce Commerce API discovery
1920
- [STOREFRONTNEXT](#storefrontnext) - Storefront Next development tools
2021

21-
**Note:** With auto-discovery, the `SCAPI` toolset is always included. When using `--toolsets` or `--tools`, only the specified toolsets/tools are enabled.
22+
**Note:** With auto-discovery, the `SCAPI` and `DIAGNOSTICS` toolsets are always included. When using `--toolsets` or `--tools`, only the specified toolsets/tools are enabled.
2223

2324
## CARTRIDGES
2425

@@ -34,6 +35,39 @@ Cartridge development, deployment, and code version management.
3435
|------|-------------|---------------|
3536
| [`cartridge_deploy`](./tools/cartridge-deploy) | Deploy cartridges to a B2C Commerce instance | [View details](./tools/cartridge-deploy) |
3637

38+
## DIAGNOSTICS
39+
40+
Script debugger, runtime log inspection, and bundled Script API / XSD documentation lookup.
41+
42+
**Status:** ✅ Generally Available
43+
44+
**Always enabled** - Base toolset available for all projects. The log and debugger tools also appear in `CARTRIDGES` and `SCAPI`; the documentation tools appear in every toolset.
45+
46+
### Script Debugger
47+
48+
| Tool | Description | Documentation |
49+
|------|-------------|---------------|
50+
| `debug_start_session` / `debug_end_session` / `debug_list_sessions` | Manage SDAPI debugger sessions | [View details](./tools/diagnostics) |
51+
| `debug_set_breakpoints` | Set breakpoints in cartridge scripts | [View details](./tools/diagnostics) |
52+
| `debug_wait_for_stop` / `debug_continue` / `debug_step_into` / `debug_step_over` / `debug_step_out` | Control execution flow | [View details](./tools/diagnostics) |
53+
| `debug_get_stack` / `debug_get_variables` / `debug_evaluate` | Inspect stack frames, variables, and evaluate expressions | [View details](./tools/diagnostics) |
54+
| `debug_capture_at_breakpoint` | One-shot capture of stack + variables at a breakpoint | [View details](./tools/diagnostics) |
55+
56+
### Logs
57+
58+
| Tool | Description | Documentation |
59+
|------|-------------|---------------|
60+
| `logs_list_files` | List log files on the instance via WebDAV | [View details](./tools/logs) |
61+
| `logs_get_recent` | Fetch recent log entries in a single request | [View details](./tools/logs) |
62+
| `logs_watch_start` / `logs_watch_poll` / `logs_watch_stop` / `logs_watch_list` | Buffered log watch lifecycle so entries aren't missed between calls | [View details](./tools/logs) |
63+
64+
### Documentation
65+
66+
| Tool | Description | Documentation |
67+
|------|-------------|---------------|
68+
| `docs_search` / `docs_read` / `docs_list` | Search and read bundled Script API documentation | [View details](./tools/docs) |
69+
| `docs_schema_search` / `docs_schema_read` / `docs_schema_list` | Search and read bundled XSD schemas | [View details](./tools/docs) |
70+
3771
## MRT
3872

3973
Managed Runtime operations for PWA Kit and Storefront Next deployments.

0 commit comments

Comments
 (0)