# dart_mcp 0.5.2 A package for making MCP servers and clients. ## Installing ``` export PUB_HOSTED_URL=https://pub.mirror.p-hatan.com flutter pub add 'dart_mcp:0.5.2' ``` Published: 2026-06-29T16:25:31.447366Z Expected archive SHA-256: 852b51da915d679be8d051e2e3b6c68ed19fe685f1c676bb35272a2d73ceac7a Available in cache; verification: upstream_checksum ## Direct dependencies - async: ^2.13.0 - collection: ^1.19.1 - json_rpc_2: >=3.0.3 <5.0.0 - meta: ^1.16.0 - stream_channel: ^2.1.4 - stream_transform: ^2.1.1 ## Package README (untrusted upstream documentation) [![pub package](https://img.shields.io/pub/v/dart_mcp.svg)](https://pub.dev/packages/dart_mcp) [![package publisher](https://img.shields.io/pub/publisher/dart_mcp.svg)](https://pub.dev/packages/dart_mcp/publisher) A Dart package for making MCP servers and clients. **Note**: This package is still experimental and is likely to evolve quickly. ## Implementing Servers To implement a server, import `package:dart_mcp/server.dart` and extend the `MCPServer` class. You must provide the server a communication channel to send and receive messages with. For each specific MCP capability or utility your server supports, there is a corresponding mixin that you can use (`ToolsSupport`, `ResourcesSupport`, etc). Each mixin has doc comments explaining how to use it - some may require you to provide implementations of methods, while others may just expose new methods that you can call. See the [examples](example/) for some example code (server examples end in `_server.dart`). ### Invoking Client Capabilities All client capabilities are exposed as methods on the `MCPServer` class. Before attempting to call these methods, you must first wait for the `MCPServer.initialized` future and then check the capabilities of the client by reading the `MCPServer.clientCapabilities`. Alternatively, if your server requires certain capabilities from the client for all operations, you may override the `MCPServer.initialize` function and return an error, which may result in a better UX for the users of the client. ## Implementing Clients To implement a client, import `package:dart_mcp/client.dart` and extend the `MCPClient` class, or directly call its constructor with a `Implementation` if you aren't implementing any "capabilities". For each specific MCP capability your client supports, there is a corresponding mixin that you can use (`RootsSupport`, `SamplingSupport`, etc). Each mixin has doc comments explaining how to use it - some may require you to provide implementations of methods, while others may just expose new methods that you can call. ### Connecting to Servers You can connect this client with STDIO servers using the `MCPClient.connectStdioServer` method, or you can call `MCPClient.connectServer` with any other communication channel. The returned `ServerConnection` should be used for all interactions with the server, starting with a call to `ServerConnection.initialize`, followed up with a call to `ServerConnection.notifyInitialized` (if initialization was successful). If a version could not be negotiated or a server does not support required features, the server connection should be closed (by calling `ServerConnection.shutdown`). See [initialization lifecycle][initialization_lifecycle] for information about the client/server initialization protocol. ### Invoking Server Capabilities and Utilities All server capabilities and utilities are exposed as methods or streams on the `ServerConnection` class. Before attempting to call methods on the server however, you should first verify the capabilities of the server by reading them from the `InitializeResult` returned from `ServerConnection.initialize`. [initialization_lifecycle]: https://spec.modelcontextprotocol.io/specification/2024-11-05/basic/lifecycle/#initialization ## Supported Protocol Versions [2024-11-05](https://spec.modelcontextprotocol.io/specification/2024-11-05/) [2025-03-26](https://spec.modelcontextprotocol.io/specification/2025-03-26/) [2025-06-18](https://spec.modelcontextprotocol.io/specification/2025-06-18/) [2025-11-05](https://spec.modelcontextprotocol.io/specification/2025-11-05/) If support for a given protocol version is dropped, that will be released as a breaking change in this package. However, we will strive to maintain backwards compatibility where possible. ## Base Utilities This table describes the state of implementation for the base protocol [utilities](https://spec.modelcontextprotocol.io/specification/2025-11-05/basic/utilities). Both the `MCPServer` and `MCPClient` support these. | Utility | Support | Notes | | --- | --- | --- | | [Ping](https://spec.modelcontextprotocol.io/specification/2025-11-05/basic/utilities/ping) | :heavy_check_mark: | | | [Cancellation](https://spec.modelcontextprotocol.io/specification/2025-11-05/basic/utilities/cancellation/) | :x: | https://github.com/dart-lang/ai/issues/37 | | [Progress](https://spec.modelcontextprotocol.io/specification/2025-11-05/basic/utilities/progress/) | :heavy_check_mark: | | ## Transport Mechanisms This table describes the supported [transport mechanisms](https://modelcontextprotocol.io/specification/2025-11-05/basic/transports). At its core this package is just built on streams, so any transport mechanism can be used, but some are directly supported out of the box. | Transport | Support | Notes | | --- | --- | --- | | [Stdio](https://modelcontextprotocol.io/specification/2025-11-05/basic/transports#stdio) | :heavy_check_mark: | | | [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-11-05/basic/transports#streamable-http) | :x: | Unsupported at this time, may come in the future. | ## Batching Requests Both the client and server support processing batch requests, but do not support creating batch requests at this time. ## Authorization Authorization is not supported at this time. This package is primarily targeted at local MCP server usage for now. ## Server Capabilities This table describes the state of implementation for the [server capabilities](https://spec.modelcontextprotocol.io/specification/2025-11-05/server/). **Note:** Servers can also invoke all [client capabilities](#client-capabilities), see [Invoking Client Capabilities](#invoking-client-capabilities). | Capability | Support | Notes | | --- | --- | --- | | [Prompts](https://spec.modelcontextprotocol.io/specification/2025-11-05/server/prompts/) | :heavy_check_mark: | | | [Resources](https://spec.modelcontextprotocol.io/specification/2025-11-05/server/resources/) | :heavy_check_mark: | | | [Tools](https://spec.modelcontextprotocol.io/specification/2025-11-05/server/tools/) | :heavy_check_mark: | | ## Server Utilities This table describes the state of implementation for the [server utilities](https://spec.modelcontextprotocol.io/specification/2025-11-05/server/utilities/). | Utility | Support | Notes | | --- | --- | --- | | [Completion](https://spec.modelcontextprotocol.io/specification/2025-11-05/server/utilities/completion/) | :heavy_check_mark: | | | [Logging](https://spec.modelcontextprotocol.io/specification/2025-11-05/server/utilities/logging/) | :heavy_check_mark: | | | [Pagination](https://spec.modelcontextprotocol.io/specification/2025-11-05/server/utilities/pagination/) | :construction: | https://github.com/dart-lang/ai/issues/28 | ## Client Capabilities This table describes the state of implementation for the client [capabilities](https://spec.modelcontextprotocol.io/specification/2025-11-05/client/). **Note:** Clients can also invoke all [server capabilities](#server-capabilities) and [server utilities](#server-utilities), see [Invoking Server Capabilities and Utilities](#invoking-server-capabilities-and-utilities). | Capability | Support | Notes | | --- | --- | --- | | [Roots](https://spec.modelcontextprotocol.io/specification/2025-11-05/client/roots/)| :heavy_check_mark: | | | [Sampling](https://spec.modelcontextprotocol.io/specification/2025-11-05/client/sampling/)| :heavy_check_mark: | | ## Changelog ## 0.5.2 - Update `listRoots` to normalize URIs to file: scheme variants when given raw file paths. This fixes non-spec compliant clients. ## 0.5.1 - Always send a properties object for tool input schemas, see https://github.com/dart-lang/ai/issues/170. ## 0.5.0 - Initial support for protocol version [2025-11-25](https://modelcontextprotocol.io/specification/2025-11-25/). - Added support for `Icon`s in `Implementation`, `Tool`, `Resource`, `ResourceTemplate`, and `Prompt`. - Added support for `ToolChoice` in sampling `CreateMessageRequest`. - Added support for URL-based elicitations in `ElicitRequest`. - Separated `ElicitationSupport` into `ElicitationFormSupport` and `ElicitationUrlSupport` mixins, which will affect which capabilities your server advertises. The original `ElicitationSupport` mixin is now deprecated (and is an alias for `ElicitationFormSupport`). - Added `onElicitationComplete` extension getter to `ElicitRequest`, which will listen for `notifications/elicitation/complete` notifications. - If a tool call fails with the `urlElicitationRequired` error code, and the client supports URL based elicitations, the client will automatically handle the elicitation and retry the tool call if the elicitation succeeds. - Added an `McpErrorCodes` namespace for MCP error codes. For now only contains the `urlElicitationRequired` error code. - Added examples for URL based elicitations, including handling `urlElicitationRequired` errors. - Added `description` field to `Implementation`. - Does **not** add support for Tasks yet. - Added support for `EnumSchema` subtypes, matching the spec. This includes multi select enums and enums with titles. Validation is also supported. - Added `Meta? meta` param to `ElicitRequest`. - Added `ConstSchema` type for constant values, with validation. - **BREAKING**: - Change many fields of `ResourceLink` to be nullable, and their associated parameters to be optional. This brings us in line with the specification. - The `WithElicitationHandler` interface is now private and implemented by the `ElicitationFormSupport` and `ElicitationUrlSupport` mixins. - Added a required `ServerConnection server` parameter to the `ElicitationSupport.handleElicitation` method. - `ElicitRequest.requestedSchema` is now nullable (for url mode). - `EnumSchema` is now a union type with 4 subtypes, matching the spec changes. ## 0.4.1 - Expose various private methods on MCP server mixins as public methods, with `@mustCallSuper` annotations. This allows intercepting calls for logging, metrics, or other purposes. - Fix the `resource` parameter type on `EmbeddedResource` to be `ResourceContents` instead of `Contents`. - **Note**: This is technically breaking but the previous API would not have been possible to use in a functional manner, so it is assumed that it had no usage previously. - Fix the `type` getter on `EmbeddedResource` to read the actual type field. - Add `toJson` method to the `CreateMessageResult` of a sampling request. ## 0.4.0 - Update the tool calling example to include progress notifications. - **Breaking**: Update APIs to accept nullable parameters when the parameters are not required for that method. This is only breaking if you override these methods. ## 0.3.3 - Fix `PingRequest` handling when it is sent from a non-Dart client. - Deprecate `ElicitationAction.reject` and replace it with `ElicitationAction.decline`. - In the initial elicitations schema this was incorrectly listed as `reject`. - This package still allows `reject` and treats it as an alias for`decline`. - The old `reject` enum value was replaced with a static constant equal exactly to `decline`, so switches are not affected. - Add `title` parameter to `Prompt` constructor. - Only execute sub-processes in a shell if they are `.bat` files. ## 0.3.2 - Deprecate the `EnumSchema` type in favor of the `StringSchema` with an `enumValues` parameter. The `EnumSchema` type was not MCP spec compatible. - Also deprecated the associated JsonType.enumeration which doesn't exist in the JSON schema spec. ## 0.3.1 - Fixes communication problem when a `MCPServer` is instantiated without instructions. - Fix the `content` argument to `PromptMessage` to be a single `Content` object. - Add new `package:dart_mcp/stdio.dart` library with a `stdioChannel` utility for creating a stream channel that separates messages by newlines. - Added more examples. - Deprecated the `WithElicitationHandler` interface - the method this required is now defined directly on the `ElicitationSupport` mixin which matches the pattern used by other mixins in this package. - Change the `schema` parameter for elicitation requests to an `ObjectSchema` to match the spec. - Deprecate the `Elicitations` server capability, this doesn't exist in the spec. ## 0.3.0 - Added error checking to required fields of all `Request` subclasses so that they will throw helpful errors when accessed and not set. - Added enum support to Schema. - Add more detail to type validation errors. - Remove some duplicate validation errors, errors are only reported for the leaf nodes and not all the way up the tree. - Deprecated a few validation error types as a part of this, including `propertyNamesInvalid`, `propertyValueInvalid`, `itemInvalid` and `prefixItemInvalid`. - Added a `custom` validation error type. - **Breaking**: Auto-validate schemas for all tools by default. This can be disabled by passing `validateArguments: false` to `registerTool`. - Updates to the latest MCP spec, [2025-06-08](https://modelcontextprotocol.io/specification/2025-06-18/changelog) - Adds support for Elicitations to allow the server to ask the user questions. - Adds `ResourceLink` as a tool return content type. - Adds support for structured tool output. - **Breaking**: Change `MCPClient.connectStdioServer` signature to accept stdin and stdout streams instead of starting processes itself. This enables custom process spawning (such as using package:process), and also enables the client to run in browser environments. - Fixed a problem where specifying `--log-file` would cause the server to stop working. ## 0.2.2 - Refactor `ClientImplementation` and `ServerImplementation` to the shared `Implementation` type to match the spec. The old names are deprecated but will still work until the next breaking release. - Add `clientInfo` field to `MCPServer`, assigned during initialization. - Move the `done` future from the `ServerConnection` into `MCPBase` so it is available to the `MPCServer` class as well. ## 0.2.1 - Fix the `protocolLogSink` support when using `MCPClient.connectStdioServer`. - Update workflow example to show thinking spinner and input and output token usage. - Update file system example to support relative paths. - Fix a bug in notification handling where leaving off the parameters caused a type exception. - Added `--help`, `--log`, and `--model` flags to the workflow example. - Fixed a bug where the examples would only connect to a server with the latest protocol version. - Handle failed calls to `listRoots` in the `RootsTrackingSupport` mixin more gracefully. Previously this would leave the `roots` future hanging indefinitely, but now it will log an error and set the roots to empty. - Added validation for Schema extension. - Fixed an issue where getting the type of a Schema with a null type would throw. ## 0.2.0 - Support protocol version 2025-03-26. - Adds support for `AudioContent`. - Adds support for `ToolAnnotations`. - Adds support for `ProgressNotification` messages. - Save the `ServerCapabilities` object on the `ServerConnection` class to make it easier to check the capabilities of the server. - Add default version negotiation logic. - Save the negotiated `ProtocolVersion` in a `protocolVersion` field for both `MCPServer` and the `ServerConnection` classes. - Automatically disconnect from servers if version negotiation fails. - Added support for adding and listing `ResourceTemplate`s. - Handlers have to handle their own matching of templates. - Added a `RootsTrackingSupport` server mixin which can be used to keep an updated list of the roots set by the client. - Added default throttling with a 500ms delay for `ResourceListChangedNotification`s and `ResourceUpdatedNotification`s. The delay can be modified by overriding `ResourcesSupport.resourceUpdateThrottleDelay`. - Add `Sink protocolLogSink` parameters to server constructor and client connection methods, which can be used to capture protocol messages for debugging purposes. - Only send notifications if the peer is still connected. Fixes issues where notifications are delayed due to throttling and the client has since closed. - **Breaking**: Fixed paginated result subtypes to use `nextCursor` instead of `cursor` as the key for the next cursor. - **Breaking**: Change the `ProgressNotification.progress` and `ProgressNotification.total` types to `num` instead of `int` to align with the spec. - **Breaking**: Change the `protocolVersion` string to a `ProtocolVersion` enum, which has all supported versions and whether or not they are supported. - **Breaking**: Change `InitializeRequest` and `InitializeResult` to take a `ProtocolVersion` instead of a string. - **Breaking**: Change the `InitializeResult`'s `instructions` to `String?` to reflect that not all servers return instructions. - Change the `MCPServer.fromStreamChannel` constructor to make the `instructions` parameter optional. - **Breaking**: Change `MCPBase` to accept a `StreamChannel` instead of a `Peer`, and construct its own `Peer`. - **Breaking**: Add `protocolLogSink` optional parameter to connect methods on `MCPClient`. - **Breaking**: Move `channel` parameter on `MCPServer.new` to a positional parameter for consistency. ## 0.1.0 - Initial release, supports all major MCP functionality for both clients and servers, at protocol version 2024-11-05. - APIs may change frequently until the 1.0.0 release based on feedback and needs.