mcp_dart 2.1.0

Dart Implementation of Model Context Protocol (MCP) SDK.

2.1.0

Compatibility Notes (Potentially Breaking)

• Streamable HTTP defaults are stricter:
  • DNS rebinding protection is enabled by default for Streamable HTTP server entry points.
  • Unsupported MCP-Protocol-Version request headers are rejected by default.
  • JSON-RPC batch POST payloads are rejected by default.
  • Use compatibility toggles to preserve legacy behavior during rollout:
    • strictProtocolVersionHeaderValidation: false
    • rejectBatchJsonRpcPayloads: false
    • enableDnsRebindingProtection: false
• Sampling response shape can now be multi-block:
  • SamplingMessage.content and CreateMessageResult.content may be either a single block or a list.
  • Prefer normalized access via contentBlocks.
• Enum expansion:
  • StopReason now includes toolUse; exhaustive switch statements may need an additional branch.

Features

• Added SDK runtime logging helper APIs: setMcpLogHandler, resetMcpLogHandler, and silenceMcpLogs.
• Added Logger.resetHandler() to restore the default internal log output.
• Added backward-compatible sampling/content API shims while keeping 2025-11-25 wire-format compliance:
  • CreateMessageRequest.toolChoice supports legacy map and typed ToolChoice
  • SamplingMessage.content and CreateMessageResult.content accept single or array content forms with normalized contentBlocks access
  • ResourceLink.annotations supports map form with typed parsedAnnotations accessor
• Added Streamable HTTP compatibility toggles:
  • strictProtocolVersionHeaderValidation
  • rejectBatchJsonRpcPayloads
• Added related-task metadata compatibility behavior by dual-writing io.modelcontextprotocol/related-task and legacy relatedTask keys.

Documentation

• Added runtime logging guidance with package:logging integration examples using import aliases.
• Updated transport logging middleware examples to match SDK logger methods (debug/info/warn/error).
• Added doc/migration_2025_11_25_compat.md with compatibility-mode and API migration guidance.
• Updated transport/client/quick-reference docs for strict defaults and compatibility toggles.

Reliability

• Fixed Streamable HTTP Accept header parsing to handle repeated/multi-value headers without throwing HttpException, improving compatibility with clients that send duplicated or split Accept values.
• Centralized DNS rebinding validation across Streamable HTTP and legacy SSE server entry points.
• Added interop coverage for Dart/TypeScript sampling flows (sampling.tools capability and tool-choice propagation).

2.0.0

Breaking Changes

• JSON Schema API:
  • JsonObject.additionalProperties and JsonSchema.object(additionalProperties: ...) now use Object? instead of bool?.
  • additionalProperties may now be either bool or JsonSchema, matching the JSON Schema specification.

Features

• MCP Apps Support:
  • Added typed MCP Apps metadata models and helpers (McpUiToolMeta, McpUiResourceMeta, McpUiCsp, McpUiPermissions) with extension capability helpers for io.modelcontextprotocol/ui.
  • Added TypeScript-style server helpers (registerAppTool, registerAppResource, getUiCapability) and metadata normalization for _meta.ui.resourceUri and legacy _meta['ui/resourceUri'].
  • Added MCP Apps server examples for helper-based and manual metadata wiring.

Compatibility

• Host Rendering:
  • Updated MCP Apps weather examples to use host-safe tool names (weather_get_current), include explicit resource_link tool output, and demonstrate host-rendered UI updates from tool input/result notifications.

Documentation

• Added and expanded MCP Apps documentation across guides and quick reference, including host compatibility guidance for tool naming constraints.

Reliability

• JSON Schema Parsing:
  • Fixed JsonObject.fromJson to accept untyped map values for additionalProperties (for example {} decoded as Map<dynamic, dynamic>), so schema objects are not silently dropped.

1.3.0

• Spec Alignment:
  • Added ResourceLink (resource_link) content type support.
  • Added icon metadata support with McpIcon, IconTheme, and optional icons fields across tools/prompts/resources/templates.
  • Added ResourceAnnotations.lastModified (ISO 8601).
  • Added MCP extensions capability support for client/server initialization capability negotiation.
• Security:
  • Added optional DNS rebinding protection to streamable HTTP/SSE server entry points via host/origin allowlists.
• Reliability:
  • Tightened null handling for JSON-RPC tool params and task store TTL parsing paths.
  • Fixed URI template matching for RFC 6570 multi-variable operators (for example {?status,assignee}) so resources/read resolves templated URIs correctly.
  • Fixed tool metadata passthrough so registered meta (including nested _meta values) is preserved in tools/list responses.
  • Improved URI template variable typing and protocol cancellation reason typing.
• Docs:
  • Updated transport, client, server, tools, and quick-reference docs for new fields and security options.

1.2.2

• Fix pana analysis issues

1.2.1

