Adding MCP Annotation and MCP Generator

README.md

@@ -8,10 +8,14 @@ A general repository for AI / GenAI packages and explorations.
 | --- | --- | --- | --- |
 | [dart_mcp](pkgs/dart_mcp/) | A package for making MCP servers and clients. | ![issues][dart_mcp_issues] | [![pub package](https://img.shields.io/pub/v/dart_mcp.svg)](https://pub.dev/packages/dart_mcp) |
 | [dart_tooling_mcp_server](pkgs/dart_tooling_mcp_server/) | An MCP server for Dart projects, exposing various developer tools to AI models. | ![issues][dart_tooling_mcp_server_issues] | n/a |
+| [mcp_annotations](pkgs/mcp_annotations/) | A package containing annotations for declaring MCP tools and servers. | ![issues][mcp_annotations_issues] | n/a |
+| [mcp_codegen](pkgs/mcp_codegen/) | A Builder/code generator that produces MCP tool and server implementations from annotated Dart code. | ![issues][mcp_codegen_issues] | n/a |
 
 
 [dart_mcp_issues]: https://img.shields.io/github/issues-search?label=issues&query=is%3Aissue+is%3Aopen+label%3Apackage%3Adart_mcp+repo%3Adart-lang/ai
 [dart_tooling_mcp_server_issues]: https://img.shields.io/github/issues-search?label=issues&query=is%3Aissue+is%3Aopen+label%3Apackage%3Adart_tooling_mcp_server+repo%3Adart-lang/ai
+[mcp_annotations_issues]: https://img.shields.io/github/issues-search?label=issues&query=is%3Aissue+is%3Aopen+label%3Apackage%3Amcp_annotations+repo%3Adart-lang/ai
+[mcp_codegen_issues]: https://img.shields.io/github/issues-search?label=issues&query=is%3Aissue+is%3Aopen+label%3Apackage%3Amcp_codegen+repo%3Adart-lang/ai
 
 <!--
 ## Publishing automation

examples/demo_server/bin/main.dart

@@ -0,0 +1,26 @@
+// ignore_for_file: unused_import
+
+import 'package:mcp_annotations/mcp_annotations.dart';
+import 'dart:convert';
+import 'package:stream_channel/stream_channel.dart';
+import 'package:async/async.dart';
+import 'package:dart_mcp/server.dart';
+import 'dart:io';
+import 'dart:async';
+
+part 'main.mcp.g.dart';
+
+@MCPServerApp(name: 'demo_server', version: '0.1.0')
+class MCPDemoServer {
+  const MCPDemoServer();
+
+  @MCPTool(description: "add two numbers")
+  num add(num a, num b) {
+    return a + b;
+  }
+}
+
+void main(List<String> args) {
+  final server = MCPDemoServer();
+  server.run(args);
+}

examples/demo_server/build.yaml

@@ -0,0 +1,7 @@
+targets:
+  $default:
+    builders:
+      mcp_codegen|mcp_builder:
+        generate_for:
+          - lib/**.dart
+          - bin/**.dart 

examples/demo_server/pubspec.yaml

@@ -0,0 +1,24 @@
+name: demo_server
+version: 0.1.0
+publish_to: none
+description: Example package demonstrating MCP annotations and code generation.
+
+environment:
+  sdk: '>=3.2.0 <4.0.0'
+
+dependencies:
+  dart_mcp: ^0.2.0
+  mcp_annotations: ^0.1.0
+
+
+dev_dependencies:
+  build_runner: ^2.4.7
+  mcp_codegen: ^0.1.0
+
+dependency_overrides:
+  mcp_annotations:
+    path: ../../pkgs/mcp_annotations
+  dart_mcp:
+    path: ../../pkgs/dart_mcp
+  mcp_codegen:
+    path: ../../pkgs/mcp_codegen

pkgs/mcp_annotations/CHANGELOG.md

@@ -0,0 +1,6 @@
+## 0.1.0
+
+- Initial release of the MCP annotations package.
+- Provides annotations for MCP server implementations.
+- Includes support for basic MCP protocol features.
+- APIs may change frequently until the 1.0.0 release based on feedback and usage patterns.

pkgs/mcp_annotations/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2025, the Dart project authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

pkgs/mcp_annotations/README.md

@@ -0,0 +1,60 @@
+# MCP Annotations
+
+A lightweight annotation library for declaring [Model Context Protocol](https://modelcontextprotocol.io) (MCP) servers, tools, and parameter metadata in pure Dart.
+
+This package is **build-time only** – it contains no runtime dependencies and should be included as a regular `dependencies:` entry in your `pubspec.yaml` alongside [`mcp_codegen`](../mcp_codegen/).
+
+---
+
+## Getting started
+
+```yaml
+# pubspec.yaml
+name: my_app
+# ...
+dependencies:
+  mcp_annotations: ^0.1.0
+  # Only required during development / code-gen – omit on publish.
+  build_runner: ^2.4.0
+  mcp_codegen: ^0.1.0
+```
+
+1. Add the annotations and generator to your project as shown above.
+2. Annotate your functions, methods, or `main()` entry-point.
+3. Run `dart run build_runner build` (or `watch`) to generate the MCP server / tool boilerplate.
+
+## Available annotations
+
+| Annotation | Use-case |
+| --- | --- |
+| `@MCPTool` | Marks a top-level function or static method as an MCP *tool*. Optional fields let you override the tool name, description, and parameter metadata. |
+| `@MCPParameter` | Provides richer metadata (title / description) for an individual parameter defined in a `@MCPTool`. |
+| `@MCPServerApp` | Marks a **class or top-level function** as the entry-point for an MCP *server*. The generator emits a concrete `MCPServer` subclass, bootstrap helpers, and – for classes – an extension `run()` method for easy launching. |
+
+See the API docs for the full list of fields and defaults.
+
+## Example
+
+```dart
+import 'package:mcp_annotations/mcp_annotations.dart';
+
+@MCPServerApp(name: 'demo_server', version: '0.1.0')
+class MCPDemoServer {
+  const MCPDemoServer();
+
+  @MCPTool(description: 'Adds two numbers.')
+  num add(num a, num b) => a + b;
+}
+
+void main(List<String> args) {
+  final server = MCPDemoServer();
+  server.run(args);
+}
+```
+
+
+You can now compile the generated server and use it with any MCP-compatible client.
+
+## Contributing
+
+Contributions are welcome!  Please read the [CONTRIBUTING.md](../../CONTRIBUTING.md) guide before submitting a pull-request. 

pkgs/mcp_annotations/lib/mcp_annotations.dart

@@ -0,0 +1,83 @@
+// Copyright (c) 2023, the Dart project authors.  Please see the AUTHORS file
+// for details. All rights reserved. Use of this source code is governed by a
+// BSD-style license that can be found in the LICENSE file.
+
+library mcp_annotations;
+
+/// Marks a top-level function or static method as an MCP tool.
+///
+/// The generator uses the annotation data to create a [Tool] description
+/// and the corresponding handler code.
+class MCPTool {
+  const MCPTool({
+    this.name,
+    this.description,
+    this.destructiveHint,
+    this.idempotentHint,
+    this.openWorldHint,
+    this.readOnlyHint,
+    this.title,
+    this.parameters,
+  });
+
+  /// Override the default tool name (defaults to the Dart identifier).
+  final String? name;
+
+  /// Human-readable description shown to the LLM.
+  final String? description;
+
+  /// Optional hint fields forwarded to [ToolAnnotations].
+  final bool? destructiveHint;
+  final bool? idempotentHint;
+  final bool? openWorldHint;
+  final bool? readOnlyHint;
+  final String? title;
+
+  /// Optional rich metadata about individual parameters.
+  ///
+  /// When provided, the generator uses this to populate `title` and
+  /// `description` on the generated JSON-Schema for the corresponding input
+  /// field.  It is perfectly safe to omit or partially fill this list — any
+  /// parameter without a matching entry just falls back to the simple schema
+  /// based on its Dart type.
+  final List<MCPParameter>? parameters;
+}
+
+/// Additional metadata for an individual parameter in an [MCPTool].
+///
+/// Only [name] is required; everything else is optional.
+class MCPParameter {
+  const MCPParameter({
+    required this.name,
+    this.title,
+    this.description,
+  });
+
+  /// The Dart parameter identifier this metadata applies to.
+  final String name;
+
+  /// A short human-readable label to show in UIs.
+  final String? title;
+
+  /// Longer explanation of the parameter.
+  final String? description;
+}
+
+/// Marks a class as an MCP server application. The generator will emit a concrete
+/// [MCPServer] subclass and bootstrap code in a companion file.
+class MCPServerApp {
+  const MCPServerApp({
+    required this.name,
+    required this.version,
+    this.instructions,
+  });
+
+  /// Name reported to the client.
+  final String name;
+
+  /// Version reported to the client.
+  final String version;
+
+  /// Optional usage instructions forwarded to the client.
+  final String? instructions;
+}

pkgs/mcp_annotations/pubspec.yaml

@@ -0,0 +1,9 @@
+name: mcp_annotations
+version: 0.1.0
+description: Annotations for generating MCP server boilerplate and tools.
+
+environment:
+  sdk: ^3.7.0
+
+dependencies:
+  meta: ^1.11.0

pkgs/mcp_codegen/CHANGELOG.md

@@ -0,0 +1,7 @@
+## 0.1.0
+
+- Initial release of the MCP code generation package.
+- Supports generating MCP server boilerplate code from annotated classes.
+- Provides code generation for MCP server implementations.
+- Includes support for basic MCP protocol features.
+- APIs may change frequently until the 1.0.0 release based on feedback and usage patterns.

pkgs/mcp_codegen/LICENSE

@@ -0,0 +1,27 @@
+Copyright 2025, the Dart project authors.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+    * Redistributions of source code must retain the above copyright
+      notice, this list of conditions and the following disclaimer.
+    * Redistributions in binary form must reproduce the above
+      copyright notice, this list of conditions and the following
+      disclaimer in the documentation and/or other materials provided
+      with the distribution.
+    * Neither the name of Google LLC nor the names of its
+      contributors may be used to endorse or promote products derived
+      from this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.