axn-mcp 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 33bb333838d7dfe4375c7d66f95b0058c66330eb309271e752f8587d77de4ac7
+  data.tar.gz: 9bc64595d2939e420e1fa55c7cfe91b19799d56a73ca0c710dc6ced07edd643f
+SHA512:
+  metadata.gz: 4fe4d4184f017f35677742055e7ab2f83c261ada3bf8d6f3da946d15f23d2c3b0dd0b9078d49aad17eddc6389a9d67c1f9b9e84d1d2e4e82023ff13d44b2622f
+  data.tar.gz: 816a6455d2f2cef47db441aa41af1d85bca24a8f6f3666a88fe5275930fdb8ad0567f3cfe5b3a602402bc1c406d9a1cbb64ec49c2c9da49c5fc3e80af76bbb9a

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0
+
+- Initial release
+- `Axn::MCP::Tool` base class for building MCP tools with Axn
+- Auto-generated JSON schemas from `expects`/`exposes` declarations
+- Automatic `model:` field handling (exposes `_id` field to LLM)
+- Auto-serialization of exposed values to JSON-safe structures
+- Annotation shortcuts: `read_only!`, `destructive!`, `idempotent!`, `open_world!`, `closed_world!`
+- Factory-style `Tool.define` for quick one-off tools
+- Dual-use: returns `Axn::Result` for direct calls, `MCP::Tool::Response` when called via MCP server
+- Typed array element schemas: `Array` fields with `of:` emit a machine-readable `items:` entry in JSON Schema rather than a bare `array` type — scalar types, `:boolean`/`:uuid` shorthands, `Data.define` structs (bare member names), and union types (`anyOf`) are all supported
+- Structured field contracts via `shape:` block: annotate individual element/member types and validations inline; `required` is derived automatically from optional vs non-optional members; blocks recurse for nested objects
+- When `of: <Data.define>` and a `shape:` block are combined, Data members provide the bare-name baseline and block-declared members overlay typed properties (enrich)

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Teamshares, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,441 @@
+# Axn::MCP
+
+Build [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) tools using [Axn](https://github.com/teamshares/axn)'s declarative `expects`/`exposes` contract. This gem wraps the official [MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk) and auto-generates JSON schemas from your Axn field declarations.
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "axn-mcp"
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+## Quick Start
+
+Define an MCP tool by inheriting from `Axn::MCP::Tool`:
+
+```ruby
+class GreetUser < Axn::MCP::Tool
+  description "Greet a user by name"
+
+  expects :name, type: String, description: "The user's name"
+  exposes :greeting, type: String, description: "The greeting message"
+
+  def call
+    expose greeting: "Hello, #{name}!"
+  end
+end
+```
+
+That's it. The gem automatically:
+
+- Generates `inputSchema` from your `expects` declarations
+- Generates `outputSchema` from your `exposes` declarations
+- Converts `Axn::Result` to `MCP::Tool::Response`
+- Serializes exposed data to JSON-safe `structured_content`
+
+## Usage
+
+### Basic Tool Definition
+
+```ruby
+class CreateNote < Axn::MCP::Tool
+  description "Create a new note"
+
+  expects :title, type: String, description: "Note title"
+  expects :content, type: String, description: "Note body"
+  expects :tags, type: Array, optional: true, description: "Optional tags"
+
+  exposes :note_id, type: Integer, description: "ID of the created note"
+
+  def call
+    note = Note.create!(title:, content:, tags: tags || [])
+    expose note_id: note.id
+  end
+end
+```
+
+### Field Descriptions
+
+Use `description:` directly as a kwarg on `expects` and `exposes`:
+
+```ruby
+expects :start_date, type: Date, optional: true, description: "Inclusive lower bound (YYYY-MM-DD)"
+exposes :results,    type: Array,                description: "Matching records"
+```
+
+> **Note:** Do *not* wrap it in `metadata: { description: ... }`. The `metadata:` key is not recognized by `expects`/`exposes` and raises `ArgumentError` at class load time.
+
+### Type Mappings
+
+Axn types map to JSON Schema types:
+
+
+| Ruby Type          | JSON Schema                    |
+| ------------------ | ------------------------------ |
+| `String`           | `string`                       |
+| `Integer`          | `integer`                      |
+| `Float`, `Numeric` | `number`                       |
+| `Hash`             | `object`                       |
+| `Array`            | `array`                        |
+| `:boolean`         | `boolean`                      |
+| `:uuid`            | `string` (format: `uuid`)      |
+| `Date`             | `string` (format: `date`)      |
+| `DateTime`, `Time` | `string` (format: `date-time`) |
+
+
+### Typed member contracts with `shape:`
+
+Add a `shape:` block to a `Hash` or `Data.define` field to declare types and validations for its members. `required` is derived automatically; unannotated members on a `Data.define` type appear as bare `{}`. The block syntax is the same on both `expects` and `exposes`. (For `Array` fields, combine `shape:` with `of:` — see the next section.)
+
+**Hash field:**
+
+```ruby
+exposes :config, type: Hash do
+  field :region,  type: String
+  field :timeout, type: Integer, optional: true
+end
+```
+
+```json
+{
+  "type": "object",
+  "required": ["region"],
+  "properties": {
+    "region":  { "type": "string" },
+    "timeout": { "type": "integer" }
+  }
+}
+```
+
+**`Data.define` struct:**
+
+```ruby
+IntegrationRecord = Data.define(:source, :provider_name, :active, :status)
+
+exposes :integration, type: IntegrationRecord do
+  field :status, type: String, inclusion: { in: %w[connected error needs_reconnect] }
+  field :active, type: :boolean, optional: true
+end
+```
+
+```json
+{
+  "type": "object",
+  "required": ["status"],
+  "properties": {
+    "status":        { "type": "string", "enum": ["connected", "error", "needs_reconnect"] },
+    "active":        { "type": "boolean" },
+    "source":        {},
+    "provider_name": {}
+  }
+}
+```
+
+Blocks recurse naturally for nested objects:
+
+```ruby
+exposes :config, type: Hash do
+  field :region,    type: String
+  field :retention, type: Hash do
+    field :days, type: Integer
+  end
+end
+```
+
+### Typed array elements with `of:`
+
+When an `Array` field carries an `of:` declaration, the generated JSON Schema includes a machine-readable `items:` entry rather than a bare `array` type.
+
+**Scalar element type:**
+
+```ruby
+exposes :tags, type: Array, of: String
+```
+
+```json
+{ "type": "array", "items": { "type": "string" } }
+```
+
+Other supported forms: `of: Integer`, `of: :boolean`, `of: :uuid`, and union types:
+
+```ruby
+exposes :values, type: Array, of: [String, Numeric]
+```
+
+```json
+{ "type": "array", "items": { "anyOf": [{ "type": "string" }, { "type": "number" }] } }
+```
+
+**`Data.define` struct — bare member names as baseline:**
+
+```ruby
+exposes :integrations, type: Array, of: IntegrationRecord
+```
+
+```json
+{
+  "type": "array",
+  "items": {
+    "type": "object",
+    "properties": { "source": {}, "provider_name": {}, "active": {}, "status": {} }
+  }
+}
+```
+
+**Combine `of:` with a `shape:` block to annotate element members:**
+
+```ruby
+exposes :integrations, type: Array, of: IntegrationRecord do
+  field :status, type: String, inclusion: { in: %w[connected error needs_reconnect] }
+  field :active, type: :boolean, optional: true
+end
+```
+
+```json
+{
+  "type": "array",
+  "items": {
+    "type": "object",
+    "required": ["status"],
+    "properties": {
+      "status":        { "type": "string", "enum": ["connected", "error", "needs_reconnect"] },
+      "active":        { "type": "boolean" },
+      "source":        {},
+      "provider_name": {}
+    }
+  }
+}
+```
+
+Annotated members are fully typed; unannotated `Data.define` members (`source`, `provider_name`) remain as bare `{}`.
+
+### ActiveRecord Model Fields
+
+When using `model: true`, the schema automatically generates an `_id` field with an appropriate description:
+
+```ruby
+class UpdateUser < Axn::MCP::Tool
+  description "Update a user's profile"
+
+  expects :user, model: true
+  expects :name, type: String, optional: true
+
+  def call
+    user.update!(name:) if name
+  end
+end
+```
+
+Generates schema:
+
+```json
+{
+  "properties": {
+    "user_id": {
+      "type": "integer",
+      "description": "ID of the User record"
+    }
+  }
+}
+```
+
+### Enums via Inclusion
+
+```ruby
+expects :status, inclusion: { in: %w[active inactive pending] }
+```
+
+Generates:
+
+```json
+{
+  "status": {
+    "type": "string",
+    "enum": ["active", "inactive", "pending"]
+  }
+}
+```
+
+### Annotations
+
+Use convenience methods or the `annotations` DSL:
+
+```ruby
+class ReadOnlyTool < Axn::MCP::Tool
+  description "Fetch data without side effects"
+  read_only!
+
+  # ...
+end
+
+class DangerousTool < Axn::MCP::Tool
+  description "Delete all the things"
+  destructive!
+  idempotent!
+
+  # ...
+end
+
+class CustomAnnotations < Axn::MCP::Tool
+  annotations(
+    read_only_hint: true,
+    idempotent_hint: true,
+    title: "My Custom Tool",
+  )
+
+  # ...
+end
+```
+
+Available shortcuts:
+
+
+| Method          | Effect                                            |
+| --------------- | ------------------------------------------------- |
+| `read_only!`    | `read_only_hint: true`, `destructive_hint: false` |
+| `destructive!`  | `destructive_hint: true`, `read_only_hint: false` |
+| `idempotent!`   | `idempotent_hint: true`                           |
+| `open_world!`   | `open_world_hint: true`                           |
+| `closed_world!` | `open_world_hint: false`                          |
+
+
+### Factory-Style Definition
+
+For quick one-off tools:
+
+```ruby
+SearchTool = Axn::MCP::Tool.define(
+  description: "Search for items",
+  expects: { query: { type: String, description: "Search query" } },
+  exposes: { results: { type: Array } },
+  annotations: { read_only_hint: true },
+) do
+  expose results: Item.search(query)
+end
+```
+
+### Server Context
+
+`server_context` is automatically available in all tools (no declaration needed):
+
+```ruby
+class AuthenticatedTool < Axn::MCP::Tool
+  description "Do something with the current user"
+
+  def call
+    current_user = server_context&.dig(:user)
+    # ...
+  end
+end
+```
+
+Note the safe navigation (`&.dig`): `server_context` may be `nil` if the tool is invoked directly as a standard Axn action rather than through the MCP server.
+
+The `server_context` field is excluded from the generated `inputSchema` since it's injected by the MCP server, not provided by the LLM.
+
+### Dual-Use: MCP Server vs Direct Invocation
+
+Tools automatically adapt their return type based on how they're called:
+
+```ruby
+# Called FROM MCP server (server_context injected) → returns MCP::Tool::Response
+# This happens automatically when registered with MCP::Server
+
+# Called DIRECTLY without server_context → returns Axn::Result
+result = MyTool.call(name: "Alice")
+if result.ok?
+  puts result.greeting
+else
+  puts "Error: #{result.message}"
+end
+
+# Or use call! to raise on failure
+result = MyTool.call!(name: "Bob")
+puts result.greeting
+```
+
+The branching is based on presence of `server_context`:
+
+- **With `server_context`**: Returns `MCP::Tool::Response` (for MCP server compatibility)
+- **Without `server_context`**: Returns `Axn::Result` (standard Axn semantics)
+
+This allows you to test tools or call them from non-MCP contexts using standard Axn patterns.
+
+## Error Handling
+
+Use Axn's standard `fail!` method for controlled failures:
+
+```ruby
+def call
+  fail! "User not found" unless user
+  fail! "Unauthorized" unless authorized?
+
+  # success path...
+end
+```
+
+Unhandled exceptions are also caught automatically. When an exception occurs:
+
+1. The error is recorded on the result
+2. Any configured `on_exception` handlers are triggered (see [Axn configuration](https://github.com/teamshares/axn))
+3. An `MCP::Tool::Response` is returned with `error: true`
+
+Both `fail!` calls and unhandled exceptions result in error responses to the LLM.
+
+## Integration with MCP Server
+
+Register your tools with an MCP server:
+
+```ruby
+require "mcp"
+require "axn-mcp"
+
+server = MCP::Server.new(
+  name: "my-server",
+  version: "1.0.0",
+  tools: [GreetUser, CreateNote, SearchTool],
+)
+
+# Use with stdio transport
+transport = MCP::Server::Transports::StdioTransport.new(server)
+transport.open
+```
+
+For complete server setup, transport options, and advanced configuration, see the [MCP Ruby SDK documentation](https://github.com/modelcontextprotocol/ruby-sdk).
+
+### Success response text: config and per-tool
+
+By default, successful responses contain a text block with the JSON-serialized `structured_content` (a SHOULD per [MCP spec](https://modelcontextprotocol.io/specification/draft/server/tools#structured-content)). To use the Axn success message instead, set **central config** once (`Axn::MCP.config.mcp_text_content = :message`) or override **per tool** with `mcp_text_content :message`. Valid values are `:structured` (default) and `:message`; per-tool overrides config.
+
+## Requirements
+
+- Ruby >= 3.2.1
+- [axn](https://github.com/teamshares/axn) >= 0.1.0-alpha.4.3
+- [mcp](https://github.com/modelcontextprotocol/ruby-sdk) >= 0.4
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec
+bundle exec rubocop
+```
+
+## License
+
+MIT License. See [LICENSE](LICENSE) for details.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/teamshares/axn-mcp](https://github.com/teamshares/axn-mcp).
+
+## Acknowledgments
+
+This gem wraps the excellent [MCP Ruby SDK](https://github.com/modelcontextprotocol/ruby-sdk) from the Model Context Protocol team.

data/Rakefile

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+require "rubocop/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]
+
+Rake::Task["build"].enhance([:default])

data/lib/axn/mcp/config.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module Axn
+  module MCP
+    class Config
+      VALID_MCP_TEXT_CONTENT = %i[structured message].freeze
+
+      attr_reader :mcp_text_content
+
+      def initialize
+        @mcp_text_content = :structured
+      end
+
+      def mcp_text_content=(value)
+        self.class.validate_mcp_text_content!(value)
+        @mcp_text_content = value
+      end
+
+      def self.validate_mcp_text_content!(value)
+        return if VALID_MCP_TEXT_CONTENT.include?(value)
+
+        raise ArgumentError,
+              "mcp_text_content must be one of #{VALID_MCP_TEXT_CONTENT.map(&:inspect).join(", ")}; got #{value.inspect}"
+      end
+    end
+  end
+end

data/lib/axn/mcp/field_declarations.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Axn
+  module MCP
+    module FieldDeclarations
+      module_function
+
+      def hydrate(declarations)
+        return declarations if declarations.is_a?(Hash)
+
+        Array(declarations).each_with_object({}) do |item, acc|
+          if item.is_a?(Hash)
+            item.each { |k, v| acc[k] = v }
+          else
+            acc[item] = {}
+          end
+        end
+      end
+    end
+  end
+end

data/lib/axn/mcp/schema_builder.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+require "date"
+
+module Axn
+  module MCP
+    module SchemaBuilder
+      TYPE_MAP = {
+        String => "string",
+        Integer => "integer",
+        Float => "number",
+        Numeric => "number",
+        Hash => "object",
+        Array => "array",
+        TrueClass => "boolean",
+        FalseClass => "boolean",
+        Date => "string",
+        DateTime => "string",
+        Time => "string",
+      }.freeze
+
+      FORMAT_MAP = {
+        Date => "date",
+        DateTime => "date-time",
+        Time => "date-time",
+      }.freeze
+
+      EXCLUDED_FROM_SCHEMA = %i[server_context].freeze
+
+      module_function
+
+      def build_input(field_configs, subfield_configs = [])
+        properties = {}
+        required = []
+
+        subfields_by_parent = subfield_configs.group_by(&:on)
+
+        field_configs.each do |config|
+          next if EXCLUDED_FROM_SCHEMA.include?(config.field)
+
+          if config.validations[:model]
+            build_model_property(config, properties, required)
+          else
+            prop = build_property(config)
+            nested_subfields = subfields_by_parent[config.field]
+            if nested_subfields&.any? && prop[:type] == "object"
+              prop[:properties] ||= {}
+              prop[:required] ||= []
+              nested_subfields.each do |subconfig|
+                subprop = build_property(subconfig)
+                prop[:properties][subconfig.field] = subprop
+                prop[:required] << subconfig.field.to_s unless optional?(subconfig)
+              end
+              prop[:required] = nil if prop[:required].empty?
+            end
+
+            properties[config.field] = prop.compact
+            required << config.field.to_s unless optional?(config)
+          end
+        end
+
+        schema = { type: "object", properties: }
+        schema[:required] = required unless required.empty?
+        schema
+      end
+
+      def build_output(field_configs)
+        properties = {}
+        required = []
+
+        field_configs.each do |config|
+          prop = build_property(config, for_output: true)
+          properties[config.field] = prop.compact
+          required << config.field.to_s unless optional?(config)
+        end
+
+        schema = { type: "object", properties: }
+        schema[:required] = required unless required.empty?
+        schema
+      end
+
+      def build_property(config, for_output: false)
+        prop = {}
+        prop[:description] = config.description if config.description
+
+        type_info = json_type_for(config.validations, for_output:)
+        prop[:type] = type_info[:type] if type_info[:type]
+        prop[:format] = type_info[:format] if type_info[:format]
+
+        prop[:default] = config.default if config.respond_to?(:default) && !config.default.nil?
+
+        if (inclusion = config.validations[:inclusion])
+          enum_values = inclusion[:in] || inclusion[:within] if inclusion.is_a?(Hash)
+          prop[:enum] = enum_values if enum_values
+        end
+
+        apply_structured_schema!(prop, config, for_output:)
+
+        prop
+      end
+
+      # Combine of: (bare element baseline) and shape: (typed member contracts) into
+      # items:/properties: schema. Precedence: shape: enriches/overrides of: baseline.
+      def apply_structured_schema!(prop, config, for_output:)
+        of    = config.validations[:of]
+        shape = config.validations[:shape]
+        return unless of || shape
+
+        if prop[:type] == "array"
+          items = of ? items_schema_for(of, for_output:) : {}
+          if shape
+            member_props, required = member_properties(shape[:members], for_output:)
+            base_props = items[:properties] || {}
+            items = items.merge(type: "object", properties: base_props.merge(member_props))
+            items[:required] = required unless required.empty?
+          end
+          prop[:items] = items unless items.empty?
+        elsif shape
+          # Hash / class field — shape: members are the object's own properties.
+          # If the field type is a Data.define subclass, use its members as the bare
+          # baseline so unannotated members still appear (same enrich logic as of:).
+          member_props, required = member_properties(shape[:members], for_output:)
+          type_klass = config.validations.dig(:type, :klass)
+          base_props = type_klass.is_a?(Class) && type_klass < Data ? type_klass.members.to_h { |m| [m, {}] } : {}
+          prop[:properties] = base_props.merge(member_props)
+          prop[:required] = required unless required.empty?
+        end
+      end
+
+      # Build a JSON Schema items: value from the of: validation hash.
+      def items_schema_for(of_validations, for_output: false)
+        klasses = Array(of_validations[:klass])
+        if klasses.size == 1
+          single_items_schema(klasses.first, for_output:)
+        else
+          { anyOf: klasses.map { |k| single_items_schema(k, for_output:) } }
+        end
+      end
+
+      def single_items_schema(klass, for_output: false)
+        if klass.is_a?(Class) && klass < Data
+          # Data.define subclass → object with named (but untyped) properties as baseline
+          { type: "object", properties: klass.members.to_h { |m| [m, {}] } }
+        else
+          json_type_for({ type: klass }, for_output:)
+        end
+      end
+
+      # Build properties/required from a shape: block's members. Recurses for nested shape/of.
+      def member_properties(members, for_output:)
+        props = {}
+        required = []
+        members.each do |m|
+          props[m.field] = build_property(m, for_output:).compact
+          required << m.field.to_s unless optional?(m)
+        end
+        [props, required]
+      end
+
+      def build_model_property(config, properties, required)
+        model_opts = config.validations[:model]
+        klass = model_opts[:klass]
+        klass_name = klass.is_a?(Class) ? klass.name : klass.to_s
+
+        id_field = :"#{config.field}_id"
+        prop = {
+          type: "integer",
+          description: config.description || "ID of the #{klass_name} record",
+        }
+
+        properties[id_field] = prop.compact
+        required << id_field.to_s unless optional?(config)
+      end
+
+      def json_type_for(validations, for_output: false)
+        if validations[:type]
+          type_opt = validations[:type]
+          klass = type_opt.is_a?(Hash) ? type_opt[:klass] : type_opt
+          klasses = Array(klass)
+
+          klass = klasses.first
+          return { type: "boolean" } if klass == :boolean
+          return { type: "string", format: "uuid" } if klass == :uuid
+
+          if TYPE_MAP.key?(klass)
+            result = { type: TYPE_MAP[klass] }
+            result[:format] = FORMAT_MAP[klass] if FORMAT_MAP.key?(klass)
+            return result
+          end
+
+          return { type: "object" } if for_output
+
+          return { type: "string" }
+        end
+
+        if validations[:inclusion]
+          inclusion = validations[:inclusion]
+          enum_values = inclusion[:in] || inclusion[:within] if inclusion.is_a?(Hash)
+          if enum_values&.any?
+            sample = enum_values.first
+            return { type: "string" } if sample.is_a?(String)
+            return { type: "integer" } if sample.is_a?(Integer)
+            return { type: "number" } if sample.is_a?(Float)
+          end
+        end
+
+        if validations[:numericality]
+          numericality = validations[:numericality]
+          return { type: "integer" } if numericality.is_a?(Hash) && numericality[:only_integer]
+
+          return { type: "number" }
+        end
+
+        return { type: "string" } if validations[:presence] || validations[:length]
+
+        {}
+      end
+
+      def optional?(config)
+        Axn::Internal::FieldConfig.optional?(config)
+      end
+    end
+  end
+end

data/lib/axn/mcp/serializer.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require "json"
+require "active_support/core_ext/object/blank"
+
+module Axn
+  module MCP
+    module Serializer
+      module_function
+
+      def serialize_exposed(result, field_configs)
+        field_configs.each_with_object({}) do |config, hash|
+          value = result.public_send(config.field)
+          hash[config.field.to_s] = serialize_value(value)
+        end
+      end
+
+      def serialize_value(value)
+        case value
+        when nil, String, Integer, Float, TrueClass, FalseClass
+          value
+        when Hash
+          value.transform_keys(&:to_s).transform_values { |v| serialize_value(v) }
+        when Array
+          value.map { |v| serialize_value(v) }
+        else
+          if value.respond_to?(:as_json)
+            value.as_json
+          elsif value.respond_to?(:to_h)
+            serialize_value(value.to_h)
+          else
+            value.to_s
+          end
+        end
+      end
+
+      def result_to_mcp_response(result, field_configs, text_content: :structured)
+        if result.ok?
+          exposed = serialize_exposed(result, field_configs)
+          success_text = success_response_text(result, exposed, text_content)
+          ::MCP::Tool::Response.new(
+            [{ type: "text", text: success_text }],
+            structured_content: exposed.presence,
+          )
+        else
+          ::MCP::Tool::Response.new(
+            [{ type: "text", text: result.error }],
+            error: true,
+          )
+        end
+      end
+
+      def success_response_text(result, exposed, text_content)
+        use_message = text_content == :message
+        success_message = result.respond_to?(:success) ? result.success : result.message
+        if use_message || exposed.blank?
+          success_message
+        else
+          JSON.generate(exposed)
+        end
+      end
+    end
+  end
+end

data/lib/axn/mcp/tool.rb

@@ -0,0 +1,151 @@
+# frozen_string_literal: true
+
+module Axn
+  module MCP
+    class Tool < ::MCP::Tool
+      include Axn
+
+      expects :server_context, optional: true, description: "MCP server context (injected automatically)"
+
+      class << self
+        NOT_SET = Object.new.freeze
+
+        def mcp_text_content(value = NOT_SET)
+          if value == NOT_SET
+            resolved_mcp_text_content
+          else
+            Config.validate_mcp_text_content!(value)
+            @mcp_text_content = value
+          end
+        end
+
+        def resolved_mcp_text_content
+          if instance_variable_defined?(:@mcp_text_content) && !@mcp_text_content.nil?
+            @mcp_text_content
+          else
+            Axn::MCP.config.mcp_text_content
+          end
+        end
+
+        def input_schema(value = NOT_SET)
+          if value != NOT_SET
+            super
+          elsif @input_schema_value
+            @input_schema_value
+          else
+            @input_schema_value = ::MCP::Tool::InputSchema.new(
+              SchemaBuilder.build_input(internal_field_configs, subfield_configs),
+            )
+          end
+        end
+
+        def input_schema_value
+          @input_schema_value || input_schema
+        end
+
+        def output_schema(value = NOT_SET)
+          if value != NOT_SET
+            super
+          elsif @output_schema_value
+            @output_schema_value
+          elsif external_field_configs.empty?
+            nil
+          else
+            @output_schema_value = ::MCP::Tool::OutputSchema.new(
+              SchemaBuilder.build_output(external_field_configs),
+            )
+          end
+        end
+
+        def output_schema_value
+          return @output_schema_value if @output_schema_value
+          return nil if external_field_configs.empty?
+
+          output_schema
+        end
+
+        def to_h
+          input_schema
+          output_schema unless external_field_configs.empty?
+          super
+        end
+
+        def call(**kwargs)
+          result = new(**kwargs).tap(&:_run).result
+
+          # Branch on presence of server_context:
+          # - Present: called from MCP server, return MCP::Tool::Response
+          # - Absent: called directly as Axn, return Axn::Result
+          return result unless kwargs.key?(:server_context)
+
+          Serializer.result_to_mcp_response(result, external_field_configs, text_content: resolved_mcp_text_content)
+        end
+
+        def call!(**)
+          result = call(**)
+
+          # For MCP calls (with server_context), just return the response
+          return result if result.is_a?(::MCP::Tool::Response)
+
+          # For direct Axn calls, raise on failure
+          return result if result.ok?
+
+          raise result.exception
+        end
+
+        # Convenience DSL for annotations
+        # See: https://github.com/modelcontextprotocol/ruby-sdk#tool-annotations
+        #
+        # Available annotations:
+        #   destructive_hint: true/false - Indicates if tool performs destructive operations (default: true)
+        #   idempotent_hint: true/false - Indicates if tool's operations are idempotent (default: false)
+        #   open_world_hint: true/false - Indicates if tool operates in open world context (default: true)
+        #   read_only_hint: true/false - Indicates if tool only reads data (default: false)
+        #   title: "string" - Human-readable title for the tool
+
+        def read_only!
+          annotations(read_only_hint: true, destructive_hint: false)
+        end
+
+        def destructive!
+          annotations(destructive_hint: true, read_only_hint: false)
+        end
+
+        def idempotent!
+          annotations(idempotent_hint: true)
+        end
+
+        def open_world!
+          annotations(open_world_hint: true)
+        end
+
+        def closed_world!
+          annotations(open_world_hint: false)
+        end
+
+        # Factory-style tool definition for quick one-off tools
+        def define(description:, expects: [], exposes: [], annotations: nil, mcp_text_content: NOT_SET, **_opts, &block)
+          tool_class = Class.new(self) do
+            include Axn unless self < Axn
+          end
+
+          FieldDeclarations.hydrate(expects).each do |field, field_opts|
+            tool_class.expects(field, **field_opts)
+          end
+
+          FieldDeclarations.hydrate(exposes).each do |field, field_opts|
+            tool_class.exposes(field, **field_opts)
+          end
+
+          tool_class.description(description)
+          tool_class.annotations(annotations) if annotations
+          tool_class.mcp_text_content(mcp_text_content) if mcp_text_content != NOT_SET
+
+          tool_class.define_method(:call, &block) if block
+
+          tool_class
+        end
+      end
+    end
+  end
+end

data/lib/axn/mcp/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Axn
+  module MCP
+    VERSION = "0.1.0"
+  end
+end

data/lib/axn/mcp.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "date"
+require "axn"
+require "mcp"
+
+require_relative "mcp/version"
+require_relative "mcp/config"
+require_relative "mcp/serializer"
+require_relative "mcp/schema_builder"
+require_relative "mcp/field_declarations"
+require_relative "mcp/tool"
+
+module Axn
+  module MCP
+    class SchemaError < StandardError; end
+
+    def self.config
+      @config ||= Config.new
+    end
+  end
+end

data/lib/axn-mcp.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require_relative "axn/mcp"

metadata

@@ -0,0 +1,97 @@
+--- !ruby/object:Gem::Specification
+name: axn-mcp
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kali Donovan
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: axn
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0.pre.alpha.4.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.1.0.pre.alpha.4.3
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: 0.2.0
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.4'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+description: Build MCP tools using Axn's expects/exposes contract with auto-generated
+  JSON schemas and responses.
+email:
+- kali@teamshares.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- lib/axn-mcp.rb
+- lib/axn/mcp.rb
+- lib/axn/mcp/config.rb
+- lib/axn/mcp/field_declarations.rb
+- lib/axn/mcp/schema_builder.rb
+- lib/axn/mcp/serializer.rb
+- lib/axn/mcp/tool.rb
+- lib/axn/mcp/version.rb
+homepage: https://github.com/teamshares/axn-mcp
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/teamshares/axn-mcp
+  source_code_uri: https://github.com/teamshares/axn-mcp
+  changelog_uri: https://github.com/teamshares/axn-mcp/blob/main/CHANGELOG.md
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.1
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.8
+specification_version: 4
+summary: MCP Tool wrapper for Axn actions
+test_files: []