tidewave 0.5.0 → 0.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d75b5659655095637ad8830051ef50f06e018339520d093c51854cec9c320fd7
-  data.tar.gz: 9325b6a4ea7ac4e1444a677bd1dc785bc6f8046e8492a5d1b70267c9424ca9a3
+  metadata.gz: c64d42ec2ee75f35b02997081d24e69fe547d8b9a20a230daeb1d1995a30cd0a
+  data.tar.gz: 74e1cc3e89cdea2b1d4701990ca3fbe3b4b3a5c828735bef5251c91a1d8c074a
 SHA512:
-  metadata.gz: 9fe7d353f945a3a3735dfdd56486188df12034736c2ac78561dca478b05b6f15fba9608dd8e8209f3d9a66659f4908c2814ec65ccdf13030f56b1387a9190fde
-  data.tar.gz: 6782f79c55813d99d5cffeb973812116aaf581570119de0ebcd739d2f65d1aa0fbc3ed3bc1cc1d478ec0b30ac18fbc2ab9db6037df18ec433b8ef50cce7eb947
+  metadata.gz: a2cf21787f51875cbec78b12b5800c7f03b8d516360fd960110f8717dc762f47e58f4f7a4b243c3f0120e254075f17495e86d6c3538d22dd8abe6ac046d3fc6d
+  data.tar.gz: 789f139be709d1bc9a0d55b8cb661b9212b3ce2b4fa546d2c644b3a676a6a2843687407e2efdc87c8a0785290c2aab1806693b07698cd71f9fb9e7f130714786

data/README.md

@@ -1,32 +1,119 @@
-# 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).
+
+To use it as a standalone MCP server, follow the installation 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
 
-## Development
+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`.
 
-Run the Minitest suite with:
+We also have specific instructions for:
 
-```shell
-bundle exec ruby -Itest test/all_test.rb
-```
+- [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
 
@@ -74,29 +161,17 @@ 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
+## Acknowledgements
 
-- `get_source_location` - get the source location for a given module/class/method,
-  so an agent can directly read the source skipping search
+A thank you to Yorick Jacquin for the initial version of this project.
 
-- `project_eval` - evaluates code within the Rails application itself, giving the agent
-  access to your runtime, dependencies, and in-memory data
+## Development
 
-## Acknowledgements
+Run the Minitest suite with:
 
-A thank you to Yorick Jacquin for the initial version of this project.
+```shell
+bundle exec ruby -Itest test/all_test.rb
+```
 
 ## License
 

data/lib/tidewave/version.rb

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

data/lib/tidewave.rb

@@ -60,7 +60,9 @@ class Tidewave
 
     if path[0] == TIDEWAVE_ROUTE
       return forbidden(INVALID_IP) unless valid_client_ip?(request)
-      return forbidden(INVALID_ORIGIN) if request.get_header("HTTP_ORIGIN") && path != [ TIDEWAVE_ROUTE ]
+      if request.get_header("HTTP_ORIGIN") && !origin_allowed_path?(path)
+        return forbidden(INVALID_ORIGIN)
+      end
 
       case [ request.request_method, path ]
       when [ "GET", [ TIDEWAVE_ROUTE ] ]
@@ -70,7 +72,9 @@ class Tidewave
       when [ "POST", [ TIDEWAVE_ROUTE, MCP_ROUTE ] ]
         mcp_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))
@@ -81,7 +85,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
 
@@ -102,41 +106,61 @@ class Tidewave
     [ 200, response_headers("text/html", body), [ body ] ]
   end
 
-  def config_endpoint(_request)
-    json_response(config_data)
+  def config_endpoint(request)
+    json_response(config_data(request), headers: { "access-control-allow-origin" => "*" })
   end
 
   def mcp_endpoint(request)
-    body = 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?
+    message = JSON.parse(request.body.read)
 
-    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 config_data
+  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],
       "framework_type" => @options[:framework_type],
       "orm_adapter" => @options[:orm_adapter],
       "team" => @options[:team] || {},
-      "tidewave_version" => VERSION
+      "tidewave_version" => VERSION,
+      "local_port" => local_port(request)
     }
   end
 
-  def json_response(payload, status: 200)
+  def json_response(payload, status: 200, headers: {})
     body = JSON.generate(payload)
-    [ status, response_headers("application/json", body), [ body ] ]
+    [ status, response_headers("application/json", body).merge(headers), [ body ] ]
   end
 
   def forbidden(message)
@@ -148,17 +172,42 @@ 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 ]
+  end
+
+  def local_port(request)
+    sock = request.env["puma.socket"]
+    return unless sock
+
+    addr = sock.respond_to?(:local_address) ? sock.local_address : sock.to_io.local_address
+    addr.ip? ? addr.ip_port : nil
+  end
+
   def valid_client_ip?(request)
     return true if @options[:allow_remote_access]
 
@@ -177,7 +226,7 @@ class Tidewave
 
     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
@@ -185,14 +234,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"
@@ -201,6 +253,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",
@@ -218,14 +276,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 } },
@@ -261,8 +314,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.0
+  version: 0.5.2
 platform: ruby
 authors:
 - Yorick Jacquin
@@ -9,7 +9,7 @@ authors:
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-05-29 00:00:00.000000000 Z
+date: 2026-07-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rack