Design a better DTD discovery mechanism

[kenzieschmoll]

Right now, we have a tool that asks the user to grab the DTD URI and instructs them as to how, but this is something we should be able to streamline further since the information is available from the host IDE. This is a tracking issue to explore options and try to design a better solution that provides a better UX.

[jakemac53]

One proposal I suggested offline is that the IDE extensions could provide MCP servers themselves, which would provide a tool getDtdUri. This would allow the LLM to get the DTD URI from that server, and pass it to tools from the dart server.

The downside being it requires an extra MCP server to configure, but potentially the plugins actually will want to expose more functionality as well.

[jakemac53]

cc @DanTup

[DanTup]

I just added a note about this at Dart-Code/Dart-Code#5551 (comment)

The downside being it requires an extra MCP server to configure

The VS Code API allows us to directly expose a tool from the extension without the need of a server. So we can provide a getDtdUri(?) tool that returns this with little effort.

[jakemac53]

The VS Code API allows us to directly expose a tool from the extension without the need of a server. So we can provide a getDtdUri(?) tool that returns this with little effort.

Great 👍. I will follow up here with a high level design (not IDE specific) and the reasoning for why I think we should do it this way and not other ways. Although ultimately the design will be flexible, because it's really just going to be "whoever owns DTD should somehow expose the DTD uri to the LLM or on the command line to the MCP server". With some specific guidelines on how best to do that.

[jakemac53]

Background

The Dart MCP server requires a DTD connection to connect to any actively running Dart or Flutter applications.

Meanwhile, the Dart/Flutter IDEs plugins typically own starting the DTD service instance, but do not have a direct link to the Dart MCP server (these are configured separately, and the client owns starting the server).

Today, we require the user to manually copy the DTD URI from their IDE (in VsCode, you use the "Copy DTD URI to clipboard" command pallette action), and paste that into the chat where they have the dart MCP server connected.

This proposal outlines some best practices for how these IDE plugins, or any other tool which owns a DTD service, can get the DTD URI plumbed through to the Dart MCP Server in a frictionless manner for the end user.

Solutions

Option 1: Expose the URI via an MCP tool or resource

Especially in an environment where IDE Plugins can register their own MCP servers automatically, this is a good option. MCP servers work well together, and MCP clients can easily call one tool to get information to plug into a different tool, even if they are from different servers.

This is also a nicely layered approach - this additional tool (or resource) simply improves the experience, but even without it the MCP server is still usable (although it requires the user to pass the URI manually). So, we can incrementally add in this functionality wherever it would help, but nothing is required to supply it.

The name of the tool and Uri of the resource do not particularly matter, which is another benefit of this approach. They just need to be sufficiently descriptive so that the LLM can understand what they are, for example a tool could be called getDtdUri. It should just return a string representing the URI to use to connect to DTD.

When to use a resource instead of a tool

Resources have one major advantage, which is that they can notify the client of changes. So, if the DTD URI were to change at some point (if it is restarted for some reason), then the server could notify the client that it has changed, prompting it to get the new URI.

This situation is recoverable anyways in the tool case, but requires the LLM to see the DTD connection has failed as the result of a failed tool call, and then it has to ask again for the URI, so this can avoid a few round trips and limit token usage.

Unfortunately, resources do not have very broad support right now so it is probably better to stick with the tools today, which have very broad support.

Option 2: Provide the DTD Uri directly in the context

When the same code is in charge of managing the context for the LLM, as well as starting up DTD, it can simply provide this URI in the context. A simple message like "The DTD Uri is " is typically sufficient.

This approach is useful if developing an agent which is very specific to Dart or Flutter tasks, so the agent itself has the dart MCP server (and knowledge of its requirements) hard coded.

Option 3: Pass the DTD Uri on the command line (would require MCP server work)

In an environment where the DTD is static for an entire session - the MCP server could support a --dtd-uri <uri> command line option, although it does not today.

