mcp-log-debugging

---
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.