mcp_models 2.1.0-dev.3

Dart model classes for the Model Context Protocol (MCP) — tools, resources, prompts, subscriptions and notifications. No codegen.

MCP Models

Dart model classes for the Model Context Protocol (MCP) 2026-07-28.

Every type defined in the official MCP schema is available as a plain Dart class with toMap() serialisation and a named factory TypeName.toMCP(Map) for deserialisation — no code generation required.

---

Features

• Full coverage of the MCP 2026-07-28 schema: JSON-RPC messages, tools, resources, prompts, elicitation, subscriptions, server discovery, notifications and more.
• Zero runtime dependencies — pure Dart.
• McpBuilder helper for declarative server capability registration.
• MapMC<K,V> and MapModel<K,V> base classes for types whose serialised form is the underlying map.

---

Installation

dependencies:
  mcp_models: ^1.0.0

Or with the CLI:

dart pub add mcp_models

---

Quick start

import 'package:mcp_models/mcp_models.dart';

// Every request now carries its own protocol version and capabilities —
// there is no more one-time `initialize` handshake. Servers advertise their
// capabilities out-of-band via `server/discover` instead.
final request = DiscoverRequest(
  id: '1',
  params: RequestParams(
    $meta: RequestMetaObject(
      protocolVersion: '2026-07-28',
      clientCapabilities: ClientCapabilities({}),
      clientInfo: Implementation(name: 'my_client', version: '1.0.0'),
    ),
  ),
);

// Serialise to a Map (ready for JSON encoding).
final json = request.toMap();

// Deserialise back.
final restored = DiscoverRequest.toMCP(json);

---

McpBuilder

McpBuilder lets you declare all server capabilities in one place and look up handlers by name/URI at runtime:

final builder = McpBuilder();

builder.tool(
  name: 'add',
  description: 'Adds two integers.',
  inputSchema: ToolSchema(
    properties: {
      'a': {'type': 'integer'},
      'b': {'type': 'integer'},
    },
    required: ['a', 'b'],
  ),
  handler: (req) async {
    final args = req.params.arguments ?? {};
    final sum = (args['a'] as int) + (args['b'] as int);
    return CallToolResult(
      content: [TextContent(text: '$sum', mimeType: 'text/plain')],
    );
  },
);

builder.resource(
  name: 'config',
  uri: 'file:///config.json',
  handler: (req) async => ReadResourceResult(
    contents: [],
    ttlMs: 0,
    cacheScope: CacheScope.private,
  ),
);

builder.prompt(
  name: 'greet',
  handler: (req) async => GetPromptResult(messages: []),
);

// Serve a tools/list response.
final toolsResult = builder.buildToolsResult();

// Dispatch a tools/call request.
final handler = builder.toolHandler('add');
if (handler != null) {
  final result = await handler(callToolRequest);
}

---

Supported MCP types

Category	Types
JSON-RPC core	JSONRPCRequest, JSONRPCNotification, JSONRPCResultResponse, JSONRPCErrorResponse
Errors	Error, ParseError, InvalidRequestError, MethodNotFoundError, InvalidParamsError, InternalError, HeaderMismatchError, MissingRequiredClientCapabilityError, UnsupportedProtocolVersionError
Meta / capabilities	RequestMetaObject, NotificationMetaObject, ResultMetaObject, Implementation, ClientCapabilities, ServerCapabilities
Server discovery	DiscoverRequest, DiscoverResultResponse, DiscoverResult
Subscriptions	SubscriptionFilter, SubscriptionsListenRequest, SubscriptionsListenResult, SubscriptionsAcknowledgedNotification
Multi round-trip	InputRequiredResult, InputResponseRequestParams, CallToolResultOutcome, GetPromptResultOutcome, ReadResourceResultOutcome
Tools	Tool, ToolSchema, ToolAnnotations, CallToolRequest, CallToolResult, ListToolsResult
Resources	Resource, ResourceTemplate, TextResourceContents, BlobResourceContents, ReadResourceResult, ListResourcesResult
Prompts	Prompt, PromptArgument, PromptMessage, GetPromptResult, ListPromptsResult
Sampling (deprecated)	CreateMessageRequest, CreateMessageResult, SamplingMessage, ModelPreferences, ModelHint, ToolChoice
Elicitation	ElicitRequest, ElicitRequestFormParams, ElicitRequestURLParams, ElicitResult, StringSchema, NumberSchema, BooleanSchema, UntitledSingleSelectEnumSchema, TitledSingleSelectEnumSchema
Content blocks	TextContent, ImageContent, AudioContent, EmbeddedResource, ResourceLink
Notifications	CancelledNotification, ProgressNotification, ResourceUpdatedNotification, ToolListChangedNotification, ResourceListChangedNotification
Misc	EmptyResult, Annotations, Role, CacheScope, LoggingLevel (deprecated), MetaObject, Icon, Theme

See the example for end-to-end usage.

---

MCP specification

This package targets the MCP 2026-07-28 schema: https://modelcontextprotocol.io/specification/2026-07-28/schema

---

Contributing

Contributions, bug reports, and feature requests are very welcome!

We especially encourage Dart developers to open GitHub Issues to help guide the development and keep this package up to date with the evolving MCP specification.

Ways to contribute:

• Found a bug or missing type? Open a bug report

• Want a new feature or schema update? Open a feature request

• Want to submit code? See CONTRIBUTING.md.

Every issue, no matter how small, helps keep this package accurate and useful for the entire Dart community. Thank you!

---

License

MIT — see LICENSE.