When provided, we would likely want to alter the tool schemas and descriptions to not accept a DTD uri at all.

Alternatively, the server itself could expose a tool to get the DTD Uri but not alter its tool descriptions. This might be easier to implement but would be a bit awkward.

Conclusion

The best approach here depends somewhat on the specific situation at hand, and the server is best left agnostic as to how this URI should be provided, although we may want to support a command line flag or environment variable.

Ultimately it could come from a user, another MCP server, an injected prompt, or possibly a command line flag or environment variable. The magic of LLMs and MCP is that it doesn't really matter how it gets injected, just that something exposes a DTD Uri to the LLM.

[jakemac53]

We could put something like the above into the README.md for the dart MCP server itself?

[DanTup]

The name of the tool and Uri of the resource do not particularly matter, which is another benefit of this approach.

It might be worth suggesting something here (for name/description) for consistency across editor plugins (for example we might want to ensure they contain both "DTD" and "Dart Tooling Daemon" to cover queries that use either).

When to use a resource instead of a tool

On https://modelcontextprotocol.io/docs/concepts/resources it says:

Resources are designed to be application-controlled, meaning that the client application can decide how and when they should be used
[...]
Claude Desktop currently requires users to explicitly select resources before they can be used
[...]
In order to expose data to models automatically, server authors should use a model-controlled primitive such as Tools.

I'm not entirely sure which this falls under, but my feeling is that this is "model controlled" since it's the model that will decide it needs this (to provide to the MCP server) and not the application?

We could put something like the above into the README.md for the dart MCP server itself?

Seems reasonable to me (although it's only worth including option 3 if it'll be supported by the server).

[jakemac53]

In order to expose data to models automatically, server authors should use a model-controlled primitive such as Tools.

Interesting, I hadn't seen this clarification before. It does make sense in a way because models only support function invocations, but my previous assumption is the clients would just support a read_resource tool or something.

[lukemmtt]

Worth noting, I've found a bash command that reliably returns the DTD URI:

ps aux | grep "dtd-uri " | grep -o 'ws://[^[:space:]]*' | head -1

How it works:

1. ps aux
   • Lists all running processes
2. grep "dtd-uri "
   • Filters for processes with "dtd-uri " (note the space " " after, which catches the --dtd-uri ws://... format which seems to be used by newer Flutter versions, as opposed to the "--dtd-uri=ws://" format with a "=" after the dtd-uri which seems to be associated with some unrelated process—maybe dev tools or an older instance of flutter or something).
3. grep -o 'ws://[^[:space:]]*'
   • Extracts just the WebSocket URL
4. head -1
   • Takes the first match (just to ensure that a valid URI is returned, rather than a set of URIs in some edge case—although for me there is only one result for this filter to begin with).

I've confirmed that the URI returned by this command, at least in my environment, is indeed the same one returned by the VS Code >Dart: Copy DTD URI to Clipboard command, and thus it works great for letting Claude Code (or similar) retrieve the DTD URI on its own and invoke DTD-dependent commands via the dart mcp server.

[jakemac53]

Interesting, we could possibly make the URI optional for the connect function, and then if we find exactly one match like this just assume it is correct. With multiple matches we could return an error listing the options, or if the client supports it we could use elicitation to ask the user which one to select.

[jakemac53]

Note that Dart/Flutter have a lot of windows users so we would probably want a solution there too, but we could make the parameter optional only on Linux for now.

[DanTup]

This feels kinda hacky to me 🙃

If the current solution isn't enough, perhaps we can get the IDE plugins to call the connect_dart_tooling_daemon tool directly after starting DTD and any time it is restarted?

VS Code has an lm.invokeTool API. It doesn't seem like there's an event when these tools change for some reason, but we could poll for now and open a VS Code request for an event.

I'm not sure about IntelliJ though.

[DanTup]

Oops, I didn't read the above comments properly.. this won't help with other clients like Claude Code if they are starting their own MCP servers 😞