v1.0.0

CHANGELOG.md

@@ -1,3 +1,24 @@
+## 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

README.md

@@ -3,38 +3,82 @@
 [![Pub Version](https://img.shields.io/pub/v/mcp_dart?color=blueviolet)](https://pub.dev/packages/mcp_dart)
 [![likes](https://img.shields.io/pub/likes/mcp_dart?logo=dart)](https://pub.dev/packages/mcp_dart/score)
 
-[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is an open protocol designed to enable seamless integration between LLM applications and external data sources and tools.
+The Model Context Protocol (MCP) is a standardized protocol for communication between AI applications and external services. It enables:
 
-This library aims to provide a simple and intuitive way to implement MCP servers and clients in Dart, while adhering to the [MCP protocol spec](https://spec.modelcontextprotocol.io/). The goal is to make this SDK as similar as possible to the official SDKs available in other languages, ensuring a consistent developer experience across platforms.
+- **Tools**: Allow AI to execute actions (API calls, computations, etc.)
+- **Resources**: Provide context and data to AI (files, databases, APIs)
+- **Prompts**: Pre-built prompt templates with arguments
+
+## Understanding MCP: Client, Server, and Host
+
+MCP follows a **client-server architecture** with three key components:
+
+- **MCP Host**: The AI application that provides the user interface and manages connections to multiple MCP servers.
+  - Example: Claude Desktop, IDEs like VS Code, custom AI applications
+  - Manages server lifecycle, discovers capabilities, and orchestrates interactions
+
+- **MCP Client**: The protocol implementation within the host that communicates with servers.
+  - Handles protocol negotiation, capability discovery, and request/response flow
+  - Typically built into or used by the MCP host
+
+- **MCP Server**: Provides capabilities (tools, resources, prompts) that AI can use through the host.
+  - Example: Servers for file system access, database queries, or API integrations
+  - Runs as a separate process and communicates via standardized transports (stdio, StreamableHTTP)
+
+**Typical Flow**: User ↔ MCP Host (with Client) ↔ MCP Protocol ↔ Your Server ↔ External Services/Data
 
 ## Requirements
 
 - Dart SDK version ^3.0.0 or higher
 
 Ensure you have the correct Dart SDK version installed. See <https://dart.dev/get-dart> for installation instructions.
 
-## Features
+## What This SDK Provides
+
+**This SDK lets you build both MCP servers and clients in Dart/Flutter.**
 
-- Stdio support (Server and Client)
-- StreamableHTTP support (Server and Client)
-- SSE support (Server only) - Deprecated
-- Stream Transport using dart streams (Server and Client in shared process)
-- Tools
-- Resources
-- Prompts
-- Sampling
-- Roots
-- Completions
+- ✅ **Build MCP Servers** - Create servers that expose tools, resources, and prompts to AI hosts
+- ✅ **Build MCP Clients** - Create AI applications that can connect to and use MCP servers
+- ✅ **Full MCP Protocol Support** - Complete [MCP specification 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18) implementation
+- ✅ **Multiple Transport Options** - Stdio, StreamableHTTP, Stream, or custom transports
+- ✅ **All Capabilities** - Tools, Resources, Prompts, Sampling, Roots, Completions, Elicitation
+- ✅ **OAuth2 Support** - Complete authentication with PKCE
+- ✅ **Type-Safe** - Comprehensive type definitions with null safety
+- ✅ **Cross-Platform** - Works on VM, Web, and Flutter
+
+The goal is to make this SDK as similar as possible to the official SDKs available in other languages, ensuring a consistent developer experience across platforms.
 
 ## Model Context Protocol Version
 
-The current version of the protocol is `2025-03-26`. This library is designed to be compatible with this version, and any future updates will be made to ensure continued compatibility.
+The current version of the protocol is `2025-06-18`. This library is designed to be compatible with this version, and any future updates will be made to ensure continued compatibility.
+
+It's also backward compatible with previous versions including `2025-03-26`, `2024-11-05`, and `2024-10-07`.
+
+**New in 2025-06-18**: Elicitation support for server-initiated user input collection.
+
+## Documentation
+
+### Getting Started
+
+- 📖 **[Quick Start Guide](docs/getting-started.md)** - Get up and running in 5 minutes
+- 🔧 **[Server Guide](docs/server-guide.md)** - Complete guide to building MCP servers
+- 💻 **[Client Guide](docs/client-guide.md)** - Complete guide to building MCP clients
+
+### Core Concepts
 
-It's also backward compatible with the previous version `2024-11-05` and `2024-10-07`.
+- 🛠️ **[Tools Documentation](docs/tools.md)** - Implementing executable tools
+- 🔌 **[Transport Options](docs/transports.md)** - Built-in and custom transport implementations
+- 📚 **[Examples](docs/examples.md)** - Real-world usage examples
+- ⚡ **[Quick Reference](docs/quick-reference.md)** - Fast lookup guide
 
-## Getting started
+### Advanced Features
 
-Below code is the simplest way to start the MCP server.
+- 🔐 **[OAuth Authentication](example/authentication/)** - OAuth2 guides and examples
+- 📝 For resources, prompts, and other features, see the Server and Client guides
+
+## Quick Start Example
+
+Below is the simplest way to create an MCP server:
 
 ```dart
 import 'package:mcp_dart/mcp_dart.dart';
@@ -53,19 +97,22 @@ void main() async {
   server.tool(
     "calculate",
     description: 'Perform basic arithmetic operations',
-    inputSchemaProperties: {
-      'operation': {
-        'type': 'string',
-        'enum': ['add', 'subtract', 'multiply', 'divide'],
+    toolInputSchema: ToolInputSchema(
+      properties: {
+        'operation': {
+          'type': 'string',
+          'enum': ['add', 'subtract', 'multiply', 'divide'],
+        },
+        'a': {'type': 'number'},
+        'b': {'type': 'number'},
       },
-      'a': {'type': 'number'},
-      'b': {'type': 'number'},
-    },
+      required: ['operation', 'a', 'b'],
+    ),
     callback: ({args, extra}) async {
       final operation = args!['operation'];
       final a = args['a'];
       final b = args['b'];
-      return CallToolResult(
+      return CallToolResult.fromContent(
         content: [
           TextContent(
             text: switch (operation) {
@@ -85,21 +132,23 @@ void main() async {
 }
 ```
 
-## Usage
+### Running Your Server
 
-Once you compile your MCP server, you can compile the client using the below code.
+Compile your MCP server to an executable:
 
 ```bash
 dart compile exe example/server_stdio.dart -o ./server_stdio
 ```
 
-Or just run it with JIT.
+Or run it directly with JIT:
 
 ```bash
 dart run example/server_stdio.dart
 ```
 
-To configure it with the client (ex, Claude Desktop), you can use the below code.
+### Connecting to AI Hosts
+
+To configure your server with AI hosts like Claude Desktop:
 
 ```json
 {
@@ -117,9 +166,32 @@ To configure it with the client (ex, Claude Desktop), you can use the below code
 }
 ```
 
-## More examples
+## Authentication
+
+This library supports OAuth2 authentication with PKCE for both clients and servers. For complete authentication guides and examples, see the [OAuth Authentication documentation](example/authentication/).
+
+## Platform Support
+
+| Platform | Stdio | StreamableHTTP | Stream | Custom |
+|----------|-------|----------------|--------|--------|
+| **Dart VM** (CLI/Server) | ✅ | ✅ | ✅ | ✅ |
+| **Web** (Browser) | ❌ | ✅ | ✅ | ✅ |
+| **Flutter** (Mobile/Desktop) | ✅ | ✅ | ✅ | ✅ |
+
+**Custom Transports**: You can implement your own transport layer by extending the transport interfaces if you need specific communication patterns not covered by the built-in options.
+
+## More Examples
+
+For additional examples including authentication, HTTP clients, and advanced features:
+
+- [All Examples](https://github.com/leehack/mcp_dart/tree/main/example)
+- [Authentication Examples](https://github.com/leehack/mcp_dart/tree/main/example/authentication)
+
+## Community & Support
 
-<https://github.com/leehack/mcp_dart/tree/main/example>
+- **Issues & Bug Reports**: [GitHub Issues](https://github.com/leehack/mcp_dart/issues)
+- **Package**: [pub.dev/packages/mcp_dart](https://pub.dev/packages/mcp_dart)
+- **Protocol Spec**: [MCP Specification](https://modelcontextprotocol.io/specification/2025-06-18)
 
 ## Credits