Skip to content

Commit 2676dec

Browse files
kenzieschmollkenzieschmoll
authored
Add documentation for setting up the MCP server in popular clients (#201)
1 parent 6861301 commit 2676dec

File tree

4 files changed

+195
-95
lines changed

4 files changed

+195
-95
lines changed

‎pkgs/dart_mcp_server/CONTRIBUTING.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
## Development
2+
3+
For local development, use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).
4+
5+
1. Run the inspector with no arguments:
6+
```shell
7+
npx @modelcontextprotocol/inspector
8+
```
9+
10+
2. Open the MCP Inspector in the browser and enter `dart_mcp_server` in
11+
the "Command" field.
12+
13+
3. Click "Connect" to connect to the server and debug using the MCP Inspector.
14+
15+
## Testing your changes with an MCP client
16+
17+
### Running the server from source
18+
19+
The server entrypoint lives at `bin/main.dart`, and can be ran however you
20+
choose, but the easiest way is to run it as a globally activated package.
21+
22+
You can globally activate it from path for local development:
23+
24+
```sh
25+
dart pub global activate -s path .
26+
```
27+
28+
Or from git:
29+
30+
```sh
31+
dart pub global activate -s git https://github.com/dart-lang/ai.git \
32+
--git-path pkgs/dart_mcp_server/
33+
```
34+
35+
And then, assuming the pub cache bin dir is [on your PATH][set-up-path], the
36+
`dart_mcp_server` command will run it, and recompile as necessary.
37+
38+
[set-up-path]: https://dart.dev/tools/pub/cmd/pub-global#running-a-script-from-your-path
39+
40+
**Note:**: For some clients, depending on how they launch the MCP server and how
41+
tolerant they are, you may need to compile it to exe to avoid extra output on
42+
stdout:
43+
44+
```sh
45+
dart compile exe bin/main.dart
46+
```
47+
48+
And then provide the path to the executable instead of using the globally
49+
activated `dart_mcp_server` command.
50+
51+
### With the example WorkflowBot
52+
53+
After compiling the binary, you can run the example [workflow client][workflow_client]
54+
to interact with the server. Note that the workflow bot sets the current
55+
directory as the root directory, so if your server expects a certain root
56+
directory you will want to run the command below from there (and alter the
57+
paths as necessary). For example, you may want to run this command from the
58+
directory of the app you wish to test the server against.
59+
60+
[workflow_client]: https://github.com/dart-lang/ai/tree/main/mcp_examples/bin/workflow_client.dart
61+
62+
63+
```dart
64+
dart pub add "dart_mcp_examples:{git: {url: https://github.com/dart-lang/ai.git, path: mcp_examples}}"
65+
dart run dart_mcp_examples:workflow_client --server dart_mcp_server
66+
```
67+
68+
### With Cursor
69+
70+
Modify your `mcp.json` file to run your locally compiled server instead of using the
71+
server from the Dart SDK.
72+
73+
Each time you make changes to the server, you'll need to restart the server on
74+
the MCP configuration page or reload the Cursor window (**Developer: Reload Window**
75+
from the Command Palette) to see the changes.

‎pkgs/dart_mcp_server/README.md‎

Lines changed: 120 additions & 95 deletions
Original file line numberDiff line numberDiff line change
@@ -1,142 +1,167 @@
11
The Dart Tooling MCP Server exposes Dart and Flutter development tool actions to compatible AI-assistant clients.
22

3-
[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=dart_tooling&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoiZGFydCBtY3Atc2VydmVyIC0tZXhwZXJpbWVudGFsLW1jcC1zZXJ2ZXIgLS1mb3JjZS1yb290cy1mYWxsYmFjayJ9)
4-
53
## Status
64

75
WIP. This package is still experimental and is likely to evolve quickly.
86

9-
## Tools
7+
## Set up your MCP client
108

