feat(bridge): add JSON Schema export to HostFunctionSchema and HostParam

Enable MCP tool registration by generating JSON Schema from host function
definitions. HostParam gains toJsonSchema() and an optional jsonSchemaOverride
for complex types (nested objects, enums). HostFunctionSchema.toJsonSchema()
produces MCP-compatible inputSchema with properties and required fields.

Author: runyaga

packages/dart_monty_bridge/lib/src/bridge/host_function_schema.dart

@@ -28,6 +28,32 @@ class HostFunctionSchema {
   /// Keyword args overlay by name.
   final List<HostParam> params;
 
+  /// Returns a JSON Schema object describing this function's input.
+  ///
+  /// Produces a schema compatible with MCP tool `inputSchema`:
+  /// ```json
+  /// {
+  ///   "type": "object",
+  ///   "properties": { ... },
+  ///   "required": ["param1"]
+  /// }
+  /// ```
+  Map<String, Object?> toJsonSchema() {
+    final properties = <String, Object?>{};
+    final required = <String>[];
+
+    for (final param in params) {
+      properties[param.name] = param.toJsonSchema();
+      if (param.isRequired) required.add(param.name);
+    }
+
+    return {
+      'type': 'object',
+      'properties': properties,
+      if (required.isNotEmpty) 'required': required,
+    };
+  }
+
   /// Maps positional + keyword args from [pending] to a named parameter map.
   ///
   /// 1. Positional args are matched to [params] by order.

packages/dart_monty_bridge/lib/src/bridge/host_param.dart

@@ -11,6 +11,7 @@ class HostParam {
     this.isRequired = true,
     this.description,
     this.defaultValue,
+    this.jsonSchemaOverride,
   });
 
   /// Parameter name (used as the key in the validated args map).
