webmcp 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f211ae3ee7700b7d3da74922a27328c3c412955110b8c38c4e560a4363ba565f
-  data.tar.gz: 186b9f6456258def8ef8c239cec92be83f062274a29eb03387055ca3e17d4b34
+  metadata.gz: c32274fd7dc9ffe43c9204439ab0d2b4bb40bfb9720a6a90aa3afdc4ee2b973c
+  data.tar.gz: 4801f44a17de9f4ac612eb6fe57dc8b95814f851dc381b3547ba0e63c505584c
 SHA512:
-  metadata.gz: 9802bbe173071fe7ac5dbc9b5c30edd66633ebb11082fa168fa494abc5b84a22c34f631f619d114cb5461a6884922cd8a8c453b586db15dc226eaf60c8f6c708
-  data.tar.gz: e452595f3829a74ad941d83a047b56e3968a7ef7de8b912ec905318d1b89bafa497bc2bb35a9fd34c82c28524fe9d0bb78be7702dcda1837405d7b941393ecb8
+  metadata.gz: 153a2e664db64df9b278b7607d50fd4dafdf854977e2ca4f849545a2b68b13e66c8078c0b45faf43c46c8d4ce78c867c1723b37f521d4adaf3db65a6ed2d584a
+  data.tar.gz: a385501050755b4c71afe2e264afeff7a8f71c74e6d603e88ea920a40f88731f71dbb4ef729e6e840a3cdcf68b3f63378ed60db49bb5c63e7620b4dbb218b2e5

data/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.1.1 — 2026-10-06
+
+- Documentation for people and AI agents: `AGENTS.md`, `llms.txt`, a README troubleshooting table with exact error messages, and changelog/issue/documentation links in the gemspec.
+
 ## 0.1.0
 
 - Autostart opted-in manifests from the external runtime under strict CSP, expose

data/README.md

@@ -1,6 +1,45 @@
 # webmcp
 
