From 774bd023cf4563b36b3d0738489dc68113f31fdc Mon Sep 17 00:00:00 2001
From: Nelson Campos <nelson.campos@cloudwalk.io>
Date: Sat, 10 May 2025 14:06:45 -0300
Subject: [PATCH 01/10] Add MCP annotations and code generation packages

- Introduced `mcp_annotations` for declaring MCP tools and servers with annotations.
- Added `mcp_codegen` for generating boilerplate code from annotations.
- Updated README to include new packages and their descriptions.
- Created a demo server example showcasing the use of MCP annotations and code generation.
- Added build configuration for the code generation process.
---
 README.md                                     |   4 +
 examples/demo_server/bin/main.dart            |  41 ++
 examples/demo_server/bin/main.mcp.g.dart      | 116 ++++++
 examples/demo_server/build.yaml               |   7 +
 examples/demo_server/pubspec.yaml             |  20 +
 pkgs/mcp_annotations/README.md                |  60 +++
 pkgs/mcp_annotations/lib/mcp_annotations.dart |  79 ++++
 pkgs/mcp_annotations/pubspec.yaml             |  10 +
 pkgs/mcp_codegen/README.md                    |  63 +++
 pkgs/mcp_codegen/build.yaml                   |   8 +
 pkgs/mcp_codegen/lib/mcp_codegen.dart         |  10 +
 pkgs/mcp_codegen/lib/src/mcp_generator.dart   | 378 ++++++++++++++++++
 pkgs/mcp_codegen/pubspec.yaml                 |  23 ++
 13 files changed, 819 insertions(+)
 create mode 100644 examples/demo_server/bin/main.dart
 create mode 100644 examples/demo_server/bin/main.mcp.g.dart
 create mode 100644 examples/demo_server/build.yaml
 create mode 100644 examples/demo_server/pubspec.yaml
 create mode 100644 pkgs/mcp_annotations/README.md
 create mode 100644 pkgs/mcp_annotations/lib/mcp_annotations.dart
 create mode 100644 pkgs/mcp_annotations/pubspec.yaml
 create mode 100644 pkgs/mcp_codegen/README.md
 create mode 100644 pkgs/mcp_codegen/build.yaml
 create mode 100644 pkgs/mcp_codegen/lib/mcp_codegen.dart
 create mode 100644 pkgs/mcp_codegen/lib/src/mcp_generator.dart
 create mode 100644 pkgs/mcp_codegen/pubspec.yaml

