Skip to content

Commit 0ba4959

Browse files
arthurgoussetarthurgousset
authored
Merge pull request #2 from hyperdrive-eng/arthurgousset/docs/get-started-readme
docs(README): add get started, example, and usage instructions
2 parents 1615fe4 + 14fee8f commit 0ba4959

File tree

1 file changed

+166
-1
lines changed

1 file changed

+166
-1
lines changed

‎README.md

Lines changed: 166 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,168 @@
11
# MCP Debugger
22

3-
An MCP server to give LLMs access to runtime debugging tools.
3+
An MCP server that gives Claude Code access to NodeJS at runtime to help you debug: [`mcp-nodejs-debugger`](https://www.npmjs.com/package/mcp-nodejs-debugger).
4+
5+
## Get started
6+
7+
1. Add to Claude Code:
8+
9+
```sh
10+
$ claude mcp add nodejs-debugger npx mcp-nodejs-debugger
11+
```
12+
13+
1. Start Claude Code
14+
15+
```sh
16+
claude
17+
╭────────────────────────────────────────────────────────────────────────────────╮
18+
│ ✻ Welcome to Claude Code research preview! │
19+
│ │
20+
│ /help for help │
21+
│ │
22+
│ Found 1 MCP server (use /mcp for status) │
23+
╰────────────────────────────────────────────────────────────────────────────────╯
24+
```
25+
26+
2. Run a NodeJS server in [debug mode](https://nodejs.org/en/learn/getting-started/debugging) (i.e. with the `--inspect` flat)
27+
28+
```sh
29+
# In another terminal
30+
$ node --inspect {your_file.js}
31+
```
32+
33+
3. Ask Claude Code to debug your NodeJS server at runtime
34+
35+
```sh
36+
> I'm getting a runtime error in NodeJS.
37+
38+
{YOUR_RUNTIME_ERROR}
39+
40+
Please help me debug this error at runtime using the nodejs-debugger mcp.
41+
```
42+
43+
## Example
44+
45+
1. Here is a buggy NodeJS server:
46+
47+
```
48+
$ node --inspect index.js
49+
50+
Debugger listening on ws://127.0.0.1:9229/2862f5a2-8618-4516-8429-1248b397e9b4
51+
52+
#######################
53+
## THE RUNTIME ERROR ##
54+
#######################
55+
MongooseServerSelectionError: Could not connect to any servers in your MongoDB Atlas cluster. One common reason is that you're trying to access the database from an IP that isn't whitelisted. Make sure your current IP address is on your Atlas cluster's IP whitelist: https://www.mongodb.com/docs/atlas/security-whitelist/
56+
at _handleConnectionErrors (/Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/node_modules/mongoose/lib/connection.js:1110:11)
57+
at NativeConnection.openUri (/Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/node_modules/mongoose/lib/connection.js:1041:11)
58+
at async main (/Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/app.js:35:3) {
59+
reason: TopologyDescription {
60+
type: 'ReplicaSetNoPrimary',
61+
servers: Map(3) {
62+
'ac-8e6hgk7-shard-00-01.cojoign.mongodb.net:27017' => [ServerDescription],
63+
'ac-8e6hgk7-shard-00-02.cojoign.mongodb.net:27017' => [ServerDescription],
64+
'ac-8e6hgk7-shard-00-00.cojoign.mongodb.net:27017' => [ServerDescription]
65+
},
66+
stale: false,
67+
compatible: true,
68+
heartbeatFrequencyMS: 10000,
69+
localThresholdMS: 15,
70+
setName: 'atlas-5syy8t-shard-0',
71+
maxElectionId: null,
72+
maxSetVersion: null,
73+
commonWireVersion: 0,
74+
logicalSessionTimeoutMinutes: null
75+
},
76+
code: undefined
77+
}
78+
```
79+
80+
1. Claude Code debugs the NodeJS server at runtime:
81+
82+
```sh
83+
> I'm getting a runtime error connecting to mongoose. Please help me debug by checking the value of
84+
the mongodb configs at runtime using the nodejs-debugger mcp.
85+
86+
⏺ I'll help you debug the mongoose connection issue using the Node.js debugger. Let's first understand where the
87+
MongoDB connection is configured.
88+
89+
⏺ Search(pattern: "**/*.js")…
90+
⎿  Found 100 files
91+
92+
⏺ Let's set a breakpoint at the mongoose connection point and continue:
93+
94+
⏺ nodejs-debugger:set_breakpoint (MCP)(file: …
95+
"/Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/app.js",
96+
line: 35)
97+
  ⎿  Breakpoint set successfully. ID:
98+
2:34:0:file:///Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/app\.js
99+
100+
⏺ Let's list all our breakpoints:
101+
102+
⏺ nodejs-debugger:list_breakpoints (MCP)
103+
  ⎿  [
104+
{
105+
"file": "/Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/app.js",
106+
"line": 35,
107+
"id": "2:34:0:file:///Users/arthur/Documents/thirdparties/mdn/express-locallibrary-tutorial/app\\.js"
108+
}
109+
]
110+
111+
⏺ Let's try to execute a specific piece of code to check the connection variables:
112+
113+
⏺ nodejs-debugger:nodejs_inspect (MCP)(js_code: "// Get the mongoose module and inspect connection\nconst mongoose = …
114+
require('mongoose');\nconsole.log('Current mongoose version:',
115+
mongoose.version);\nconsole.log('Current mongoose connection state:',
116+
mongoose.connection.readyState);\n// Log connection string safely (without
117+
password)\nconst connectionString = process.env.MONGODB_URI || \n
118+
\"mongodb+srv://cooluser:[email protected]/local_library?retryWr
119+
ites=true&w=majority&appName=Cluster0\";\nconsole.log('Connection string
120+
(masked):', connectionString.replace(/(?<=mongodb\\+srv:\\/\\/\\w+:)(.+?)(?=@)/,
121+
'*****'));")
122+
123+
  ⎿  Console output:
124+
[log] Current mongoose version: 8.9.5
125+
[log] Current mongoose connection state: 0
126+
[log] Connection string (masked): mongodb+srv://cooluser:[email protected]/local_library?retryWri
127+
tes=true&w=majority&appName=Cluster0
128+
129+
⏺ The runtime error you're seeing in your application is related to MongoDB
130+
Atlas connection issues. Based on your error message, the problem is:
131+
132+
1. You're using placeholder credentials ("cooluser:coolpassword")
133+
134+
To fix this, you have two options:
135+
136+
1. Use a local MongoDB instance by changing line 29-30 in app.js to:
137+
const dev_db_url = "mongodb://127.0.0.1:27017/local_library";
138+
2. Or correctly set up MongoDB Atlas:
139+
- Log into Atlas at https://cloud.mongodb.com
140+
- Go to Network Access and add your current IP to whitelist
141+
- Create proper database credentials
142+
- Update the connection string with real credentials
143+
144+
Which option would you like to proceed with?
145+
```
146+
147+
## Usage
148+
149+
1. Add to Claude Code:
150+
151+
```sh
152+
claude mcp add nodejs-debugger npx mcp-nodejs-debugger
153+
```
154+
155+
1. Verify connection
156+
157+
```sh
158+
> /mcp
159+
⎿ MCP Server Status
160+
161+
• nodejs-debugger: connected
162+
```
163+
164+
1. Remove from Claude Code:
165+
166+
```sh
167+
claude remove nodejs-debugger
168+
```

0 commit comments

Comments
 (0)