Building an MCP Client - Part 3: Debug

5 months ago

In the previous article, we built a simple MCP client, but the codebase has become larger and more complex. To help readers understand, the simplest way to grasp the program is to observe the data flow being processed inside it, see what's happening at a specific point, and why it needs to be called... In short, it’s about setting up debugging.

Usually, when using a framework to develop an application, the framework often integrates debugging instructions, so you just need to read the documentation and follow the guide. However, for the series of examples on building an MCP server for 2coffee.dev, developed from scratch using TypeScript without using any available frameworks, there is no built-in debugging. Therefore, this guide is for readers to set up debugging in the VSCode code editor.

First, understand the rules for setting up debugging. In fact, there are many ways, such as setting up debugging in an executable file (.js, .ts) or using a debug flag in a more complex program. Most of the source code in the example only needs to run a single file like build/client.js, so it’s simple to just set up debugging for that file.

However, the project is written in TypeScript, and when debugging, you always want to set breakpoints on the source file (.ts) instead of the built file (.js) because the source file is clean, easier to observe, and modify. To achieve this, the principle here is to always include sourceMaps when building from TypeScript to JavaScript so that the tool can map the running code from the .js file to the .ts file.

Open .vscode/launch.json and add a configuration named "Debug Client".

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug Client",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/build/client.js",
      "preLaunchTask": "npm: build",
      "sourceMaps": true,
      "console": "integratedTerminal"
    }
  ]
}

program points to the file to be executed. Some might wonder why it doesn’t point to client.ts. That’s because we are using Node.js to run, and Node.js doesn’t natively support TypeScript yet. preLaunchTask is used to run the npm run build command before accessing the executable file. sourceMaps is enabled to map from .js to .ts, and console is used for receiving data from the Terminal (since the readline module is used).

But before that, you need to configure sourceMaps in tsconfig.json.

{
  "compilerOptions": {
      ...
      "sourceMap": true,
      ...
  }
}

That's it! Now open the src/client.ts file and set a breakpoint at a point you want to observe. Then select Run > Start Debugging or press F5 to start the debugging process.

Result