@corsenai/corsen-context 1.2.0 → 1.3.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Corsen AI
-
-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.
+MIT License
+
+Copyright (c) 2026 Corsen AI
+
+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.

package/README.md

@@ -1,27 +1,27 @@
-# @corsenai/corsen-context
-
-The core engine of **[Corsen Context](https://github.com/CorsenAI/corsen-context)** — the Universal AI Context Layer that makes any website AI-native with an MCP server + enhanced `llms.txt`.
-
-```bash
-npm install @corsenai/corsen-context
-```
-
-```typescript
-import { CorsenContext, createInMemoryProvider } from '@corsenai/corsen-context';
-
-const cc = new CorsenContext(
-  { siteUrl: 'https://example.com' },
-  createInMemoryProvider([
-    { url: 'https://example.com/', title: 'Home', description: 'Welcome', markdown: '# Home', metadata: {}, type: 'page' },
-  ]),
-);
-
-const server = cc.createMCPServer();
-const result = await server.handleRequest(requestBody, clientIp);
-```
-
-This package provides the framework-agnostic core: the MCP JSON-RPC 2.0 server, `llms.txt` generators, HTML→Markdown converter, SSRF-safe fetching, rate limiting, caching, and the content-access policy.
-
-- **Full docs:** https://github.com/CorsenAI/corsen-context#readme
-- **Security model:** [SECURITY.md](https://github.com/CorsenAI/corsen-context/blob/main/SECURITY.md)
-- **License:** MIT
+# @corsenai/corsen-context
+
+The core engine of **[Corsen Context](https://github.com/CorsenAI/corsen-context)** — the Universal AI Context Layer that makes any website AI-native with an MCP server + enhanced `llms.txt`.
+
+```bash
+npm install @corsenai/corsen-context
+```
+
+```typescript
+import { CorsenContext, createInMemoryProvider } from '@corsenai/corsen-context';
+
+const cc = new CorsenContext(
+  { siteUrl: 'https://example.com' },
+  createInMemoryProvider([
+    { url: 'https://example.com/', title: 'Home', description: 'Welcome', markdown: '# Home', metadata: {}, type: 'page' },
+  ]),
+);
+
+const server = cc.createMCPServer();
+const result = await server.handleRequest(requestBody, clientIp);
+```
+
+This package provides the framework-agnostic core: the MCP JSON-RPC 2.0 server, `llms.txt` generators, HTML→Markdown converter, SSRF-safe fetching, rate limiting, caching, and the content-access policy.
+
+- **Full docs:** https://github.com/CorsenAI/corsen-context#readme
+- **Security model:** [SECURITY.md](https://github.com/CorsenAI/corsen-context/blob/main/SECURITY.md)
+- **License:** MIT

package/dist/index.d.mts

@@ -379,13 +379,13 @@ declare class MCPServer {
 /**
  * Single source of truth for version strings.
  *
- * Keep CORSEN_CONTEXT_VERSION in sync with each package.json `version` on release
- * (the release tooling does this). serverInfo and the CLI both read from here so
- * the version can never silently drift between what is published and what is
- * reported over MCP.
+ * CORSEN_CONTEXT_VERSION is bumped by hand on every release, in the same
+ * commit that updates the package.json versions. serverInfo and the CLI both
+ * read from here so the version can never silently drift between what is
+ * published and what is reported over MCP.
  */
 /** Corsen Context release version. */
-declare const CORSEN_CONTEXT_VERSION = "1.2.0";
+declare const CORSEN_CONTEXT_VERSION = "1.3.0";
 /** MCP protocol version implemented by this server. */
 declare const MCP_PROTOCOL_VERSION = "2025-11-25";
 
@@ -461,6 +461,64 @@ declare function mcpLinkTag(config: DiscoveryConfig): string;
 declare function generateLlmsTxt(config: ResolvedConfig, provider: ContentProvider): Promise<string>;
 declare function generateLlmsFullTxt(config: ResolvedConfig, provider: ContentProvider): Promise<string>;
 
+/**
+ * WebMCP exposes the same tools to an agent running inside the page, through
+ * `document.modelContext`. The browser never reimplements a tool: it receives
+ * the definitions from the server and every `execute()` calls back into the
+ * existing MCP endpoint, so there is one implementation per runtime and one
+ * contract for every transport.
+ *
+ * Spec: https://webmachinelearning.github.io/webmcp/
+ */
+/** Tool annotations defined by the WebMCP `ToolAnnotations` dictionary. */
+interface WebMCPToolAnnotations {
+    /** Tool only reads state. Lets an agent decide when a call is safe. */
+    readOnlyHint: boolean;
+    /** Tool output is untrusted data, from the perspective of this site. */
+    untrustedContentHint: boolean;
+}
+interface WebMCPTool extends MCPToolDefinition {
+    annotations: WebMCPToolAnnotations;
+}
+interface WebMCPScriptConfig {
+    /**
+     * MCP endpoint the browser bridge calls. Defaults to `/v1/mcp`.
+     *
+     * The bridge is deliberately keyless: any credential embedded in a public
+     * page's script is disclosed to every visitor, so a key-protected endpoint
+     * should not enable the WebMCP bridge at all.
+     */
+    mcpEndpoint?: string;
+}
+/**
+ * Every tool Corsen Context exposes reads published site content, so all of
+ * them are read-only and all of them return untrusted data: page bodies come
+ * from authors, comments and imports, and an agent must treat that output as
+ * data rather than as instructions.
+ */
+declare const WEBMCP_TOOL_ANNOTATIONS: Readonly<Record<string, WebMCPToolAnnotations>>;
+/** Annotations for a tool. Unknown tools fall back to the safest pair. */
+declare function webMCPAnnotationsFor(name: string): WebMCPToolAnnotations;
+/** Attach WebMCP annotations to MCP tool definitions. */
+declare function toWebMCPTools(tools: MCPToolDefinition[]): WebMCPTool[];
+/**
+ * Build the inline script that registers the tools with the in-page agent.
+ *
+ * Deliberate constraints:
+ * - `exposedTo` is never set, so tools stay same-origin by default.
+ * - Registration is refused inside a frame: the Permissions Policy `tools`
+ *   feature already defaults to `['self']`, and this keeps a same-origin
+ *   frame from registering the set a second time.
+ * - The bridge only forwards calls to this site's own MCP endpoint; the page
+ *   cannot introduce a tool the server does not already serve.
+ * - Every forwarded call carries the MCP-Protocol-Version header, which the
+ *   endpoint requires on every request after initialize.
+ * - Chrome 153+ passes an AbortSignal as execute's second argument; the
+ *   bridge forwards it to fetch, so a cancelled execution aborts the
+ *   in-flight request instead of leaving work running.
+ */
+declare function generateWebMCPScript(tools: WebMCPTool[], config?: WebMCPScriptConfig): string;
+
 declare function parseSitemap(sitemapUrl: string, maxPages?: number): Promise<SitemapEntry[]>;
 declare function discoverSitemap(siteUrl: string): Promise<string | null>;
 
@@ -794,4 +852,4 @@ declare class CorsenContext {
     };
 }
 
-export { API_VERSION, ApiKeyManager, type ApiKeyRecord, CORSEN_CONTEXT_VERSION, CREDIT_LINE, type CacheDriver, type ContentList, type ContentListItem, type ContentProvider, CorsenContext, type CorsenContextConfig, type DiscoveryConfig, type InMemoryPage, type JSONRPCRequest, type JSONRPCResponse, JSONRPC_ERRORS, type LogLevel, type Logger, type LoggerOptions, MAX_BODY_SIZE, MAX_JSON_DEPTH, type MCPCapabilities, type MCPResourceDefinition, MCPServer, type MCPToolDefinition, MCP_PROTOCOL_VERSION, MemoryCache, MemoryRateLimitStore, type PageContent, REQUEST_TIMEOUT_MS, type RateLimitResult, type RateLimitStore, RateLimiter, RedisCache, type RedisClient, RedisRateLimitStore, type ResolvedConfig, SECURITY_HEADERS, type SearchResult, type SitemapEntry, buildRateLimitKey, corsenContextConfigSchema, createInMemoryProvider, createLogger, createSitemapProvider, discoverSitemap, extractClientIp, extractMetadata, filterPublicPages, filterPublicSearchResults, generateLlmsFullTxt, generateLlmsTxt, generateRobotsTxt, generateWellKnownMcp, getLogger, getPageParamsSchema, hashApiKey, htmlToMarkdown, isPrivateIp, isPrivateUrl, isPublicListItem, isPublicPageContent, listContentParamsSchema, mcpLinkTag, mcpLogger, parseSitemap, resolveConfig, resolvePublicPageUrl, safeFetch, searchParamsSchema, securityLogger, setLogger, validateApiKey, validateHost, validateOrigin };
+export { API_VERSION, ApiKeyManager, type ApiKeyRecord, CORSEN_CONTEXT_VERSION, CREDIT_LINE, type CacheDriver, type ContentList, type ContentListItem, type ContentProvider, CorsenContext, type CorsenContextConfig, type DiscoveryConfig, type InMemoryPage, type JSONRPCRequest, type JSONRPCResponse, JSONRPC_ERRORS, type LogLevel, type Logger, type LoggerOptions, MAX_BODY_SIZE, MAX_JSON_DEPTH, type MCPCapabilities, type MCPResourceDefinition, MCPServer, type MCPToolDefinition, MCP_PROTOCOL_VERSION, MemoryCache, MemoryRateLimitStore, type PageContent, REQUEST_TIMEOUT_MS, type RateLimitResult, type RateLimitStore, RateLimiter, RedisCache, type RedisClient, RedisRateLimitStore, type ResolvedConfig, SECURITY_HEADERS, type SearchResult, type SitemapEntry, WEBMCP_TOOL_ANNOTATIONS, type WebMCPScriptConfig, type WebMCPTool, type WebMCPToolAnnotations, buildRateLimitKey, corsenContextConfigSchema, createInMemoryProvider, createLogger, createSitemapProvider, discoverSitemap, extractClientIp, extractMetadata, filterPublicPages, filterPublicSearchResults, generateLlmsFullTxt, generateLlmsTxt, generateRobotsTxt, generateWebMCPScript, generateWellKnownMcp, getLogger, getPageParamsSchema, hashApiKey, htmlToMarkdown, isPrivateIp, isPrivateUrl, isPublicListItem, isPublicPageContent, listContentParamsSchema, mcpLinkTag, mcpLogger, parseSitemap, resolveConfig, resolvePublicPageUrl, safeFetch, searchParamsSchema, securityLogger, setLogger, toWebMCPTools, validateApiKey, validateHost, validateOrigin, webMCPAnnotationsFor };

package/dist/index.d.ts

@@ -379,13 +379,13 @@ declare class MCPServer {
 /**
  * Single source of truth for version strings.
  *
- * Keep CORSEN_CONTEXT_VERSION in sync with each package.json `version` on release
- * (the release tooling does this). serverInfo and the CLI both read from here so
- * the version can never silently drift between what is published and what is
- * reported over MCP.
+ * CORSEN_CONTEXT_VERSION is bumped by hand on every release, in the same
+ * commit that updates the package.json versions. serverInfo and the CLI both
+ * read from here so the version can never silently drift between what is
+ * published and what is reported over MCP.
  */
 /** Corsen Context release version. */
-declare const CORSEN_CONTEXT_VERSION = "1.2.0";
+declare const CORSEN_CONTEXT_VERSION = "1.3.0";
 /** MCP protocol version implemented by this server. */
 declare const MCP_PROTOCOL_VERSION = "2025-11-25";
 
@@ -461,6 +461,64 @@ declare function mcpLinkTag(config: DiscoveryConfig): string;
 declare function generateLlmsTxt(config: ResolvedConfig, provider: ContentProvider): Promise<string>;
 declare function generateLlmsFullTxt(config: ResolvedConfig, provider: ContentProvider): Promise<string>;
 
+/**
+ * WebMCP exposes the same tools to an agent running inside the page, through
+ * `document.modelContext`. The browser never reimplements a tool: it receives
+ * the definitions from the server and every `execute()` calls back into the
+ * existing MCP endpoint, so there is one implementation per runtime and one
+ * contract for every transport.
+ *
+ * Spec: https://webmachinelearning.github.io/webmcp/
+ */
+/** Tool annotations defined by the WebMCP `ToolAnnotations` dictionary. */
+interface WebMCPToolAnnotations {
+    /** Tool only reads state. Lets an agent decide when a call is safe. */
+    readOnlyHint: boolean;
+    /** Tool output is untrusted data, from the perspective of this site. */
+    untrustedContentHint: boolean;
+}
+interface WebMCPTool extends MCPToolDefinition {
+    annotations: WebMCPToolAnnotations;
+}
+interface WebMCPScriptConfig {
+    /**
+     * MCP endpoint the browser bridge calls. Defaults to `/v1/mcp`.
+     *
+     * The bridge is deliberately keyless: any credential embedded in a public
+     * page's script is disclosed to every visitor, so a key-protected endpoint
+     * should not enable the WebMCP bridge at all.
+     */
+    mcpEndpoint?: string;
+}
+/**
+ * Every tool Corsen Context exposes reads published site content, so all of
+ * them are read-only and all of them return untrusted data: page bodies come
+ * from authors, comments and imports, and an agent must treat that output as
+ * data rather than as instructions.
+ */
+declare const WEBMCP_TOOL_ANNOTATIONS: Readonly<Record<string, WebMCPToolAnnotations>>;
+/** Annotations for a tool. Unknown tools fall back to the safest pair. */
+declare function webMCPAnnotationsFor(name: string): WebMCPToolAnnotations;
+/** Attach WebMCP annotations to MCP tool definitions. */
+declare function toWebMCPTools(tools: MCPToolDefinition[]): WebMCPTool[];
+/**
+ * Build the inline script that registers the tools with the in-page agent.
+ *
+ * Deliberate constraints:
+ * - `exposedTo` is never set, so tools stay same-origin by default.
+ * - Registration is refused inside a frame: the Permissions Policy `tools`
+ *   feature already defaults to `['self']`, and this keeps a same-origin
+ *   frame from registering the set a second time.
+ * - The bridge only forwards calls to this site's own MCP endpoint; the page
+ *   cannot introduce a tool the server does not already serve.
+ * - Every forwarded call carries the MCP-Protocol-Version header, which the
+ *   endpoint requires on every request after initialize.
+ * - Chrome 153+ passes an AbortSignal as execute's second argument; the
+ *   bridge forwards it to fetch, so a cancelled execution aborts the
+ *   in-flight request instead of leaving work running.
+ */
+declare function generateWebMCPScript(tools: WebMCPTool[], config?: WebMCPScriptConfig): string;
+
 declare function parseSitemap(sitemapUrl: string, maxPages?: number): Promise<SitemapEntry[]>;
 declare function discoverSitemap(siteUrl: string): Promise<string | null>;
 
@@ -794,4 +852,4 @@ declare class CorsenContext {
     };
 }
 
-export { API_VERSION, ApiKeyManager, type ApiKeyRecord, CORSEN_CONTEXT_VERSION, CREDIT_LINE, type CacheDriver, type ContentList, type ContentListItem, type ContentProvider, CorsenContext, type CorsenContextConfig, type DiscoveryConfig, type InMemoryPage, type JSONRPCRequest, type JSONRPCResponse, JSONRPC_ERRORS, type LogLevel, type Logger, type LoggerOptions, MAX_BODY_SIZE, MAX_JSON_DEPTH, type MCPCapabilities, type MCPResourceDefinition, MCPServer, type MCPToolDefinition, MCP_PROTOCOL_VERSION, MemoryCache, MemoryRateLimitStore, type PageContent, REQUEST_TIMEOUT_MS, type RateLimitResult, type RateLimitStore, RateLimiter, RedisCache, type RedisClient, RedisRateLimitStore, type ResolvedConfig, SECURITY_HEADERS, type SearchResult, type SitemapEntry, buildRateLimitKey, corsenContextConfigSchema, createInMemoryProvider, createLogger, createSitemapProvider, discoverSitemap, extractClientIp, extractMetadata, filterPublicPages, filterPublicSearchResults, generateLlmsFullTxt, generateLlmsTxt, generateRobotsTxt, generateWellKnownMcp, getLogger, getPageParamsSchema, hashApiKey, htmlToMarkdown, isPrivateIp, isPrivateUrl, isPublicListItem, isPublicPageContent, listContentParamsSchema, mcpLinkTag, mcpLogger, parseSitemap, resolveConfig, resolvePublicPageUrl, safeFetch, searchParamsSchema, securityLogger, setLogger, validateApiKey, validateHost, validateOrigin };
+export { API_VERSION, ApiKeyManager, type ApiKeyRecord, CORSEN_CONTEXT_VERSION, CREDIT_LINE, type CacheDriver, type ContentList, type ContentListItem, type ContentProvider, CorsenContext, type CorsenContextConfig, type DiscoveryConfig, type InMemoryPage, type JSONRPCRequest, type JSONRPCResponse, JSONRPC_ERRORS, type LogLevel, type Logger, type LoggerOptions, MAX_BODY_SIZE, MAX_JSON_DEPTH, type MCPCapabilities, type MCPResourceDefinition, MCPServer, type MCPToolDefinition, MCP_PROTOCOL_VERSION, MemoryCache, MemoryRateLimitStore, type PageContent, REQUEST_TIMEOUT_MS, type RateLimitResult, type RateLimitStore, RateLimiter, RedisCache, type RedisClient, RedisRateLimitStore, type ResolvedConfig, SECURITY_HEADERS, type SearchResult, type SitemapEntry, WEBMCP_TOOL_ANNOTATIONS, type WebMCPScriptConfig, type WebMCPTool, type WebMCPToolAnnotations, buildRateLimitKey, corsenContextConfigSchema, createInMemoryProvider, createLogger, createSitemapProvider, discoverSitemap, extractClientIp, extractMetadata, filterPublicPages, filterPublicSearchResults, generateLlmsFullTxt, generateLlmsTxt, generateRobotsTxt, generateWebMCPScript, generateWellKnownMcp, getLogger, getPageParamsSchema, hashApiKey, htmlToMarkdown, isPrivateIp, isPrivateUrl, isPublicListItem, isPublicPageContent, listContentParamsSchema, mcpLinkTag, mcpLogger, parseSitemap, resolveConfig, resolvePublicPageUrl, safeFetch, searchParamsSchema, securityLogger, setLogger, toWebMCPTools, validateApiKey, validateHost, validateOrigin, webMCPAnnotationsFor };

package/dist/index.js

@@ -47,6 +47,7 @@ __export(index_exports, {
   RedisCache: () => RedisCache,
   RedisRateLimitStore: () => RedisRateLimitStore,
   SECURITY_HEADERS: () => SECURITY_HEADERS,
+  WEBMCP_TOOL_ANNOTATIONS: () => WEBMCP_TOOL_ANNOTATIONS,
   buildRateLimitKey: () => buildRateLimitKey,
   corsenContextConfigSchema: () => corsenContextConfigSchema,
   createInMemoryProvider: () => createInMemoryProvider,
@@ -60,6 +61,7 @@ __export(index_exports, {
   generateLlmsFullTxt: () => generateLlmsFullTxt,
   generateLlmsTxt: () => generateLlmsTxt,
   generateRobotsTxt: () => generateRobotsTxt,
+  generateWebMCPScript: () => generateWebMCPScript,
   generateWellKnownMcp: () => generateWellKnownMcp,
   getLogger: () => getLogger,
   getPageParamsSchema: () => getPageParamsSchema,
@@ -79,9 +81,11 @@ __export(index_exports, {
   searchParamsSchema: () => searchParamsSchema,
   securityLogger: () => securityLogger,
   setLogger: () => setLogger,
+  toWebMCPTools: () => toWebMCPTools,
   validateApiKey: () => validateApiKey,
   validateHost: () => validateHost,
-  validateOrigin: () => validateOrigin
+  validateOrigin: () => validateOrigin,
+  webMCPAnnotationsFor: () => webMCPAnnotationsFor
 });
 module.exports = __toCommonJS(index_exports);
 
@@ -175,7 +179,7 @@ var SECURITY_HEADERS = {
 };
 
 // src/version.ts
-var CORSEN_CONTEXT_VERSION = "1.2.0";
+var CORSEN_CONTEXT_VERSION = "1.3.0";
 var MCP_PROTOCOL_VERSION = "2025-11-25";
 
 // src/security.ts
@@ -1171,12 +1175,12 @@ var MCPServer = class _MCPServer {
     if (this.config.mcp.tools.includes("search_site")) {
       tools.push({
         name: "search_site",
-        description: "Search site content by keyword. Returns matching pages with snippets.",
+        description: "Search this site's public content by keyword and get matching pages with titles, URLs and text snippets. Use this first when the user asks about something on this site and you do not know which page covers it. Read-only: returns content, never changes anything.",
         inputSchema: {
           type: "object",
           properties: {
-            query: { type: "string", description: "Search query" },
-            limit: { type: "number", description: "Max results (1-50, default 10)" }
+            query: { type: "string", description: "Keywords to search for, in the site's own language. Use the user's words." },
+            limit: { type: "number", description: "Maximum number of results to return (1-50, default 10)." }
           },
           required: ["query"]
         }
@@ -1185,11 +1189,11 @@ var MCPServer = class _MCPServer {
     if (this.config.mcp.tools.includes("get_page_content")) {
       tools.push({
         name: "get_page_content",
-        description: "Get full page content as clean markdown with metadata (title, description, dates).",
+        description: "Read one page of this site in full, as clean markdown with its title, description and dates. Use this after search_site or get_sitemap to read a specific page. Read-only.",
         inputSchema: {
           type: "object",
           properties: {
-            uri: { type: "string", description: "Page URL or resource URI" }
+            uri: { type: "string", description: "The page's absolute URL on this site, exactly as returned by search_site, list_content or get_sitemap." }
           },
           required: ["uri"]
         }
@@ -1198,13 +1202,13 @@ var MCPServer = class _MCPServer {
     if (this.config.mcp.tools.includes("list_content")) {
       tools.push({
         name: "list_content",
-        description: "List content by type (page, post, product) with pagination.",
+        description: "Browse this site's public content by type (e.g. page, post, product) with pagination. Use to enumerate what the site publishes when a keyword search is too narrow. Read-only.",
         inputSchema: {
           type: "object",
           properties: {
-            type: { type: "string", description: "Content type (e.g., post, page, product, or any custom type)" },
-            page: { type: "number", description: "Page number (default 1)" },
-            limit: { type: "number", description: "Items per page (1-100, default 20)" }
+            type: { type: "string", description: "The content type to list: post, page, product, or any custom type the site exposes." },
+            page: { type: "number", description: "Result page number (default 1)." },
+            limit: { type: "number", description: "Items per page (1-100, default 20)." }
           }
         }
       });
@@ -1212,7 +1216,7 @@ var MCPServer = class _MCPServer {
     if (this.config.mcp.tools.includes("get_sitemap")) {
       tools.push({
         name: "get_sitemap",
-        description: "Get structured sitemap of the entire site with URLs, titles, types, and dates.",
+        description: "Get the structured sitemap of this site's public content: every URL with its title, type and last-modified date. Use for a complete overview of what the site exposes to agents. Read-only.",
         inputSchema: {
           type: "object",
           properties: {}
@@ -1565,6 +1569,82 @@ function extractMetadata(html) {
   return meta;
 }
 
+// src/webmcp.ts
+var WEBMCP_TOOL_ANNOTATIONS = Object.freeze(
+  {
+    search_site: { readOnlyHint: true, untrustedContentHint: true },
+    get_page_content: { readOnlyHint: true, untrustedContentHint: true },
+    list_content: { readOnlyHint: true, untrustedContentHint: true },
+    get_sitemap: { readOnlyHint: true, untrustedContentHint: true }
+  }
+);
+function webMCPAnnotationsFor(name) {
+  return WEBMCP_TOOL_ANNOTATIONS[name] ?? { readOnlyHint: true, untrustedContentHint: true };
+}
+function toWebMCPTools(tools) {
+  return tools.map((tool) => ({ ...tool, annotations: webMCPAnnotationsFor(tool.name) }));
+}
+function embedJson(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+function generateWebMCPScript(tools, config = {}) {
+  const endpoint = config.mcpEndpoint || "/v1/mcp";
+  return `(function () {
+  var tools = ${embedJson(tools)};
+  var endpoint = ${embedJson(endpoint)};
+  var protocolVersion = ${embedJson(MCP_PROTOCOL_VERSION)};
+
+  if (window.top !== window.self) return;
+
+  // Chrome 150 moved the getter to document and kept navigator as a
+  // deprecated alias; support both while the origin trial runs.
+  var mc = document.modelContext || navigator.modelContext;
+  if (!mc || typeof mc.registerTool !== 'function') return;
+
+  function call(name, args, signal) {
+    return fetch(endpoint, {
+      method: 'POST',
+      credentials: 'omit',
+      signal: signal || null,
+      // The endpoint rejects version-less calls: MCP requires the negotiated
+      // protocol version header on every request after initialize.
+      headers: {
+        'Content-Type': 'application/json',
+        'MCP-Protocol-Version': protocolVersion
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: Date.now(),
+        method: 'tools/call',
+        params: { name: name, arguments: args || {} }
+      })
+    })
+      .then(function (res) {
+        if (!res.ok) throw new Error('Corsen Context: MCP endpoint returned ' + res.status);
+        return res.json();
+      })
+      .then(function (body) {
+        if (body && body.error) throw new Error(body.error.message || 'MCP error');
+        var content = body && body.result && body.result.content;
+        if (!Array.isArray(content)) return '';
+        return content
+          .map(function (part) { return part && typeof part.text === 'string' ? part.text : ''; })
+          .join('\\n');
+      });
+  }
+
+  tools.forEach(function (tool) {
+    mc.registerTool({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      annotations: tool.annotations,
+      execute: function (input, options) { return call(tool.name, input, options && options.signal); }
+    });
+  });
+})();`;
+}
+
 // src/redis-cache.ts
 var RedisCache = class {
   redis;
@@ -1842,6 +1922,7 @@ var CorsenContext = class {
   RedisCache,
   RedisRateLimitStore,
   SECURITY_HEADERS,
+  WEBMCP_TOOL_ANNOTATIONS,
   buildRateLimitKey,
   corsenContextConfigSchema,
   createInMemoryProvider,
@@ -1855,6 +1936,7 @@ var CorsenContext = class {
   generateLlmsFullTxt,
   generateLlmsTxt,
   generateRobotsTxt,
+  generateWebMCPScript,
   generateWellKnownMcp,
   getLogger,
   getPageParamsSchema,
@@ -1874,7 +1956,9 @@ var CorsenContext = class {
   searchParamsSchema,
   securityLogger,
   setLogger,
+  toWebMCPTools,
   validateApiKey,
   validateHost,
-  validateOrigin
+  validateOrigin,
+  webMCPAnnotationsFor
 });

package/dist/index.mjs

@@ -88,7 +88,7 @@ var SECURITY_HEADERS = {
 };
 
 // src/version.ts
-var CORSEN_CONTEXT_VERSION = "1.2.0";
+var CORSEN_CONTEXT_VERSION = "1.3.0";
 var MCP_PROTOCOL_VERSION = "2025-11-25";
 
 // src/security.ts
@@ -1084,12 +1084,12 @@ var MCPServer = class _MCPServer {
     if (this.config.mcp.tools.includes("search_site")) {
       tools.push({
         name: "search_site",
-        description: "Search site content by keyword. Returns matching pages with snippets.",
+        description: "Search this site's public content by keyword and get matching pages with titles, URLs and text snippets. Use this first when the user asks about something on this site and you do not know which page covers it. Read-only: returns content, never changes anything.",
         inputSchema: {
           type: "object",
           properties: {
-            query: { type: "string", description: "Search query" },
-            limit: { type: "number", description: "Max results (1-50, default 10)" }
+            query: { type: "string", description: "Keywords to search for, in the site's own language. Use the user's words." },
+            limit: { type: "number", description: "Maximum number of results to return (1-50, default 10)." }
           },
           required: ["query"]
         }
@@ -1098,11 +1098,11 @@ var MCPServer = class _MCPServer {
     if (this.config.mcp.tools.includes("get_page_content")) {
       tools.push({
         name: "get_page_content",
-        description: "Get full page content as clean markdown with metadata (title, description, dates).",
+        description: "Read one page of this site in full, as clean markdown with its title, description and dates. Use this after search_site or get_sitemap to read a specific page. Read-only.",
         inputSchema: {
           type: "object",
           properties: {
-            uri: { type: "string", description: "Page URL or resource URI" }
+            uri: { type: "string", description: "The page's absolute URL on this site, exactly as returned by search_site, list_content or get_sitemap." }
           },
           required: ["uri"]
         }
@@ -1111,13 +1111,13 @@ var MCPServer = class _MCPServer {
     if (this.config.mcp.tools.includes("list_content")) {
       tools.push({
         name: "list_content",
-        description: "List content by type (page, post, product) with pagination.",
+        description: "Browse this site's public content by type (e.g. page, post, product) with pagination. Use to enumerate what the site publishes when a keyword search is too narrow. Read-only.",
         inputSchema: {
           type: "object",
           properties: {
-            type: { type: "string", description: "Content type (e.g., post, page, product, or any custom type)" },
-            page: { type: "number", description: "Page number (default 1)" },
-            limit: { type: "number", description: "Items per page (1-100, default 20)" }
+            type: { type: "string", description: "The content type to list: post, page, product, or any custom type the site exposes." },
+            page: { type: "number", description: "Result page number (default 1)." },
+            limit: { type: "number", description: "Items per page (1-100, default 20)." }
           }
         }
       });
@@ -1125,7 +1125,7 @@ var MCPServer = class _MCPServer {
     if (this.config.mcp.tools.includes("get_sitemap")) {
       tools.push({
         name: "get_sitemap",
-        description: "Get structured sitemap of the entire site with URLs, titles, types, and dates.",
+        description: "Get the structured sitemap of this site's public content: every URL with its title, type and last-modified date. Use for a complete overview of what the site exposes to agents. Read-only.",
         inputSchema: {
           type: "object",
           properties: {}
@@ -1478,6 +1478,82 @@ function extractMetadata(html) {
   return meta;
 }
 
+// src/webmcp.ts
+var WEBMCP_TOOL_ANNOTATIONS = Object.freeze(
+  {
+    search_site: { readOnlyHint: true, untrustedContentHint: true },
+    get_page_content: { readOnlyHint: true, untrustedContentHint: true },
+    list_content: { readOnlyHint: true, untrustedContentHint: true },
+    get_sitemap: { readOnlyHint: true, untrustedContentHint: true }
+  }
+);
+function webMCPAnnotationsFor(name) {
+  return WEBMCP_TOOL_ANNOTATIONS[name] ?? { readOnlyHint: true, untrustedContentHint: true };
+}
+function toWebMCPTools(tools) {
+  return tools.map((tool) => ({ ...tool, annotations: webMCPAnnotationsFor(tool.name) }));
+}
+function embedJson(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+function generateWebMCPScript(tools, config = {}) {
+  const endpoint = config.mcpEndpoint || "/v1/mcp";
+  return `(function () {
+  var tools = ${embedJson(tools)};
+  var endpoint = ${embedJson(endpoint)};
+  var protocolVersion = ${embedJson(MCP_PROTOCOL_VERSION)};
+
+  if (window.top !== window.self) return;
+
+  // Chrome 150 moved the getter to document and kept navigator as a
+  // deprecated alias; support both while the origin trial runs.
+  var mc = document.modelContext || navigator.modelContext;
+  if (!mc || typeof mc.registerTool !== 'function') return;
+
+  function call(name, args, signal) {
+    return fetch(endpoint, {
+      method: 'POST',
+      credentials: 'omit',
+      signal: signal || null,
+      // The endpoint rejects version-less calls: MCP requires the negotiated
+      // protocol version header on every request after initialize.
+      headers: {
+        'Content-Type': 'application/json',
+        'MCP-Protocol-Version': protocolVersion
+      },
+      body: JSON.stringify({
+        jsonrpc: '2.0',
+        id: Date.now(),
+        method: 'tools/call',
+        params: { name: name, arguments: args || {} }
+      })
+    })
+      .then(function (res) {
+        if (!res.ok) throw new Error('Corsen Context: MCP endpoint returned ' + res.status);
+        return res.json();
+      })
+      .then(function (body) {
+        if (body && body.error) throw new Error(body.error.message || 'MCP error');
+        var content = body && body.result && body.result.content;
+        if (!Array.isArray(content)) return '';
+        return content
+          .map(function (part) { return part && typeof part.text === 'string' ? part.text : ''; })
+          .join('\\n');
+      });
+  }
+
+  tools.forEach(function (tool) {
+    mc.registerTool({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      annotations: tool.annotations,
+      execute: function (input, options) { return call(tool.name, input, options && options.signal); }
+    });
+  });
+})();`;
+}
+
 // src/redis-cache.ts
 var RedisCache = class {
   redis;
@@ -1754,6 +1830,7 @@ export {
   RedisCache,
   RedisRateLimitStore,
   SECURITY_HEADERS,
+  WEBMCP_TOOL_ANNOTATIONS,
   buildRateLimitKey,
   corsenContextConfigSchema,
   createInMemoryProvider,
@@ -1767,6 +1844,7 @@ export {
   generateLlmsFullTxt,
   generateLlmsTxt,
   generateRobotsTxt,
+  generateWebMCPScript,
   generateWellKnownMcp,
   getLogger,
   getPageParamsSchema,
@@ -1786,7 +1864,9 @@ export {
   searchParamsSchema,
   securityLogger,
   setLogger,
+  toWebMCPTools,
   validateApiKey,
   validateHost,
-  validateOrigin
+  validateOrigin,
+  webMCPAnnotationsFor
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@corsenai/corsen-context",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Universal AI Context Layer — MCP Server + Enhanced llms.txt for any website",
   "author": "Corsen AI <contact@corsen.ai>",
   "license": "MIT",