diff --git a/README.md b/README.md
index fabb6426..3eb66e25 100644
--- a/README.md
+++ b/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
diff --git a/examples/demo_server/bin/main.dart b/examples/demo_server/bin/main.dart
new file mode 100644
index 00000000..557a9b46
--- /dev/null
+++ b/examples/demo_server/bin/main.dart
@@ -0,0 +1,41 @@
+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 {
+  @MCPTool(
+    description: 'Adds two numbers.',
+    parameters: [
+      MCPParameter(name: 'a', description: 'The first number to add.'),
+      MCPParameter(name: 'b', description: 'The second number to add.'),
+    ],
+  )
+  num add(num a, num b) {
+    return a + b;
+  }
+
+  @MCPTool(
+    description: 'Returns the length of a string.',
+    parameters: [
+      MCPParameter(
+        name: 'text',
+        description: 'The string to get the length of.',
+      ),
+    ],
+  )
+  int strlen(String text) {
+    return text.length;
+  }
+}
+
+void main(List<String> args) {
+  final server = MCPDemoServer();
+  server.run(args);
+}
diff --git a/examples/demo_server/bin/main.mcp.g.dart b/examples/demo_server/bin/main.mcp.g.dart
new file mode 100644
index 00000000..8d6e3082
--- /dev/null
+++ b/examples/demo_server/bin/main.mcp.g.dart
@@ -0,0 +1,116 @@
+// GENERATED CODE - DO NOT MODIFY BY HAND
+
+part of 'main.dart';
+
+// **************************************************************************
+// MCPGenerator
+// **************************************************************************
+
+// GENERATED CODE - DO NOT MODIFY BY HAND
+// ignore_for_file: unused_element, unused_import, unnecessary_cast
+
+final Tool _tool_add = Tool(
+  name: 'add',
+  description: 'Adds two numbers.',
+  inputSchema: ObjectSchema(
+    properties: {
+      'a': NumberSchema(description: 'The first number to add.'),
+      'b': NumberSchema(description: 'The second number to add.'),
+    },
+    required: ['a', 'b'],
+  ),
+  annotations: null,
+);
+
+FutureOr<CallToolResult> _handler_add(
+    MCPDemoServer _impl, CallToolRequest _request) async {
+  final _args = _request.arguments ?? const <String, Object?>{};
+  final num a = _args['a'] as num;
+  final num b = _args['b'] as num;
+  final _result = await Future.sync(() => _impl.add(a, b));
+  return CallToolResult(content: [TextContent(text: _result.toString())]);
+}
+
+final Tool _tool_strlen = Tool(
+  name: 'strlen',
+  description: 'Returns the length of a string.',
+  inputSchema: ObjectSchema(
+    properties: {
+      'text': StringSchema(description: 'The string to get the length of.'),
+    },
+    required: ['text'],
+  ),
+  annotations: null,
+);
+
+FutureOr<CallToolResult> _handler_strlen(
+    MCPDemoServer _impl, CallToolRequest _request) async {
+  final _args = _request.arguments ?? const <String, Object?>{};
+  final String text = _args['text'] as String;
+  final _result = await Future.sync(() => _impl.strlen(text));
+  return CallToolResult(content: [TextContent(text: _result.toString())]);
+}
+
+final class _GeneratedServer extends MCPServer
+    with LoggingSupport, ToolsSupport, ResourcesSupport, RootsTrackingSupport {
+  final MCPDemoServer _impl;
+  _GeneratedServer(super.channel, this._impl)
+      : super.fromStreamChannel(
+          implementation:
+              ServerImplementation(name: 'demo_server', version: '0.1.0'),
+          instructions: '',
+        );
+
+  @override
+  FutureOr<InitializeResult> initialize(InitializeRequest request) {
+    registerTool(_tool_add, (r) => _handler_add(_impl, r));
+    registerTool(_tool_strlen, (r) => _handler_strlen(_impl, r));
+    return super.initialize(request);
+  }
+}
+
+Future<void> _runGeneratedMcpServer(
+    List<String> args, MCPDemoServer _impl) async {
+  _GeneratedServer? server;
+  await runZonedGuarded(
+    () async {
+      final channel = StreamChannel.withCloseGuarantee(stdin, stdout)
+          .transform(StreamChannelTransformer.fromCodec(utf8))
+          .transformStream(const LineSplitter())
+          .transformSink(
+        StreamSinkTransformer.fromHandlers(
+          handleData: (data, sink) {
+            sink.add('$data\n');
+          },
+        ),
+      );
+
+      server = _GeneratedServer(channel, _impl);
+    },
+    (e, s) {
+      if (server != null) {
+        try {
+          server!.log(LoggingLevel.error, '$e\n$s');
+        } catch (_) {}
+      } else {
+        stderr
+          ..writeln(e)
+          ..writeln(s);
+      }
+    },
+    zoneSpecification: ZoneSpecification(
+      print: (_, __, ___, value) {
+        if (server != null) {
+          try {
+            server!.log(LoggingLevel.info, value);
+          } catch (_) {}
+        }
+      },
+    ),
+  );
+}
+// Call `_runGeneratedMcpServer(args);` from your annotated main().
+
+extension _MCPDemoServerRunner on MCPDemoServer {
+  Future<void> run(List<String> args) => _runGeneratedMcpServer(args, this);
+}
diff --git a/examples/demo_server/build.yaml b/examples/demo_server/build.yaml
new file mode 100644
index 00000000..d3861f42
--- /dev/null
+++ b/examples/demo_server/build.yaml
@@ -0,0 +1,7 @@
+targets:
+  $default:
+    builders:
+      mcp_codegen|mcp_builder:
+        generate_for:
+          - lib/**.dart
+          - bin/**.dart 
\ No newline at end of file
diff --git a/examples/demo_server/pubspec.yaml b/examples/demo_server/pubspec.yaml
new file mode 100644
index 00000000..458b619a
--- /dev/null
+++ b/examples/demo_server/pubspec.yaml
@@ -0,0 +1,20 @@
+name: fast_mcp_demo
+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:
+    path: ../../pkgs/dart_mcp
+  mcp_annotations:
+    path: ../../pkgs/mcp_annotations
+
+
+dev_dependencies:
+  build_runner: ^2.4.7
+  mcp_codegen:
+    path: ../../pkgs/mcp_codegen
+  
\ No newline at end of file
diff --git a/pkgs/mcp_annotations/README.md b/pkgs/mcp_annotations/README.md
new file mode 100644
index 00000000..d355a6d9
--- /dev/null
+++ b/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. 
\ No newline at end of file
diff --git a/pkgs/mcp_annotations/lib/mcp_annotations.dart b/pkgs/mcp_annotations/lib/mcp_annotations.dart
new file mode 100644
index 00000000..39f54b92
--- /dev/null
+++ b/pkgs/mcp_annotations/lib/mcp_annotations.dart
@@ -0,0 +1,79 @@
+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;
+}
diff --git a/pkgs/mcp_annotations/pubspec.yaml b/pkgs/mcp_annotations/pubspec.yaml
new file mode 100644
index 00000000..143327e5
--- /dev/null
+++ b/pkgs/mcp_annotations/pubspec.yaml
@@ -0,0 +1,10 @@
+name: mcp_annotations
+version: 0.1.0-wip
+description: Annotations for generating MCP server boilerplate and tools.
+publish_to: none
+
+environment:
+  sdk: ^3.7.0
+
+dependencies:
+  meta: ^1.11.0
\ No newline at end of file
diff --git a/pkgs/mcp_codegen/README.md b/pkgs/mcp_codegen/README.md
new file mode 100644
index 00000000..f7b0ff96
--- /dev/null
+++ b/pkgs/mcp_codegen/README.md
@@ -0,0 +1,63 @@
+# MCP Codegen
+
+[![Dart Build Status](https://img.shields.io/github/actions/workflow/status/dart-lang/ai/dart.yml?label=build)](https://github.com/dart-lang/ai/actions)
+
+A [build_runner](https://pub.dev/packages/build_runner) generator that turns
+`mcp_annotations` into concrete Model Context Protocol implementations.
+
+Given a Dart package that uses `@MCPTool` or `@MCPServerApp` from
+[`mcp_annotations`](../mcp_annotations/), this builder produces:
+
+* **JSON tool descriptors** that can be read by any MCP-compatible client.
+* **Handler stubs** that route an MCP invocation to your annotated Dart
+  function.
+* **Boot-strapped MCPServer** subclasses that wire everything together.
+
+---
+
+## Installing
+
+Add the generator and its companion annotations package to your project:
+
+```yaml
+# pubspec.yaml
+name: my_app
+# ...
+dependencies:
+  mcp_annotations: ^0.1.0
+
+dev_dependencies:
+  build_runner: ^2.4.0
+  mcp_codegen: ^0.1.0
+```
+
+> **Note** – `mcp_codegen` should *only* appear under `dev_dependencies` as it is
+> never used at runtime.
+
+## Running the generator
+
+```shell
+# One-off build
+$ dart run build_runner build
+
+# Continuous build
+$ dart run build_runner watch
+```
+
+## Configuration
+
+The generator exposes a single option, `output_extensions`, allowing you to
+change the suffix for generated files.  The default is `.mcp.g.dart`.
+
+```yaml
+# build.yaml
+builders:
+  mcp_codegen|mcpBuilder:
+    options:
+      output_extensions: '.my_mcp.g.dart'
+```
+
+## Contributing
+
+Please see the top-level [CONTRIBUTING.md](../../CONTRIBUTING.md) file for
+guidance on how to file bugs and submit pull-requests. 
\ No newline at end of file
diff --git a/pkgs/mcp_codegen/build.yaml b/pkgs/mcp_codegen/build.yaml
new file mode 100644
index 00000000..90004a2a
--- /dev/null
+++ b/pkgs/mcp_codegen/build.yaml
@@ -0,0 +1,8 @@
+builders:
+  mcp_builder:
+    import: "package:mcp_codegen/mcp_codegen.dart"
+    builder_factories: ["mcpBuilder"]
+    build_extensions: {".dart": [".mcp.g.dart"]}
+    auto_apply: dependents
+    build_to: source
+    applies_builders: ["source_gen|combining_builder"] 
\ No newline at end of file
diff --git a/pkgs/mcp_codegen/lib/mcp_codegen.dart b/pkgs/mcp_codegen/lib/mcp_codegen.dart
new file mode 100644
index 00000000..56079555
--- /dev/null
+++ b/pkgs/mcp_codegen/lib/mcp_codegen.dart
@@ -0,0 +1,10 @@
+library mcp_codegen;
+
+import 'package:build/build.dart';
+import 'package:source_gen/source_gen.dart';
+
+import 'src/mcp_generator.dart';
+
+Builder mcpBuilder(BuilderOptions options) {
+  return PartBuilder([MCPGenerator()], '.mcp.g.dart');
+}
diff --git a/pkgs/mcp_codegen/lib/src/mcp_generator.dart b/pkgs/mcp_codegen/lib/src/mcp_generator.dart
new file mode 100644
index 00000000..330312b3
--- /dev/null
+++ b/pkgs/mcp_codegen/lib/src/mcp_generator.dart
@@ -0,0 +1,378 @@
+import 'dart:async';
+import 'package:analyzer/dart/element/element.dart';
+import 'package:analyzer/dart/constant/value.dart';
+import 'package:build/build.dart';
+import 'package:mcp_annotations/mcp_annotations.dart';
+import 'package:source_gen/source_gen.dart';
+
+class MCPGenerator extends Generator {
+  static final _mcpToolChecker = TypeChecker.fromRuntime(MCPTool);
+  static final _mcpServerChecker = TypeChecker.fromRuntime(MCPServerApp);
+
+  /// HELPER: iterate top level functions in a [LibraryElement].
+  Iterable<FunctionElement> _topLevelFunctions(LibraryElement lib) sync* {
+    for (final unit in lib.units) {
+      for (final func in unit.functions) {
+        yield func;
+      }
+    }
+  }
+
+  /// HELPER: iterate all classes in a [LibraryElement].
+  Iterable<ClassElement> _classes(LibraryElement lib) sync* {
+    for (final unit in lib.units) {
+      for (final clazz in unit.classes) {
+        yield clazz;
+      }
+    }
+  }
+
+  @override
+  FutureOr<String?> generate(LibraryReader library, BuildStep buildStep) {
+    final serverAnnotatedElements = <Element, DartObject>{};
+
+    for (final annotated in _topLevelFunctions(library.element)) {
+      final annotation = _mcpServerChecker.firstAnnotationOfExact(annotated);
+      if (annotation != null) {
+        serverAnnotatedElements[annotated] = annotation;
+      }
+    }
+
+    for (final clazz in _classes(library.element)) {
+      final annotation = _mcpServerChecker.firstAnnotationOfExact(clazz);
+      if (annotation != null) {
+        serverAnnotatedElements[clazz] = annotation;
+      }
+    }
+
+    if (serverAnnotatedElements.isEmpty) return null;
+
+    // Currently support exactly one per library for simplicity.
+    if (serverAnnotatedElements.length > 1) {
+      log.warning(
+        'Multiple @MCPServerApp annotations found in ${library.element.source.uri}. '
+        'Only the first one will be used.',
+      );
+    }
+
+    final serverElement = serverAnnotatedElements.keys.first;
+    final serverAnnotation = serverAnnotatedElements.values.first;
+
+    final serverName =
+        serverAnnotation.getField('name')?.toStringValue() ??
+        serverElement.name;
+    final serverVersion =
+        serverAnnotation.getField('version')?.toStringValue() ?? '0.0.0';
+    final serverInstructions =
+        serverAnnotation.getField('instructions')?.toStringValue();
+
+    // Collect tool functions within the server context.
+    final toolFunctions = <ExecutableElement, DartObject>{};
+
+    if (serverElement is ClassElement) {
+      for (final method in serverElement.methods) {
+        final ann = _mcpToolChecker.firstAnnotationOfExact(method);
+        if (ann != null) {
+          toolFunctions[method] = ann;
+        }
+      }
+    } else if (serverElement is FunctionElement) {
+      for (final function in _topLevelFunctions(library.element)) {
+        final ann = _mcpToolChecker.firstAnnotationOfExact(function);
+        if (ann != null) {
+          toolFunctions[function] = ann;
+        }
+      }
+    }
+
+    if (toolFunctions.isEmpty) {
+      log.warning(
+        'No @MCPTool annotated functions found in '
+        '${library.element.source.uri}. The generated server will have no tools.',
+      );
+    }
+
+    final buffer = StringBuffer();
+    buffer.writeln('// GENERATED CODE - DO NOT MODIFY BY HAND');
+    buffer.writeln(
+      '// ignore_for_file: unused_element, unused_import, unnecessary_cast',
+    );
+    buffer.writeln();
+    // No additional imports inside part files (must contain only code).
+    buffer.writeln();
+
+    // Generate per-tool constants & handlers.
+    for (final entry in toolFunctions.entries) {
+      final func = entry.key;
+      final ann = entry.value;
+
+      final toolName = ann.getField('name')?.toStringValue() ?? func.name;
+      final description = ann.getField('description')?.toStringValue();
+
+      // Map of parameter name -> (title, description) from annotation metadata.
+      final _paramMeta = <String, Map<String, String?>>{};
+      final metaList = ann.getField('parameters')?.toListValue();
+      if (metaList != null) {
+        for (final meta in metaList) {
+          final name = meta.getField('name')?.toStringValue();
+          if (name == null) continue;
+          _paramMeta[name] = {
+            'title': meta.getField('title')?.toStringValue(),
+            'description': meta.getField('description')?.toStringValue(),
+          };
+        }
+      }
+
+      final propsBuffer = StringBuffer();
+      final requiredParams = <String>[];
+      for (final param in func.parameters) {
+        final meta = _paramMeta[param.name];
+        final schema = _schemaForParam(
+          param,
+          title: meta?['title'],
+          description: meta?['description'],
+        );
+        propsBuffer.writeln("      '${param.name}': $schema,");
+        if (!param.isOptional) {
+          requiredParams.add("'${param.name}'");
+        }
+      }
+
+      final inputSchemaCode = '''ObjectSchema(
+        properties: {
+${propsBuffer.toString()}        },
+        required: [${requiredParams.join(', ')}],
+      )''';
+
+      // Build ToolAnnotations hints.
+      final hintFields = <String>[];
+      void addHint(String field) {
+        final value = ann.getField(field);
+        if (value == null || value.isNull) return;
+        hintFields.add(
+          '$field: ${value.toBoolValue() ?? value.toStringValue()}',
+        );
+      }
+
+      addHint('destructiveHint');
+      addHint('idempotentHint');
+      addHint('openWorldHint');
+      addHint('readOnlyHint');
+      addHint('title');
+
+      var annotationsCode = 'null';
+      if (hintFields.isNotEmpty) {
+        annotationsCode = 'ToolAnnotations(${hintFields.join(', ')})';
+      }
+
+      buffer
+        ..writeln('final Tool _tool_${func.name} = Tool(')
+        ..writeln("  name: '$toolName',")
+        ..writeln(
+          "  description: ${description != null ? '\'${_escape(description)}\'' : 'null'},",
+        )
+        ..writeln('  inputSchema: $inputSchemaCode,')
+        ..writeln('  annotations: $annotationsCode,')
+        ..writeln(');')
+        ..writeln();
+
+      // Generate handler definition.
+      if (serverElement is ClassElement) {
+        final className = serverElement.name;
+        buffer.writeln('FutureOr<CallToolResult> _handler_${func.name}(');
+        buffer.writeln('  $className _impl, CallToolRequest _request) async {');
+      } else {
+        buffer.writeln(
+          'FutureOr<CallToolResult> _handler_${func.name}(CallToolRequest _request) async {',
+        );
+      }
+
+      buffer.writeln(
+        '  final _args = _request.arguments ?? const <String, Object?>{};',
+      );
+
+      final callArgsList = <String>[];
+      for (final param in func.parameters) {
+        final pName = param.name;
+        final pTypeCode = param.type.getDisplayString(withNullability: false);
+        buffer.writeln(
+          '  final $pTypeCode $pName = _args[\'$pName\'] as $pTypeCode;',
+        );
+        callArgsList.add(pName);
+      }
+
+      final callExpr =
+          serverElement is ClassElement
+              ? '_impl.${func.name}(${callArgsList.join(', ')})'
+              : '${func.name}(${callArgsList.join(', ')})';
+
+      buffer.writeln('  final _result = await Future.sync(() => $callExpr);');
+      buffer.writeln(
+        '  return CallToolResult(content: [TextContent(text: _result.toString())]);',
+      );
+      buffer.writeln('}');
+      buffer.writeln();
+    }
+
+    // Generate server subclass.
+    buffer.writeln(
+      'final class _GeneratedServer extends MCPServer'
+      ' with LoggingSupport, ToolsSupport, ResourcesSupport, RootsTrackingSupport {',
+    );
+
+    if (serverElement is ClassElement) {
+      final className = serverElement.name;
+      buffer.writeln('  final $className _impl;');
+      buffer.writeln('  _GeneratedServer(super.channel, this._impl)');
+    } else {
+      buffer.writeln('  _GeneratedServer(super.channel)');
+    }
+
+    buffer.writeln('      : super.fromStreamChannel(');
+    buffer.writeln(
+      "          implementation: ServerImplementation(name: '$serverName', version: '$serverVersion'),",
+    );
+    buffer.writeln(
+      "          instructions: ${serverInstructions != null ? '\'${_escape(serverInstructions)}\'' : '\'\''},",
+    );
+    buffer.writeln('        );');
+    buffer.writeln();
+
+    // initialize override registers tools then defers to super.
+    buffer.writeln('  @override');
+    buffer.writeln(
+      '  FutureOr<InitializeResult> initialize(InitializeRequest request) {',
+    );
+
+    if (serverElement is ClassElement) {
+      for (final func in toolFunctions.keys) {
+        buffer.writeln(
+          '    registerTool(_tool_${func.name}, (r) => _handler_${func.name}(_impl, r));',
+        );
+      }
+    } else {
+      for (final func in toolFunctions.keys) {
+        buffer.writeln(
+          '    registerTool(_tool_${func.name}, _handler_${func.name});',
+        );
+      }
+    }
+
+    buffer.writeln('    return super.initialize(request);');
+    buffer.writeln('  }');
+    buffer.writeln('}');
+    buffer.writeln();
+
+    // Bootstrap helper that sets up the stdio channel and runs the server in a
+    // guarded zone which forwards uncaught errors and `print` calls to the
+    // client via the logging API when possible.
+
+    if (serverElement is ClassElement) {
+      final className = serverElement.name;
+      buffer.writeln(
+        'Future<void> _runGeneratedMcpServer(List<String> args, $className _impl) async {',
+      );
+    } else {
+      buffer.writeln(
+        'Future<void> _runGeneratedMcpServer(List<String> args) async {',
+      );
+    }
+
+    buffer.writeln('  _GeneratedServer? server;');
+    buffer.writeln('  await runZonedGuarded(');
+    buffer.writeln('    () async {');
+    buffer.writeln(
+      '      final channel = StreamChannel.withCloseGuarantee(stdin, stdout)',
+    );
+    buffer.writeln(
+      '          .transform(StreamChannelTransformer.fromCodec(utf8))',
+    );
+    buffer.writeln('          .transformStream(const LineSplitter())');
+    buffer.writeln('          .transformSink(');
+    buffer.writeln('        StreamSinkTransformer.fromHandlers(');
+    buffer.writeln('          handleData: (data, sink) {');
+    buffer.writeln('            sink.add(\'\$data\\n\');');
+    buffer.writeln('          },');
+    buffer.writeln('        ),');
+    buffer.writeln('      );');
+    buffer.writeln();
+
+    if (serverElement is ClassElement) {
+      buffer.writeln('      server = _GeneratedServer(channel, _impl);');
+    } else {
+      buffer.writeln('      server = _GeneratedServer(channel);');
+    }
+
+    buffer.writeln('    },');
+    buffer.writeln('    (e, s) {');
+    buffer.writeln('      if (server != null) {');
+    buffer.writeln('        try {');
+    buffer.writeln('          server!.log(LoggingLevel.error, \'\$e\\n\$s\');');
+    buffer.writeln('        } catch (_) {}');
+    buffer.writeln('      } else {');
+    buffer.writeln('        stderr');
+    buffer.writeln('          ..writeln(e)');
+    buffer.writeln('          ..writeln(s);');
+    buffer.writeln('      }');
+    buffer.writeln('    },');
+    buffer.writeln('    zoneSpecification: ZoneSpecification(');
+    buffer.writeln('      print: (_, __, ___, value) {');
+    buffer.writeln('        if (server != null) {');
+    buffer.writeln('          try {');
+    buffer.writeln('            server!.log(LoggingLevel.info, value);');
+    buffer.writeln('          } catch (_) {}');
+    buffer.writeln('        }');
+    buffer.writeln('      },');
+    buffer.writeln('    ),');
+    buffer.writeln('  );');
+    buffer.writeln('}');
+
+    // If using class-based server, generate a convenience extension for `run`.
+    if (serverElement is ClassElement) {
+      final className = serverElement.name;
+      buffer.writeln();
+      buffer.writeln('extension _${className}Runner on $className {');
+      buffer.writeln(
+        '  Future<void> run(List<String> args) => _runGeneratedMcpServer(args, this);',
+      );
+      buffer.writeln('}');
+    }
+
+    return buffer.toString();
+  }
+
+  String _escape(String input) => input.replaceAll("'", "\\'");
+
+  String _schemaForParam(
+    ParameterElement param, {
+    String? title,
+    String? description,
+  }) {
+    final type = param.type.getDisplayString(withNullability: false);
+
+    String _args() {
+      final parts = <String>[];
+      if (title != null) parts.add("title: '${_escape(title)}'");
+      if (description != null) {
+        parts.add("description: '${_escape(description)}'");
+      }
+      return parts.isEmpty ? '' : parts.join(', ');
+    }
+
+    final argStr = _args();
+
+    switch (type) {
+      case 'int':
+        return argStr.isEmpty ? 'IntegerSchema()' : 'IntegerSchema($argStr)';
+      case 'double':
+      case 'num':
+        return argStr.isEmpty ? 'NumberSchema()' : 'NumberSchema($argStr)';
+      case 'String':
+        return argStr.isEmpty ? 'StringSchema()' : 'StringSchema($argStr)';
+      case 'bool':
+        return argStr.isEmpty ? 'BooleanSchema()' : 'BooleanSchema($argStr)';
+      default:
+        return argStr.isEmpty ? 'ObjectSchema()' : 'ObjectSchema($argStr)';
+    }
+  }
+}
diff --git a/pkgs/mcp_codegen/pubspec.yaml b/pkgs/mcp_codegen/pubspec.yaml
new file mode 100644
index 00000000..8f62c368
--- /dev/null
+++ b/pkgs/mcp_codegen/pubspec.yaml
@@ -0,0 +1,23 @@
+name: mcp_codegen
+version: 0.1.0-wip
+publish_to: none
+description: >-
+  Source-gen builder that generates boilerplate MCP server and tool code.
+
+environment:
+  sdk: ^3.7.0
+
+dependencies:
+  analyzer: ^6.4.0
+  build: ^2.4.0
+  source_gen: ^1.5.0
+  dart_mcp:
+    path: ../dart_mcp
+  mcp_annotations:
+    path: ../mcp_annotations  
+  meta: ^1.11.0
+
+dev_dependencies:
+  build_runner: ^2.4.7
+  build_test: ^2.2.2 
+

From b61150788a5f8d8d3a406c10dcc9d6947e86ffdd Mon Sep 17 00:00:00 2001
From: Nelson Campos <nelson.campos@cloudwalk.io>
Date: Sat, 10 May 2025 14:28:19 -0300
Subject: [PATCH 02/10] Update files to include copyright

---
 examples/demo_server/bin/main.dart            | 4 ++++
 pkgs/mcp_annotations/lib/mcp_annotations.dart | 4 ++++
 pkgs/mcp_codegen/lib/mcp_codegen.dart         | 4 ++++
 pkgs/mcp_codegen/lib/src/mcp_generator.dart   | 4 ++++
 4 files changed, 16 insertions(+)

diff --git a/examples/demo_server/bin/main.dart b/examples/demo_server/bin/main.dart
index 557a9b46..b7aabcca 100644
--- a/examples/demo_server/bin/main.dart
+++ b/examples/demo_server/bin/main.dart
@@ -1,3 +1,7 @@
+// 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.
+
 import 'package:mcp_annotations/mcp_annotations.dart';
 import 'dart:convert';
 import 'package:stream_channel/stream_channel.dart';
diff --git a/pkgs/mcp_annotations/lib/mcp_annotations.dart b/pkgs/mcp_annotations/lib/mcp_annotations.dart
index 39f54b92..36f1d9a6 100644
--- a/pkgs/mcp_annotations/lib/mcp_annotations.dart
+++ b/pkgs/mcp_annotations/lib/mcp_annotations.dart
@@ -1,3 +1,7 @@
+// 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.
diff --git a/pkgs/mcp_codegen/lib/mcp_codegen.dart b/pkgs/mcp_codegen/lib/mcp_codegen.dart
index 56079555..e7efd9e7 100644
--- a/pkgs/mcp_codegen/lib/mcp_codegen.dart
+++ b/pkgs/mcp_codegen/lib/mcp_codegen.dart
@@ -1,3 +1,7 @@
+// 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_codegen;
 
 import 'package:build/build.dart';
diff --git a/pkgs/mcp_codegen/lib/src/mcp_generator.dart b/pkgs/mcp_codegen/lib/src/mcp_generator.dart
index 330312b3..950305d0 100644
--- a/pkgs/mcp_codegen/lib/src/mcp_generator.dart
+++ b/pkgs/mcp_codegen/lib/src/mcp_generator.dart
@@ -1,3 +1,7 @@
+// 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.
+
 import 'dart:async';
 import 'package:analyzer/dart/element/element.dart';
 import 'package:analyzer/dart/constant/value.dart';

From f06be20a39bdbf942cea0fc6cad97134f49a30b1 Mon Sep 17 00:00:00 2001
From: Nelson Campos <nelson.campos@cloudwalk.io>
Date: Sat, 10 May 2025 14:28:52 -0300
Subject: [PATCH 03/10] Rename demo server package from `fast_mcp_demo` to
 `demo_server` in pubspec.yaml

---
 examples/demo_server/pubspec.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/demo_server/pubspec.yaml b/examples/demo_server/pubspec.yaml
index 458b619a..26b3dc50 100644
--- a/examples/demo_server/pubspec.yaml
+++ b/examples/demo_server/pubspec.yaml
@@ -1,4 +1,4 @@
-name: fast_mcp_demo
+name: demo_server
 version: 0.1.0
 publish_to: none
 description: Example package demonstrating MCP annotations and code generation.

From fc7c39c77ee14853f93d377d086c257aef812072 Mon Sep 17 00:00:00 2001
From: Nelson Campos <nelson.campos@cloudwalk.io>
Date: Sat, 10 May 2025 14:38:32 -0300
Subject: [PATCH 04/10] Refactor MCPDemoServer class in main.dart

- Simplified the constructor of MCPDemoServer to a constant constructor.
- Streamlined the add method to use a concise arrow function for better readability.
---
 examples/demo_server/bin/main.dart | 14 ++++----------
 1 file changed, 4 insertions(+), 10 deletions(-)

diff --git a/examples/demo_server/bin/main.dart b/examples/demo_server/bin/main.dart
index b7aabcca..593665d3 100644
--- a/examples/demo_server/bin/main.dart
+++ b/examples/demo_server/bin/main.dart
@@ -14,16 +14,10 @@ part 'main.mcp.g.dart';
 
 @MCPServerApp(name: 'demo_server', version: '0.1.0')
 class MCPDemoServer {
-  @MCPTool(
-    description: 'Adds two numbers.',
-    parameters: [
-      MCPParameter(name: 'a', description: 'The first number to add.'),
-      MCPParameter(name: 'b', description: 'The second number to add.'),
-    ],
-  )
-  num add(num a, num b) {
-    return a + b;
-  }
+  const MCPDemoServer();
+
+  @MCPTool(description: 'Adds two numbers.')
+  num add(num a, num b) => a + b;
 
   @MCPTool(
     description: 'Returns the length of a string.',

From 5c409d3900e0e70a58a547745a203e0e8a29dede Mon Sep 17 00:00:00 2001
From: Nelson Campos <nelson.campos@cloudwalk.io>
Date: Sat, 10 May 2025 16:03:24 -0300
Subject: [PATCH 05/10] Implement MCP code generation framework

- Introduced a new code generation framework for MCP servers and tools.
- Added `HandlerBuilder`, `ServerBuilder`, `SchemaBuilder`, and `CodeEmitter` classes to facilitate the generation of server and tool code.
- Implemented `AnnotationScanner` and `ToolScanner` for scanning libraries for MCP annotations.
- Refactored `MCPGenerator` to utilize the new builders and scanners for cleaner code generation.
- Added utility methods for handling annotations and generating schemas for tool parameters.
---
 .../lib/src/builders/handler_builder.dart     |  60 +++
 .../lib/src/builders/schema_builder.dart      |  53 +++
 .../lib/src/builders/server_builder.dart      |  99 +++++
 .../lib/src/emitter/code_emitter.dart         |  47 +++
 pkgs/mcp_codegen/lib/src/mcp_generator.dart   | 390 ++----------------
 .../lib/src/scanners/annotation_scanner.dart  |  25 ++
 .../lib/src/scanners/tool_scanner.dart        |  41 ++
 .../lib/src/utils/annotation_utils.dart       |  19 +
 8 files changed, 370 insertions(+), 364 deletions(-)
 create mode 100644 pkgs/mcp_codegen/lib/src/builders/handler_builder.dart
 create mode 100644 pkgs/mcp_codegen/lib/src/builders/schema_builder.dart
 create mode 100644 pkgs/mcp_codegen/lib/src/builders/server_builder.dart
 create mode 100644 pkgs/mcp_codegen/lib/src/emitter/code_emitter.dart
 create mode 100644 pkgs/mcp_codegen/lib/src/scanners/annotation_scanner.dart
 create mode 100644 pkgs/mcp_codegen/lib/src/scanners/tool_scanner.dart
 create mode 100644 pkgs/mcp_codegen/lib/src/utils/annotation_utils.dart

diff --git a/pkgs/mcp_codegen/lib/src/builders/handler_builder.dart b/pkgs/mcp_codegen/lib/src/builders/handler_builder.dart
new file mode 100644
index 00000000..411b04af
--- /dev/null
+++ b/pkgs/mcp_codegen/lib/src/builders/handler_builder.dart
@@ -0,0 +1,60 @@
+// Copyright (c) 2023, the Dart project authors.
+// See the AUTHORS file for details. All rights reserved.
+// Use of this source code is governed by a BSD-style license in the LICENSE file.
+
+import 'package:analyzer/dart/constant/value.dart';
+import 'package:analyzer/dart/element/element.dart';
+
+import 'schema_builder.dart';
+
+/// Creates handler functions and their corresponding `Tool` declarations for
+/// each tool method or top-level function.
+class HandlerBuilder {
+  String build(ExecutableElement func, DartObject ann, bool isClass) {
+    final params = func.parameters
+        .map(
+          (p) =>
+              "final ${p.type.getDisplayString(withNullability: false)} ${p.name} = _args['${p.name}'] as ${p.type.getDisplayString(withNullability: false)};",
+        )
+        .join('\\n    ');
+
+    final call =
+        isClass
+            ? '_impl.${func.name}(${func.parameters.map((p) => p.name).join(', ')})'
+            : '${func.name}(${func.parameters.map((p) => p.name).join(', ')})';
+
+    return '''final Tool _tool_${func.name} = Tool(
+  name: '${ann.getField('name')?.toStringValue() ?? func.name}',
+  description: ${ann.getField('description')?.toStringValue() != null ? "'${ann.getField('description')!.toStringValue()}'" : 'null'},
+  inputSchema: ${SchemaBuilder().build(func.parameters, ann.getField('parameters')?.toListValue())},
+  annotations: ${_buildAnnotations(ann)},
+);
+
+FutureOr<CallToolResult> _handler_${func.name}(${isClass ? '${func.enclosingElement.name} _impl, ' : ''}CallToolRequest _request) async {
+    final _args = _request.arguments ?? const <String, Object?>{};
+    $params
+    final _result = await Future.sync(() => $call);
+    return CallToolResult(content: [TextContent(text: _result.toString())]);
+}''';
+  }
+
+  String _buildAnnotations(DartObject ann) {
+    final flags = [
+      'destructiveHint',
+      'idempotentHint',
+      'openWorldHint',
+      'readOnlyHint',
+      'title',
+    ];
+
+    final entries = <String>[];
+    for (var flag in flags) {
+      final v = ann.getField(flag);
+      if (v != null && !v.isNull) {
+        final val = v.toBoolValue() ?? v.toStringValue();
+        entries.add('$flag: $val');
+      }
+    }
+    return entries.isEmpty ? 'null' : 'ToolAnnotations(${entries.join(', ')})';
+  }
+}
diff --git a/pkgs/mcp_codegen/lib/src/builders/schema_builder.dart b/pkgs/mcp_codegen/lib/src/builders/schema_builder.dart
new file mode 100644
index 00000000..23315f9d
--- /dev/null
+++ b/pkgs/mcp_codegen/lib/src/builders/schema_builder.dart
@@ -0,0 +1,53 @@
+// Copyright (c) 2023, the Dart project authors.
+// See the AUTHORS file for details. All rights reserved.
+// Use of this source code is governed by a BSD-style license in the LICENSE file.
+
+import 'package:analyzer/dart/constant/value.dart';
+import 'package:analyzer/dart/element/element.dart';
+
+/// Builds a JSON schema representation for a list of [ParameterElement]s.
+class SchemaBuilder {
+  String build(List<ParameterElement> params, List<DartObject>? meta) {
+    final props = <String>[];
+    final required = <String>[];
+    final paramMeta = {
+      for (var m in meta ?? []) m.getField('name')?.toStringValue(): m,
+    };
+
+    for (var p in params) {
+      final m = paramMeta[p.name];
+      final title = m?.getField('title')?.toStringValue();
+      final desc = m?.getField('description')?.toStringValue();
+      props.add(
+        "'${p.name}': ${_schemaFor(p.type.getDisplayString(withNullability: false), title, desc)}",
+      );
+      if (!p.isOptional) required.add("'${p.name}'");
+    }
+
+    return '''ObjectSchema(
+      properties: {${props.join(', ')}},
+      required: [${required.join(', ')}],
+    )''';
+  }
+
+  String _schemaFor(String type, String? title, String? description) {
+    final args = [
+      if (title != null) "title: '$title'",
+      if (description != null) "description: '$description'",
+    ];
+    final argStr = args.isEmpty ? '' : args.join(', ');
+    switch (type) {
+      case 'int':
+        return 'IntegerSchema($argStr)';
+      case 'double':
+      case 'num':
+        return 'NumberSchema($argStr)';
+      case 'String':
+        return 'StringSchema($argStr)';
+      case 'bool':
+        return 'BooleanSchema($argStr)';
+      default:
+        return 'ObjectSchema($argStr)';
+    }
+  }
+}
diff --git a/pkgs/mcp_codegen/lib/src/builders/server_builder.dart b/pkgs/mcp_codegen/lib/src/builders/server_builder.dart
new file mode 100644
index 00000000..6077a7ed
--- /dev/null
+++ b/pkgs/mcp_codegen/lib/src/builders/server_builder.dart
@@ -0,0 +1,99 @@
+// Copyright (c) 2023, the Dart project authors.
+// See the AUTHORS file for details. All rights reserved.
+// Use of this source code is governed by a BSD-style license in the LICENSE file.
+
+import 'package:analyzer/dart/constant/value.dart';
+import 'package:analyzer/dart/element/element.dart';
+
+class ServerBuilder {
+  String build({
+    required Element serverElement,
+    required DartObject annotation,
+    required List<ExecutableElement> tools,
+  }) {
+    final isClass = serverElement is ClassElement;
+    final name =
+        annotation.getField('name')?.toStringValue() ?? serverElement.name;
+    final version = annotation.getField('version')?.toStringValue() ?? '0.0.0';
+    final instructions =
+        annotation.getField('instructions')?.toStringValue() ?? '';
+
+    final buffer =
+        StringBuffer()
+          ..writeln(
+            'final class _GeneratedServer extends MCPServer with LoggingSupport, ToolsSupport, ResourcesSupport, RootsTrackingSupport {',
+          )
+          ..write(
+            isClass
+                ? '  final ${serverElement.name} _impl;\n  _GeneratedServer(super.channel, this._impl)'
+                : '  _GeneratedServer(super.channel)',
+          )
+          ..writeln('      : super.fromStreamChannel(')
+          ..writeln(
+            "          implementation: ServerImplementation(name: '$name', version: '$version'),",
+          )
+          ..writeln("          instructions: '$instructions',")
+          ..writeln('        );')
+          ..writeln()
+          ..writeln('  @override')
+          ..writeln(
+            '  FutureOr<InitializeResult> initialize(InitializeRequest request) {',
+          );
+
+    for (var f in tools) {
+      buffer.writeln(
+        isClass
+            ? '    registerTool(_tool_${f.name}, (r) => _handler_${f.name}(_impl, r));'
+            : '    registerTool(_tool_${f.name}, _handler_${f.name});',
+      );
+    }
+
+    buffer
+      ..writeln('    return super.initialize(request);')
+      ..writeln('  }')
+      ..writeln('}');
+
+    buffer.writeln(_bootstrap(isClass ? ', ${serverElement.name} _impl' : ''));
+    if (isClass) {
+      buffer
+        ..writeln()
+        ..writeln(
+          'extension _${serverElement.name}Runner on ${serverElement.name} {',
+        )
+        ..writeln(
+          '  Future<void> run(List<String> args) => _runGeneratedMcpServer(args, this);',
+        )
+        ..writeln('}');
+    }
+
+    return buffer.toString();
+  }
+
+  String _bootstrap(String extraArg) => '''
+Future<void> _runGeneratedMcpServer(List<String> args$extraArg) async {
+  _GeneratedServer? server;
+  await runZonedGuarded(
+    () async {
+      final channel = StreamChannel.withCloseGuarantee(stdin, stdout)
+        .transform(StreamChannelTransformer.fromCodec(utf8))
+        .transformStream(const LineSplitter())
+        .transformSink(StreamSinkTransformer.fromHandlers(handleData: (data, sink) => sink.add('\$data\\n')));
+      ${extraArg.isNotEmpty ? 'server = _GeneratedServer(channel$extraArg);' : 'server = _GeneratedServer(channel);'}
+    },
+    (e, s) {
+      if (server != null) {
+        try { server!.log(LoggingLevel.error, '\$e\\n\$s'); } catch (_) {}
+      } else {
+        stderr..writeln(e)..writeln(s);
+      }
+    },
+    zoneSpecification: ZoneSpecification(
+      print: (_, __, ___, value) {
+        if (server != null) {
+          try { server!.log(LoggingLevel.info, value); } catch (_) {}
+        }
+      },
+    ),
+  );
+}''';
+}
diff --git a/pkgs/mcp_codegen/lib/src/emitter/code_emitter.dart b/pkgs/mcp_codegen/lib/src/emitter/code_emitter.dart
new file mode 100644
index 00000000..59e6763f
--- /dev/null
+++ b/pkgs/mcp_codegen/lib/src/emitter/code_emitter.dart
@@ -0,0 +1,47 @@
+// Copyright (c) 2023, the Dart project authors.
+// See the AUTHORS file for details. All rights reserved.
+// Use of this source code is governed by a BSD-style license in the LICENSE file.
+
+import 'package:analyzer/dart/constant/value.dart';
+import 'package:analyzer/dart/element/element.dart';
+
+import '../builders/handler_builder.dart';
+import '../builders/server_builder.dart';
+
+/// Responsible for orchestrating code emission for tools and the server
+/// wrapper.
+class CodeEmitter {
+  final HandlerBuilder _handlerBuilder = HandlerBuilder();
+  final ServerBuilder _serverBuilder = ServerBuilder();
+
+  String emit({
+    required Element serverElement,
+    required DartObject annotation,
+    required Map<ExecutableElement, DartObject> tools,
+  }) {
+    final buffer =
+        StringBuffer()
+          ..writeln('// GENERATED CODE - DO NOT MODIFY BY HAND')
+          ..writeln('// ignore_for_file: unused_import, unnecessary_cast')
+          ..writeln();
+
+    // Emit tool constant declarations and their handlers.
+    tools.forEach((func, ann) {
+      buffer.writeln(
+        _handlerBuilder.build(func, ann, serverElement is ClassElement),
+      );
+      buffer.writeln();
+    });
+
+    // Emit the server scaffold and bootstrap code.
+    buffer.writeln(
+      _serverBuilder.build(
+        serverElement: serverElement,
+        annotation: annotation,
+        tools: tools.keys.toList(),
+      ),
+    );
+
+    return buffer.toString();
+  }
+}
diff --git a/pkgs/mcp_codegen/lib/src/mcp_generator.dart b/pkgs/mcp_codegen/lib/src/mcp_generator.dart
index 950305d0..88930b32 100644
--- a/pkgs/mcp_codegen/lib/src/mcp_generator.dart
+++ b/pkgs/mcp_codegen/lib/src/mcp_generator.dart
@@ -1,382 +1,44 @@
-// 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.
+// Copyright (c) 2023, the Dart project authors.
+// See the AUTHORS file for details. All rights reserved.
+// Use of this source code is governed by a BSD-style license in the LICENSE file.
 
 import 'dart:async';
-import 'package:analyzer/dart/element/element.dart';
-import 'package:analyzer/dart/constant/value.dart';
+
 import 'package:build/build.dart';
 import 'package:mcp_annotations/mcp_annotations.dart';
 import 'package:source_gen/source_gen.dart';
 
-class MCPGenerator extends Generator {
-  static final _mcpToolChecker = TypeChecker.fromRuntime(MCPTool);
-  static final _mcpServerChecker = TypeChecker.fromRuntime(MCPServerApp);
-
-  /// HELPER: iterate top level functions in a [LibraryElement].
-  Iterable<FunctionElement> _topLevelFunctions(LibraryElement lib) sync* {
-    for (final unit in lib.units) {
-      for (final func in unit.functions) {
-        yield func;
-      }
-    }
-  }
+import 'scanners/annotation_scanner.dart';
+import 'scanners/tool_scanner.dart';
+import 'emitter/code_emitter.dart';
 
-  /// HELPER: iterate all classes in a [LibraryElement].
-  Iterable<ClassElement> _classes(LibraryElement lib) sync* {
-    for (final unit in lib.units) {
-      for (final clazz in unit.classes) {
-        yield clazz;
-      }
-    }
-  }
+/// Orchestrates the scanning and emission process to generate MCP server
+/// source code.
+class MCPGenerator extends Generator {
+  final AnnotationScanner _annotationScanner = AnnotationScanner();
+  final ToolScanner _toolScanner = ToolScanner();
+  final CodeEmitter _emitter = CodeEmitter();
 
   @override
   FutureOr<String?> generate(LibraryReader library, BuildStep buildStep) {
-    final serverAnnotatedElements = <Element, DartObject>{};
-
-    for (final annotated in _topLevelFunctions(library.element)) {
-      final annotation = _mcpServerChecker.firstAnnotationOfExact(annotated);
-      if (annotation != null) {
-        serverAnnotatedElements[annotated] = annotation;
-      }
-    }
-
-    for (final clazz in _classes(library.element)) {
-      final annotation = _mcpServerChecker.firstAnnotationOfExact(clazz);
-      if (annotation != null) {
-        serverAnnotatedElements[clazz] = annotation;
-      }
-    }
-
-    if (serverAnnotatedElements.isEmpty) return null;
-
-    // Currently support exactly one per library for simplicity.
-    if (serverAnnotatedElements.length > 1) {
-      log.warning(
-        'Multiple @MCPServerApp annotations found in ${library.element.source.uri}. '
-        'Only the first one will be used.',
-      );
-    }
-
-    final serverElement = serverAnnotatedElements.keys.first;
-    final serverAnnotation = serverAnnotatedElements.values.first;
-
-    final serverName =
-        serverAnnotation.getField('name')?.toStringValue() ??
-        serverElement.name;
-    final serverVersion =
-        serverAnnotation.getField('version')?.toStringValue() ?? '0.0.0';
-    final serverInstructions =
-        serverAnnotation.getField('instructions')?.toStringValue();
-
-    // Collect tool functions within the server context.
-    final toolFunctions = <ExecutableElement, DartObject>{};
-
-    if (serverElement is ClassElement) {
-      for (final method in serverElement.methods) {
-        final ann = _mcpToolChecker.firstAnnotationOfExact(method);
-        if (ann != null) {
-          toolFunctions[method] = ann;
-        }
-      }
-    } else if (serverElement is FunctionElement) {
-      for (final function in _topLevelFunctions(library.element)) {
-        final ann = _mcpToolChecker.firstAnnotationOfExact(function);
-        if (ann != null) {
-          toolFunctions[function] = ann;
-        }
-      }
-    }
-
-    if (toolFunctions.isEmpty) {
-      log.warning(
-        'No @MCPTool annotated functions found in '
-        '${library.element.source.uri}. The generated server will have no tools.',
-      );
-    }
-
-    final buffer = StringBuffer();
-    buffer.writeln('// GENERATED CODE - DO NOT MODIFY BY HAND');
-    buffer.writeln(
-      '// ignore_for_file: unused_element, unused_import, unnecessary_cast',
-    );
-    buffer.writeln();
-    // No additional imports inside part files (must contain only code).
-    buffer.writeln();
-
-    // Generate per-tool constants & handlers.
-    for (final entry in toolFunctions.entries) {
-      final func = entry.key;
-      final ann = entry.value;
-
-      final toolName = ann.getField('name')?.toStringValue() ?? func.name;
-      final description = ann.getField('description')?.toStringValue();
-
-      // Map of parameter name -> (title, description) from annotation metadata.
-      final _paramMeta = <String, Map<String, String?>>{};
-      final metaList = ann.getField('parameters')?.toListValue();
-      if (metaList != null) {
-        for (final meta in metaList) {
-          final name = meta.getField('name')?.toStringValue();
-          if (name == null) continue;
-          _paramMeta[name] = {
-            'title': meta.getField('title')?.toStringValue(),
-            'description': meta.getField('description')?.toStringValue(),
-          };
-        }
-      }
-
-      final propsBuffer = StringBuffer();
-      final requiredParams = <String>[];
-      for (final param in func.parameters) {
-        final meta = _paramMeta[param.name];
-        final schema = _schemaForParam(
-          param,
-          title: meta?['title'],
-          description: meta?['description'],
-        );
-        propsBuffer.writeln("      '${param.name}': $schema,");
-        if (!param.isOptional) {
-          requiredParams.add("'${param.name}'");
-        }
-      }
-
-      final inputSchemaCode = '''ObjectSchema(
-        properties: {
-${propsBuffer.toString()}        },
-        required: [${requiredParams.join(', ')}],
-      )''';
-
-      // Build ToolAnnotations hints.
-      final hintFields = <String>[];
-      void addHint(String field) {
-        final value = ann.getField(field);
-        if (value == null || value.isNull) return;
-        hintFields.add(
-          '$field: ${value.toBoolValue() ?? value.toStringValue()}',
-        );
-      }
-
-      addHint('destructiveHint');
-      addHint('idempotentHint');
-      addHint('openWorldHint');
-      addHint('readOnlyHint');
-      addHint('title');
-
-      var annotationsCode = 'null';
-      if (hintFields.isNotEmpty) {
-        annotationsCode = 'ToolAnnotations(${hintFields.join(', ')})';
-      }
-
-      buffer
-        ..writeln('final Tool _tool_${func.name} = Tool(')
-        ..writeln("  name: '$toolName',")
-        ..writeln(
-          "  description: ${description != null ? '\'${_escape(description)}\'' : 'null'},",
-        )
-        ..writeln('  inputSchema: $inputSchemaCode,')
-        ..writeln('  annotations: $annotationsCode,')
-        ..writeln(');')
-        ..writeln();
-
-      // Generate handler definition.
-      if (serverElement is ClassElement) {
-        final className = serverElement.name;
-        buffer.writeln('FutureOr<CallToolResult> _handler_${func.name}(');
-        buffer.writeln('  $className _impl, CallToolRequest _request) async {');
-      } else {
-        buffer.writeln(
-          'FutureOr<CallToolResult> _handler_${func.name}(CallToolRequest _request) async {',
-        );
-      }
-
-      buffer.writeln(
-        '  final _args = _request.arguments ?? const <String, Object?>{};',
-      );
-
-      final callArgsList = <String>[];
-      for (final param in func.parameters) {
-        final pName = param.name;
-        final pTypeCode = param.type.getDisplayString(withNullability: false);
-        buffer.writeln(
-          '  final $pTypeCode $pName = _args[\'$pName\'] as $pTypeCode;',
-        );
-        callArgsList.add(pName);
-      }
-
-      final callExpr =
-          serverElement is ClassElement
-              ? '_impl.${func.name}(${callArgsList.join(', ')})'
-              : '${func.name}(${callArgsList.join(', ')})';
-
-      buffer.writeln('  final _result = await Future.sync(() => $callExpr);');
-      buffer.writeln(
-        '  return CallToolResult(content: [TextContent(text: _result.toString())]);',
-      );
-      buffer.writeln('}');
-      buffer.writeln();
-    }
-
-    // Generate server subclass.
-    buffer.writeln(
-      'final class _GeneratedServer extends MCPServer'
-      ' with LoggingSupport, ToolsSupport, ResourcesSupport, RootsTrackingSupport {',
-    );
-
-    if (serverElement is ClassElement) {
-      final className = serverElement.name;
-      buffer.writeln('  final $className _impl;');
-      buffer.writeln('  _GeneratedServer(super.channel, this._impl)');
-    } else {
-      buffer.writeln('  _GeneratedServer(super.channel)');
-    }
-
-    buffer.writeln('      : super.fromStreamChannel(');
-    buffer.writeln(
-      "          implementation: ServerImplementation(name: '$serverName', version: '$serverVersion'),",
-    );
-    buffer.writeln(
-      "          instructions: ${serverInstructions != null ? '\'${_escape(serverInstructions)}\'' : '\'\''},",
-    );
-    buffer.writeln('        );');
-    buffer.writeln();
-
-    // initialize override registers tools then defers to super.
-    buffer.writeln('  @override');
-    buffer.writeln(
-      '  FutureOr<InitializeResult> initialize(InitializeRequest request) {',
+    // Locate the element annotated with `@MCPServerApp`.
+    final serverEntry = _annotationScanner.findFirst<MCPServerApp>(
+      library.element,
     );
 
-    if (serverElement is ClassElement) {
-      for (final func in toolFunctions.keys) {
-        buffer.writeln(
-          '    registerTool(_tool_${func.name}, (r) => _handler_${func.name}(_impl, r));',
-        );
-      }
-    } else {
-      for (final func in toolFunctions.keys) {
-        buffer.writeln(
-          '    registerTool(_tool_${func.name}, _handler_${func.name});',
-        );
-      }
-    }
+    if (serverEntry == null) return null;
 
-    buffer.writeln('    return super.initialize(request);');
-    buffer.writeln('  }');
-    buffer.writeln('}');
-    buffer.writeln();
+    final serverElement = serverEntry.key;
+    final serverAnn = serverEntry.value;
 
-    // Bootstrap helper that sets up the stdio channel and runs the server in a
-    // guarded zone which forwards uncaught errors and `print` calls to the
-    // client via the logging API when possible.
+    // Gather tools defined in the same library (or within the server class).
+    final tools = _toolScanner.scan(library.element, serverElement);
 
-    if (serverElement is ClassElement) {
-      final className = serverElement.name;
-      buffer.writeln(
-        'Future<void> _runGeneratedMcpServer(List<String> args, $className _impl) async {',
-      );
-    } else {
-      buffer.writeln(
-        'Future<void> _runGeneratedMcpServer(List<String> args) async {',
-      );
-    }
-
-    buffer.writeln('  _GeneratedServer? server;');
-    buffer.writeln('  await runZonedGuarded(');
-    buffer.writeln('    () async {');
-    buffer.writeln(
-      '      final channel = StreamChannel.withCloseGuarantee(stdin, stdout)',
-    );
-    buffer.writeln(
-      '          .transform(StreamChannelTransformer.fromCodec(utf8))',
+    // Delegate code generation.
+    return _emitter.emit(
+      serverElement: serverElement,
+      annotation: serverAnn,
+      tools: tools,
     );
-    buffer.writeln('          .transformStream(const LineSplitter())');
-    buffer.writeln('          .transformSink(');
-    buffer.writeln('        StreamSinkTransformer.fromHandlers(');
-    buffer.writeln('          handleData: (data, sink) {');
-    buffer.writeln('            sink.add(\'\$data\\n\');');
-    buffer.writeln('          },');
-    buffer.writeln('        ),');
-    buffer.writeln('      );');
-    buffer.writeln();
-
-    if (serverElement is ClassElement) {
-      buffer.writeln('      server = _GeneratedServer(channel, _impl);');
-    } else {
-      buffer.writeln('      server = _GeneratedServer(channel);');
-    }
-
-    buffer.writeln('    },');
-    buffer.writeln('    (e, s) {');
-    buffer.writeln('      if (server != null) {');
-    buffer.writeln('        try {');
-    buffer.writeln('          server!.log(LoggingLevel.error, \'\$e\\n\$s\');');
-    buffer.writeln('        } catch (_) {}');
-    buffer.writeln('      } else {');
-    buffer.writeln('        stderr');
-    buffer.writeln('          ..writeln(e)');
-    buffer.writeln('          ..writeln(s);');
-    buffer.writeln('      }');
-    buffer.writeln('    },');
-    buffer.writeln('    zoneSpecification: ZoneSpecification(');
-    buffer.writeln('      print: (_, __, ___, value) {');
-    buffer.writeln('        if (server != null) {');
-    buffer.writeln('          try {');
-    buffer.writeln('            server!.log(LoggingLevel.info, value);');
-    buffer.writeln('          } catch (_) {}');
-    buffer.writeln('        }');
-    buffer.writeln('      },');
-    buffer.writeln('    ),');
-    buffer.writeln('  );');
-    buffer.writeln('}');
-
-    // If using class-based server, generate a convenience extension for `run`.
-    if (serverElement is ClassElement) {
-      final className = serverElement.name;
-      buffer.writeln();
-      buffer.writeln('extension _${className}Runner on $className {');
-      buffer.writeln(
-        '  Future<void> run(List<String> args) => _runGeneratedMcpServer(args, this);',
-      );
-      buffer.writeln('}');
-    }
-
-    return buffer.toString();
-  }
-
-  String _escape(String input) => input.replaceAll("'", "\\'");
-
-  String _schemaForParam(
-    ParameterElement param, {
-    String? title,
-    String? description,
-  }) {
-    final type = param.type.getDisplayString(withNullability: false);
-
-    String _args() {
-      final parts = <String>[];
-      if (title != null) parts.add("title: '${_escape(title)}'");
-      if (description != null) {
-        parts.add("description: '${_escape(description)}'");
-      }
-      return parts.isEmpty ? '' : parts.join(', ');
-    }
-
-    final argStr = _args();
-
-    switch (type) {
-      case 'int':
-        return argStr.isEmpty ? 'IntegerSchema()' : 'IntegerSchema($argStr)';
-      case 'double':
-      case 'num':
-        return argStr.isEmpty ? 'NumberSchema()' : 'NumberSchema($argStr)';
-      case 'String':
-        return argStr.isEmpty ? 'StringSchema()' : 'StringSchema($argStr)';
-      case 'bool':
-        return argStr.isEmpty ? 'BooleanSchema()' : 'BooleanSchema($argStr)';
-      default:
-        return argStr.isEmpty ? 'ObjectSchema()' : 'ObjectSchema($argStr)';
-    }
   }
 }
diff --git a/pkgs/mcp_codegen/lib/src/scanners/annotation_scanner.dart b/pkgs/mcp_codegen/lib/src/scanners/annotation_scanner.dart
new file mode 100644
index 00000000..e0d606dc
--- /dev/null
+++ b/pkgs/mcp_codegen/lib/src/scanners/annotation_scanner.dart
@@ -0,0 +1,25 @@
+// Copyright (c) 2023, the Dart project authors.
+// See the AUTHORS file for details. All rights reserved.
+// Use of this source code is governed by a BSD-style license in the LICENSE file.
+
+import 'package:analyzer/dart/constant/value.dart';
+import 'package:analyzer/dart/element/element.dart';
+import 'package:mcp_annotations/mcp_annotations.dart';
+import 'package:source_gen/source_gen.dart';
+
+/// Scans a library for the first element annotated with [MCPServerApp].
+class AnnotationScanner {
+  final TypeChecker _serverChecker = TypeChecker.fromRuntime(MCPServerApp);
+
+  /// Returns the first element annotated with `@MCPServerApp`, or `null` if
+  /// no such element exists.
+  MapEntry<Element, DartObject>? findFirst<T>(LibraryElement lib) {
+    for (var unit in lib.units) {
+      for (var element in [...unit.functions, ...unit.classes]) {
+        final ann = _serverChecker.firstAnnotationOfExact(element);
+        if (ann != null) return MapEntry<Element, DartObject>(element, ann);
+      }
+    }
+    return null;
+  }
+}
diff --git a/pkgs/mcp_codegen/lib/src/scanners/tool_scanner.dart b/pkgs/mcp_codegen/lib/src/scanners/tool_scanner.dart
new file mode 100644
index 00000000..b4c87e57
--- /dev/null
+++ b/pkgs/mcp_codegen/lib/src/scanners/tool_scanner.dart
@@ -0,0 +1,41 @@
+// Copyright (c) 2023, the Dart project authors.
+// See the AUTHORS file for details. All rights reserved.
+// Use of this source code is governed by a BSD-style license in the LICENSE file.
+
+import 'package:analyzer/dart/constant/value.dart';
+import 'package:analyzer/dart/element/element.dart';
+import 'package:mcp_annotations/mcp_annotations.dart';
+import 'package:source_gen/source_gen.dart';
+
+import '../utils/annotation_utils.dart';
+
+/// Scans for `@MCPTool` annotations within the context of the discovered
+/// server element.
+class ToolScanner {
+  final TypeChecker _toolChecker = TypeChecker.fromRuntime(MCPTool);
+
+  /// Returns a map whose keys are the annotated executable elements (methods
+  /// or top-level functions) and whose values are their corresponding
+  /// annotation values.
+  Map<ExecutableElement, DartObject> scan(
+    LibraryElement lib,
+    Element serverElement,
+  ) {
+    // When the server is a class, look only at its methods.
+    if (serverElement is ClassElement) {
+      return {
+        for (var method in serverElement.methods)
+          if (method.isAnnotated(_toolChecker))
+            method: method.firstAnnotation(_toolChecker)!,
+      };
+    }
+
+    // Otherwise, scan all top-level functions in the compilation units.
+    return {
+      for (var unit in lib.units)
+        for (var fn in unit.functions)
+          if (fn.isAnnotated(_toolChecker))
+            fn: fn.firstAnnotation(_toolChecker)!,
+    };
+  }
+}
diff --git a/pkgs/mcp_codegen/lib/src/utils/annotation_utils.dart b/pkgs/mcp_codegen/lib/src/utils/annotation_utils.dart
new file mode 100644
index 00000000..ca21adcc
--- /dev/null
+++ b/pkgs/mcp_codegen/lib/src/utils/annotation_utils.dart
@@ -0,0 +1,19 @@
+// Copyright (c) 2023, the Dart project authors.
+// See the AUTHORS file for details. All rights reserved.
+// Use of this source code is governed by a BSD-style license in the LICENSE file.
+
+import 'package:analyzer/dart/constant/value.dart';
+import 'package:analyzer/dart/element/element.dart';
+import 'package:source_gen/source_gen.dart';
+
+/// Utility extension methods for working with annotations via `source_gen`'s
+/// `TypeChecker` API.
+extension AnnotationHelpers on Element {
+  /// Returns `true` when [checker] matches at least one annotation on `this`.
+  bool isAnnotated(TypeChecker checker) => checker.hasAnnotationOfExact(this);
+
+  /// Returns the first annotation on `this` that matches [checker] using an
+  /// *exact* type check, or `null` when none is found.
+  DartObject? firstAnnotation(TypeChecker checker) =>
+      checker.firstAnnotationOfExact(this);
+}

From 0287a098b56bdf316c31e50331344d4f6e46ec40 Mon Sep 17 00:00:00 2001
From: Nelson Campos <nelson.campos@cloudwalk.io>
Date: Sat, 10 May 2025 16:17:46 -0300
Subject: [PATCH 06/10] Add tests for code generation

- Updated `HandlerBuilder` and `ServerBuilder` to improve code generation logic, including changes to argument handling.
- Introduced new test files for `HandlerBuilder`, `SchemaBuilder`, `ServerBuilder`, and scanners to ensure proper functionality and coverage.
- Added utility tests for annotation detection and tool registration.
---
 .../lib/src/builders/handler_builder.dart     |  2 +-
 .../lib/src/builders/server_builder.dart      | 12 ++--
 .../test/builders/handler_builder_test.dart   | 47 ++++++++++++++
 .../test/builders/schema_builder_test.dart    | 64 +++++++++++++++++++
 .../builders/server_code_emitter_test.dart    | 60 +++++++++++++++++
 .../scanners/annotation_scanner_test.dart     | 30 +++++++++
 .../test/scanners/tool_scanner_test.dart      | 43 +++++++++++++
 pkgs/mcp_codegen/test/utils_test.dart         | 39 +++++++++++
 8 files changed, 292 insertions(+), 5 deletions(-)
 create mode 100644 pkgs/mcp_codegen/test/builders/handler_builder_test.dart
 create mode 100644 pkgs/mcp_codegen/test/builders/schema_builder_test.dart
 create mode 100644 pkgs/mcp_codegen/test/builders/server_code_emitter_test.dart
 create mode 100644 pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart
 create mode 100644 pkgs/mcp_codegen/test/scanners/tool_scanner_test.dart
 create mode 100644 pkgs/mcp_codegen/test/utils_test.dart

diff --git a/pkgs/mcp_codegen/lib/src/builders/handler_builder.dart b/pkgs/mcp_codegen/lib/src/builders/handler_builder.dart
index 411b04af..093fb3c5 100644
--- a/pkgs/mcp_codegen/lib/src/builders/handler_builder.dart
+++ b/pkgs/mcp_codegen/lib/src/builders/handler_builder.dart
@@ -16,7 +16,7 @@ class HandlerBuilder {
           (p) =>
               "final ${p.type.getDisplayString(withNullability: false)} ${p.name} = _args['${p.name}'] as ${p.type.getDisplayString(withNullability: false)};",
         )
-        .join('\\n    ');
+        .join('\n    ');
 
     final call =
         isClass
diff --git a/pkgs/mcp_codegen/lib/src/builders/server_builder.dart b/pkgs/mcp_codegen/lib/src/builders/server_builder.dart
index 6077a7ed..ec508e58 100644
--- a/pkgs/mcp_codegen/lib/src/builders/server_builder.dart
+++ b/pkgs/mcp_codegen/lib/src/builders/server_builder.dart
@@ -53,7 +53,7 @@ class ServerBuilder {
       ..writeln('  }')
       ..writeln('}');
 
-    buffer.writeln(_bootstrap(isClass ? ', ${serverElement.name} _impl' : ''));
+    buffer.writeln(_bootstrap(isClass, serverElement.name!));
     if (isClass) {
       buffer
         ..writeln()
@@ -69,8 +69,11 @@ class ServerBuilder {
     return buffer.toString();
   }
 
-  String _bootstrap(String extraArg) => '''
-Future<void> _runGeneratedMcpServer(List<String> args$extraArg) async {
+  String _bootstrap(bool includeImpl, String implType) {
+    final paramSig = includeImpl ? ', $implType _impl' : '';
+    final argCall = includeImpl ? ', _impl' : '';
+    return '''
+Future<void> _runGeneratedMcpServer(List<String> args$paramSig) async {
   _GeneratedServer? server;
   await runZonedGuarded(
     () async {
@@ -78,7 +81,7 @@ Future<void> _runGeneratedMcpServer(List<String> args$extraArg) async {
         .transform(StreamChannelTransformer.fromCodec(utf8))
         .transformStream(const LineSplitter())
         .transformSink(StreamSinkTransformer.fromHandlers(handleData: (data, sink) => sink.add('\$data\\n')));
-      ${extraArg.isNotEmpty ? 'server = _GeneratedServer(channel$extraArg);' : 'server = _GeneratedServer(channel);'}
+      ${includeImpl ? 'server = _GeneratedServer(channel$argCall);' : 'server = _GeneratedServer(channel);'}
     },
     (e, s) {
       if (server != null) {
@@ -96,4 +99,5 @@ Future<void> _runGeneratedMcpServer(List<String> args$extraArg) async {
     ),
   );
 }''';
+  }
 }
diff --git a/pkgs/mcp_codegen/test/builders/handler_builder_test.dart b/pkgs/mcp_codegen/test/builders/handler_builder_test.dart
new file mode 100644
index 00000000..9436ae09
--- /dev/null
+++ b/pkgs/mcp_codegen/test/builders/handler_builder_test.dart
@@ -0,0 +1,47 @@
+import 'package:analyzer/dart/constant/value.dart';
+import 'package:analyzer/dart/element/element.dart';
+import 'package:build/build.dart';
+import 'package:build_test/build_test.dart';
+import 'package:test/test.dart';
+
+import 'package:mcp_codegen/src/builders/handler_builder.dart';
+
+void main() {
+  group('HandlerBuilder', () {
+    late FunctionElement addFunc;
+    late DartObject addAnn;
+
+    setUpAll(() async {
+      const src = '''
+        library test_lib;
+        import 'package:mcp_annotations/mcp_annotations.dart';
+
+        @MCPTool(destructiveHint: true, title: 'Adder')
+        int add(int a, int b) => a + b;
+      ''';
+      await resolveSources({'test_pkg|lib/test_lib.dart': src}, (
+        resolver,
+      ) async {
+        final libId = AssetId.parse('test_pkg|lib/test_lib.dart');
+        final library = await resolver.libraryFor(libId);
+        addFunc =
+            library.topLevelElements.firstWhere((e) => e.name == 'add')
+                as FunctionElement;
+        addAnn = addFunc.metadata.first.computeConstantValue()!;
+      });
+    });
+
+    test('produces tool and handler code', () {
+      final code = HandlerBuilder().build(addFunc, addAnn, false);
+      expect(code, contains('final Tool _tool_add'));
+      expect(code, contains('FutureOr<CallToolResult> _handler_add'));
+    });
+
+    test('includes annotation flags', () {
+      final code = HandlerBuilder().build(addFunc, addAnn, false);
+      expect(code, contains('ToolAnnotations('));
+      expect(code, contains('destructiveHint: true'));
+      expect(code, contains('title: Adder'));
+    });
+  });
+}
diff --git a/pkgs/mcp_codegen/test/builders/schema_builder_test.dart b/pkgs/mcp_codegen/test/builders/schema_builder_test.dart
new file mode 100644
index 00000000..cd2aa5a6
--- /dev/null
+++ b/pkgs/mcp_codegen/test/builders/schema_builder_test.dart
@@ -0,0 +1,64 @@
+import 'package:analyzer/dart/element/element.dart';
+import 'package:build/build.dart';
+import 'package:build_test/build_test.dart';
+import 'package:test/test.dart';
+
+import 'package:mcp_codegen/src/builders/schema_builder.dart';
+
+void main() {
+  group('SchemaBuilder', () {
+    const source = '''
+      library test_lib;
+      import 'package:mcp_annotations/mcp_annotations.dart';
+
+      @MCPTool()
+      int add(int a, int b) => a + b;
+    ''';
+
+    late FunctionElement addFunc;
+
+    setUpAll(() async {
+      await resolveSources({'test_pkg|lib/test_lib.dart': source}, (
+        resolver,
+      ) async {
+        final libId = AssetId.parse('test_pkg|lib/test_lib.dart');
+        final library = await resolver.libraryFor(libId);
+        addFunc =
+            library.topLevelElements.firstWhere((e) => e.name == 'add')
+                as FunctionElement;
+      });
+    });
+
+    test('generates schema for int params', () {
+      final schema = SchemaBuilder().build(addFunc.parameters, null);
+      expect(schema, contains("'a'"));
+      expect(schema, contains('IntegerSchema'));
+    });
+
+    test('supports multiple Dart core types', () async {
+      const typedSrc = '''
+        library t2;
+        import 'package:mcp_annotations/mcp_annotations.dart';
+
+        @MCPTool()
+        void fn(int a, double b, num c, String d, bool e, Map<String,String> f) {}
+      ''';
+
+      await resolveSources({'test_pkg|lib/t2.dart': typedSrc}, (
+        resolver,
+      ) async {
+        final libId = AssetId.parse('test_pkg|lib/t2.dart');
+        final lib = await resolver.libraryFor(libId);
+        final fnElem =
+            lib.topLevelElements.firstWhere((e) => e.name == 'fn')
+                as FunctionElement;
+        final schema = SchemaBuilder().build(fnElem.parameters, null);
+        expect(schema, contains('IntegerSchema'));
+        expect(schema, contains('NumberSchema'));
+        expect(schema, contains('StringSchema'));
+        expect(schema, contains('BooleanSchema'));
+        expect(schema, contains('ObjectSchema'));
+      });
+    });
+  });
+}
diff --git a/pkgs/mcp_codegen/test/builders/server_code_emitter_test.dart b/pkgs/mcp_codegen/test/builders/server_code_emitter_test.dart
new file mode 100644
index 00000000..705e9f2b
--- /dev/null
+++ b/pkgs/mcp_codegen/test/builders/server_code_emitter_test.dart
@@ -0,0 +1,60 @@
+import 'package:analyzer/dart/constant/value.dart';
+import 'package:analyzer/dart/element/element.dart';
+import 'package:build/build.dart';
+import 'package:build_test/build_test.dart';
+import 'package:test/test.dart';
+
+import 'package:mcp_codegen/src/builders/server_builder.dart';
+import 'package:mcp_codegen/src/emitter/code_emitter.dart';
+import 'package:mcp_codegen/src/scanners/annotation_scanner.dart';
+import 'package:mcp_codegen/src/scanners/tool_scanner.dart';
+
+void main() {
+  group('ServerBuilder & CodeEmitter', () {
+    late LibraryElement library;
+    late Map<ExecutableElement, DartObject> tools;
+    late MapEntry<Element, DartObject> serverEntry;
+
+    setUpAll(() async {
+      const src = '''
+        library test_lib;
+        import 'package:mcp_annotations/mcp_annotations.dart';
+
+        @MCPServerApp()
+        void myServer() {}
+
+        @MCPTool()
+        int add(int a, int b) => a + b;
+      ''';
+
+      await resolveSources({'test_pkg|lib/test_lib.dart': src}, (
+        resolver,
+      ) async {
+        final libId = AssetId.parse('test_pkg|lib/test_lib.dart');
+        library = await resolver.libraryFor(libId);
+        serverEntry = AnnotationScanner().findFirst(library)!;
+        tools = ToolScanner().scan(library, library);
+      });
+    });
+
+    test('server scaffold contains tool registration', () {
+      final serverCode = ServerBuilder().build(
+        serverElement: serverEntry.key,
+        annotation: serverEntry.value,
+        tools: tools.keys.toList(),
+      );
+      expect(serverCode, contains('final class _GeneratedServer'));
+      expect(serverCode, contains('registerTool(_tool_add'));
+    });
+
+    test('CodeEmitter integrates everything', () {
+      final emitted = CodeEmitter().emit(
+        serverElement: serverEntry.key,
+        annotation: serverEntry.value,
+        tools: tools,
+      );
+      expect(emitted, contains('_GeneratedServer'));
+      expect(emitted, contains('_handler_add'));
+    });
+  });
+}
diff --git a/pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart b/pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart
new file mode 100644
index 00000000..e6bbfe56
--- /dev/null
+++ b/pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart
@@ -0,0 +1,30 @@
+import 'package:build/build.dart';
+import 'package:build_test/build_test.dart';
+import 'package:test/test.dart';
+
+import 'package:mcp_codegen/src/scanners/annotation_scanner.dart';
+
+void main() {
+  group('AnnotationScanner', () {
+    test('finds top-level server function', () async {
+      const src = '''
+        library test_lib;
+        import 'package:mcp_annotations/mcp_annotations.dart';
+
+        @MCPServerApp()
+        void myServer() {}
+      ''';
+
+      await resolveSources({'test_pkg|lib/test_lib.dart': src}, (
+        resolver,
+      ) async {
+        final libId = AssetId.parse('test_pkg|lib/test_lib.dart');
+        final library = await resolver.libraryFor(libId);
+        final scanner = AnnotationScanner();
+        final result = scanner.findFirst(library);
+        expect(result, isNotNull);
+        expect(result!.key.name, 'myServer');
+      });
+    });
+  });
+}
diff --git a/pkgs/mcp_codegen/test/scanners/tool_scanner_test.dart b/pkgs/mcp_codegen/test/scanners/tool_scanner_test.dart
new file mode 100644
index 00000000..89eb34f9
--- /dev/null
+++ b/pkgs/mcp_codegen/test/scanners/tool_scanner_test.dart
@@ -0,0 +1,43 @@
+import 'package:analyzer/dart/element/element.dart';
+import 'package:build/build.dart';
+import 'package:build_test/build_test.dart';
+import 'package:test/test.dart';
+
+import 'package:mcp_codegen/src/scanners/tool_scanner.dart';
+
+void main() {
+  group('ToolScanner', () {
+    test('finds annotated methods and functions', () async {
+      const src = '''
+        library test_lib;
+        import 'package:mcp_annotations/mcp_annotations.dart';
+
+        @MCPServerApp()
+        class MyServer {
+          @MCPTool()
+          int add(int a, int b) => a + b;
+        }
+
+        @MCPTool()
+        String echo(String message) => message;
+      ''';
+
+      await resolveSources({'test_pkg|lib/test_lib.dart': src}, (
+        resolver,
+      ) async {
+        final libId = AssetId.parse('test_pkg|lib/test_lib.dart');
+        final library = await resolver.libraryFor(libId);
+        final serverElement = library.topLevelElements
+            .whereType<ClassElement>()
+            .firstWhere((c) => c.name == 'MyServer');
+
+        final scanner = ToolScanner();
+        final classTools = scanner.scan(library, serverElement);
+        expect(classTools.keys.map((e) => e.name), contains('add'));
+
+        final globalTools = scanner.scan(library, library);
+        expect(globalTools.keys.map((e) => e.name), contains('echo'));
+      });
+    });
+  });
+}
diff --git a/pkgs/mcp_codegen/test/utils_test.dart b/pkgs/mcp_codegen/test/utils_test.dart
new file mode 100644
index 00000000..618e7da8
--- /dev/null
+++ b/pkgs/mcp_codegen/test/utils_test.dart
@@ -0,0 +1,39 @@
+import 'package:build/build.dart';
+import 'package:build_test/build_test.dart';
+import 'package:test/test.dart';
+import 'package:source_gen/source_gen.dart';
+import 'package:mcp_annotations/mcp_annotations.dart';
+
+import 'package:mcp_codegen/src/utils/annotation_utils.dart';
+
+void main() {
+  const src = '''
+    library test_lib;
+    import 'package:mcp_annotations/mcp_annotations.dart';
+
+    @MCPTool()
+    void toolFn() {}
+
+    void nonAnnotated() {}
+  ''';
+
+  test('AnnotationHelpers detects annotations correctly', () async {
+    await resolveSources({'test_pkg|lib/test_lib.dart': src}, (resolver) async {
+      final libId = AssetId.parse('test_pkg|lib/test_lib.dart');
+      final library = await resolver.libraryFor(libId);
+      final toolElement = library.topLevelElements.firstWhere(
+        (e) => e.name == 'toolFn',
+      );
+      final nonElement = library.topLevelElements.firstWhere(
+        (e) => e.name == 'nonAnnotated',
+      );
+
+      final checker = TypeChecker.fromRuntime(MCPTool);
+      expect(toolElement.isAnnotated(checker), isTrue);
+      expect(nonElement.isAnnotated(checker), isFalse);
+
+      expect(toolElement.firstAnnotation(checker), isNotNull);
+      expect(nonElement.firstAnnotation(checker), isNull);
+    });
+  });
+}

From 24998174cbf1ca11d790eaf0893fd028d4afc3ea Mon Sep 17 00:00:00 2001
From: Nelson Campos <nelson.campos@cloudwalk.io>
Date: Sat, 10 May 2025 16:17:53 -0300
Subject: [PATCH 07/10] Refactor generated code in main.mcp.g.dart

- Removed unused element warnings and simplified input schema property definitions for better clarity.
- Streamlined the data transformation logic in the server setup for improved readability.
- Cleaned up comments to enhance code maintainability.
---
 examples/demo_server/bin/main.mcp.g.dart | 20 +++++---------------
 1 file changed, 5 insertions(+), 15 deletions(-)

diff --git a/examples/demo_server/bin/main.mcp.g.dart b/examples/demo_server/bin/main.mcp.g.dart
index 8d6e3082..ecff98ad 100644
--- a/examples/demo_server/bin/main.mcp.g.dart
+++ b/examples/demo_server/bin/main.mcp.g.dart
@@ -7,16 +7,13 @@ part of 'main.dart';
 // **************************************************************************
 
 // GENERATED CODE - DO NOT MODIFY BY HAND
-// ignore_for_file: unused_element, unused_import, unnecessary_cast
+// ignore_for_file: unused_import, unnecessary_cast
 
 final Tool _tool_add = Tool(
   name: 'add',
   description: 'Adds two numbers.',
   inputSchema: ObjectSchema(
-    properties: {
-      'a': NumberSchema(description: 'The first number to add.'),
-      'b': NumberSchema(description: 'The second number to add.'),
-    },
+    properties: {'a': NumberSchema(), 'b': NumberSchema()},
     required: ['a', 'b'],
   ),
   annotations: null,
@@ -36,7 +33,7 @@ final Tool _tool_strlen = Tool(
   description: 'Returns the length of a string.',
   inputSchema: ObjectSchema(
     properties: {
-      'text': StringSchema(description: 'The string to get the length of.'),
+      'text': StringSchema(description: 'The string to get the length of.')
     },
     required: ['text'],
   ),
@@ -77,14 +74,8 @@ Future<void> _runGeneratedMcpServer(
       final channel = StreamChannel.withCloseGuarantee(stdin, stdout)
           .transform(StreamChannelTransformer.fromCodec(utf8))
           .transformStream(const LineSplitter())
-          .transformSink(
-        StreamSinkTransformer.fromHandlers(
-          handleData: (data, sink) {
-            sink.add('$data\n');
-          },
-        ),
-      );
-
+          .transformSink(StreamSinkTransformer.fromHandlers(
+              handleData: (data, sink) => sink.add('$data\n')));
       server = _GeneratedServer(channel, _impl);
     },
     (e, s) {
@@ -109,7 +100,6 @@ Future<void> _runGeneratedMcpServer(
     ),
   );
 }
-// Call `_runGeneratedMcpServer(args);` from your annotated main().
 
 extension _MCPDemoServerRunner on MCPDemoServer {
   Future<void> run(List<String> args) => _runGeneratedMcpServer(args, this);

From 9f57a340470f57d3129555602eda5624e97a12f7 Mon Sep 17 00:00:00 2001
From: Nelson Campos <nelson.campos@cloudwalk.io>
Date: Sat, 10 May 2025 16:18:34 -0300
Subject: [PATCH 08/10] Update test files to include copyright notices

- Added copyright headers to multiple test files in the mcp_codegen package to comply with licensing requirements.
---
 pkgs/mcp_codegen/test/builders/handler_builder_test.dart     | 4 ++++
 pkgs/mcp_codegen/test/builders/schema_builder_test.dart      | 4 ++++
 pkgs/mcp_codegen/test/builders/server_code_emitter_test.dart | 4 ++++
 pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart  | 4 ++++
 pkgs/mcp_codegen/test/scanners/tool_scanner_test.dart        | 4 ++++
 pkgs/mcp_codegen/test/utils_test.dart                        | 4 ++++
 6 files changed, 24 insertions(+)

diff --git a/pkgs/mcp_codegen/test/builders/handler_builder_test.dart b/pkgs/mcp_codegen/test/builders/handler_builder_test.dart
index 9436ae09..6e617e72 100644
--- a/pkgs/mcp_codegen/test/builders/handler_builder_test.dart
+++ b/pkgs/mcp_codegen/test/builders/handler_builder_test.dart
@@ -1,3 +1,7 @@
+// 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.
+
 import 'package:analyzer/dart/constant/value.dart';
 import 'package:analyzer/dart/element/element.dart';
 import 'package:build/build.dart';
diff --git a/pkgs/mcp_codegen/test/builders/schema_builder_test.dart b/pkgs/mcp_codegen/test/builders/schema_builder_test.dart
index cd2aa5a6..f62424bc 100644
--- a/pkgs/mcp_codegen/test/builders/schema_builder_test.dart
+++ b/pkgs/mcp_codegen/test/builders/schema_builder_test.dart
@@ -1,3 +1,7 @@
+// 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.
+
 import 'package:analyzer/dart/element/element.dart';
 import 'package:build/build.dart';
 import 'package:build_test/build_test.dart';
diff --git a/pkgs/mcp_codegen/test/builders/server_code_emitter_test.dart b/pkgs/mcp_codegen/test/builders/server_code_emitter_test.dart
index 705e9f2b..6c5d79d7 100644
--- a/pkgs/mcp_codegen/test/builders/server_code_emitter_test.dart
+++ b/pkgs/mcp_codegen/test/builders/server_code_emitter_test.dart
@@ -1,3 +1,7 @@
+// 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.
+
 import 'package:analyzer/dart/constant/value.dart';
 import 'package:analyzer/dart/element/element.dart';
 import 'package:build/build.dart';
diff --git a/pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart b/pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart
index e6bbfe56..4c50df5f 100644
--- a/pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart
+++ b/pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart
@@ -1,3 +1,7 @@
+// 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.
+
 import 'package:build/build.dart';
 import 'package:build_test/build_test.dart';
 import 'package:test/test.dart';
diff --git a/pkgs/mcp_codegen/test/scanners/tool_scanner_test.dart b/pkgs/mcp_codegen/test/scanners/tool_scanner_test.dart
index 89eb34f9..9cbf3c3e 100644
--- a/pkgs/mcp_codegen/test/scanners/tool_scanner_test.dart
+++ b/pkgs/mcp_codegen/test/scanners/tool_scanner_test.dart
@@ -1,3 +1,7 @@
+// 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.
+
 import 'package:analyzer/dart/element/element.dart';
 import 'package:build/build.dart';
 import 'package:build_test/build_test.dart';
diff --git a/pkgs/mcp_codegen/test/utils_test.dart b/pkgs/mcp_codegen/test/utils_test.dart
index 618e7da8..1d94c590 100644
--- a/pkgs/mcp_codegen/test/utils_test.dart
+++ b/pkgs/mcp_codegen/test/utils_test.dart
@@ -1,3 +1,7 @@
+// 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.
+
 import 'package:build/build.dart';
 import 'package:build_test/build_test.dart';
 import 'package:test/test.dart';

From 5eb9351191c1ed073e117c23ad77544ec91fbba8 Mon Sep 17 00:00:00 2001
From: Nelson Campos <nelson.campos@cloudwalk.io>
Date: Sat, 10 May 2025 16:21:19 -0300
Subject: [PATCH 09/10] Refactor annotation scanner test to update server class
 structure

- Changed the `myServer` function to a `MyServer` class with a constant constructor and an `add` method annotated with `@MCPTool()`.
- Updated the test expectation to reflect the new class name.
---
 .../test/scanners/annotation_scanner_test.dart            | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart b/pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart
index 4c50df5f..d975e776 100644
--- a/pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart
+++ b/pkgs/mcp_codegen/test/scanners/annotation_scanner_test.dart
@@ -16,7 +16,11 @@ void main() {
         import 'package:mcp_annotations/mcp_annotations.dart';
 
         @MCPServerApp()
-        void myServer() {}
+        class MyServer {
+          const MyServer();
+          @MCPTool()
+          int add(int a, int b) => a + b;
+        }
       ''';
 
       await resolveSources({'test_pkg|lib/test_lib.dart': src}, (
@@ -27,7 +31,7 @@ void main() {
         final scanner = AnnotationScanner();
         final result = scanner.findFirst(library);
         expect(result, isNotNull);
-        expect(result!.key.name, 'myServer');
+        expect(result!.key.name, 'MyServer');
       });
     });
   });

From 052b3c5ea99bb5e6ab86ffe6a09c76fc4745ca70 Mon Sep 17 00:00:00 2001
From: Nelson Campos <nelson.campos@cloudwalk.io>
Date: Sat, 10 May 2025 16:55:19 -0300
Subject: [PATCH 10/10] Update dependencies and clean up demo server code

- Updated `pubspec.yaml` in the demo server to use versioned dependencies for `dart_mcp` and `mcp_annotations`.
- Added `mcp_codegen` as a dev dependency.
- Refactored `main.dart` to simplify the `add` method and removed the unused `strlen` method.
- Added changelogs and licenses for `mcp_annotations` and `mcp_codegen` packages, marking their initial release.
- Updated `pubspec.yaml` for both packages to reflect version changes.
---
 examples/demo_server/bin/main.dart       | 21 ++++--------------
 examples/demo_server/bin/main.mcp.g.dart | 23 +-------------------
 examples/demo_server/pubspec.yaml        | 14 +++++++-----
 pkgs/mcp_annotations/CHANGELOG.md        |  6 ++++++
 pkgs/mcp_annotations/LICENSE             | 27 ++++++++++++++++++++++++
 pkgs/mcp_annotations/pubspec.yaml        |  3 +--
 pkgs/mcp_codegen/CHANGELOG.md            |  7 ++++++
 pkgs/mcp_codegen/LICENSE                 | 27 ++++++++++++++++++++++++
 pkgs/mcp_codegen/pubspec.yaml            | 15 +++++++------
 9 files changed, 91 insertions(+), 52 deletions(-)
 create mode 100644 pkgs/mcp_annotations/CHANGELOG.md
 create mode 100644 pkgs/mcp_annotations/LICENSE
 create mode 100644 pkgs/mcp_codegen/CHANGELOG.md
 create mode 100644 pkgs/mcp_codegen/LICENSE

diff --git a/examples/demo_server/bin/main.dart b/examples/demo_server/bin/main.dart
index 593665d3..898cd0a2 100644
--- a/examples/demo_server/bin/main.dart
+++ b/examples/demo_server/bin/main.dart
@@ -1,6 +1,4 @@
-// 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.
+// ignore_for_file: unused_import
 
 import 'package:mcp_annotations/mcp_annotations.dart';
 import 'dart:convert';
@@ -16,20 +14,9 @@ part 'main.mcp.g.dart';
 class MCPDemoServer {
   const MCPDemoServer();
 
-  @MCPTool(description: 'Adds two numbers.')
-  num add(num a, num b) => a + b;
-
-  @MCPTool(
-    description: 'Returns the length of a string.',
-    parameters: [
-      MCPParameter(
-        name: 'text',
-        description: 'The string to get the length of.',
-      ),
-    ],
-  )
-  int strlen(String text) {
-    return text.length;
+  @MCPTool(description: "add two numbers")
+  num add(num a, num b) {
+    return a + b;
   }
 }
 
diff --git a/examples/demo_server/bin/main.mcp.g.dart b/examples/demo_server/bin/main.mcp.g.dart
index ecff98ad..89d49397 100644
--- a/examples/demo_server/bin/main.mcp.g.dart
+++ b/examples/demo_server/bin/main.mcp.g.dart
@@ -11,7 +11,7 @@ part of 'main.dart';
 
 final Tool _tool_add = Tool(
   name: 'add',
-  description: 'Adds two numbers.',
+  description: 'add two numbers',
   inputSchema: ObjectSchema(
     properties: {'a': NumberSchema(), 'b': NumberSchema()},
     required: ['a', 'b'],
@@ -28,26 +28,6 @@ FutureOr<CallToolResult> _handler_add(
   return CallToolResult(content: [TextContent(text: _result.toString())]);
 }
 
-final Tool _tool_strlen = Tool(
-  name: 'strlen',
-  description: 'Returns the length of a string.',
-  inputSchema: ObjectSchema(
-    properties: {
-      'text': StringSchema(description: 'The string to get the length of.')
-    },
-    required: ['text'],
-  ),
-  annotations: null,
-);
-
-FutureOr<CallToolResult> _handler_strlen(
-    MCPDemoServer _impl, CallToolRequest _request) async {
-  final _args = _request.arguments ?? const <String, Object?>{};
-  final String text = _args['text'] as String;
-  final _result = await Future.sync(() => _impl.strlen(text));
-  return CallToolResult(content: [TextContent(text: _result.toString())]);
-}
-
 final class _GeneratedServer extends MCPServer
     with LoggingSupport, ToolsSupport, ResourcesSupport, RootsTrackingSupport {
   final MCPDemoServer _impl;
@@ -61,7 +41,6 @@ final class _GeneratedServer extends MCPServer
   @override
   FutureOr<InitializeResult> initialize(InitializeRequest request) {
     registerTool(_tool_add, (r) => _handler_add(_impl, r));
-    registerTool(_tool_strlen, (r) => _handler_strlen(_impl, r));
     return super.initialize(request);
   }
 }
diff --git a/examples/demo_server/pubspec.yaml b/examples/demo_server/pubspec.yaml
index 26b3dc50..3b6a85db 100644
--- a/examples/demo_server/pubspec.yaml
+++ b/examples/demo_server/pubspec.yaml
@@ -7,14 +7,18 @@ environment:
   sdk: '>=3.2.0 <4.0.0'
 
 dependencies:
-  dart_mcp:
-    path: ../../pkgs/dart_mcp
-  mcp_annotations:
-    path: ../../pkgs/mcp_annotations
+  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
-  
\ No newline at end of file
diff --git a/pkgs/mcp_annotations/CHANGELOG.md b/pkgs/mcp_annotations/CHANGELOG.md
new file mode 100644
index 00000000..53706427
--- /dev/null
+++ b/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.
diff --git a/pkgs/mcp_annotations/LICENSE b/pkgs/mcp_annotations/LICENSE
new file mode 100644
index 00000000..2b76736b
--- /dev/null
+++ b/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.
diff --git a/pkgs/mcp_annotations/pubspec.yaml b/pkgs/mcp_annotations/pubspec.yaml
index 143327e5..47c9eca7 100644
--- a/pkgs/mcp_annotations/pubspec.yaml
+++ b/pkgs/mcp_annotations/pubspec.yaml
@@ -1,7 +1,6 @@
 name: mcp_annotations
-version: 0.1.0-wip
+version: 0.1.0
 description: Annotations for generating MCP server boilerplate and tools.
-publish_to: none
 
 environment:
   sdk: ^3.7.0
diff --git a/pkgs/mcp_codegen/CHANGELOG.md b/pkgs/mcp_codegen/CHANGELOG.md
new file mode 100644
index 00000000..7008faed
--- /dev/null
+++ b/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.
diff --git a/pkgs/mcp_codegen/LICENSE b/pkgs/mcp_codegen/LICENSE
new file mode 100644
index 00000000..2b76736b
--- /dev/null
+++ b/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.
diff --git a/pkgs/mcp_codegen/pubspec.yaml b/pkgs/mcp_codegen/pubspec.yaml
index 8f62c368..4fcfa37e 100644
--- a/pkgs/mcp_codegen/pubspec.yaml
+++ b/pkgs/mcp_codegen/pubspec.yaml
@@ -1,6 +1,5 @@
 name: mcp_codegen
-version: 0.1.0-wip
-publish_to: none
+version: 0.1.0
 description: >-
   Source-gen builder that generates boilerplate MCP server and tool code.
 
@@ -11,13 +10,17 @@ dependencies:
   analyzer: ^6.4.0
   build: ^2.4.0
   source_gen: ^1.5.0
-  dart_mcp:
-    path: ../dart_mcp
-  mcp_annotations:
-    path: ../mcp_annotations  
+  dart_mcp: ^0.2.0
+  mcp_annotations: ^0.1.0
   meta: ^1.11.0
 
 dev_dependencies:
   build_runner: ^2.4.7
   build_test: ^2.2.2 
 
+dependency_overrides:
+  mcp_annotations:
+    path: ../mcp_annotations
+  dart_mcp:
+    path: ../dart_mcp
+