@@ -28,6 +29,29 @@ class HostParam {
   /// Default value when the argument is absent and not required.
   final Object? defaultValue;
 
+  /// Optional full JSON Schema override for this parameter.
+  ///
+  /// When set, [toJsonSchema] returns this map directly instead of
+  /// generating from [type] and [description]. Use this for complex
+  /// schemas (nested objects, enums, arrays with item types) that
+  /// [HostParamType] cannot express.
+  final Map<String, Object?>? jsonSchemaOverride;
+
+  /// Returns a JSON Schema property definition for this parameter.
+  ///
+  /// If [jsonSchemaOverride] is set, returns it directly. Otherwise
+  /// generates a schema from [type] and [description].
+  Map<String, Object?> toJsonSchema() {
+    if (jsonSchemaOverride != null) return jsonSchemaOverride!;
+
+    final schema = <String, Object?>{
+      'type': type.jsonSchemaType,
+    };
+    if (description != null) schema['description'] = description;
+
+    return schema;
+  }
+
   /// Validates and optionally coerces [value].
   ///
   /// Returns the validated (possibly coerced) value.

packages/dart_monty_bridge/test/src/bridge/host_function_schema_test.dart

@@ -0,0 +1,199 @@
+import 'package:dart_monty_bridge/dart_monty_bridge.dart';
+import 'package:test/test.dart';
+
+void main() {
+  group('HostParam.toJsonSchema', () {
+    test('generates schema from type and description', () {
+      const param = HostParam(
+        name: 'query',
+        type: HostParamType.string,
+        description: 'Search query',
+      );
+
+      expect(param.toJsonSchema(), {
+        'type': 'string',
+        'description': 'Search query',
+      });
+    });
+
+    test('omits description when null', () {
+      const param = HostParam(
+        name: 'count',
+        type: HostParamType.integer,
+      );
+
+      expect(param.toJsonSchema(), {'type': 'integer'});
+    });
+
+    test('maps all HostParamType values', () {
+      const cases = {
+        HostParamType.string: 'string',
+        HostParamType.integer: 'integer',
+        HostParamType.number: 'number',
+        HostParamType.boolean: 'boolean',
+        HostParamType.list: 'array',
+        HostParamType.map: 'object',
+        HostParamType.any: 'string',
+      };
+
+      for (final entry in cases.entries) {
+        final param = HostParam(name: 'x', type: entry.key);
+        expect(
+          param.toJsonSchema()['type'],
+          entry.value,
+          reason: '${entry.key} should map to ${entry.value}',
+        );
+      }
+    });
+
+    test('uses jsonSchemaOverride when set', () {
+      const override = {
+        'type': 'object',
+        'properties': {
+          'x': {'type': 'number'},
+          'y': {'type': 'number'},
+        },
+        'required': ['x', 'y'],
+      };
+
+      const param = HostParam(
+        name: 'point',
+        type: HostParamType.map,
+        description: 'A 2D point',
+        jsonSchemaOverride: override,
+      );
+
+      expect(param.toJsonSchema(), override);
+    });
+
+    test('jsonSchemaOverride takes precedence over type and description', () {
+      const param = HostParam(
+        name: 'color',
+        type: HostParamType.string,
+        description: 'ignored',
+        jsonSchemaOverride: {
+          'type': 'string',
+          'enum': ['red', 'green', 'blue'],
+        },
+      );
+
+      final schema = param.toJsonSchema();
+      expect(schema['enum'], ['red', 'green', 'blue']);
+      expect(schema.containsKey('description'), isFalse);
+    });
+  });
+
+  group('HostFunctionSchema.toJsonSchema', () {
+    test('generates empty object schema for no params', () {
+      const schema = HostFunctionSchema(
+        name: 'ping',
+        description: 'Health check',
+      );
+
+      expect(schema.toJsonSchema(), {
+        'type': 'object',
+        'properties': <String, Object?>{},
+      });
+    });
+
+    test('generates schema with required and optional params', () {
+      const schema = HostFunctionSchema(
+        name: 'search',
+        description: 'Search documents',
+        params: [
+          HostParam(
+            name: 'query',
+            type: HostParamType.string,
+            description: 'Search query',
+          ),
+          HostParam(
+            name: 'limit',
+            type: HostParamType.integer,
+            description: 'Max results',
+            isRequired: false,
+            defaultValue: 10,
+          ),
+          HostParam(
+            name: 'verbose',
+            type: HostParamType.boolean,
+            isRequired: false,
+          ),
+        ],
+      );
+
+      expect(schema.toJsonSchema(), {
+        'type': 'object',
+        'properties': {
+          'query': {'type': 'string', 'description': 'Search query'},
+          'limit': {'type': 'integer', 'description': 'Max results'},
+          'verbose': {'type': 'boolean'},
+        },
+        'required': ['query'],
+      });
+    });
+
+    test('omits required key when all params are optional', () {
+      const schema = HostFunctionSchema(
+        name: 'configure',
+        description: 'Set options',
+        params: [
+          HostParam(
+            name: 'timeout',
+            type: HostParamType.number,
+            isRequired: false,
+          ),
+        ],
+      );
+
+      final jsonSchema = schema.toJsonSchema();
+      expect(jsonSchema.containsKey('required'), isFalse);
+    });
+
+    test('includes all required params in required list', () {
+      const schema = HostFunctionSchema(
+        name: 'create',
+        description: 'Create resource',
+        params: [
+          HostParam(name: 'name', type: HostParamType.string),
+          HostParam(name: 'tags', type: HostParamType.list),
+          HostParam(name: 'meta', type: HostParamType.map),
+        ],
+      );
+
+      expect(schema.toJsonSchema()['required'], ['name', 'tags', 'meta']);
+    });
+
+    test('respects jsonSchemaOverride on individual params', () {
+      const schema = HostFunctionSchema(
+        name: 'draw',
+        description: 'Draw a shape',
+        params: [
+          HostParam(
+            name: 'shape',
+            type: HostParamType.string,
+            jsonSchemaOverride: {
+              'type': 'string',
+              'enum': ['circle', 'square', 'triangle'],
+              'description': 'Shape type',
+            },
+          ),
+          HostParam(
+            name: 'radius',
+            type: HostParamType.number,
+            isRequired: false,
+            description: 'Shape radius',
+          ),
+        ],
+      );
+
+      final jsonSchema = schema.toJsonSchema();
+      final properties =
+          jsonSchema['properties']! as Map<String, Object?>;
+      final shapeSchema = properties['shape']! as Map<String, Object?>;
+      expect(shapeSchema['enum'], ['circle', 'square', 'triangle']);
+
+      final radiusSchema = properties['radius']! as Map<String, Object?>;
+      expect(radiusSchema, {'type': 'number', 'description': 'Shape radius'});
+    });
+  });
+}