• Features:

  • Progress Notifications: Implemented full support for progress tracking.
    • Added RequestHandlerExtra.sendProgress() helper for servers to report progress.
    • Added RequestOptions.onprogress callback for clients to receive progress updates.
    • Updated Progress and ProgressNotification types to include optional message field (compliant with 2025-11-25 spec).
  • Protocol Improvements:
    • JsonRpcMessage.fromJson now supports custom/unknown methods instead of throwing.
    • Fixed JsonRpcRequest metadata extraction to correctly handle nested _meta in params.
    • Updated ToolAnnotations to make title optional, preventing deserialization errors when the field is missing.

• Fixes:

  • StreamableHTTP: Prevented the client from attempting to "reconnect" to short-lived POST response streams (used for tool calls). This fixes an issue where multiple tool calls could exhaust the browser's connection limit by spawning zombie reconnection attempts.

• Examples:

  • New Jaspr Client: Added a comprehensive web client example (example/jaspr-client) built with Jaspr, featuring:
    • Interactive UI for Tools, Resources, Prompts, and Tasks.
    • Real-time connection management.
    • Visual task progression and sampling dialogs.
  • Anthropic Client: Fixed issues in the Anthropic client example.
  • Task Server: Added CORS headers and logging to simple_task_interactive_server.dart.
  • Updated examples to remove deprecated API usage.

• Documentation:

  • Overhauled documentation (doc/) to match current API (v1.1.2+).
  • Added AGENTS.md with comprehensive developer guidelines.

• Testing:

  • Updated test/types_test.dart and test/types_edge_cases_test.dart to correct expectations for unknown methods. JsonRpcMessage.fromJson returns a generic JsonRpcRequest (or JsonRpcNotification) for unknown methods instead of throwing, aligning tests with existing library behavior.

1.2.0

Breaking Changes

Tip

All breaking changes below are auto-fixable. Run dart fix --apply to automatically update your code.

• Renamed Core Classes:
  • Client is now McpClient to avoid conflicts with other libraries (like http).
  • ClientOptions is now McpClientOptions.
  • ServerOptions is now McpServerOptions.
• Renamed Request/Notification Parameters:
  • ReadResourceRequestParams -> ReadResourceRequest
  • GetPromptRequestParams -> GetPromptRequest
  • ElicitRequestParams -> ElicitRequest
  • CreateMessageRequestParams -> CreateMessageRequest
  • LoggingMessageNotificationParams -> LoggingMessageNotification
  • CancelledNotificationParams -> CancelledNotification
  • ProgressNotificationParams -> ProgressNotification
  • TaskCreationParams -> TaskCreation

1.1.2

• Fixed StdioClientTransport stderr handling: Corrected process mode to always use ProcessStartMode.normal to ensure stdin/stdout piping works correctly. Fixed inverted stderr mode logic where stderrMode: normal now properly exposes stderr via getter (without internal listening), and stderrMode: inheritStdio now manually pipes stderr to parent process.

1.1.1

• Structured Content Support: Added explicit structuredContent field to CallToolResult with automatic backward compatibility support.
  • CallToolResult.fromStructuredContent now automatically populates both structuredContent (for modern clients) and content (as JSON string for legacy clients).
  • Updated validation logic to correctly validate structuredContent payload against tool schema.

1.1.0

Breaking Changes

• Protocol Version Update: Updated default protocol version to 2025-11-25.
• Strict Capabilities Typing: ServerCapabilities and ClientCapabilities fields (tasks, sampling, elicitation, etc.) are now strictly typed objects instead of Map<String, dynamic> or bool.
  • Updated ServerCapabilities to use ServerCapabilitiesTasks, ServerCapabilitiesTools, etc.
  • Updated ClientCapabilities to use ClientCapabilitiesTasks, ClientCapabilitiesElicitation, ClientCapabilitiesSampling, etc.
  • Migration: Update capability declarations to use the new typed classes (e.g., ServerCapabilities(tasks: ServerCapabilitiesTasks(listChanged: true))).
• File Removal: lib/src/server/mcp.dart has been removed. Use lib/src/server/mcp_server.dart (exported via lib/src/server/module.dart) instead.
• Transport Interface Change: Transport.send now accepts an optional named parameter relatedRequestId. Custom transports must update their method signature.
• Client Validation: Client.callTool now strictly validates tool outputs against their defined JSON schema (if present). Mismatches will throw an McpError(ErrorCode.invalidParams).
• API Refactoring:
  • McpServer.tool, resource, and prompt are deprecated. Use registerTool, registerResource, and registerPrompt instead.
  • McpServer.registerTool uses a new callback signature: FutureOr<CallToolResult> Function(Map<String, dynamic> args, RequestHandlerExtra extra).
  • The deprecated McpServer.tool retains the old named-parameter signature for backward compatibility.
• Tool Schema Definitions: ToolInputSchema (aka JsonObject) now requires properties to be defined using JsonSchema objects (e.g., JsonSchema.string()) instead of raw Maps.
• Tool Listing Types: ListToolsRequestParams has been replaced by ListToolsRequest (update any code passing params: to Client.listTools or constructing JsonRpcListToolsRequest).
• Tool Result Structured Content: CallToolResult no longer uses a dedicated structuredContent field in its API; structured results are represented as additional top-level fields (CallToolResult.extra). CallToolResult.fromStructuredContent now takes a single Map<String, dynamic> argument.
• RequestHandlerExtra Signature Changes: RequestHandlerExtra.sendNotification and RequestHandlerExtra.sendRequest have updated signatures (added task-related metadata/options). Update any server callbacks that call these helpers directly.

