tidewave 0.5.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 80a98c944044fd2164929251e642cd2c35713a3bcd2a427485aa9aed5b9c2780
-  data.tar.gz: dac0861994231e0cfb23eb9203c43c9ed310f0fbb0041e1d674443df1e592323
+  metadata.gz: d8aec0fffb76b0c91651452a2d8e2b1adc3fe37681a0c778c01a4762602985ed
+  data.tar.gz: d0f6abae17bcc8281baed3f3db784b0243186c5008a8866a612e42bda4333e14
 SHA512:
-  metadata.gz: 2e0cd1d84fc3aa6e2f9da2a4c1cd7dcc613e29552ed20f0b73bdcb5770bef22f5555846e290638c77bb1c5df3c1c2d53285b3fb03cd41c127394630f785e60b2
-  data.tar.gz: 50ac0f18928027d78246fe69b0c77f552a3b05772875f8b01f016d05cffbbfeca4262359bff6407781ecb7509a99b2955788e3c1080bac110061f950c7afbd37
+  metadata.gz: 8b683cb4a188e66e456078a39467a10ff6bc9aa1ac3b3f2e92338eadf5cbe1b0a693e6d80dd32d6e8dfdb167dd0b83af1d1183c442fc6d8348beb036180e05ba
+  data.tar.gz: b3366af6bdd77c9312e8e6d70e56d898b02f75555f9b1932fea379bdb36621a8381f31df8696f86f7a6a5604885ae0ded2f22ee51a9bf323e80c7c7e52422c99

data/README.md

@@ -1,27 +1,124 @@
-# Tidewave
+# Tidewave Rails
 
