webmcp 0.0.1 → 0.1.1

data/lib/webmcp/view_helpers.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module WebMCP
+  module ViewHelpers
+    DEFAULT_TRANSPORT = Value.deep_freeze({ "csrf" => { "source" => "meta", "name" => "csrf-token", "header" => "X-CSRF-Token" } })
+
+    def webmcp_manifest_tag(*tool_names, transport: DEFAULT_TRANSPORT, nonce: webmcp_nonce, autostart: true)
+      tools = tool_names.map { |name| WebMCP.registry.fetch(name) }
+      Manifest.to_script_tag(Manifest.build(tools, transport: transport), nonce: nonce, autostart: autostart)
+    end
+
+    def webmcp_runtime_tag
+      src = asset_path("webmcp/runtime.js")
+      nonce = webmcp_nonce
+      nonce_attr = nonce.nil? ? "" : %( nonce="#{Value.escape_html(nonce)}")
+      Value.html_safe(%(<script type="module" src="#{Value.escape_html(src)}"#{nonce_attr}></script>))
+    end
+
+    def webmcp_origin_trial_meta_tag
+      OriginTrial.meta_tag(WebMCP.config.origin_trial_token)
+    end
+
+    private
+
+    def webmcp_nonce
+      content_security_policy_nonce if respond_to?(:content_security_policy_nonce)
+    end
+  end
+end

data/lib/webmcp.rb

@@ -1,16 +1,58 @@
 # frozen_string_literal: true
 
+require "json"
+require "digest"
+require "cgi"
+require "logger"
 require_relative "webmcp/version"
 
-# WebMCP — Ruby/Rails toolkit for the W3C Web Model Context Protocol.
-#
-# Status: early development. The WebMCP spec is in Chrome origin trial
-# (Chrome 149-156) and its surface is still moving; this gem tracks the
-# spec and will ship its first usable release once the API stabilizes.
-#
-# Planned surface:
-#   - Tool definitions in Ruby, shared between server-side MCP and WebMCP
-#   - Declarative form attribute helpers (toolname/tooldescription/...)
-#   - Rack middleware for serving the Origin-Trial token header
 module WebMCP
+  class DefinitionError < ArgumentError; end
+
+  class Configuration
+    attr_accessor :logger, :origin_trial_token
+
+    def initialize
+      @logger = Logger.new($stderr)
+      @origin_trial_token = ENV["WEBMCP_ORIGIN_TRIAL_TOKEN"]
+    end
+  end
+
+  class << self
+    def config
+      @config ||= Configuration.new
+    end
+
+    def configure
+      yield config
+    end
+
+    def registry
+      @registry ||= Registry.new
+    end
+
+    def register(tool)
+      registry.register(tool)
+    end
+
+    def tools
+      registry.tools
+    end
+
+    def freeze!
+      registry.freeze!
+    end
+  end
 end
+
+require_relative "webmcp/value"
+require_relative "webmcp/schema"
+require_relative "webmcp/tool"
+require_relative "webmcp/projection"
+require_relative "webmcp/testing"
+require_relative "webmcp/registry"
+require_relative "webmcp/manifest"
+require_relative "webmcp/origin_trial"
+require_relative "webmcp/form_helper"
+require_relative "webmcp/view_helpers"
+require_relative "webmcp/railtie" if defined?(Rails::Railtie)

data/runtime/webmcp-runtime.js

@@ -0,0 +1,344 @@
+/**
+ * @webmcp/runtime v0.1.0 — manifest v1
+ * Registers server-defined tools and invokes their same-origin HTTP endpoints.
+ * The application keeps responsibility for authentication, CSRF protection, and
+ * authorization; this runtime uses the existing browser session and endpoints.
+ */
+
+const forbiddenKeys = new Set(['__proto__', 'constructor', 'prototype']);
+const messages = {
+  invalid_input: 'Provide only declared parameters with the required types.',
+  csrf_token_missing: 'Refresh the page to obtain a CSRF token, then try again.',
+  network_error: 'The request failed. Check the connection and try again.',
+  aborted: 'The request was cancelled.',
+  invalid_response: 'The endpoint returned invalid JSON. Check the endpoint response.',
+  response_too_large: 'Narrow the request and try again.',
+  unknown_outcome: 'The result is unknown. Do not retry automatically; ask the user to check.',
+};
+
+function failure(code, status) {
+  return {
+    ok: false,
+    ...(status === undefined ? {} : { status }),
+    error: {
+      code,
+      message: code === 'http_error'
+        ? `The endpoint returned HTTP ${status}. Check the request and your access.`
+        : messages[code],
+    },
+  };
+}
+
+function matchesScalar(type, value) {
+  switch (type) {
+    case 'string': return typeof value === 'string';
+    case 'boolean': return typeof value === 'boolean';
+    case 'number': return typeof value === 'number' && Number.isFinite(value);
+    case 'integer': return Number.isInteger(value);
+    default: return false;
+  }
+}
+
+/** Returns { ok: true } or an invalid_input outcome. No schema constraint checks. */
+export function validateInput(tool, input) {
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    return failure('invalid_input');
+  }
+  const schema = tool.inputSchema ?? {};
+  const properties = schema.properties ?? {};
+  for (const key of schema.required ?? []) {
+    if (!Object.hasOwn(input, key)) return failure('invalid_input');
+  }
+  for (const key of Object.keys(input)) {
+    if (forbiddenKeys.has(key) || !Object.hasOwn(properties, key)) {
+      return failure('invalid_input');
+    }
+    const property = properties[key];
+    const value = input[key];
+    if (property.type === 'array') {
+      if (!Array.isArray(value)) return failure('invalid_input');
+      // Iteration also rejects sparse slots, which would serialize as null.
+      for (const item of value) {
+        if (!matchesScalar(property.items?.type, item)) return failure('invalid_input');
+      }
+    } else if (!matchesScalar(property.type, value)) {
+      return failure('invalid_input');
+    }
+  }
+  return { ok: true };
+}
+
+function* parameters(tool, input) {
+  const properties = tool.inputSchema?.properties ?? {};
+  const mapping = tool.endpoint.paramMap ?? {};
+  for (const key of Object.keys(input)) {
+    if (!forbiddenKeys.has(key) && Object.hasOwn(properties, key)) {
+      yield [Object.hasOwn(mapping, key) ? mapping[key] : key, input[key]];
+    }
+  }
+}
+
+/** Encodes declared own keys; null/undefined scalar values are omitted. */
+export function encodeQuery(tool, input) {
+  const query = new URLSearchParams();
+  for (const [key, value] of parameters(tool, input)) {
+    if (value === null || value === undefined) continue;
+    if (Array.isArray(value)) {
+      const name = tool.endpoint.arrayFormat === 'brackets' ? `${key}[]` : key;
+      for (const item of value) query.append(name, String(item));
+    } else {
+      query.append(key, String(value));
+    }
+  }
+  return query.toString();
+}
+
+function csrfToken(csrf, doc) {
+  if (csrf.source === 'meta') {
+    const name = csrf.name.replace(/["\\]/g, '\\$&');
+    return doc?.querySelector(`meta[name="${name}"]`)?.content;
+  }
+  if (csrf.source === 'cookie') {
+    for (const part of (doc?.cookie ?? '').split(';')) {
+      const cookie = part.trim();
+      const separator = cookie.indexOf('=');
+      if (separator < 0 || cookie.slice(0, separator) !== csrf.name) continue;
+      const value = cookie.slice(separator + 1);
+      try {
+        return decodeURIComponent(value);
+      } catch {
+        return value;
+      }
+    }
+  }
+  return undefined;
+}
+
+/** Returns { url, options } or a pre-dispatch failure. The caller supplies signal. */
+export function buildRequest(tool, input, transport, doc) {
+  const validation = validateInput(tool, input);
+  if (!validation.ok) return validation;
+  const endpoint = tool.endpoint;
+  const path = endpoint?.path;
+  if (typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//') ||
+      /[\\\u0000-\u001f\u007f]/.test(path)) {
+    return failure('invalid_input');
+  }
+  let url;
+  try {
+    const origin = doc?.location?.origin ?? globalThis.location?.origin;
+    url = new URL(path, origin);
+    if (url.origin !== origin) return failure('invalid_input');
+  } catch {
+    return failure('invalid_input');
+  }
+  const method = endpoint.method.toUpperCase();
+  const headers = { Accept: 'application/json' };
+  const options = { method, mode: 'same-origin', credentials: 'same-origin', redirect: 'error', headers };
+  const csrf = transport?.csrf;
+  if (csrf) {
+    const token = csrfToken(csrf, doc);
+    if (!token && method !== 'GET') return failure('csrf_token_missing');
+    if (token) headers[csrf.header] = token;
+  }
+  if (method === 'GET') {
+    for (const [key, value] of new URLSearchParams(encodeQuery(tool, input))) {
+      url.searchParams.append(key, value);
+    }
+  } else {
+    headers['Content-Type'] = 'application/json';
+    options.body = JSON.stringify(Object.fromEntries(parameters(tool, input)));
+  }
+  return { url: url.href, options };
+}
+
+/**
+ * Pure outcome conversion. phase is 'before-dispatch', 'after-dispatch' (errors),
+ * or 'response' (default). A parsed response is { status, data, invalidResponse? }.
+ */
+export function toOutcome(tool, value, phase = 'response') {
+  const readOnly = tool.annotations?.readOnlyHint === true;
+  if (phase === 'before-dispatch') {
+    const code = value?.name === 'AbortError' ? 'aborted'
+      : value?.code === 'csrf_token_missing' ? 'csrf_token_missing' : 'invalid_input';
+    return failure(code);
+  }
+  if (phase === 'after-dispatch') {
+    return failure(readOnly
+      ? value?.name === 'AbortError' ? 'aborted' : 'network_error'
+      : 'unknown_outcome');
+  }
+  const { status, data, invalidResponse } = value;
+  if (status < 200 || status >= 300) return failure('http_error', status);
+  if (status === 204) return { ok: true, status, data: null };
+  let omitted = invalidResponse ? 'invalid_response' : undefined;
+  if (!omitted && tool.maxResponseChars !== undefined) {
+    try {
+      if (JSON.stringify(data).length > tool.maxResponseChars) omitted = 'response_too_large';
+    } catch {
+      omitted = 'invalid_response';
+    }
+  }
+  if (!omitted) return { ok: true, status, data };
+  if (readOnly) return failure(omitted, status);
+  return {
+    ok: true, status, data: null, dataOmitted: omitted,
+    message: 'The operation succeeded. Do not repeat it.',
+  };
+}
+
+function executor(tool, transport, doc, fetcher) {
+  return async (inputObject, options = {}) => {
+    let phase = 'before-dispatch';
+    try {
+      const request = buildRequest(tool, inputObject, transport, doc);
+      if (request.ok === false) return request;
+      const signal = options?.signal;
+      if (signal?.aborted) return toOutcome(tool, { name: 'AbortError' }, phase);
+      phase = 'after-dispatch';
+      const response = await fetcher(request.url, { ...request.options, signal });
+      const status = response.status;
+      if (status === 204 || status < 200 || status >= 300) {
+        return toOutcome(tool, { status });
+      }
+      let data;
+      try {
+        data = await response.json();
+      } catch (error) {
+        // A body read can itself fail after dispatch; only a JSON parse failure
+        // proves that the received response was non-JSON.
+        if (error?.name !== 'SyntaxError') throw error;
+        return toOutcome(tool, { status, invalidResponse: true });
+      }
+      return toOutcome(tool, { status, data });
+    } catch (error) {
+      return toOutcome(tool, error, phase);
+    }
+  };
+}
+
+export function mount({
+  selector = '#webmcp-manifest', modelContext, fetch: fetcher = globalThis.fetch,
+  document: doc = globalThis.document,
+} = {}) {
+  const context = modelContext === undefined
+    ? doc?.modelContext ?? globalThis.navigator?.modelContext : modelContext;
+  if (!context) return { refresh: async () => {}, dispose() {} };
+
+  const registrations = new Map();
+  let queue = Promise.resolve();
+  let generation = 0;
+  let disposed = false;
+  let warnedVersion = false;
+  let finishDisposal;
+  const disposal = new Promise(resolve => { finishDisposal = resolve; });
+
+  function remove(name, entry) {
+    entry.controller.abort();
+    if (registrations.get(name) === entry) registrations.delete(name);
+  }
+
+  function readManifest() {
+    try {
+      const element = doc?.querySelector(selector);
+      if (!element) return { tools: [] };
+      const manifest = JSON.parse(element.textContent);
+      if (manifest?.webmcpManifestVersion !== 1) {
+        if (!warnedVersion) {
+          warnedVersion = true;
+          console.warn('WebMCP: unsupported manifest version; no tools registered.');
+        }
+        return { tools: [] };
+      }
+      if (!Array.isArray(manifest.tools)) throw new TypeError('Manifest tools must be an array.');
+      return manifest;
+    } catch (error) {
+      console.warn('WebMCP: could not read the manifest.', error);
+      return { tools: [] };
+    }
+  }
+
+  async function reconcile(currentGeneration) {
+    if (disposed || currentGeneration !== generation) return;
+    const manifest = readManifest();
+    const desired = new Map(manifest.tools.map(tool => [tool.name, tool]));
+    for (const [name, entry] of registrations) {
+      if (!desired.has(name) || desired.get(name).fingerprint !== entry.fingerprint) {
+        remove(name, entry);
+      }
+    }
+    for (const [name, tool] of desired) {
+      if (disposed || currentGeneration !== generation) return;
+      if (registrations.has(name)) continue;
+      const entry = { fingerprint: tool.fingerprint, controller: new AbortController() };
+      registrations.set(name, entry);
+      const registration = (async () => {
+        try {
+          const definition = {
+            name: tool.name, description: tool.description, inputSchema: tool.inputSchema,
+            execute: executor(tool, manifest.transport, doc, fetcher),
+          };
+          if (tool.title !== undefined) definition.title = tool.title;
+          if (tool.annotations !== undefined) definition.annotations = tool.annotations;
+          await context.registerTool(definition, { signal: entry.controller.signal });
+          if (disposed || currentGeneration !== generation) remove(name, entry);
+        } catch (error) {
+          remove(name, entry);
+          console.warn(`WebMCP: could not register tool "${name}".`, error);
+        }
+      })();
+      // Disposal releases callers even if an implementation never settles its
+      // registerTool promise. The handler above still cleans up a late result.
+      await Promise.race([registration, disposal]);
+    }
+  }
+
+  function refresh() {
+    if (disposed) return Promise.resolve();
+    const currentGeneration = ++generation;
+    queue = queue.then(() => reconcile(currentGeneration)).catch(error => {
+      console.warn('WebMCP: could not refresh tools.', error);
+    });
+    return queue;
+  }
+
+  function dispose() {
+    if (disposed) return;
+    disposed = true;
+    ++generation;
+    doc?.removeEventListener('turbo:load', onTurboLoad);
+    for (const [name, entry] of registrations) remove(name, entry);
+    queue = Promise.resolve();
+    finishDisposal();
+  }
+
+  function onTurboLoad() { void refresh(); }
+  doc?.addEventListener('turbo:load', onTurboLoad);
+  void refresh();
+  return { refresh, dispose };
+}
+
+// Opt in through markup so strict CSP applications need no inline bootstrap.
+if (globalThis.document) {
+  const doc = globalThis.document;
+  const started = Symbol.for('webmcp.runtime.autostart');
+  const autostart = () => {
+    if (globalThis[started]) return;
+    // Turbo keeps this module loaded across visits, so a page without an
+    // opted-in manifest (a sign-in page, say) waits for a later visit that has one.
+    if (!doc.querySelector('#webmcp-manifest')?.hasAttribute('data-webmcp-autostart')) {
+      doc.addEventListener('turbo:load', autostart);
+      return;
+    }
+    doc.removeEventListener('turbo:load', autostart);
+    globalThis[started] = true;
+    const handle = mount();
+    globalThis.WebMCPRuntime = { handle, mount };
+    doc.dispatchEvent(new CustomEvent('webmcp:mounted', { detail: handle }));
+  };
+  if (doc.readyState === 'loading') {
+    doc.addEventListener('DOMContentLoaded', autostart, { once: true });
+  } else {
+    autostart();
+  }
+}

metadata

@@ -1,32 +1,143 @@
 --- !ruby/object:Gem::Specification
 name: webmcp
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.1
 platform: ruby
 authors:
 - seunghan Kim
 bindir: bin
 cert_chain: []
-date: 2026-08-09 00:00:00.000000000 Z
-dependencies: []
-description: 'Define agent-callable tools once in Ruby and expose them to browsers
-  via the WebMCP standard (document.modelContext): declarative form attributes, imperative
-  registration payloads, and Origin-Trial header middleware. Currently in early development
-  while the W3C spec stabilizes (Chrome origin trial).'
+date: 2026-10-06 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+- !ruby/object:Gem::Dependency
+  name: actionview
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '9'
+description: A dependency-free Ruby core for immutable WebMCP definitions and safe
+  manifests, with optional MCP SDK projection and Rails 7.1+ integration.
 email:
 - theqwe2000@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE.txt
 - README.md
+- Rakefile
+- app/assets/javascripts/webmcp/runtime.js
+- conformance/README.md
+- conformance/RUNTIME.sha256
+- conformance/fixtures/escape-parity.json
+- conformance/fixtures/projection-result.json
+- conformance/fixtures/read-array.json
+- conformance/fixtures/write-post.json
+- lib/tasks/webmcp.rake
 - lib/webmcp.rb
+- lib/webmcp/form_helper.rb
+- lib/webmcp/manifest.rb
+- lib/webmcp/origin_trial.rb
+- lib/webmcp/projection.rb
+- lib/webmcp/railtie.rb
+- lib/webmcp/registry.rb
+- lib/webmcp/schema.rb
+- lib/webmcp/testing.rb
+- lib/webmcp/tool.rb
+- lib/webmcp/value.rb
 - lib/webmcp/version.rb
+- lib/webmcp/view_helpers.rb
+- runtime/webmcp-runtime.js
 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: []
@@ -45,5 +156,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.2
 specification_version: 4
-summary: Ruby/Rails toolkit for WebMCP (W3C Web Model Context Protocol) — early development.
+summary: Server-side WebMCP tools, explicit MCP projections, Rails forms and Origin-Trial
+  helpers
 test_files: []