11-
| Tool Name | Feature Group | Description |
12-
| --- | --- | --- |
13-
| `analyze_files` | `static analysis` | Analyzes the entire project for errors. |
14-
| `signature_help` | `static_analysis` | Gets signature information for usage at a given cursor position. |
15-
| `hover` | `static_analysis` | Gets the hover information for a given cursor position. |
16-
| `resolve_workspace_symbol` | `static analysis` | Look up a symbol or symbols in all workspaces by name. |
17-
| `dart_fix` | `static tool` | Runs `dart fix --apply` for the given project roots. |
18-
| `dart_format` | `static tool` | Runs `dart format .` for the given project roots. |
19-
| `pub` | `static tool` | Runs a `dart pub` command for the given project roots. |
20-
| `pub_dev_search` | `package search` | Searches pub.dev for packages relevant to a given search query. |
21-
| `get_runtime_errors` | `runtime analysis` | Retrieves the list of runtime errors that have occurred in the active Dart or Flutter application. |
22-
| `take_screenshot` | `runtime analysis` | Takes a screenshot of the active Flutter application in its current state. |
23-
| `get_widget_tree` | `runtime analysis` | Retrieves the widget tree from the active Flutter application. |
24-
| `get_selected_widget` | `runtime analysis` | Retrieves the selected widget from the active Flutter application. |
25-
| `hot_reload` | `runtime tool` | Performs a hot reload of the active Flutter application. |
26-
| `connect_dart_tooling_daemon`* | `configuration` | Connects to the locally running Dart Tooling Daemon. |
27-
| `get_active_location` | `editor` | Gets the active cursor position in the connected editor (if available). |
28-
| `run_tests` | `static tool` | Runs tests for the given project roots. |
29-
| `create_project` | `static tool` | Creates a new Dart or Flutter project. |
30-
31-
> *Experimental: may be removed.
9+
<!-- Note: since many of our tools require access to the Dart Tooling Daemon, we may want
10+
to be cautious about recommending tools where access to the Dart Tooling Daemon does not exist. -->
3211