-Tidewave is the coding agent for full-stack web app development. Integrate Claude Code, OpenAI Codex, and other agents with your web app and web framework at every layer, from UI to database. [See our website](https://tidewave.ai) for more information.
+Tidewave Rails is an MCP server that provides runtime-level tools for developing Ruby on Rails apps using coding agents.
 
-This project can also be used as [a standalone Model Context Protocol server](https://hexdocs.pm/tidewave/mcp.html).
+Your agent will be able to use this MCP server to talk to your running Rails app in development to:
+
+- execute code in the context of the running app (like a Rails console for agents)
+- read the app's live logs
+- query your development database
+- get source locations of classes and methods
+- read documentation pinned to the exact gem versions your app depends on
+
+This MCP server is an open-source component of [Tidewave](https://tidewave.ai), the agentic development environment for Rails and Phoenix.
+
+You can use this project as a standalone MCP server or integrated with the [Tidewave product](https://tidewave.ai) by following the instructions below.
 
 ## Installation
 
-You can install Tidewave by running:
+### 1. Add the Tidewave gem to your app
+
+You can add Tidewave Rails to your app by running:
 
 ```shell
 bundle add tidewave --group development
 ```
 
-or by manully adding the `tidewave` gem to the development group in your Gemfile:
+or by manually adding the `tidewave` gem to the development group in your Gemfile:
 
 ```ruby
 gem "tidewave", group: :development
 ```
 
-Now make sure [Tidewave is installed](https://hexdocs.pm/tidewave/installation.html) and you are ready to connect Tidewave to your app.
+### 2. Add the Tidewave MCP to your agent/editor
+
+Add the Tidewave MCP server to your editor or MCP client configuration as the type "http" (streamable), pointing to the `/tidewave/mcp` path and port your web application is running at. For example, `http://localhost:3000/tidewave/mcp`.
+
+We also have specific instructions for:
+
+- [Claude Code](https://tidewave.hexdocs.pm/mcp_claude_code.html)
+- [Codex](https://tidewave.hexdocs.pm/mcp_codex.html)
+- [Cursor](https://tidewave.hexdocs.pm/mcp_cursor.html)
+- [Neovim](https://tidewave.hexdocs.pm/mcp_neovim.html)
+- [OpenCode](https://tidewave.hexdocs.pm/mcp_opencode.html)
+- [VS Code](https://tidewave.hexdocs.pm/mcp_vscode.html)
+- [Zed](https://tidewave.hexdocs.pm/mcp_zed.html)
+- [Others](https://tidewave.hexdocs.pm/mcp.html)
+
+## Usage
+
+As with any other MCP server, your agent will call the tools exposed by the Tidewave MCP whenever it sees fit. But you can also prompt it to call them explicitly.
+
+## Available MCP tools
+
+### `project_eval`
+
+Evaluates Ruby code in the context of your running application, with access to its runtime, loaded dependencies, and in-memory data, returning the result plus anything printed to standard output. It's like a Rails console for the agent.
+
+[![project_eval demo](docs/assets/project_eval-poster.png)](https://asciinema.org/a/v0Bs9WtOUARzewC3)
+
+Your agent can use it when it would rather run code than assume behavior, grounding its next step in what the running app actually does. For example, calling a method to see what comes back or reproducing a failing code path against live app state to debug it.
+
+### `execute_sql_query`
+
+Runs a SQL query against your app's development database and returns the rows to the agent.
+
+[![execute_sql_query demo](docs/assets/execute_sql_query-poster.png)](https://asciinema.org/a/qJtkEDf2YAPqjBHI)
+
+Your agent can use it to run any SQL against your development database. For example, ask it to insert some test records to see how a page looks with realistic data. Or, after a create action, the agent can verify whether the record was saved with the expected values.
+
+### `get_docs`
+
+Looks up the documentation for a class, method, or constant, reading from the exact gem versions locked in your app's Gemfile.lock.
+
+[![get_docs demo](docs/assets/get_docs-poster.png)](https://asciinema.org/a/Aa0u915syzncFYH8)
+
+Your agent can use it when it's unsure how a class or method works, so the code it generates is grounded in the docs for the exact versions of the gems your app uses, rather than training data that may be stale or a generic docs lookup that can't guarantee it matches the version your app depends on.
+
+### `get_logs`
+
+Returns output from your running server's log.
+
+[![get_logs demo](docs/assets/get_logs-poster.png)](https://asciinema.org/a/1260413)
+
+Your agent can use it to see what happened after a request. For example, reading the request log and backtrace when something misbehaves, or checking the log after an action to confirm the request came in with the expected params.
+
+### `get_models`
+
+Lists all of your app's models and where each one is defined, by file and line.
+
+[![get_models demo](docs/assets/get_models-poster.png)](https://asciinema.org/a/qeELC7wEgMEI5T7n)
+
+Your agent can use it to map the data domain and find where each model lives before opening files, rather than grepping around for class definitions.
+
+### `get_source_location`
+
+Returns the file and line where a class, module, or method is defined, across both your app and its dependencies.
+
+[![get_source_location demo](docs/assets/get_source_location-poster.png)](https://asciinema.org/a/1260415)
+
+Your agent can use it to jump straight to where a class or method is defined, by file and line, instead of grepping for it, including when the definition lives in a gem dependency.
+
+Also, because it resolves the location from your running app instead of parsing source text, it handles metaprogramming, where a method is generated at runtime and does not appear as a literal `def` for grep to find.
+
+> [!NOTE]
+> #### Why no tools for routes, associations, etc?
+>
+> Tidewave does not include tools for listing your routes, associations, etc. because
+> agents are better off reading their respective source files, which gives agents more
+> context and enables them to perform any necessary edit without additional tool calls.
+>
+> Instead, Tidewave aims to fill in missing gaps, such as evaluating code inside your
+> Rails app (without starting new instances) and finding source location, which can be
+> tricky, even with grepping, due to metaprogramming and the different places Bundler
+> can install your dependencies.
 
 ## Troubleshooting
 
+### The Tidewave toolbar is missing
+
+This may happen if you are compressing your responses (gzip, brotli, etc) after the Tidewave middleware runs. Use `bin/rails middleware` and make sure Tidewave comes after `Rack::Deflater` or similar. Also look into your browser and terminal logs for any errors.
+
 ### Using multiple hosts/subdomains
 
 If you are using multiple hosts/subdomains during development, you must use `*.localhost`, as such domains are considered secure by browsers. Additionally, add the following to `config/initializers/development.rb`:
@@ -40,7 +137,7 @@ The above will allow your application to run embedded within Tidewave across mul
 
 ### Content security policy
 
-If you have enabled Content-Security-Policy, Tidewave will automatically enable "unsafe-eval" under `script-src` in order for contextual browser testing to work correctly. It also disables the `frame-ancestors` directive.
+If you have enabled Content-Security-Policy, Tidewave will automatically enable "unsafe-eval" under `script-src` in order for contextual browser testing to work correctly. It also disables the `frame-ancestors` directive. This is done only in the environments that Tidewave is loadead (development by default).
 
 ### Production Environment
 
@@ -66,37 +163,7 @@ The following config is available:
 
   * `team` - set your Tidewave Team configuration, such as `config.tidewave.team = { id: "my-company" }`
 
-## Available tools
-
-- `execute_sql_query` - executes a SQL query within your application
-  database, useful for the agent to verify the result of an action
-
-- `get_docs` - get the documentation for a given module/class/method.
-  It consults the exact versions used by the project, ensuring you always
-  get correct information
-
-- `get_logs` - reads logs written by the server
-
-- `get_models` - lists all modules in the application and their location
-  for quick discovery
-
-- `get_source_location` - get the source location for a given module/class/method,
-  so an agent can directly read the source skipping search
-
-- `project_eval` - evaluates code within the Rails application itself, giving the agent
-  access to your runtime, dependencies, and in-memory data
-
-> [!NOTE]
-> #### Why no tools for routes, associations, etc?
->
-> Tidewave does not include tools for listing your routes, associations, etc. because
-> agents are better off reading their respective source files, which gives agents more
-> context and enable them to perform any necessary edit without additional tools calls.
->
-> Instead, Tidewave aims to fill in missing gaps, such as evaluating code inside your
-> Rails app (without starting new instances) and finding source location, which can be
-> tricky, even with grepping, due to meta-programming and the different places Bundler
-> can install your dependencies.
+  * `toolbar` - controls whether the Tidewave toolbar is injected into HTML pages. Defaults to `true`
 
 ## Acknowledgements
 

data/lib/tidewave/configuration.rb

@@ -2,7 +2,7 @@
 
 class Tidewave
   class Configuration
-    attr_accessor :logger, :allow_remote_access, :preferred_orm, :dev, :client_url, :team, :logger_middleware
+    attr_accessor :logger, :allow_remote_access, :preferred_orm, :dev, :client_url, :team, :logger_middleware, :toolbar
 
     def initialize
       # Rails has a hosts middleware which already checks for this
@@ -13,6 +13,7 @@ class Tidewave
       @client_url = "https://tidewave.ai"
       @team = {}
       @logger_middleware = nil
+      @toolbar = true
     end
   end
 end

data/lib/tidewave/magic_bytes.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class Tidewave
+  module MagicBytes
+    module_function
+
+    def type(bytes)
+      case bytes
+      when /\A\xFF\xD8\xFF/n
+        :jpg
+      when /\A\x89PNG\r\n\x1A\n/n
+        :png
+      when /\A\x1A\x45\xDF\xA3/n
+        bytes.include?("webm") ? :webm : :unknown
+      else
+        :unknown
+      end
+    end
+  end
+end

data/lib/tidewave/railtie.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require "logger"
+require "uri"
 require "tidewave/configuration"
 require "tidewave/exceptions_middleware"
 require "tidewave/quiet_requests_middleware"
@@ -24,6 +25,7 @@ class Tidewave
         framework_type: "rails",
         project_name: app.class.module_parent.name,
         team: tidewave_config.team,
+        toolbar: tidewave_config.toolbar,
         logger: tidewave_config.logger || Rails.logger,
         root: Rails.root,
         log_file: Rails.root.join("log", "#{Rails.env}.log"),
@@ -35,11 +37,21 @@ class Tidewave
         # If the user configured CSP, we need to alter it in dev
         # to allow TC to run browser_eval.
         app.config.content_security_policy.try do |content_security_policy|
-          content_security_policy.directives["script-src"].try do |script_src|
+          directives = content_security_policy.directives
+          script_src = directives["script-src"] || directives["default-src"]&.dup
+          client_origin = URI.parse(tidewave_config.client_url.to_s).origin
+
+          script_src.try do
             script_src << "'unsafe-eval'" unless script_src.include?("'unsafe-eval'")
+            script_src << client_origin unless script_src.include?(client_origin)
+            directives["script-src"] = script_src
+          end
+
+          directives["script-src-elem"].try do |script_src_elem|
+            script_src_elem << client_origin unless script_src_elem.include?(client_origin)
           end
 
-          content_security_policy.directives.delete("frame-ancestors")
+          directives.delete("frame-ancestors")
         end
       end
     end

data/lib/tidewave/tools/execute_sql_query.rb

@@ -48,6 +48,17 @@ class Tidewave::Tools::ExecuteSqlQuery < Tidewave::Tool
   def call(arguments_hash)
     query = arguments_hash.fetch("query")
     arguments = arguments_hash.fetch("arguments", [])
-    @database_adapter.execute_query(query, arguments)
+    result = @database_adapter.execute_query(query, arguments)
+
+    preamble = if result[:row_count] > result[:rows].length
+      <<~TEXT
+        Query returned #{result[:row_count]} rows. Only the first #{result[:rows].length} rows are included in the result. Use your database's pagination syntax, such as LIMIT + OFFSET, to show more rows if applicable.
+
+      TEXT
+    else
+      ""
+    end
+
+    preamble + result.inspect
   end
 end

data/lib/tidewave/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class Tidewave
-  VERSION = "0.5.1"
+  VERSION = "0.8.0"
 end

data/lib/tidewave.rb

@@ -1,11 +1,16 @@
 # frozen_string_literal: true
 
+require "fileutils"
+require "cgi"
 require "ipaddr"
 require "json"
+require "pathname"
 require "rack/request"
+require "uri"
 require "tidewave/version"
 require "tidewave/tool"
 require "tidewave/database_adapter"
+require "tidewave/magic_bytes"
 require "tidewave/railtie" if defined?(Rails::Railtie)
 
 class Tidewave
@@ -25,10 +30,56 @@ Dir[gem_tools_path].sort.each do |file|
 end
 
 class Tidewave
+  class ToolbarBody
+    def initialize(body, toolbar)
+      @body = body
+      @toolbar = toolbar
+      @closed = false
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      pending = +""
+      injected = false
+
+      @body.each do |part|
+        if injected
+          yield part
+        else
+          pending << part
+
+          if closing_head = pending.downcase.index("</head>")
+            toolbar = @toolbar.dup.force_encoding(pending.encoding)
+            output = pending.insert(closing_head, toolbar)
+            pending = nil
+            injected = true
+            yield output
+          end
+        end
+      end
+
+      yield pending unless injected || pending.empty?
+    end
+
+    def close
+      return if @closed
+
+      @closed = true
+      @body.close if @body.respond_to?(:close)
+    end
+  end
+
   TIDEWAVE_ROUTE = "tidewave".freeze
   MCP_ROUTE = "mcp".freeze
   CONFIG_ROUTE = "config".freeze
+  APP_ROUTE = "app".freeze
+  UPLOAD_ROUTE = "upload".freeze
   PROTOCOL_VERSION = "2025-03-26".freeze
+  MAX_UPLOAD_SIZE = 10_000_000
+  ALLOWED_UPLOAD_CONTENT_TYPES = [ "image/png", "image/jpeg", "video/webm" ].freeze
+  ALLOWED_UPLOAD_TYPES = [ "screenshot", "recording" ].freeze
+  TMP_DIR = "tmp".freeze
 
   INVALID_IP = <<~TEXT.freeze
     For security reasons, Tidewave does not accept remote connections by default.
@@ -37,12 +88,19 @@ class Tidewave
   TEXT
 
   INVALID_ORIGIN = "For security reasons, Tidewave does not accept requests with an origin header for this endpoint.".freeze
+  INVALID_UPLOAD = "Bad Request: missing or invalid file parameter".freeze
+  ENCODED_HTML_WARNING = <<~TEXT.freeze
+    Tidewave could not inject the toolbar because the HTML response is encoded.
+
+    If you use Rack::Deflater or another compression middleware, place it before Tidewave in the middleware stack.
+  TEXT
 
   DEFAULT_OPTIONS = {
     allow_remote_access: false,
     client_url: "https://tidewave.ai",
     framework_type: "rack",
-    team: {}
+    team: {},
+    toolbar: true
   }.freeze
 
   def initialize(app, options = {})
@@ -51,6 +109,7 @@ class Tidewave
     raise ArgumentError, "project_name is required" if @options[:project_name].to_s.empty?
 
     @logger = @options[:logger]
+    @root = @options[:root] ? Pathname.new(@options[:root].to_s) : Pathname.pwd
     @tools = build_tool_registry
   end
 
@@ -60,22 +119,27 @@ class Tidewave
 
     if path[0] == TIDEWAVE_ROUTE
       return forbidden(INVALID_IP) unless valid_client_ip?(request)
-      if request.get_header("HTTP_ORIGIN") && !origin_allowed_path?(path)
-        return forbidden(INVALID_ORIGIN)
-      end
+
+      return forbidden(INVALID_ORIGIN) if request.get_header("HTTP_ORIGIN") && !origin_allowed_path?(path)
 
       case [ request.request_method, path ]
       when [ "GET", [ TIDEWAVE_ROUTE ] ]
         home_endpoint(request)
+      when [ "GET", [ TIDEWAVE_ROUTE, APP_ROUTE ] ]
+        app_endpoint(request)
       when [ "GET", [ TIDEWAVE_ROUTE, CONFIG_ROUTE ] ]
         config_endpoint(request)
       when [ "POST", [ TIDEWAVE_ROUTE, MCP_ROUTE ] ]
         mcp_endpoint(request)
+      when [ "POST", [ TIDEWAVE_ROUTE, UPLOAD_ROUTE ] ]
+        upload_endpoint(request)
       else
-        not_found
+        # The MCP Streamable HTTP transport requires the MCP endpoint to answer
+        # non-POST methods with 405 (GET without SSE support, DELETE, etc.)
+        path == [ TIDEWAVE_ROUTE, MCP_ROUTE ] ? method_not_allowed() : not_found()
       end
     else
-      strip_x_frame_options(@app.call(env))
+      inject_toolbar(request, strip_x_frame_options(@app.call(env)))
     end
   end
 
@@ -83,7 +147,7 @@ class Tidewave
 
   def strip_x_frame_options(response)
     status, headers, body = response
-    headers.delete("X-Frame-Options")
+    headers.delete("x-frame-options")
     [ status, headers, body ]
   end
 
@@ -104,28 +168,66 @@ class Tidewave
     [ 200, response_headers("text/html", body), [ body ] ]
   end
 
+  def app_endpoint(_request)
+    client_url = @options[:client_url].to_s.sub(%r{/\z}, "")
+    body = <<~HTML
+      <!DOCTYPE html>
+      <html>
+        <head>
+          <meta charset="UTF-8" />
+          <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+          <script type="module" src="#{client_url}/tc/control.js"></script>
+        </head>
+        <body></body>
+      </html>
+    HTML
+
+    headers = response_headers("text/html", body)
+    headers["content-security-policy"] = "base-uri 'self'; frame-ancestors 'self';"
+    [ 200, headers, [ body ] ]
+  end
+
   def config_endpoint(request)
-    json_response(config_data(request), headers: { "Access-Control-Allow-Origin" => "*" })
+    json_response(config_data(request), headers: { "access-control-allow-origin" => "*" })
   end
 
   def mcp_endpoint(request)
-    body = request.body.read
+    message = JSON.parse(request.body.read)
 
-    message = JSON.parse(body)
-    validation_error = validate_jsonrpc_message(message)
-    return jsonrpc_error_response(nil, -32600, validation_error) if validation_error
-
-    response = handle_mcp_message(message)
-    return json_response({ "status" => "ok" }, status: 202) if response.nil?
-
-    json_response(response)
+    if message.is_a?(Array)
+      handle_mcp_batch(message)
+    else
+      handle_mcp_single(message)
+    end
   rescue JSON::ParserError
-    jsonrpc_error_response(nil, -32700, "Parse error")
+    jsonrpc_error_response(nil, -32700, "Parse error", status: 400)
   rescue StandardError => error
     @logger&.error("Error handling MCP request: #{error.message}")
     jsonrpc_error_response(nil, -32603, "Internal error")
   end
 
+  def handle_mcp_single(message)
+    validation_error = validate_jsonrpc_message(message)
+    return jsonrpc_error_response(nil, -32600, validation_error, status: 400) if validation_error
+
+    response = handle_mcp_message(message)
+    response.nil? ? accepted_response : json_response(response)
+  end
+
+  def handle_mcp_batch(messages)
+    return jsonrpc_error_response(nil, -32600, "Invalid Request", status: 400) if messages.empty?
+
+    responses = messages.map { |message| handle_mcp_batch_message(message) }.compact
+    responses.empty? ? accepted_response : json_response(responses)
+  end
+
+  def handle_mcp_batch_message(message)
+    validation_error = validate_jsonrpc_message(message)
+    return jsonrpc_error_response_body(nil, -32600, validation_error) if validation_error
+
+    handle_mcp_message(message)
+  end
+
   def config_data(request)
     {
       "project_name" => @options[:project_name],
@@ -133,8 +235,90 @@ class Tidewave
       "orm_adapter" => @options[:orm_adapter],
       "team" => @options[:team] || {},
       "tidewave_version" => VERSION,
-      "local_port" => local_port(request)
+      "local_port" => local_port(request),
+      "tmp_dir" => TMP_DIR
+    }
+  end
+
+  def inject_toolbar(request, response)
+    status, headers, body = response
+    return response if @options[:toolbar] == false || !html_response?(headers)
+
+    if encoded_response?(headers)
+      warn_encoded_html
+      return response
+    end
+
+    return response unless body.respond_to?(:each)
+
+    delete_response_header(headers, "content-length")
+    delete_response_header(headers, "etag")
+    [ status, headers, ToolbarBody.new(body, toolbar_html(request)) ]
+  end
+
+  def html_response?(headers)
+    content_types = Array(response_header(headers, "content-type"))
+
+    content_types.any? { |content_type| content_type.to_s.downcase.start_with?("text/html") }
+  end
+
+  def encoded_response?(headers)
+    Array(response_header(headers, "content-encoding")).any? do |content_encoding|
+      content_encoding.to_s.split(",").any? do |encoding|
+        !encoding.strip.empty? && encoding.strip.downcase != "identity"
+      end
+    end
+  end
+
+  def response_header(headers, name)
+    key = headers.keys.find { |header| header.downcase == name }
+    headers[key] if key
+  end
+
+  def delete_response_header(headers, name)
+    headers.delete_if { |header, _value| header.downcase == name }
+  end
+
+  def warn_encoded_html
+    return if @warned_encoded_html
+
+    @warned_encoded_html = true
+    @logger&.warn(ENCODED_HTML_WARNING)
+  end
+
+  def toolbar_html(request)
+    client_url = @options[:client_url].to_s.sub(%r{/\z}, "")
+    payload = {
+      "tidewave" => config_data(request),
+      "root" => @root.to_s,
+      "wsl_distro" => ENV["WSL_DISTRO_NAME"],
+      "framework" => {}
     }
+
+    <<~HTML
+      <meta name="tidewave:config" content="#{CGI.escapeHTML(JSON.generate(payload))}" />
+      <script async type="module" src="#{client_url}/tc/toolbar.js"></script>
+    HTML
+  end
+
+  def upload_endpoint(request)
+    return text_response(400, INVALID_UPLOAD) if upload_too_large?(request)
+
+    params = request.POST
+    type = params["type"]
+    upload = normalize_upload(params["file"])
+
+    unless ALLOWED_UPLOAD_TYPES.include?(type) && allowed_upload?(upload)
+      return text_response(400, INVALID_UPLOAD)
+    end
+
+    FileUtils.mkdir_p(upload_dir(type))
+    destination = upload_path(type, upload[:filename])
+    FileUtils.cp(upload[:path], destination)
+
+    json_response({ "status" => "ok", "path" => relative_path_from_root(destination) })
+  rescue ArgumentError
+    text_response(400, INVALID_UPLOAD)
   end
 
   def json_response(payload, status: 200, headers: {})
@@ -151,19 +335,37 @@ class Tidewave
     text_response(404, "Not Found")
   end
 
+  def method_not_allowed
+    status, headers, body = text_response(405, "Method Not Allowed")
+    [ status, headers.merge("allow" => "POST"), body ]
+  end
+
+  def accepted_response
+    [ 202, { "content-length" => "0" }, [] ]
+  end
+
   def text_response(status, message)
     [ status, response_headers("text/plain; charset=utf-8", message), [ message ] ]
   end
 
+  # Rack 3 requires response header keys to be lowercase. Capitalized keys break
+  # case-sensitive middleware such as Rack::Deflater, which strips "content-length"
+  # before gzipping; a surviving "Content-Length" leaves a stale (uncompressed)
+  # length on the compressed body and hangs spec-compliant HTTP clients.
   def response_headers(content_type, body)
     {
-      "Content-Type" => content_type,
-      "Content-Length" => body.bytesize.to_s
+      "content-type" => content_type,
+      "content-length" => body.bytesize.to_s
     }
   end
 
   def origin_allowed_path?(path)
-    path == [ TIDEWAVE_ROUTE ] || path == [ TIDEWAVE_ROUTE, CONFIG_ROUTE ]
+    [
+      [ TIDEWAVE_ROUTE ],
+      [ TIDEWAVE_ROUTE, APP_ROUTE ],
+      [ TIDEWAVE_ROUTE, CONFIG_ROUTE ],
+      [ TIDEWAVE_ROUTE, UPLOAD_ROUTE ]
+    ].include?(path)
   end
 
   def local_port(request)
@@ -186,13 +388,74 @@ class Tidewave
     false
   end
 
+  def upload_too_large?(request)
+    request.content_length && request.content_length.to_i > MAX_UPLOAD_SIZE
+  end
+
+  def normalize_upload(upload)
+    case upload
+    when Hash
+      tempfile = upload[:tempfile] || upload["tempfile"]
+      {
+        filename: upload[:filename] || upload["filename"],
+        content_type: upload[:type] || upload["type"],
+        path: tempfile&.path
+      }
+    else
+      return {} unless upload.respond_to?(:original_filename) && upload.respond_to?(:content_type)
+
+      {
+        filename: upload.original_filename,
+        content_type: upload.content_type,
+        path: upload.tempfile&.path
+      }
+    end
+  end
+
+  def allowed_upload?(upload)
+    ALLOWED_UPLOAD_CONTENT_TYPES.include?(upload[:content_type].to_s.split(";").first) &&
+      upload[:path] &&
+      Tidewave::MagicBytes.type(File.binread(upload[:path], 128)) != :unknown
+  end
+
+  def upload_dir(type)
+    @root.join(TMP_DIR, "tidewave", folder_for_upload_type(type)).to_s
+  end
+
+  def upload_path(type, filename)
+    filename = filename.to_s
+
+    unless filename.match?(/\A[A-Za-z0-9_.-]+\z/) && !filename.include?("..")
+      raise ArgumentError, "filename must only contain numbers, letters, hyphens, and underscores: #{filename}"
+    end
+
+    unless [ ".png", ".jpg", ".jpeg", ".webm" ].include?(File.extname(filename).downcase)
+      raise ArgumentError, "filename must have a valid extension (.png, .jpg, .jpeg, .webm): #{filename}"
+    end
+
+    File.join(upload_dir(type), filename)
+  end
+
+  def folder_for_upload_type(type)
+    case type
+    when "screenshot"
+      "screenshots"
+    when "recording"
+      "recordings"
+    end
+  end
+
+  def relative_path_from_root(path)
+    Pathname.new(path).relative_path_from(@root).to_s
+  end
+
   def validate_jsonrpc_message(message)
     return "Message must be a JSON object" unless message.is_a?(Hash)
     return "Invalid JSON-RPC version" unless message["jsonrpc"] == "2.0"
 
     has_id = message.key?("id")
     has_method = message.key?("method")
-    has_result = message.key?("result")
+    has_result = message.key?("result") || message.key?("error")
 
     return nil if has_method
     return nil if has_id && has_result
@@ -200,14 +463,17 @@ class Tidewave
     "Invalid JSON-RPC message structure"
   end
 
+  # Returns the JSON-RPC response for a request, or nil for messages that
+  # must not be replied to (notifications and client-sent responses), which
+  # the transport acknowledges with 202 Accepted.
   def handle_mcp_message(message)
+    return nil unless message.key?("method") && message.key?("id")
+
     method = message["method"]
     request_id = message["id"]
     params = message["params"].is_a?(Hash) ? message["params"] : {}
 
     case method
-    when "notifications/initialized", "notifications/cancelled"
-      nil
     when "ping"
       jsonrpc_success_response_body(request_id, {})
     when "initialize"
@@ -216,6 +482,12 @@ class Tidewave
       jsonrpc_success_response_body(request_id, { "tools" => tool_definitions })
     when "tools/call"
       handle_tool_call(request_id, params)
+    when "prompts/list"
+      jsonrpc_success_response_body(request_id, { "prompts" => [] })
+    when "resources/list"
+      jsonrpc_success_response_body(request_id, { "resources" => [] })
+    when "resources/templates/list"
+      jsonrpc_success_response_body(request_id, { "resourceTemplates" => [] })
     else
       {
         "jsonrpc" => "2.0",
@@ -233,14 +505,9 @@ class Tidewave
     client_version = params["protocolVersion"]
     return jsonrpc_error_response_body(request_id, -32602, "Protocol version is required") if client_version.nil? || client_version.empty?
 
-    if client_version < PROTOCOL_VERSION
-      return jsonrpc_error_response_body(
-        request_id,
-        -32602,
-        "Unsupported protocol version. Server supports #{PROTOCOL_VERSION} or later"
-      )
-    end
-
+    # Version negotiation: when the client requests a version we don't
+    # support, we respond with the version we do support and the client
+    # decides whether to continue or disconnect.
     jsonrpc_success_response_body(request_id, {
       "protocolVersion" => PROTOCOL_VERSION,
       "capabilities" => { "tools" => { "listChanged" => false } },
@@ -276,8 +543,8 @@ class Tidewave
     }
   end
 
-  def jsonrpc_error_response(request_id, code, message)
-    json_response(jsonrpc_error_response_body(request_id, code, message))
+  def jsonrpc_error_response(request_id, code, message, status: 200)
+    json_response(jsonrpc_error_response_body(request_id, code, message), status: status)
   end
 
   def jsonrpc_error_response_body(request_id, code, message)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: tidewave
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Yorick Jacquin
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-14 00:00:00.000000000 Z
+date: 2026-07-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack
@@ -41,6 +41,7 @@ files:
 - lib/tidewave/database_adapters/active_record.rb
 - lib/tidewave/database_adapters/sequel.rb
 - lib/tidewave/exceptions_middleware.rb
+- lib/tidewave/magic_bytes.rb
 - lib/tidewave/quiet_requests_middleware.rb
 - lib/tidewave/railtie.rb
 - lib/tidewave/tool.rb