-0.1.0 · Spec baseline: **Draft CG Report 2026-10-02** · Browser test target: **Chrome 154.0.8037.98**. All 9 real-browser checks pass on Rails 8.1 and 8.0, plus a production asset/CSP smoke test (details below).
+[![Gem Version](https://img.shields.io/gem/v/webmcp)](https://rubygems.org/gems/webmcp) [![CI](https://github.com/seunghan91/webmcp/actions/workflows/ci.yml/badge.svg)](https://github.com/seunghan91/webmcp/actions/workflows/ci.yml) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE.txt)
+
+Server-side WebMCP toolkit for Ruby and Rails — the reference implementation of the family.
+
+[WebMCP](https://github.com/webmachinelearning/webmcp) is a W3C Community Group
+proposal that lets a web page register tools an in-browser AI agent can call
+through `document.modelContext`. This gem is the server side of that: you define
+tools where your app already knows its routes, sessions and permissions, and a
+small browser runtime registers them on the pages you choose. When an agent calls
+a tool, the runtime calls your existing same-origin endpoint with the user's
+session and CSRF token, so authentication and authorization stay in your app.
+
+- **Tool definitions** — `WebMCP::Tool.define`, validated against the spec's naming, annotation and schema rules at boot.
+- **Projection from MCP SDK tools** — `WebMCP::Tool.from_mcp` reuses a tool's identity from the official [`mcp`](https://rubygems.org/gems/mcp) gem and makes every browser-side difference explicit, with a pinned source fingerprint that fails tests when the MCP tool drifts.
+- **Rails helpers** — `webmcp_manifest_tag` (per-page opt-in), `webmcp_runtime_tag` (CSP nonce aware, autostart), `form_with ..., webmcp: {...}` for declarative forms (keeps custom FormBuilders).
+- **Origin Trial** — `WebMCP::OriginTrial` Rack middleware and `webmcp_origin_trial_meta_tag`.
+- **Shared browser runtime** — zero dependencies; same-origin only, `redirect: 'error'`, CSRF read per call, declared parameters only, read/write outcome envelopes, no retries.
+
+```ruby
+# Gemfile
+gem "webmcp", "~> 0.1"
+```
+
+**Status:** 0.x, tracking the WebMCP Draft CG Report of 2026-10-02. WebMCP runs
+behind a Chrome origin trial (Chrome 149–156, extension requested to 162) or the
+`chrome://flags/#enable-webmcp-testing` flag. The shared runtime is tested in real
+Chrome 154 by the [Ruby reference suite](https://github.com/seunghan91/webmcp/blob/main/test/integration/RESULTS.md)
+(CSRF-protected writes, blocked redirects, HTTP errors, Turbo navigation, strict CSP).
+
+| Language | Package | Registry |
+|---|---|---|
+| Ruby / Rails (reference) | [`webmcp`](https://github.com/seunghan91/webmcp) | [RubyGems](https://rubygems.org/gems/webmcp) |
+| Go (`net/http`) | [`webmcp-go`](https://github.com/seunghan91/webmcp-go) | [pkg.go.dev](https://pkg.go.dev/github.com/seunghan91/webmcp-go) |
+| Python / Django | [`webmcp-django`](https://github.com/seunghan91/webmcp-django) | [PyPI](https://pypi.org/project/webmcp-django/) |
+| Rust | [`webmcp`](https://github.com/seunghan91/webmcp-rust) | [crates.io](https://crates.io/crates/webmcp) |
+
+All four emit the same manifest v1 (checked against shared conformance fixtures,
+fingerprints included) and ship the byte-identical browser runtime.
+
+Coding agents: start with [AGENTS.md](AGENTS.md). LLM summary: [llms.txt](llms.txt).
 
 ## Intent: share identity, project the rest explicitly
 
@@ -220,6 +259,26 @@ This copies `runtime/webmcp-runtime.js` into
 The Railtie adds asset paths and, for Sprockets, a precompile entry. Other asset
 pipelines can copy the canonical module directly. Do not edit the generated copy.
 
+## Troubleshooting
+
+| Symptom (exact text) | Cause | Fix |
+|---|---|---|
+| `document.modelContext` is `undefined` | WebMCP is unavailable or the page is not a secure context | Chrome 149+ with the origin trial token (header or `<meta http-equiv="origin-trial">`) or `chrome://flags/#enable-webmcp-testing`; serve over HTTPS or localhost |
+| `NotAllowedError` from `registerTool` | The document may not use the `tools` Permissions Policy feature (default allowlist `self`) | For cross-origin frames delegate with `allow="tools"` and make sure ancestor `Permissions-Policy` headers permit it |
+| `UnknownError: Failed to parse input arguments` from `executeTool` | Chrome 154 and earlier accept only a JSON **string** input; object input ships in Chrome 155 | Agent side: pass `JSON.stringify(input)` on Chrome ≤ 154. The runtime's `execute` receives an object either way |
+| `SecurityError` from `registerTool` on an older trial build | The response sent `Origin-Agent-Cluster: ?0` (requirement removed from the spec on 2026-09-30, still enforced by older builds) | Stop sending `?0`; enable the OAC opt-out warning to find it |
+| Console: `WebMCP: could not register tool "<name>"` with `InvalidStateError` | Another script in the same document already registered that name | Use unique names; names are unique per document, not per site |
+| Console: `WebMCP: unsupported manifest version; no tools registered.` | Runtime and manifest come from different package versions | Upgrade so both use manifest v1 and the same runtime |
+| Tool result `error.code: "csrf_token_missing"` | A non-GET tool (including a read-only POST) has CSRF transport configured but no readable token on the page | Render the configured token (Rails `csrf_meta_tags`, Django `{% webmcp_csrf_meta %}`, Go/Rust: your own escaped `<meta name="csrf-token">`) or configure a readable cookie source. Without CSRF transport the runtime skips this check |
+| `error.code: "invalid_input"` | The agent sent an undeclared parameter, a missing required one, or the wrong scalar type | Fix the schema or descriptions; the runtime forwards declared parameters only |
+| `error.code: "unknown_outcome"` | A write request failed after dispatch: network error, abort, or a **redirect** (redirects are never followed) | Make the endpoint answer without redirecting (e.g. 401 JSON instead of redirecting to sign-in); never retry automatically |
+| `error.code: "network_error"` on a read | Network failure or redirect rejection after dispatch (an aborted read returns `aborted`) | Check connectivity and answer JSON without redirects; reads may be retried |
+| `error.code: "response_too_large"` | Read response exceeded `maxResponseChars` | Narrow the query or raise the limit; responses are never truncated |
+| `dataOmitted: "invalid_response"` on a write | The endpoint returned 2xx with a non-JSON body | Return JSON from write endpoints |
+| Tools from the previous page remain, or none appear, after client-side navigation | Turbo is handled automatically; other SPAs (Inertia, React routers) are not | After the SPA replaces or removes `#webmcp-manifest`, `await WebMCPRuntime.handle.refresh()`. `webmcp:mounted` only delivers the initial handle. If the first page has no manifest, mount the runtime from your app entry (`mount()`) and keep that handle |
+| A string-returning tool yields `hi` instead of `"hi"` | Chrome 154 does not JSON-quote string results (spec says it should) | The shared runtime always returns an envelope object, so this only affects hand-written tools |
+| Definition error at boot such as `GET endpoints require read_only: true` | The definition violates a rule above | Fix the definition; errors are raised at boot on purpose |
+
 ## Security model
 
 The server remains the security boundary. Tools call existing same-origin

data/lib/webmcp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module WebMCP
-  VERSION = "0.1.0"
+  VERSION = "0.1.1"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: webmcp
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - seunghan Kim
@@ -135,6 +135,9 @@ homepage: https://github.com/seunghan91/webmcp
 licenses:
 - MIT
 metadata:
+  changelog_uri: https://github.com/seunghan91/webmcp/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/seunghan91/webmcp/issues
+  documentation_uri: https://github.com/seunghan91/webmcp#readme
   source_code_uri: https://github.com/seunghan91/webmcp
   rubygems_mfa_required: 'true'
 rdoc_options: []