Features

• Task Management System:
  • Implemented comprehensive Task support in lib/src/server/tasks/.
  • Introduced TaskStore abstract interface with InMemoryTaskStore as the default implementation.
  • Added strictly typed TaskResultHandler and TaskSession.
  • Introduced TaskMessageQueue for handling task messages.
• McpServer Enhancements:
  • Added McpServer high-level support for tasks via tasks(...) method.
  • Integrated notifyTaskStatus into McpServer.
  • Added McpServer support for sampling/createMessage.
  • Exposed onError handler setter/getter on McpServer.
• StreamableMcpServer:
  • Added StreamableMcpServer class for simplified Streamable HTTP server creation (handles serverFactory, event store, and connection management).
• Client Enhancements:
  • Added onTaskStatus callback to Client.
  • Simplified client request handlers for sampling and elicitation.

Fixes

• Fixed Task serialization.
• Fixed capabilities recognition in McpServer.
• Added comprehensive tests for StreamableMcpServer and Task features.

1.0.2

• Fix pana analysis issues
• Fix Web support for StreamableHTTP client

1.0.1

• Fix Documentation links in README.md

1.0.0

• Update protocol version to 2025-06-18
• Add Elicitation support (server-initiated input collection)
  • API: McpServer.elicitUserInput() (server) | Client.onElicitRequest (client handler)
  • Types: ElicitRequestParams (message, requestedSchema), ElicitResult (action, content), ClientCapabilitiesElicitation
  • Uses elicitation/create method (Inspector-compatible)
  • Accepts JSON Schema Maps for flexible schema definition
  • Helpers: .accepted, .declined, .cancelled getters on ElicitResult
  • Example: elicitation_http_server.dart
  • Tests: elicitation_test.dart
• CRITICAL FIX: Logger → stderr (prevents JSON-RPC corruption in stdio)
• Comprehensive Test Coverage: Added 203 new tests across 4 phases (+13.1% overall coverage: 56.9% → 70.0%)
  • Phase 1: External API coverage (Server MCP, URI templates, Client/Server capabilities) - 108 tests
  • Phase 2: Transport coverage (Stdio, SSE, HTTPS) - 38 tests
  • Phase 3: Types & edge cases (Protocol lifecycle, error handling) - 45 tests
  • Phase 4: Advanced scenarios (Protocol timeouts/aborts, Streamable HTTPS integration) - 12 tests
  • Fixed critical URI template variable duplication bug
  • Fixed McpError code preservation in request handlers
  • All 351 tests passing ✅

0.7.0

• Add support for Completions capability per MCP 2025-06-18 spec
• Add ServerCapabilitiesCompletions class for explicit completions capability declaration
• Update ServerCapabilities to include completions field
• Update client capability check to use explicit completions capability instead of inferring from prompts/resources
• Add integration tests and example for completions capability usage

0.6.4

• Fix issue with StreamableHTTP server not setting correct content-type for SSE

0.6.3

• Replace print statements with lightweight logging implementation

0.6.2

• Remove trailing CR before processing the lines

0.6.1

• Fix issue with CallToolResult not including metadata

0.6.0

• Add ToolInputSchema and ToolOutputSchema support in server.tool()
• Deprecate inputSchemaProperties and outputSchemaProperties in server.tool()
• Update examples to use ToolInputSchema and ToolOutputSchema

0.5.3

• Support Web Client for StreamableHTTP

0.5.2

• Preserve required fields in ToolInputSchema

0.5.1

• Add support for OutputScheme (https://modelcontextprotocol.io/specification/draft/server/tools#output-schema)

0.5.0

• Protocol version 2025-03-26

0.4.3

• Fix SSE behavior on StreamableHTTP
• Added sendNotification and sendRequest to extra for server callbacks

0.4.2

• Add Tool Annotation
• Remove additionalProperties from all models
• Add AudioContent

0.4.1

• Add IOStreamTransport to connect a client and server via dart streams in a single application

0.4.0

• Add support for StreamableHTTP client
• Add support for StreamableHTTP server

0.3.6

• Improve pub.dev points

0.3.5

• Lower min dart sdk to 3.0.0

0.3.4

• Fix Sampling result parsing error

0.3.3

• Add Gemini MCP Client Example
• Add Anthropic MCP Client Example
• Add Weather MCP Server Example

0.3.2

• Add SSE Server Manager for easier SSE server implementation

0.3.1

• Add Client support (stdio)
• Add resource and prompts example to stdio server and client

0.3.0

• Full refactor of the codebase to match it with the Typescript SDK implementation.

0.2.0

• Make it no need to call trasnport.connect()

0.1.1

• Add examples visible in pub.dev

0.1.0

• Add SSE support

0.0.2

• Expose more types

0.0.1

• Initial version.