33-
## Usage
34-
35-
This server only supports the STDIO transport mechanism and runs locally on
36-
your machine. Many of the tools require that your MCP client has `roots`
37-
support, and usage of the tools is scoped to only these directories.
12+
The Dart MCP server can work with any MCP client that supports standard I/O (stdio) as the
13+
transport medium. To access all the features of the Dart MCP server, an MCP client must support
14+
[Tools](https://modelcontextprotocol.io/docs/concepts/tools) and
15+
[Resources](https://modelcontextprotocol.io/docs/concepts/resources). For the best development
16+
experience with the Dart MCP server, an MCP client should also support
17+
[Roots](https://modelcontextprotocol.io/docs/concepts/roots).
3818

3919
If you are using a client that claims it supports roots but does not actually
4020
set them, pass `--force-roots-fallback` which will instead enable tools for
4121
managing the roots.
4222

43-
### Running from the SDK
44-
45-
For most users, you should just use the `dart mcp-server` command. For now you
46-
also need to provide `--experimental-mcp-server` in order for the command to
47-
succeed.
23+
Here are specific instructions for some popular tools:
4824

49-
### Running a local checkout
25+
### Gemini CLI
5026

51-
The server entrypoint lives at `bin/main.dart`, and can be ran however you
52-
choose, but the easiest way is to run it as a globally activated package.
27+
To configure the [Gemini CLI](https://github.com/google-gemini/gemini-cli) to use the Dart MCP
28+
server, edit the `.gemini/settings.json` file in your local project (configuration will only
29+
apply to this project) or edit the global `~/.gemini/settings.json` file in your home directory
30+
(configuration will apply for all projects).
5331

54-
You can globally activate it from path for local development:
55-
56-
```sh
57-
dart pub global activate -s path .
58-
```
59-
60-
Or from git:
61-
62-
```sh
63-
dart pub global activate -s git https://github.com/dart-lang/ai.git \
64-
--git-path pkgs/dart_mcp_server/
32+
```json
33+
{
34+
"mcpServers": {
35+
"dart": {
36+
"command": "dart",
37+
"args": [
38+
"mcp-server",
39+
"--experimental-mcp-server", // Can be removed for Dart 3.9.0 or later.
40+
]
41+
}
42+
}
43+
}
6544
```
6645

67-
And then, assuming the pub cache bin dir is [on your PATH][set-up-path], the
68-
`dart_mcp_server` command will run it, and recompile as necessary.
46+
For more information, see the official Gemini CLI documentation for
47+
[setting up MCP servers](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md#how-to-set-up-your-mcp-server).
6948

70-
[set-up-path]: https://dart.dev/tools/pub/cmd/pub-global#running-a-script-from-your-path
49+
### Gemini Code Assist in VS Code
7150

72-
**Note:**: For some clients, depending on how they launch the MCP server and how
73-
tolerant they are, you may need to compile it to exe to avoid extra output on
74-
stdout:
51+
> Note: this currently requires the "Insiders" channel. Follow
52+
[instructions](https://developers.google.com/gemini-code-assist/docs/use-agentic-chat-pair-programmer#before-you-begin)
53+
to enable this build.
7554

76-
```sh
77-
dart compile exe bin/main.dart
78-
```
79-
80-
And then provide the path to the executable instead of using the globally
81-
activated `dart_mcp_server` command.
82-
83-
### With the example WorkflowBot
55+
[Gemini Code Assist](https://codeassist.google/)'s
56+
[Agent mode](https://developers.google.com/gemini-code-assist/docs/use-agentic-chat-pair-programmer) integrates the Gemini CLI to provide a powerful
57+
AI agent directly in your IDE. To configure Gemini Code Assist to use the Dart MCP
58+
server, follow the instructions to [configure the Gemini](#gemini-cli) CLI above.
8459

85-
After compiling the binary, you can run the example [workflow bot][workflow_bot]
86-
to interact with the server. Note that the workflow bot sets the current
87-
directory as the root directory, so if your server expects a certain root
88-
directory you will want to run the command below from there (and alter the
89-
paths as necessary). For example, you may want to run this command from the
90-
directory of the app you wish to test the server against.
60+
You can verify the MCP server has been configured properly by typing `/mcp` in the chat window in Agent mode.
9161

92-
[workflow_bot]: https://github.com/dart-lang/ai/tree/main/mcp_examples/bin/workflow_client.dart
93-
94-
```dart
95-
dart pub add "dart_mcp_examples:{git: {url: https://github.com/dart-lang/ai.git, path: mcp_examples}}"
96-
dart run dart_mcp_examples:workflow_client --server dart_mcp_server
97-
```
62+
![Gemini Code Assist list mcp tools](_docs/gca_mcp_list_tools.png "Gemini Code Assist list MCP tools")
9863

99-
### With Cursor
64+
For more information see the official Gemini Code Assist documentation for
65+
[using agent mode](https://developers.google.com/gemini-code-assist/docs/use-agentic-chat-pair-programmer#before-you-begin).
10066

101-
The following button should work for most users:
67+
<!-- ### Android Studio -->
68+
<!-- TODO(https://github.com/dart-lang/ai/issues/199): once we are confident that the
69+
Dart MCP server will work well with Android Studio's MCP support, add documentation here
70+
for configuring the server in Android Studio. -->
10271

103-
[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=dart_tooling&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoiZGFydCBtY3Atc2VydmVyIC0tZXhwZXJpbWVudGFsLW1jcC1zZXJ2ZXIgLS1mb3JjZS1yb290cy1mYWxsYmFjayJ9)
72+
### Cursor
10473

105-
To manually install it, go to Cursor -> Settings -> Cursor Settings and select "MCP".
74+
[![Add to Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/install-mcp?name=dart&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoiZGFydCBtY3Atc2VydmVyIC0tZXhwZXJpbWVudGFsLW1jcC1zZXJ2ZXIgLS1mb3JjZS1yb290cy1mYWxsYmFjayJ9)
10675

107-
Then, click "Add new global MCP server".
76+
The easiest way to configure the Dart MCP server with Cursor is by clicking the "Add to Cursor"
77+
button above.
10878

109-
If you are directly editing your mcp.json file, it should look like this:
79+
Alternatively, you can configure the server manually. Go to **Cursor -> Settings -> Cursor Settings > Tools & Integrations**, and then click **"Add Custom MCP"** or **"New MCP Server"**
80+
depending on whether you already have other MCP servers configured. Edit the `.cursor/mcp.json` file in your local project (configuration will only apply to this project) or
81+
edit the global `~/.cursor/mcp.json` file in your home directory (configuration will apply for
82+
all projects) to configure the Dart MCP server:
11083

11184
```json
11285
{
11386
"mcpServers": {
114-
"dart_mcp": {
87+
"dart": {
11588
"command": "dart",
11689
"args": [
11790
"mcp-server",
118-
"--experimental-mcp-server",
119-
"--force-roots-fallback"
91+
"--experimental-mcp-server", // Can be removed for Dart 3.9.0 or later
92+
"--force-roots-fallback" // Workaround for a Cursor issue with Roots support
12093
]
12194
}
12295
}
12396
}
12497
```
12598

126-
Each time you make changes to the server, you'll need to restart the server on
127-
the MCP configuration page or reload the Cursor window (Developer: Reload Window
128-
from the Command Palette) to see the changes.
99+
For more information, see the official Cursor documentation for
100+
[installing MCP servers](https://docs.cursor.com/context/model-context-protocol#installing-mcp-servers).
101+
102+
### GitHub Copilot in VS Code
103+
104+
<!-- TODO: once the dart.mcpServer setting is not hidden, we may be able
105+
to provide a deep link to the Dart Extension Settings UI for users to
106+
enable the server. See docs: https://code.visualstudio.com/docs/configure/settings#_settings-editor.
107+
This may be preferable to adding the deep link button to VS Code's mcp settings. -->
108+
109+
To configure the Dart MCP server with Copilot or any other AI agent that supports the
110+
[VS Code MCP API](https://code.visualstudio.com/api/extension-guides/mcp), add the following
111+
to your VS Code user settings:
112+
```json
113+
"dart.mcpServer": true
114+
```
115+
116+
By adding this setting, the Dart VS Code extension will register the Dart MCP Server
117+
configuration with VS Code so that you don't have to manually configure the server.
118+
Copilot will then automatically configure the Dart MCP server on your behalf. This is
119+
a global setting.
120+
121+
Alternatively, you can click the "Add to VS Code" button below to manually configure the server
122+
in your VS Code user settings.
123+
124+
[![Add to VS Code](_docs/add_to_vs_code.png)](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22dart%22%2C%22command%22%3A%22dart%22%2C%22args%22%3A%5B%22mcp-server%22%2C%22--experimental-mcp%22%5D%7D)
129125

130-
## Development
126+
Or, you can manually edit the `.vscode/mcp.json` file in your workspace,
127+
which will only configure the Dart MCP server for the local workspace:
131128

132-
For local development, use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).
129+
```json
130+
"servers": {
131+
"dart": {
132+
"type": "stdio",
133+
"command": "dart",
134+
"args": [
135+
"mcp-server",
136+
"--experimental-mcp-server", // Can be removed for Dart 3.9.0 or later
137+
]
138+
}
139+
}
140+
```
133141

134-
1. Run the inspector with no arguments:
135-
```shell
136-
npx @modelcontextprotocol/inspector
137-
```
142+
For more information, see the official VS Code documentation for
143+
[enabling MCP support](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_enable-mcp-support-in-vs-code).
138144

139-
2. Open the MCP Inspector in the browser and enter `dart_mcp_server` in
140-
the "Command" field.
145+
## Tools
141146

142-
3. Click "Connect" to connect to the server and debug using the MCP Inspector.
147+
| Tool Name | Feature Group | Description |
148+
| --- | --- | --- |
149+
| `analyze_files` | `static analysis` | Analyzes the entire project for errors. |
150+
| `signature_help` | `static_analysis` | Gets signature information for usage at a given cursor position. |
151+
| `hover` | `static_analysis` | Gets the hover information for a given cursor position. |
152+
| `resolve_workspace_symbol` | `static analysis` | Look up a symbol or symbols in all workspaces by name. |
153+
| `dart_fix` | `static tool` | Runs `dart fix --apply` for the given project roots. |
154+
| `dart_format` | `static tool` | Runs `dart format .` for the given project roots. |
155+
| `pub` | `static tool` | Runs a `dart pub` command for the given project roots. |
156+
| `pub_dev_search` | `package search` | Searches pub.dev for packages relevant to a given search query. |
157+
| `get_runtime_errors` | `runtime analysis` | Retrieves the list of runtime errors that have occurred in the active Dart or Flutter application. |
158+
| `take_screenshot` | `runtime analysis` | Takes a screenshot of the active Flutter application in its current state. |
159+
| `get_widget_tree` | `runtime analysis` | Retrieves the widget tree from the active Flutter application. |
160+
| `get_selected_widget` | `runtime analysis` | Retrieves the selected widget from the active Flutter application. |
161+
| `hot_reload` | `runtime tool` | Performs a hot reload of the active Flutter application. |
162+
| `connect_dart_tooling_daemon`* | `configuration` | Connects to the locally running Dart Tooling Daemon. |
163+
| `get_active_location` | `editor` | Gets the active cursor position in the connected editor (if available). |
164+
| `run_tests` | `static tool` | Runs tests for the given project roots. |
165+
| `create_project` | `static tool` | Creates a new Dart or Flutter project. |
166+
167+
> *Experimental: may be removed.

‎pkgs/dart_mcp_server/_docs/add_to_vs_code.png‎

3.06 KB
Loading

‎pkgs/dart_mcp_server/_docs/gca_mcp_list_tools.png‎

34.3 KB
Loading

0 commit comments

Comments
 (0)