MCP Debugging

Why black-box MCP checks matter

Unit tests on helper functions are necessary, but they are not sufficient for MCP servers. A tool can be:

defined in the source tree,
validated correctly in isolation,
even listed by tools/list,

…and still fail when a real MCP client calls it through the server entrypoint.

This repository has direct coverage for workspace helpers in src/tests/tools/workspace-tools.test.ts, but the safer guardrail is an end-to-end client check that exercises the same path used by Copilot, Claude Desktop, or any other MCP host.

Preferred workflow: MCP Inspector CLI

The fastest contributor workflow is the official Inspector CLI — it avoids custom JSON-RPC framing and uses the real MCP client path.

Quick check: list all tools

npm run build
npx -y @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list

Call an instruction tool

npx -y @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call \
  --tool-name document \
  --tool-arg 'request="Document this pseudocode in short markdown."'

Call a workspace helper tool

npx -y @modelcontextprotocol/inspector --cli node dist/index.js \
  --method tools/call \
  --tool-name workspace-read \
  --tool-arg 'scope="source"' \
  --tool-arg 'path="README.md"'

Repository smoke tests

These commands are intended for repeatable verification during development and CI:

npm run test:mcp:ts
npm run test:mcp:py:inspector
npm run test:mcp:smoke:inspector

Command	Purpose
`npm run test:mcp:ts`	Fast unit-level coverage for workspace tools and mock MCP envelopes
`npm run test:mcp:py:inspector`	Black-box smoke test via the official Inspector CLI
`npm run test:mcp:smoke:inspector`	Combined local regression pass

Interpreting failures

Symptom	Likely cause
Tool missing from `tools/list`	Registration or build-generation issue
Tool is listed but `tools/call` returns `Unknown instruction tool`	Routing/dispatch mismatch
Validation error — missing required field	Schema or argument-shape mismatch
Initialize or call timeout	Startup, transport, or long-running tool behavior

Workspace tool naming

tools/list advertises the namespaced workspace surface:

workspace-list
workspace-read
workspace-artifact
workspace-fetch
workspace-compare

The server also accepts legacy bare aliases (list, read, artifact, fetch, compare) as a compatibility path, but new tests and manual checks should prefer the namespaced public names so tools/list and tools/call stay aligned.

Inspector safety notes

The Inspector proxy can spawn local processes.