[lldb] Document MCP tools & resources

[JDevlieghere]

Add documentation for the tools and resources exposed by LLDB's MCP server.

[llvmbot]

@llvm/pr-subscribers-lldb

Author: Jonas Devlieghere (JDevlieghere)

Changes

Add documentation for the tools and resources exposed by LLDB's MCP server.

---

Full diff: https://github.com/llvm/llvm-project/pull/148708.diff

1 Files Affected:

• (modified) lldb/docs/use/mcp.md (+63-1)

diff --git a/lldb/docs/use/mcp.md b/lldb/docs/use/mcp.md
index 375c164fe771c..b7474246b54f3 100644
--- a/lldb/docs/use/mcp.md
+++ b/lldb/docs/use/mcp.md
@@ -75,7 +75,69 @@ Configuration example for [Visual Studio Code](https://code.visualstudio.com/doc
 }
 ```
 
-### Troubleshooting
+## Tools
+
+Tools are a primitive in the Model Context Protocol that enable servers to
+expose functionality to clients.
+
+LLDB's MCP integration exposes one tool, named `lldb_command` which allows the
+model to run the same commands a user would type in the LLDB command
+interpreter. It takes two arguments:
+
+1. The unique debugger ID as a number.
+2. The command and its arguments as a string.
+
+## Resources
+
+Resources are a primitive in the Model Context Protocol that allow servers to
+expose content that can be read by clients.
+
+LLDB's MCP integration exposes a resource for each debugger and target
+instance. Debugger resources are accessible using the following URI:
+
+```
+lldb://debugger/<debugger id>
+```
+
+Example output:
+
+```json
+{
+  "contents": [
+    {
+      "uri": "lldb://debugger/1",
+      "mimeType": "application/json",
+      "text": "{\"debugger_id\":1,\"name\":\"debugger_1\",\"num_targets\":1}"
+    }
+  ]
+}
+```
+
+Debuggers can contain one or more targets, which are accessible using the
+following URI:
+
+```
+lldb://debugger/<debugger id>/target/<target idx>
+```
+
+Example output:
+
+```json
+{
+  "contents": [
+    {
+      "uri": "lldb://debugger/1/target/0",
+      "mimeType": "application/json",
+      "text": "{\"arch\":\"arm64-apple-macosx26.0.0\",\"debugger_id\":1,\"dummy\":false,\"path\":\"/bin/count\",\"platform\":\"host\",\"selected\":true,\"target_idx\":0}"
+    }
+  ]
+}
+```
+
+Note that unlike the debugger id, which is unique, the target index is not
+stable and may be reused when a target is removed and a new target is added.
+
+## Troubleshooting
 
 The MCP server uses the `Host` log channel. You can enable logging with the
 `log enable` command.

[DavidSpickett]

Is this debugger ID mentioned elsewhere, where do you get this ID from?

[DavidSpickett]

Oh I see, you read the URI? But you need a debugger ID for that too. Hmm.

[JDevlieghere]

All the resources are listed, so you don't need to know it a priori. Depending on the implementation, the model either looks at the resources our you specify one to operate on.

[DavidSpickett]

The second bit is what I wondered about. Always annoying to be asked "which X do you want" without knowing how many X there are.

But if the model would present them to you, then that's fine.

[DavidSpickett]

In other words -
If I, the human, ever have to get the debugger ID myself, document how I can enumerate them.
If I, the human, don't have to do that, don't change anything.

[JDevlieghere]

It's the latter, you never specify the debugger ID. At most, you select a resource through the UI, and the model connects the dots behind the scenes that that debugger resource has a certain ID and passes it along here.

[DavidSpickett]

LGTM with whatever is the correct thing to document for debugger IDs.

[DavidSpickett]

Also, the server made it into 21.x but the docs obviously didn't and there's no release note for it. Is it complete "enough" to cherry-pick this and add a release note?

[JDevlieghere]

Also, the server made it into 21.x but the docs obviously didn't and there's no release note for it. Is it complete "enough" to cherry-pick this and add a release note?

I will add a release note and create a back port request. Do you think it's worth cherrypicking the documentation changes too? I would assume most users consult the website so I usually don't bother, but maybe that assumption isn't accurate.

[DavidSpickett]

This is unlikely to cause a conflict on the release branch so I'd include it anyway, it's easy to do.

But I agree people are more likely to read the website anyway.

[DavidSpickett]

Someone running lldb in a secure cluster might be glad to have the page in their install dir :)