debug-mcp

name	debug-mcp
description	Use when the gdevelop-mcp server misbehaves — tools missing, prompts not exposed, JSON-RPC errors, or unexpected responses.

Debugging the MCP server

Symptoms → likely causes

Symptom	Likely cause
Tool not visible in client	Server didn't restart, or stale dist/. Run npm run build and restart the client.
Tools list works but a call returns nothing	Handler threw without try/catch. Check it returns textResult or errorResult.
Random "unexpected token" parse errors on client side	A 3rd-party package wrote to stdout. Move its invocation to a subprocess with piped stdio.
EADDRINUSE on preview	Static server didn't release the port. Restart the MCP.
Could not locate GDevelop install	Set GDEVELOP_PATH=/path/to/GDevelop\ 5.app.
Typecheck fails after a refactor	Stale dist/ causing self-imports. rm -rf dist && npm run build.

Smoke-test the server end-to-end

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"1"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized","params":{}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
  | node dist/index.js

You should see one JSON-RPC response per request, all parseable. If any line is not valid JSON, something is polluting stdout — find the console.log or move the offender to a subprocess.

MCP Inspector

For an interactive UI:

npm run inspect

Opens a local web UI where you can call each tool manually and inspect the exact JSON request/response.

Logging without polluting stdout

console.error(...) writes to stderr, which the MCP transport ignores. Safe for ad-hoc debugging — but remove or guard before committing.

Common stdio mistakes

• A library calls console.info/console.log/console.warn — these all go to stdout. Either patch console.* for the duration of the call OR (preferred) spawn the library in a child process.
• A library writes raw to process.stdout.write — same fix.
• An async callback fires after a tool returns and logs something — hardest to spot. Always await everything before returning from a handler.

Common test failures

• "ERR_MODULE_NOT_FOUND" for a .js import → ESM resolution. The build produces .js from .ts, but vitest works directly on .ts via vite-node. Use .js extensions in imports; vitest handles the rest.
• Filesystem races between tests → ensure each test uses its own mkdtempSync dir.