@redocly/realm 0.136.0-next.0 → 0.136.0-next.10

package/dist/server/plugins/mcp/gateway-mcp/fetch-capability.d.ts

@@ -1,6 +1,13 @@
 import type { ApiDescriptionInfo, McpToolContext } from '../types.js';
 import type { SandboxFetch } from '../codemode/types.js';
+import type { UpstreamAuthRequiredEvent } from './upstream-auth.js';
 export declare function getCallableApis(context: McpToolContext): ApiDescriptionInfo[];
+/**
+ * Fetch capability at request/worker time is derived purely from the build-time stamps:
+ * `fetchEligible` is stamped per API by the lifecycle plugin under `isGatewayCapabilityEnabled`
+ * (entitlement + hide checks), and the map arriving here is already RBAC-filtered.
+ * No EntitlementsProvider read — this code runs in graphs where the provider is uninitialized.
+ */
 export declare function isFetchCapable(context: McpToolContext): boolean;
-export declare function buildExecuteHostFetch(context: McpToolContext): SandboxFetch;
+export declare function buildExecuteHostFetch(context: McpToolContext, onAuthRequired?: (event: UpstreamAuthRequiredEvent) => void): SandboxFetch;
 //# sourceMappingURL=fetch-capability.d.ts.map

package/dist/server/plugins/mcp/gateway-mcp/fetch-capability.js

@@ -1 +1 @@
-import{isGatewayCapabilityEnabled as a}from"./eligibility.js";import{buildAllowedHostMatchers as l}from"./fetch/allowed-hosts.js";import{buildFetchBridge as s}from"./fetch/fetch-bridge.js";function i(t){return Object.values(t.apiDescriptionsMap??{}).filter(e=>e.fetchEligible)}function u(t){const e=t.config?.mcp;return a(e)&&i(t).length>0}function f(t){const e=t.config?.mcp,o=i(t).flatMap(r=>r.servers??[]);return s({allowedHosts:l(o,e?.gateway?.allowedHosts),authorization:t.upstreamAuthorization})}export{f as buildExecuteHostFetch,i as getCallableApis,u as isFetchCapable};
+import{buildAllowedHostMatchers as a}from"./fetch/allowed-hosts.js";import{buildFetchBridge as s}from"./fetch/fetch-bridge.js";function i(e){return Object.values(e.apiDescriptionsMap??{}).filter(r=>r.fetchEligible)}function u(e){return i(e).length>0}function n(e,r){const l=i(e).map(t=>({slug:t.relativePath,name:t.name,matchers:a(t.servers??[]),secret:e.upstreamSecrets?.[t.relativePath]}));return s({allowedHosts:a([]),apis:l,authorization:e.upstreamAuthorization,onAuthRequired:r,maxFetchesPerExec:e.gatewayFetchBudgetPerExec,clientIp:e.clientIp})}export{n as buildExecuteHostFetch,i as getCallableApis,u as isFetchCapable};

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/apply-edge-rate-limit.d.ts

@@ -0,0 +1,3 @@
+import type { Store } from '../../../../store.js';
+export declare function applyEdgeRateLimit(request: Request, store: Store): Promise<Response | undefined>;
+//# sourceMappingURL=apply-edge-rate-limit.d.ts.map

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/apply-edge-rate-limit.js

@@ -0,0 +1 @@
+import{envConfig as o}from"../../../../config/env-config.js";import{KvRepository as s}from"../../../../persistence/kv/repositories/kv-repository.js";import{logger as m}from"../../../../tools/notifiers/logger.js";import{ipRateLimitKey as p}from"./ip-key.js";import{checkEdgeRateLimit as c}from"./edge-limiter.js";import{resolveGatewayFetchLimits as d}from"./limits.js";import{reportMcpRateLimited as f}from"./rate-limit-telemetry.js";async function S(n,a){const i=p(n);if(!i)return;let e,t;try{const r=await s.create({baseDbDir:a.serverOutDir,sqldRemoteDatabaseUrl:o.SQLD_REMOTE_DATABASE_URL,sqldRemoteDatabaseAuthToken:o.SQLD_REMOTE_DATABASE_AUTH_TOKEN});t=d(),e=await c({kv:r,ip:i,limits:t,now:Date.now()})}catch(r){m.warn(`gateway rate-limit init error, failing open: ${String(r)}`);return}if(!e.allowed)return f({scope:e.scope,retryAfterSeconds:e.retryAfterSeconds,limit:e.scope==="rate"?t.ratePerMin:t.quotaPerDay}),new Response(JSON.stringify({jsonrpc:"2.0",error:{code:-32029,message:`Rate limit exceeded (${e.scope}); retry after ${e.retryAfterSeconds}s`},id:null}),{status:429,headers:{"Content-Type":"application/json","Retry-After":String(e.retryAfterSeconds)}})}export{S as applyEdgeRateLimit};

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/edge-limiter.d.ts

@@ -0,0 +1,16 @@
+import type { KvRepository } from '../../../../persistence/kv/repositories/kv-repository.js';
+import type { GatewayFetchLimits } from './limits.js';
+export type EdgeDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    retryAfterSeconds: number;
+    scope: 'rate' | 'quota';
+};
+export declare function checkEdgeRateLimit(params: {
+    kv: KvRepository;
+    ip: string;
+    limits: GatewayFetchLimits;
+    now: number;
+}): Promise<EdgeDecision>;
+//# sourceMappingURL=edge-limiter.d.ts.map

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/edge-limiter.js

@@ -0,0 +1 @@
+import{checkAndIncrement as c}from"./window-counter.js";const s=60,d=86400;async function w(i){const{kv:e,ip:t,limits:o,now:r}=i;await e.sync();const n=await c({kv:e,ip:t,windowSeconds:s,limit:o.ratePerMin,now:r});if(!n.allowed)return{allowed:!1,retryAfterSeconds:n.retryAfterSeconds,scope:"rate"};const a=await c({kv:e,ip:t,windowSeconds:d,limit:o.quotaPerDay,now:r});return a.allowed?{allowed:!0}:{allowed:!1,retryAfterSeconds:a.retryAfterSeconds,scope:"quota"}}export{w as checkEdgeRateLimit};

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/ip-key.d.ts

@@ -0,0 +1,2 @@
+export declare function ipRateLimitKey(req: Request): string | undefined;
+//# sourceMappingURL=ip-key.d.ts.map

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/ip-key.js

@@ -0,0 +1 @@
+import{isIP as l}from"node:net";import{getFeedbackClientIp as a}from"../../../../web-server/utils/feedback-ip.js";import{extractMappedIpv4 as c}from"../fetch/ssrf-blocklist.js";function I(t){const n=a(t);if(n)return f(n)}function f(t){if(l(t)===6){const n=c(t);return n||`${u(t)}::/64`}return t}function u(t){const n=t.split("%")[0],[e,i=""]=n.split("::"),r=e?e.split(":"):[],o=i?i.split(":"):[],s=8-r.length-o.length;return[...r,...Array(Math.max(0,s)).fill("0"),...o].slice(0,4).map(p=>parseInt(p||"0",16).toString(16)).join(":")}export{I as ipRateLimitKey};

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/limits.d.ts

@@ -0,0 +1,7 @@
+export type GatewayFetchLimits = {
+    ratePerMin: number;
+    quotaPerDay: number;
+    budgetPerExec: number;
+};
+export declare function resolveGatewayFetchLimits(): GatewayFetchLimits;
+//# sourceMappingURL=limits.d.ts.map

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/limits.js

@@ -0,0 +1 @@
+import{EntitlementsProvider as u}from"../../../../entitlements/entitlements-provider.js";import{FEATURE as r,GATEWAY_FETCH_LIMIT_DEFAULTS as a}from"../../../../../constants/common.js";function n(e,i,o){const t=e.entitlements?.[i];return typeof t=="number"&&Number.isFinite(t)?t:o}function P(){const e=u.instance();return{ratePerMin:n(e,r.gatewayFetchRatePerMin,a.ratePerMin),quotaPerDay:n(e,r.gatewayFetchQuotaPerDay,a.quotaPerDay),budgetPerExec:n(e,r.gatewayFetchBudgetPerExec,a.budgetPerExec)}}export{P as resolveGatewayFetchLimits};

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/rate-limit-telemetry.d.ts

@@ -0,0 +1,8 @@
+type RateLimitedEvent = {
+    scope: 'rate' | 'quota';
+    retryAfterSeconds: number;
+    limit: number;
+};
+export declare function reportMcpRateLimited({ scope, retryAfterSeconds, limit }: RateLimitedEvent): void;
+export {};
+//# sourceMappingURL=rate-limit-telemetry.d.ts.map

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/rate-limit-telemetry.js

@@ -0,0 +1 @@
+import{telemetry as o}from"../../../../telemetry/index.js";import{logger as i}from"../../../../tools/notifiers/logger.js";import{McpServerType as m}from"../../constants.js";import{serverAttributes as p}from"../../utils/telemetry-attributes.js";function d({scope:e,retryAfterSeconds:r,limit:t}){try{o.sendMcpRateLimitedMessage([{...p(m.Docs),scope:e,retry_after_seconds:r,limit:t}])}catch{}i.warn(`Gateway MCP rate limited [scope=${e}] retryAfterSeconds=${r} limit=${t}`)}export{d as reportMcpRateLimited};

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/window-counter.d.ts

@@ -0,0 +1,15 @@
+import type { KvRepository } from '../../../../persistence/kv/repositories/kv-repository.js';
+export type WindowCheck = {
+    allowed: false;
+    retryAfterSeconds: number;
+} | {
+    allowed: true;
+};
+export declare function checkAndIncrement(params: {
+    kv: KvRepository;
+    ip: string;
+    windowSeconds: number;
+    limit: number;
+    now: number;
+}): Promise<WindowCheck>;
+//# sourceMappingURL=window-counter.d.ts.map

package/dist/server/plugins/mcp/gateway-mcp/rate-limit/window-counter.js

@@ -0,0 +1 @@
+import{logger as g}from"../../../../tools/notifiers/logger.js";function u(e,t,o){return["mcp","gateway-fetch-rl",e,String(t),String(o)]}async function S(e){const{kv:t,ip:o,windowSeconds:n,limit:w,now:l}=e,r=Math.floor(l/1e3),c=Math.floor(r/n),i=u(o,n,c);try{const s=(await t.get(i))?.count??0;if(s>=w){const d=(c+1)*n-r;return{allowed:!1,retryAfterSeconds:Math.max(1,d)}}return await t.set(i,{count:s+1},{ttlInSeconds:n}),{allowed:!0}}catch(a){return g.warn(`gateway rate-limit store error, failing open: ${String(a)}`),{allowed:!0}}}export{S as checkAndIncrement};

package/dist/server/plugins/mcp/gateway-mcp/secret-store.d.ts

@@ -0,0 +1,24 @@
+import type { KvService } from '@redocly/config';
+import type { UpstreamAuthScheme } from './upstream-auth-scheme.js';
+export declare const ELICITATION_TTL_MS: number;
+export type StoredSecret = {
+    header: string;
+    value: string;
+};
+export type ElicitationTarget = {
+    subject: string;
+    api: string;
+    name: string;
+    auth: UpstreamAuthScheme;
+};
+export declare class SecretStore {
+    #private;
+    setSecret(kv: KvService, subject: string, api: string, secret: StoredSecret): Promise<void>;
+    getSecretsForSubject(kv: KvService, subject: string): Promise<Record<string, StoredSecret>>;
+    deleteSubject(kv: KvService, subject: string): Promise<void>;
+    createElicitation(kv: KvService, target: ElicitationTarget): Promise<string>;
+    peekElicitation(kv: KvService, token: string): Promise<ElicitationTarget | undefined>;
+    consumeElicitation(kv: KvService, token: string): Promise<ElicitationTarget | undefined>;
+}
+export declare const secretStore: SecretStore;
+//# sourceMappingURL=secret-store.d.ts.map

package/dist/server/plugins/mcp/gateway-mcp/secret-store.js

@@ -0,0 +1 @@
+import{createCipheriv as o,createDecipheriv as f,createHash as u,hkdfSync as a,randomBytes as h,randomUUID as m}from"node:crypto";import{JWT_SECRET_KEY as c}from"../../../constants/common.js";import{secretTtlSeconds as l}from"./subject.js";const p=900*1e3,d="mcp-upstream-secrets",y="mcp-elicitation",S="mcp-elicitation";class g{async setSecret(t,e,r,n){const i={api:r,...this.#c(this.#a(e),n,r)};await t.set(this.#n(e,r),i,{ttlInSeconds:l(e)})}async getSecretsForSubject(t,e){const r=this.#a(e),{items:n}=await t.list({prefix:this.#i(e)}),i={};for(const s of n)if(s.value)try{i[s.value.api]=this.#r(r,s.value,s.value.api)}catch{continue}return i}async deleteSubject(t,e){const{items:r}=await t.list({prefix:this.#i(e)}),n=r.flatMap(i=>i.value?[this.#n(e,i.value.api)]:[]);n.length!==0&&await t.transaction(async i=>{for(const s of n)await i.delete(s)})}async createElicitation(t,e){const r=m();return await t.set(this.#t(r),this.#c(this.#e(),e),{ttlInSeconds:p/1e3}),r}async peekElicitation(t,e){const r=await t.get(this.#t(e));if(r)try{return this.#r(this.#e(),r)}catch{return}}async consumeElicitation(t,e){const r=this.#t(e),n=await t.transaction(async i=>{const s=await i.get(r);return s&&await i.delete(r),s});if(n)try{return this.#r(this.#e(),n)}catch{return}}#i(t){return["mcp","secret",this.#s(t)]}#n(t,e){return["mcp","secret",this.#s(t),e]}#t(t){return["mcp","elicitation",t]}#s(t){return u("sha256").update(t).digest("hex")}#a(t){return Buffer.from(a("sha256",c,t,d,32))}#e(){return Buffer.from(a("sha256",c,S,y,32))}#c(t,e,r){const n=h(12),i=o("aes-256-gcm",t,n);r&&i.setAAD(Buffer.from(r,"utf8"));const s=Buffer.concat([i.update(JSON.stringify(e),"utf8"),i.final()]);return{iv:n.toString("base64"),tag:i.getAuthTag().toString("base64"),data:s.toString("base64")}}#r(t,e,r){const n=f("aes-256-gcm",t,Buffer.from(e.iv,"base64"));r&&n.setAAD(Buffer.from(r,"utf8")),n.setAuthTag(Buffer.from(e.tag,"base64"));const i=Buffer.concat([n.update(Buffer.from(e.data,"base64")),n.final()]).toString("utf8");return JSON.parse(i)}}const E=new g;export{p as ELICITATION_TTL_MS,g as SecretStore,E as secretStore};

package/dist/server/plugins/mcp/gateway-mcp/subject.d.ts

@@ -0,0 +1,20 @@
+import type { ApiFunctionsUser } from '@redocly/config';
+export declare const ANONYMOUS_SUBJECT_PREFIX = "anon:";
+export declare const USER_SUBJECT_PREFIX = "user:";
+export declare const MISSING_SESSION_HANDLE_MESSAGE = "This API requires credentials and the caller is anonymous; call createAnonymousSession first, then retry with sessionHandle";
+export declare const MALFORMED_SESSION_HANDLE_MESSAGE = "The sessionHandle is not a valid handle; call createAnonymousSession to obtain one";
+export type SubjectResolution = {
+    kind: 'resolved';
+    subject: string;
+} | {
+    kind: 'anonymous';
+} | {
+    kind: 'invalid';
+    message: string;
+};
+export declare function createSessionHandle(): string;
+export declare function isValidSessionHandle(value: string): boolean;
+export declare function userSubject(user: ApiFunctionsUser | undefined): string | undefined;
+export declare function resolveSecretSubject(user: ApiFunctionsUser | undefined, sessionHandle: string | undefined): SubjectResolution;
+export declare function secretTtlSeconds(subject: string): number;
+//# sourceMappingURL=subject.d.ts.map

package/dist/server/plugins/mcp/gateway-mcp/subject.js

@@ -0,0 +1 @@
+import{randomBytes as r}from"node:crypto";const i=32,S=/^[A-Za-z0-9_-]{43}$/,c=1440*60,u=720*60*60,s="anon:",d="user:",f="This API requires credentials and the caller is anonymous; call createAnonymousSession first, then retry with sessionHandle",a="The sessionHandle is not a valid handle; call createAnonymousSession to obtain one";function N(){return r(i).toString("base64url")}function E(e){return S.test(e)}function l(e){if(!e?.isAuthenticated)return;const n=e.claims,o=(typeof n?.sub=="string"&&n.sub?n.sub:void 0)??(e.email||void 0);if(o)return`${d}${e.idpId??"local"}:${o}`}function A(e,n){const t=l(e);return t?{kind:"resolved",subject:t}:n===void 0?{kind:"anonymous"}:E(n)?{kind:"resolved",subject:`${s}${n}`}:{kind:"invalid",message:a}}function T(e){return e.startsWith(s)?c:u}export{s as ANONYMOUS_SUBJECT_PREFIX,a as MALFORMED_SESSION_HANDLE_MESSAGE,f as MISSING_SESSION_HANDLE_MESSAGE,d as USER_SUBJECT_PREFIX,N as createSessionHandle,E as isValidSessionHandle,A as resolveSecretSubject,T as secretTtlSeconds,l as userSubject};

package/dist/server/plugins/mcp/gateway-mcp/upstream-auth-scheme.d.ts

@@ -0,0 +1,18 @@
+import type { McpToolContext } from '../types.js';
+import { getApiDescriptionFromFs } from '../docs-mcp/tools/openapi/utils.js';
+export type UpstreamAuthScheme = {
+    kind: 'raw';
+} | {
+    kind: 'bearer';
+} | {
+    kind: 'apiKey';
+    header: string;
+} | {
+    kind: 'oauth2ClientCredentials';
+    tokenUrl: string;
+    scopes: string[];
+};
+type SecuritySchemeLoader = typeof getApiDescriptionFromFs;
+export declare function resolveUpstreamAuthScheme(context: McpToolContext, apiRelativePath: string, loadDescription?: SecuritySchemeLoader): Promise<UpstreamAuthScheme>;
+export {};
+//# sourceMappingURL=upstream-auth-scheme.d.ts.map

package/dist/server/plugins/mcp/gateway-mcp/upstream-auth-scheme.js

@@ -0,0 +1 @@
+import{getApiDescriptionFromFs as o}from"../docs-mcp/tools/openapi/utils.js";const c={kind:"raw"};async function u(i,r,n=o){const s=Object.values(i.apiDescriptionsMap??{}).find(t=>t.relativePath===r);if(!s)return c;try{const t=await n({relativePath:s.relativePath,outdir:i.outdir||"",user:i.user,rbac:i.config?.access?.rbac||{},requiresLogin:!!i.config?.access?.requiresLogin});return a(t)}catch{return c}}function a(i){const r=Object.values(i?.components?.securitySchemes??{}).filter(l),n=r.find(e=>e.type==="oauth2"&&e.flows?.clientCredentials);if(n?.flows.clientCredentials){const e=n.flows.clientCredentials;return{kind:"oauth2ClientCredentials",tokenUrl:e.tokenUrl,scopes:Object.keys(e.scopes??{})}}if(r.find(e=>e.type==="http"&&e.scheme==="bearer"||e.type==="oauth2"))return{kind:"bearer"};const t=r.find(e=>e.type==="apiKey"&&e.in==="header");return t?{kind:"apiKey",header:t.name||"X-Api-Key"}:c}function l(i){return typeof i=="object"&&i!==null&&"type"in i}export{u as resolveUpstreamAuthScheme};

package/dist/server/plugins/mcp/gateway-mcp/upstream-auth.d.ts

@@ -0,0 +1,10 @@
+import type { CallToolResult } from '@modelcontextprotocol/server';
+export declare const UPSTREAM_AUTH_REQUIRED_META = "com.redocly/upstream-auth-required";
+export type UpstreamAuthRequiredEvent = {
+    api: string;
+    name: string;
+};
+export declare function withAuthRequiredMeta(result: CallToolResult, events: UpstreamAuthRequiredEvent[]): CallToolResult;
+export declare function readAuthRequiredMeta(result: CallToolResult): UpstreamAuthRequiredEvent[];
+export declare function stripAuthRequiredMeta(result: CallToolResult): CallToolResult;
+//# sourceMappingURL=upstream-auth.d.ts.map

package/dist/server/plugins/mcp/gateway-mcp/upstream-auth.js

@@ -0,0 +1 @@
+const n="com.redocly/upstream-auth-required";function i(e,a){const t=[...new Map(a.map(r=>[r.api,r])).values()];return t.length===0?e:{...e,_meta:{...e._meta,[n]:t}}}function o(e){const a=e._meta?.[n];return Array.isArray(a)?a.filter(t=>typeof t?.api=="string"&&typeof t?.name=="string"):[]}function p(e){if(!e._meta||!(n in e._meta))return e;const{[n]:a,...t}=e._meta,r={...e};return Object.keys(t).length>0?r._meta=t:delete r._meta,r}export{n as UPSTREAM_AUTH_REQUIRED_META,o as readAuthRequiredMeta,p as stripAuthRequiredMeta,i as withAuthRequiredMeta};

package/dist/server/plugins/mcp/handlers/docs-mcp-handler.js

@@ -1 +1 @@
-import{toFetchResponse as E,toReqRes as k}from"fetch-to-node";import{logger as m}from"../../../tools/notifiers/logger.js";import{isObject as v}from"../../../../utils/guards/is-object.js";import{getAccessibleSkills as N}from"../../../utils/skills/get-accessible-skills.js";import{getSkillUrl as O}from"../../../utils/skills/get-skill-url.js";import{createDocsMcpServer as L}from"../servers/docs-server.js";import{filterApiDescriptionsByRbac as H,filterGraphqlDescriptionsByRbac as I}from"../utils.js";import{createMethodNotAllowedError as j,withErrorHandling as B}from"./errors.js";import{attachSseKeepalive as _}from"./sse-keepalive.js";import{constructInvalidTokenResponse as J,constructUnauthorizedResponse as P,handleMcpAuth as F,shouldHandleMcpAuth as G}from"../auth/auth-handlers.js";import{extractTokenFromAuthHeader as V}from"../utils/jwt.js";import{DEFAULT_DOCS_MCP_SERVER_NAME as $}from"../constants.js";const u="X-Redocly-AI-Metadata";function q(r){if(r)try{const e=JSON.parse(r);if(v(e))return e;m.warn(`Ignoring ${u} header: not a JSON object.`)}catch{m.warn(`Ignoring ${u} header: invalid JSON.`)}}const z=async(r,e,g)=>{const t=!!e?.config?.access?.requiresLogin,i=e?.config?.access?.rbac||{};let c;const f=r.headers.get("Authorization");if(G(t,i)){const{isAuthenticated:s,isTokenValid:p,currentUser:a,accessToken:d}=await F(r,e);if(!s)return P(new URL(r.url).origin);if(!p)return J();a&&(e.user=a),c=d}else f&&(c=V(f||"")??void 0);let n;return await B(async()=>{if(r.method==="GET")return new Response(JSON.stringify({error:"Method Not Allowed",message:`In order to use this MCP server, you need register it in your MCP Client (VS Code, Cursor, Claude Code, etc.) using that URL: ${r.url}`}),{status:405,headers:{"Content-Type":"application/json"}});if(r.method!=="POST")return j();const s=g,p=s?.props?.config?.apiDescriptionsMap||{},a=s?.props?.config?.graphqlDescriptions||[],d=s?.props?.config?.mcpDocsServerName||$,{config:{mcp:h={}}}=e,R=H(p,e.user,i,t),A=I(a,e.user,i,t),D=s?.props?.skillsBaseUrl||new URL(r.url).origin,M=N(s?.props?.skills||[],e.user,i,t).map(o=>({slug:o.slug,name:o.name,description:o.description,content:o.content,uri:O(D,o.slug)})),w=e.config.products?Object.values(e.config.products).map(o=>o?.name):[],y=h.docs?.name||d,S=q(r.headers.get(u)),T=s?.props?.tools||[];n=await L({name:y,tools:T,skills:M,context:{...e,accessToken:c,outdir:e.outdir||"",baseUrl:e.baseUrl||new URL(r.url).origin,apiDescriptionsMap:R,graphqlDescriptions:A,products:w,metadata:S}});const U=await r.json(),{req:C,res:l}=k(r),b=_(l);try{await n.transport.handleRequest(C,l,U)}catch(o){throw b.stop(),o}return E(l)},async()=>{n&&(await n.cleanup(),n=void 0)})};var ie=z;export{ie as default};
+import{logger as g}from"../../../tools/notifiers/logger.js";import{getFeedbackClientIp as O}from"../../../web-server/utils/feedback-ip.js";import{GATEWAY_FETCH_LIMIT_DEFAULTS as v}from"../../../../constants/common.js";import{isObject as F}from"../../../../utils/guards/is-object.js";import{getAccessibleSkills as N}from"../../../utils/skills/get-accessible-skills.js";import{getSkillUrl as _}from"../../../utils/skills/get-skill-url.js";import{createDocsMcpServer as L}from"../servers/docs-server.js";import{filterApiDescriptionsByRbac as k,filterGraphqlDescriptionsByRbac as B}from"../utils.js";import{createMethodNotAllowedError as P,withErrorHandling as H}from"./errors.js";import{constructForbiddenResponse as j,constructInvalidTokenResponse as V,constructUnauthorizedResponse as G,handleMcpAuth as J,shouldHandleMcpAuth as $}from"../auth/auth-handlers.js";import{extractTokenFromAuthHeader as z}from"../utils/jwt.js";import{DEFAULT_DOCS_MCP_SERVER_NAME as K}from"../constants.js";import{canAccessFeature as Y}from"../../../utils/rbac.js";import{DEFAULT_ANONYMOUS_VISITOR_TEAM as W,RbacFeatures as X}from"../../../../constants/common.js";const u="X-Redocly-AI-Metadata";function Q(r){if(r)try{const e=JSON.parse(r);if(F(e))return e;g.warn(`Ignoring ${u} header: not a JSON object.`)}catch{g.warn(`Ignoring ${u} header: invalid JSON.`)}}const Z=async(r,e,s)=>{const i=!!e?.config?.access?.requiresLogin,t=e?.config?.access?.rbac||{},f=s?.props?.config?.mcpMode??"tools",h=s?.props?.config?.gatewayFetchBudgetPerExec??v.budgetPerExec;let p;const m=r.headers.get("Authorization");if($(i,t)){const{isAuthenticated:d,isTokenValid:o,currentUser:c,accessToken:l}=await J(r,e);if(!d)return G(new URL(r.url).origin);if(!o)return V();c&&(e.user=c),p=l}else m&&(p=z(m||"")??void 0);const A={isAuthenticated:!!e.user?.isAuthenticated,teams:e.user?.teams||[W],claims:e.user?.claims??{}};if(!Y(X.MCP,A,t,i))return j();let a;return await H(async()=>{const d=s?.props?.config?.elicitationEnabled??!1;if(r.method==="GET")return new Response(JSON.stringify({error:"Method Not Allowed",message:`In order to use this MCP server, you need to register it in your MCP Client (VS Code, Cursor, Claude Code, etc.) using this URL: ${r.url}`}),{status:405,headers:{"Content-Type":"application/json"}});if(r.method!=="POST")return P();const o=s,c=o?.props?.config?.apiDescriptionsMap||{},l=o?.props?.config?.graphqlDescriptions||[],M=o?.props?.config?.mcpDocsServerName||K,{config:{mcp:E={}}}=e,T=k(c,e.user,t,i),D=B(l,e.user,t,i),R=e.config.products?Object.values(e.config.products).map(n=>n?.name):[],w=E.docs?.name||M,S=Q(r.headers.get(u)),b=o?.props?.tools||[],y=o?.props?.skillsBaseUrl||new URL(r.url).origin,U=N(o?.props?.skills||[],e.user,t,i).map(n=>({slug:n.slug,name:n.name,description:n.description,content:n.content,uri:_(y,n.slug)})),C=await r.json(),I={name:w,tools:b,skills:U,context:{...e,accessToken:p,outdir:e.outdir||"",baseUrl:e.baseUrl||new URL(r.url).origin,apiDescriptionsMap:T,graphqlDescriptions:D,products:R,metadata:S,mcpMode:f,elicitationEnabled:d,gatewayFetchBudgetPerExec:h,clientIp:O(r)}};return a=await L({...I,getKv:e.getKv}),await q(r,a,C)},async()=>{a&&(await a.cleanup(),a=void 0)},f)};async function q(r,e,s){return e.transport.handleRequest(r,s!==void 0?{parsedBody:s}:void 0)}var me=Z;export{me as default};

package/dist/server/plugins/mcp/handlers/errors.d.ts

@@ -1,4 +1,4 @@
-import type { McpErrorCodeTypes } from '../types.js';
+import type { McpErrorCodeTypes, McpMode } from '../types.js';
 export type McpErrorData = {
     readonly code: McpErrorCodeTypes;
     readonly message: string;
@@ -13,8 +13,8 @@ export declare class McpError extends Error {
     createErrorResponse(): Response;
 }
 export declare function createMethodNotAllowedError(requestId?: string | number | null): Response;
-export declare function createInternalServerError(error: Error | string, requestId?: string | number | null): Response;
+export declare function createInternalServerError(error: Error | string, requestId?: string | number | null, mode?: McpMode): Response;
 export declare function createInvalidRequestError(message?: string, requestId?: string | number | null): Response;
 export declare function createInvalidParamsError(message?: string, requestId?: string | number | null): Response;
-export declare function withErrorHandling<T>(operation: () => Promise<T>, cleanup?: () => Promise<void>): Promise<T | Response>;
+export declare function withErrorHandling<T>(operation: () => Promise<T>, cleanup?: () => Promise<void>, mode?: McpMode): Promise<T | Response>;
 //# sourceMappingURL=errors.d.ts.map

package/dist/server/plugins/mcp/handlers/errors.js

@@ -1 +1 @@
-import{telemetry as d}from"../../../telemetry/index.js";import{McpErrorCodes as o,McpServerType as s}from"../constants.js";import{getMcpMode as i}from"../utils/mode.js";class n extends Error{code;data;requestId;constructor(e,t,a,c){super(t),this.name="McpError",this.code=e,this.data=a,this.requestId=c}createErrorResponse(){const e={jsonrpc:"2.0",error:{code:this.code,message:this.message,...this.data?{data:this.data}:{}},id:this.requestId??null},t=p(this.code);return new Response(JSON.stringify(e),{status:t,headers:{"Content-Type":"application/json"}})}}function p(r){switch(r){case o.InvalidRequest:case o.InvalidParams:return 400;case o.MethodNotFound:return 404;case o.ServerError:return 405;case o.InternalError:default:return 500}}function v(r){return new n(o.ServerError,"Method not allowed",void 0,r).createErrorResponse()}function u(r,e){const t=r instanceof Error?r.message:String(r),a=r instanceof Error?r.stack:void 0;return d.sendMcpErrorMessage([{id:s.Docs,object:"mcpServer",uri:`urn:redocly:realm:mcp:server:${s.Docs}`,server_type:s.Docs,message:t,stack:a||"",mode:i()}]),new n(o.InternalError,"Internal server error mcp",t,e).createErrorResponse()}function f(r="Invalid request",e){return new n(o.InvalidRequest,r,void 0,e).createErrorResponse()}function h(r="Invalid parameters",e){return new n(o.InvalidParams,r,void 0,e).createErrorResponse()}async function I(r,e){try{return await r()}catch(t){return d.sendMcpErrorMessage([{id:s.Docs,object:"mcpServer",uri:`urn:redocly:realm:mcp:server:${s.Docs}`,server_type:s.Docs,message:t?.message||"",stack:t?.stack||"",mode:i()}]),e&&e(),u(t)}}export{n as McpError,u as createInternalServerError,h as createInvalidParamsError,f as createInvalidRequestError,v as createMethodNotAllowedError,I as withErrorHandling};
+import{telemetry as c}from"../../../telemetry/index.js";import{McpErrorCodes as s,McpServerType as d}from"../constants.js";import{serverAttributes as i}from"../utils/telemetry-attributes.js";class n extends Error{code;data;requestId;constructor(e,t,o,a){super(t),this.name="McpError",this.code=e,this.data=o,this.requestId=a}createErrorResponse(){const e={jsonrpc:"2.0",error:{code:this.code,message:this.message,...this.data?{data:this.data}:{}},id:this.requestId??null},t=u(this.code);return new Response(JSON.stringify(e),{status:t,headers:{"Content-Type":"application/json"}})}}function u(r){switch(r){case s.InvalidRequest:case s.InvalidParams:return 400;case s.MethodNotFound:return 404;case s.ServerError:return 405;case s.InternalError:default:return 500}}function h(r){return new n(s.ServerError,"Method not allowed",void 0,r).createErrorResponse()}function p(r,e,t="tools"){const o=r instanceof Error?r.message:String(r),a=r instanceof Error?r.stack:void 0;return c.sendMcpErrorMessage([{...i(d.Docs),message:o,stack:a||"",error_class:"server_error",mode:t}]),new n(s.InternalError,"Internal server error mcp",o,e).createErrorResponse()}function v(r="Invalid request",e){return new n(s.InvalidRequest,r,void 0,e).createErrorResponse()}function I(r="Invalid parameters",e){return new n(s.InvalidParams,r,void 0,e).createErrorResponse()}async function g(r,e,t="tools"){try{return await r()}catch(o){return c.sendMcpErrorMessage([{...i(d.Docs),message:o?.message||"",stack:o?.stack||"",error_class:"server_error",mode:t}]),e&&e(),p(o,void 0,t)}}export{n as McpError,p as createInternalServerError,I as createInvalidParamsError,v as createInvalidRequestError,h as createMethodNotAllowedError,g as withErrorHandling};

package/dist/server/plugins/mcp/handlers/handle-mcp-request.js

@@ -1 +1 @@
-import{withPathPrefix as f}from"@redocly/theme/core/utils";import{importApiRoutesHandler as g}from"../../../api-routes/import-api-routes-handlers.js";import{enhanceContext as h}from"../../../api-routes/helpers/enhance-context.js";import{telemetry as D}from"../../../telemetry/index.js";import{KvService as A}from"../../../persistence/kv/services/kv-service.js";import{envConfig as o}from"../../../config/env-config.js";import{acceptsHtml as T}from"../../../utils/ai-agent-detection.js";import{handleErrorPageRender as R}from"../../../web-server/utils.js";import{MCP_NOT_ALLOWED_TEMPLATE_ID as E}from"../constants.js";import{resolvePublicBaseUrl as w}from"../../../web-server/utils/resolve-public-base-url.js";async function C(i,t,e){const s=t.req.raw;if(s.method==="GET"&&T(s.headers.get("accept"))&&e.globalData.mcpData?.docs?.enabled)return R(t,e,{slug:i.slug},405,E);const r=t.get("auth"),n=await e.resolveRouteStaticData(i)||{},l=f(i.slug),{requestHandlers:c}=await g(e.serverOutDir),m=c[i.requestHandlerId],p=(await m()).default,u=async()=>await A.getInstance({baseDbDir:e.serverOutDir,sqldRemoteDatabaseUrl:o.SQLD_REMOTE_DATABASE_URL,sqldRemoteDatabaseAuthToken:o.SQLD_REMOTE_DATABASE_AUTH_TOKEN}),d=h({honoCtx:t,ctx:{user:{teams:r.teams,email:r.claims.email,claims:r.claims,idpAccessToken:r.idpAccessToken,idpId:r.claims.idpId,isAuthenticated:r.isAuthenticated},config:e.config,outdir:e.outdir,baseUrl:new URL(t.req.url).origin},telemetry:D,getKv:u}),a=await p(t.req.raw,d,{...n,props:{...n.props,routeSlug:l,outdir:e.outdir,skills:e.config.skills?.hide===!0?[]:e.getSkills(),skillsBaseUrl:w(e,t)}});return a instanceof Response?a:typeof a=="string"?new Response(a,{headers:{"Content-Type":"text/plain"}}):new Response(JSON.stringify(a),{headers:{"Content-Type":"application/json"}})}export{C as handleMcpRequest};
+import{withPathPrefix as g}from"@redocly/theme/core/utils";import{importApiRoutesHandler as D}from"../../../api-routes/import-api-routes-handlers.js";import{enhanceContext as h}from"../../../api-routes/helpers/enhance-context.js";import{telemetry as R}from"../../../telemetry/index.js";import{KvService as A}from"../../../persistence/kv/services/kv-service.js";import{envConfig as l}from"../../../config/env-config.js";import{acceptsHtml as E}from"../../../utils/ai-agent-detection.js";import{handleErrorPageRender as T}from"../../../web-server/utils.js";import{MCP_NOT_ALLOWED_TEMPLATE_ID as _}from"../constants.js";import{MCP_DOCS_SERVER_HANDLER_ID as w}from"../index.js";import{resolvePublicBaseUrl as S}from"../../../web-server/utils/resolve-public-base-url.js";import{applyEdgeRateLimit as q}from"../gateway-mcp/rate-limit/apply-edge-rate-limit.js";async function B(a,t,e){const n=t.req.raw;if(a.requestHandlerId===w&&n.method==="GET"&&E(n.headers.get("accept"))&&e.globalData.mcpData?.docs?.enabled)return T(t,e,{slug:a.slug},405,_);const r=t.get("auth"),s=await q(n,e);if(s)return s;const o=await e.resolveRouteStaticData(a)||{},m=g(a.slug),{requestHandlers:c}=await D(e.serverOutDir),p=c[a.requestHandlerId],d=(await p()).default,u=async()=>await A.getInstance({baseDbDir:e.serverOutDir,sqldRemoteDatabaseUrl:l.SQLD_REMOTE_DATABASE_URL,sqldRemoteDatabaseAuthToken:l.SQLD_REMOTE_DATABASE_AUTH_TOKEN}),f=h({honoCtx:t,ctx:{user:{teams:r.teams,email:r.claims.email,claims:r.claims,idpAccessToken:r.idpAccessToken,idpId:r.claims.idpId,isAuthenticated:r.isAuthenticated},config:e.config,outdir:e.outdir,baseUrl:new URL(t.req.url).origin},telemetry:R,getKv:u}),i=await d(t.req.raw,f,{...o,props:{...o.props,routeSlug:m,outdir:e.outdir,skills:e.config.skills?.hide===!0?[]:e.getSkills(),skillsBaseUrl:S(e,t)}});return i instanceof Response?i:typeof i=="string"?new Response(i,{headers:{"Content-Type":"text/plain"}}):new Response(JSON.stringify(i),{headers:{"Content-Type":"application/json"}})}export{B as handleMcpRequest};

package/dist/server/plugins/mcp/handlers/mcp-credentials-handler.d.ts

@@ -0,0 +1,5 @@
+import type { ApiRoutesHandler } from '@redocly/config';
+export declare function setCredentialsFetchImpl(impl: typeof fetch): void;
+declare const mcpCredentialsHandler: ApiRoutesHandler;
+export default mcpCredentialsHandler;
+//# sourceMappingURL=mcp-credentials-handler.d.ts.map

package/dist/server/plugins/mcp/handlers/mcp-credentials-handler.js

@@ -0,0 +1,101 @@
+import{secretStore as l}from"../gateway-mcp/secret-store.js";import{buildAllowedHostMatchers as C}from"../gateway-mcp/fetch/allowed-hosts.js";import{assertUrlAllowed as P}from"../gateway-mcp/fetch/ssrf-guard.js";import{readCappedBody as I,getDefaultAgent as _}from"../gateway-mcp/fetch/fetch-bridge.js";const m={"Content-Type":"text/html; charset=utf-8","Cache-Control":"no-store","X-Frame-Options":"DENY","Referrer-Policy":"no-referrer","Content-Security-Policy":"default-src 'none'; style-src 'unsafe-inline'; form-action 'self'"},E=3e4,T=64*1024;let v=fetch;function L(e){v=e}const z=async(e,t)=>{const o=await t.getKv();if(e.method==="GET"){const n=new URL(e.url).searchParams.get("token")??"",r=await l.peekElicitation(o,n);return r?new Response(q(r,n),{status:200,headers:m}):u()}if(e.method==="POST"){const n=await e.formData(),r=String(n.get("token")??"");return String(n.get("mode")??"token")==="client-credentials"?F(o,n,r):R(o,n,r)}return new Response("Method Not Allowed",{status:405,headers:{Allow:"GET, POST"}})};async function R(e,t,o){const n=String(t.get("secret")??"");if(!n)return u();const r=await l.consumeElicitation(e,o);return r?(await l.setSecret(e,r.subject,r.api,O(r.auth,n)),new Response(x(r.name),{status:200,headers:m})):u()}async function F(e,t,o){const n=String(t.get("client_id")??"").trim(),r=String(t.get("client_secret")??"").trim();if(!n||!r)return u();const b=await l.peekElicitation(e,o);if(!b||b.auth.kind!=="oauth2ClientCredentials")return u();const a=await l.consumeElicitation(e,o);if(!a||a.auth.kind!=="oauth2ClientCredentials")return u();const f=a.auth;try{const A=C([{url:f.tokenUrl}]),S=P(f.tokenUrl,A),w=new AbortController,$=setTimeout(()=>w.abort(),E);let y;try{y=await v(S,{method:"POST",headers:{"content-type":"application/x-www-form-urlencoded"},body:new URLSearchParams({grant_type:"client_credentials",client_id:n,client_secret:r,...f.scopes.length>0?{scope:f.scopes.join(" ")}:{}}),redirect:"manual",signal:w.signal,dispatcher:_()})}finally{clearTimeout($)}if(!y.ok)return h(a.name);let k;try{k=await I(y,T)}catch{return h(a.name)}let p;try{p=JSON.parse(k)}catch{return h(a.name)}const g=typeof p=="object"&&p!==null&&"access_token"in p?p.access_token:void 0;return typeof g!="string"||!g?h(a.name):(await l.setSecret(e,a.subject,a.api,{header:"Authorization",value:`Bearer ${g}`}),new Response(x(a.name),{status:200,headers:m}))}catch{return h(a.name)}}function O(e,t){return e.kind==="apiKey"?{header:e.header,value:t}:e.kind==="bearer"||e.kind==="oauth2ClientCredentials"?{header:"Authorization",value:B(t)}:{header:"Authorization",value:t}}function B(e){const t=e.trim();return t.toLowerCase().startsWith("bearer")?t:`Bearer ${t}`}function i(e){return e.replaceAll("&","&amp;").replaceAll("<","&lt;").replaceAll(">","&gt;").replaceAll('"',"&quot;")}function s(e){return`<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>API credentials</title>
+<style>
+:root{color-scheme:light dark}
+*{box-sizing:border-box}
+body{font-family:-apple-system,BlinkMacSystemFont,"Segoe UI",Roboto,Helvetica,Arial,sans-serif;margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;background:#f3f4f6;color:#111827;padding:1.5rem}
+.card{width:100%;max-width:26rem;background:#ffffff;border-radius:.75rem;box-shadow:0 10px 25px -5px rgba(0,0,0,.1),0 8px 10px -6px rgba(0,0,0,.1);padding:2rem}
+h1{font-size:1.25rem;margin:0 0 .5rem}
+.section{margin-top:1.5rem;padding-top:1.5rem;border-top:1px solid #e5e7eb}
+.section h2{font-size:1rem;margin:0 0 .5rem}
+p.hint{color:#6b7280;font-size:.875rem;line-height:1.4}
+label{display:block;margin:1rem 0 .25rem;font-weight:600;font-size:.875rem}
+input[type=password],input[type=text]{width:100%;padding:.625rem .75rem;font-size:1rem;border:1px solid #d1d5db;border-radius:.5rem;background:#fff;color:#111827}
+input:focus{outline:none;border-color:#4f46e5;box-shadow:0 0 0 3px rgba(79,70,229,.2)}
+button{margin-top:1.25rem;padding:.625rem 1.5rem;font-size:1rem;font-weight:600;color:#fff;background:#4f46e5;border:none;border-radius:.5rem;cursor:pointer}
+button:hover{background:#4338ca}
+button:focus-visible{outline:2px solid #4f46e5;outline-offset:2px}
+code{background:#f3f4f6;padding:.125rem .375rem;border-radius:.25rem;font-size:.85em}
+footer{margin-top:1.5rem;padding-top:1rem;border-top:1px solid #e5e7eb;font-size:.75rem;color:#9ca3af;text-align:center}
+@media (prefers-color-scheme:dark){
+body{background:#0b0f19;color:#e5e7eb}
+.card{background:#111827;box-shadow:0 10px 25px -5px rgba(0,0,0,.4)}
+.section{border-top-color:#1f2937}
+p.hint{color:#9ca3af}
+input[type=password],input[type=text]{background:#0b0f19;border-color:#374151;color:#e5e7eb}
+code{background:#1f2937}
+footer{border-top-color:#1f2937;color:#6b7280}
+}
+</style>
+</head>
+<body><div class="card">${e}</div></body>
+</html>`}function c(e){return`<h1>\u{1F512} ${i(e)}</h1>`}function d(){return"<footer>Secured by Redocly &middot; credentials never enter the AI conversation</footer>"}function q(e,t){switch(e.auth.kind){case"bearer":return H(e.name,t);case"apiKey":return N(e.name,t,e.auth.header);case"oauth2ClientCredentials":return U(e.name,t,e.auth.scopes);default:return j(e.name,t)}}function H(e,t){return s(`
+${c(`Credentials for ${e}`)}
+<p class="hint">Stored encrypted for you only (24 hours for anonymous callers, 30 days when signed in) and sent to the API as the <code>Authorization</code> header. It never passes through the AI conversation.</p>
+<form method="post" action="/mcp/credentials" autocomplete="off">
+<input type="hidden" name="token" value="${i(t)}">
+<input type="hidden" name="mode" value="token">
+<label for="secret">API token</label>
+<input type="password" id="secret" name="secret" placeholder="your API token" required autofocus>
+<p class="hint">Paste the raw token or one already prefixed with <code>Bearer</code> &mdash; we add the prefix automatically if it is missing.</p>
+<button type="submit">Save credentials</button>
+</form>
+${d()}`)}function N(e,t,o){return s(`
+${c(`Credentials for ${e}`)}
+<p class="hint">Stored encrypted for you only (24 hours for anonymous callers, 30 days when signed in) and sent to the API as the <code>${i(o)}</code> header. It never passes through the AI conversation.</p>
+<form method="post" action="/mcp/credentials" autocomplete="off">
+<input type="hidden" name="token" value="${i(t)}">
+<input type="hidden" name="mode" value="token">
+<label for="secret">${i(o)} value</label>
+<input type="password" id="secret" name="secret" placeholder="value" required autofocus>
+<button type="submit">Save credentials</button>
+</form>
+${d()}`)}function U(e,t,o){const n=o.length>0?o.map(i).join(", "):"default scopes";return s(`
+${c(`Credentials for ${e}`)}
+<p class="hint">Paste a token you already have, or let us exchange client credentials for one via OAuth2 client_credentials.</p>
+<div class="section">
+<h2>I have a token</h2>
+<form method="post" action="/mcp/credentials" autocomplete="off">
+<input type="hidden" name="token" value="${i(t)}">
+<input type="hidden" name="mode" value="token">
+<label for="secret">API token</label>
+<input type="password" id="secret" name="secret" placeholder="your API token" required autofocus>
+<p class="hint">We add <code>Bearer</code> automatically if it is missing.</p>
+<button type="submit">Save token</button>
+</form>
+</div>
+<div class="section">
+<h2>Exchange client credentials</h2>
+<p class="hint">We request a token from the API on your behalf. Scopes: ${n}.</p>
+<form method="post" action="/mcp/credentials" autocomplete="off">
+<input type="hidden" name="token" value="${i(t)}">
+<input type="hidden" name="mode" value="client-credentials">
+<label for="client_id">Client ID</label>
+<input type="text" id="client_id" name="client_id" required>
+<label for="client_secret">Client secret</label>
+<input type="password" id="client_secret" name="client_secret" required>
+<button type="submit">Exchange &amp; save</button>
+</form>
+</div>
+${d()}`)}function j(e,t){return s(`
+${c(`Credentials for ${e}`)}
+<p class="hint">The value is stored encrypted for you only (24 hours for anonymous callers, 30 days when signed in) and is sent to the API as the <code>Authorization</code> header. It never passes through the AI conversation.</p>
+<form method="post" action="/mcp/credentials" autocomplete="off">
+<input type="hidden" name="token" value="${i(t)}">
+<input type="hidden" name="mode" value="token">
+<label for="secret">Authorization header value</label>
+<input type="password" id="secret" name="secret" placeholder="Bearer &lt;your token&gt;" required autofocus>
+<button type="submit">Save credentials</button>
+</form>
+${d()}`)}function x(e){return s(`
+${c("Credentials saved")}
+<p>Credentials for ${i(e)} are set for this session. Return to your AI client and continue - confirm the elicitation prompt if it is still open.</p>
+${d()}`)}function h(e){return new Response(s(`
+${c("Exchange failed")}
+<p>We could not exchange your client credentials for a token for ${i(e)}. This link has been used up - go back to your AI client and request a new link, then try again.</p>
+${d()}`),{status:502,headers:m})}function u(){return new Response(s(`${c("Link expired")}<p>This credentials link is invalid or has expired. Retry the request in your AI client to get a fresh link.</p>${d()}`),{status:404,headers:m})}var W=z;export{W as default,L as setCredentialsFetchImpl};

package/dist/server/plugins/mcp/index.d.ts

@@ -1,5 +1,6 @@
 import type { LifecyclePluginInstance } from '../../types';
 export declare const MCP_DOCS_SERVER_HANDLER_ID = "mcp-docs-server-handler";
+export declare const MCP_CREDENTIALS_HANDLER_ID = "mcp-credentials-handler";
 export declare function mcpServerPlugin(): Promise<LifecyclePluginInstance>;
 export default mcpServerPlugin;
 //# sourceMappingURL=index.d.ts.map

package/dist/server/plugins/mcp/index.js

@@ -1 +1 @@
-import{fileURLToPath as O}from"node:url";import{dirname as T,join as c}from"node:path";import{logger as g}from"../../tools/notifiers/logger.js";import{reporter as A}from"../../tools/notifiers/reporter.js";import{isDefined as R}from"../../../utils/guards/is-defined.js";import{buildGraphqlDescriptions as w,filterIgnoredApiDescriptions as u,getCleanedUpApiDescriptions as L,isMcpInRedirects as q}from"./utils.js";import{isMcpCodeModeEnabled as G}from"./utils/mode.js";import{getDefaultToolSchemas as N}from"./docs-mcp/tool-schemas.js";import{EXECUTE_TOOL_SCHEMA as j}from"./codemode/tools/execute-schema.js";import{isGatewayCapabilityEnabled as U,isGatewayEligible as H}from"./gateway-mcp/eligibility.js";import{telemetryTraceStep as I}from"../../../cli/telemetry/helpers/trace-step.js";import{DEFAULT_DOCS_MCP_SERVER_NAME as F,MCP_NOT_ALLOWED_TEMPLATE_ID as x}from"./constants.js";const h="mcp-docs-server-handler",V="/mcp",p=T(O(import.meta.url));async function B(){let r=!1;return{id:"mcp",async processContent(i,o){r||await I("build.plugin.mcp",async a=>{const s=await i.loadOpenApiDefinitions(o),l=await i.loadGraphqlDefinitions(o),n=await o.getConfig(),{mcp:t,redirects:D}=n;if(a?.setAttribute("config",JSON.stringify(t||{})),!(t?.hide||t?.docs?.hide)&&(q(D)&&await A.panicOnBuildContentError('The reserved route "/mcp" cannot be used in redirect configuration. Please remove any redirects involving "/mcp" from your redocly.yaml config.'),i.createTemplate(x,"@redocly/theme/layouts/McpNotAllowed"),!t?.docs?.hide)){g.info("Configuring MCP servers...");const C=c(p,"./handlers/docs-mcp-handler.js"),E=L(u(s,t?.docs?.ignore||[])),M=!!n?.access?.requiresLogin,d=n?.access?.rbac||{},v=U(t),m=new Map;for(const e of E){const b=e.definition.info?.title||"",S=e.definition.info?.version||"";m.set(e.relativePath,{name:b,description:e.definition.info?.description||"",version:S,servers:e.definition.servers||[],relativePath:e.relativePath,...v&&H(e.definition.info,e.relativePath,d)?{fetchEligible:!0}:{}})}const f=w(u(l,t?.docs?.ignore||[])),y=Object.values(n.products||{}).map(e=>e?.name).filter(R),P=n.l10n?.locales?.map(e=>e.code)??o.fs.localeFolders,_=N({products:y,locales:P,requiresLogin:M,rbac:d,hasGraphqlApis:f.length>0});i.addMcpTools(c(p,"./docs-mcp/tools/index.js"),_),G()&&i.addMcpTools(c(p,"./codemode/tools/execute.js"),[j]),await J({actions:i,handlerPath:C,apiDescriptionsMap:Object.fromEntries(m),graphqlDescriptions:f,mcpConfig:t}),r=!0}})},async afterRoutesCreated(i,o){const a=await o.getConfig(),{mcp:s}=a;i.setGlobalData({mcpData:{docs:{enabled:!s?.hide&&!s?.docs?.hide,name:s?.docs?.name}}})}}}var te=B;async function J({actions:r,handlerPath:i,apiDescriptionsMap:o,graphqlDescriptions:a,mcpConfig:s}){r.createRequestHandler(h,i),r.addApiRoute({slug:V,requestHandlerId:h,httpMethod:"all",getStaticData:async()=>({props:{config:{apiDescriptionsMap:o,graphqlDescriptions:a,mcpDocsServerName:s?.docs?.name||F},serverOutDir:r.serverOutDir,tools:r.getMcpTools().map(({importPath:l,...n})=>n)}})}),g.info("Registered Docs MCP Server endpoint at /mcp")}export{h as MCP_DOCS_SERVER_HANDLER_ID,te as default,B as mcpServerPlugin};
+import{fileURLToPath as w}from"node:url";import{dirname as q,join as p}from"node:path";import{logger as f}from"../../tools/notifiers/logger.js";import{reporter as G}from"../../tools/notifiers/reporter.js";import{isDefined as N}from"../../../utils/guards/is-defined.js";import{bundledOpenApiDocumentsToMcpOpenApi as H,bundledGraphqlDocumentsToMcpOpenApi as I,buildGraphqlDescriptions as U,filterIgnoredApiDescriptions as M,getCleanedUpApiDescriptions as j,isMcpInRedirects as x}from"./utils.js";import{getMcpMode as F,isMcpElicitationEnabled as B}from"./utils/mode.js";import{getDefaultToolSchemas as V}from"./docs-mcp/tool-schemas.js";import{EXECUTE_TOOL_SCHEMA as J}from"./codemode/tools/execute-schema.js";import{isGatewayCapabilityEnabled as W,isGatewayEligible as X}from"./gateway-mcp/eligibility.js";import{resolveGatewayFetchLimits as k}from"./gateway-mcp/rate-limit/limits.js";import{telemetryTraceStep as z}from"../../../cli/telemetry/helpers/trace-step.js";import{DEFAULT_DOCS_MCP_SERVER_NAME as C,MCP_NOT_ALLOWED_TEMPLATE_ID as K}from"./constants.js";const P="mcp-docs-server-handler",Q="/mcp",_="mcp-credentials-handler",Y="/mcp/credentials",d=q(w(import.meta.url));async function Z(){let i=!1;return{id:"mcp",async processContent(t,r){i||await z("com.redocly.build.plugin.mcp",async c=>{const s=H(await t.loadApiDocuments(r)),l=I(await t.loadApiDocuments(r)),n=await r.getConfig(),{mcp:o,redirects:a}=n;if(c?.setAttribute("config",JSON.stringify(o||{})),!(o?.hide||o?.docs?.hide)&&(x(a)&&await G.panicOnBuildContentError('The reserved route "/mcp" cannot be used in redirect configuration. Please remove any redirects involving "/mcp" from your redocly.yaml config.'),t.createTemplate(K,"@redocly/theme/layouts/McpNotAllowed"),!o?.docs?.hide)){f.info("Configuring MCP servers...");const m=p(d,"./handlers/docs-mcp-handler.js"),y=j(M(s,o?.docs?.ignore||[])),v=!!n?.access?.requiresLogin,u=n?.access?.rbac||{},A=W(o),g=new Map;for(const e of y){const O=e.definition.info?.title||"",L=e.definition.info?.version||"";g.set(e.relativePath,{name:O,description:typeof e.definition.info?.description=="string"?e.definition.info.description:"",version:L,servers:e.definition.servers||[],relativePath:e.relativePath,...A&&X(e.definition.info,e.relativePath,u)?{fetchEligible:!0}:{}})}const h=U(M(l,o?.docs?.ignore||[])),b=Object.values(n.products||{}).map(e=>e?.name).filter(N),R=n.l10n?.locales?.map(e=>e.code)??r.fs.localeFolders,D=F(),E=B(),{budgetPerExec:S}=k(),T=V({products:b,locales:R,requiresLogin:v,rbac:u,hasGraphqlApis:h.length>0,elicitationEnabled:E});t.addMcpTools(p(d,"./docs-mcp/tools/index.js"),T),D==="code"&&t.addMcpTools(p(d,"./codemode/tools/execute.js"),[J]),await $({actions:t,handlerPath:m,apiDescriptionsMap:Object.fromEntries(g),graphqlDescriptions:h,mcpConfig:o,mcpMode:D,elicitationEnabled:E,gatewayFetchBudgetPerExec:S}),i=!0}})},async afterRoutesCreated(t,r){const c=await r.getConfig(),{mcp:s}=c;t.setGlobalData({mcpData:{docs:{enabled:!s?.hide&&!s?.docs?.hide,name:s?.docs?.name||C}}})}}}var fe=Z;async function $({actions:i,handlerPath:t,apiDescriptionsMap:r,graphqlDescriptions:c,mcpConfig:s,mcpMode:l,elicitationEnabled:n,gatewayFetchBudgetPerExec:o}){if(i.createRequestHandler(P,t),i.addApiRoute({slug:Q,requestHandlerId:P,httpMethod:"all",getStaticData:async()=>({props:{config:{apiDescriptionsMap:r,graphqlDescriptions:c,mcpDocsServerName:s?.docs?.name||C,mcpMode:l,elicitationEnabled:n,gatewayFetchBudgetPerExec:o},serverOutDir:i.serverOutDir,tools:i.getMcpTools().map(({importPath:a,...m})=>m)}})}),f.info("Registered Docs MCP Server endpoint at /mcp"),n){const a=p(d,"./handlers/mcp-credentials-handler.js");i.createRequestHandler(_,a),i.addApiRoute({slug:Y,requestHandlerId:_,httpMethod:"all",getStaticData:async()=>({props:{}})}),f.info("Registered MCP credentials endpoint at /mcp/credentials")}}export{_ as MCP_CREDENTIALS_HANDLER_ID,P as MCP_DOCS_SERVER_HANDLER_ID,fe as default,Z as mcpServerPlugin};

package/dist/server/plugins/mcp/servers/docs-server.d.ts

@@ -1,10 +1,12 @@
 import type { McpToolSchema } from '../../../types';
 import type { McpToolContext, SkillMcpResource } from '../types.js';
+import type { KvService } from '@redocly/config';
 import { type McpServerInstance } from './mcp-server.js';
-export declare function createDocsMcpServer({ name, tools, context, skills }: {
+export declare function createDocsMcpServer({ name, tools, context, skills, getKv, }: {
     name: string;
     tools: McpToolSchema[];
     context: McpToolContext;
     skills?: SkillMcpResource[];
+    getKv: () => Promise<KvService>;
 }): Promise<McpServerInstance>;
 //# sourceMappingURL=docs-server.d.ts.map

package/dist/server/plugins/mcp/servers/docs-server.js

@@ -1 +1 @@
-import{logger as O}from"../../../tools/notifiers/logger.js";import{mcpToolWorkers as _,MCP_TOOL_IS_AVAILABLE_KEY as u}from"../../../workers/mcp-tool-worker-pool.js";import{EXECUTE_TOOL_SCHEMA as C}from"../codemode/tools/execute-schema.js";import{EXECUTE_TOOL_NAME as p,DESCRIBE_TOOLS_TOOL_NAME as M,CODE_MODE_TOOL_NAMES as b,FETCH_TOOL_NAME as S}from"../codemode/constants.js";import{buildCodeModeInstructions as A,buildExecuteDescription as h,DESCRIBE_TOOLS_DESCRIPTION as x}from"../codemode/prompts.js";import{composeExecuteAnnotations as L,getActiveCapabilities as D}from"../codemode/capabilities/index.js";import{describeToolsSchema as v,describeTools as y}from"../codemode/tools/describe-tools.js";import{isMcpCodeModeEnabled as g}from"../utils/mode.js";import{connectMcpServer as I,createMcpServer as k,createToolDispatch as w,extractSerializableContext as N}from"./mcp-server.js";async function K({name:E,tools:a,context:i,skills:d=[]}){const n=g(),r=n?D(i):[],s=r.some(e=>e.id===S),{server:o,transport:f}=k(E,n?A(s):void 0),c=N(i),m=w(c),l=async e=>{try{return await _.exec(u,[{toolName:e,context:c}],{timeout:1e4})}catch(t){return O.error(`Failed to check MCP tool availability for "${e}": ${t instanceof Error?t.message:String(t)}`),!1}};if(n){const e=a.filter(t=>!b.has(t.name));o.tool(p,h(s),C.schema,L(r),m(p)),o.tool(M,x,v(e,r),y(e,l,r,i))}else await Promise.all(a.map(async e=>{const t=e.annotations||{title:e.name},T=o.tool(e.name,e.description,e.schema,t,m(e.name));await l(e.name)||T.disable()}));for(const e of d)o.registerResource(e.slug,e.uri,{title:e.name,description:e.description,mimeType:"text/markdown"},async()=>({contents:[{uri:e.uri,mimeType:"text/markdown",text:e.content}]}));return I(o,f)}export{K as createDocsMcpServer};
+import{fromJsonSchema as _}from"@modelcontextprotocol/server";import{logger as h}from"../../../tools/notifiers/logger.js";import{mcpToolWorkers as C,MCP_TOOL_IS_AVAILABLE_KEY as b}from"../../../workers/mcp-tool-worker-pool.js";import{CREATE_ANONYMOUS_SESSION_TOOL_NAME as A}from"../constants.js";import{isAnonymousSessionToolAvailable as T}from"../docs-mcp/tools/core/create-anonymous-session.js";import{EXECUTE_TOOL_SCHEMA as M}from"../codemode/tools/execute-schema.js";import{EXECUTE_TOOL_NAME as S,DESCRIBE_TOOLS_TOOL_NAME as g,CODE_MODE_TOOL_NAMES as L,FETCH_TOOL_NAME as v}from"../codemode/constants.js";import{buildCodeModeInstructions as y,buildExecuteDescription as D,DESCRIBE_TOOLS_DESCRIPTION as I}from"../codemode/prompts.js";import{composeExecuteAnnotations as x,getActiveCapabilities as N}from"../codemode/capabilities/index.js";import{describeToolsSchema as k,describeTools as w}from"../codemode/tools/describe-tools.js";import{mcpJsonSchemaValidator as R}from"../utils/json-schema-validator.js";import{connectMcpServer as F,createMcpServer as H,createToolDispatch as P,extractSerializableContext as B}from"./mcp-server.js";function U(a){const o=M.schema;if(T(a))return o;const{sessionHandle:t,...c}=o.properties;return{...o,properties:c}}async function Z({name:a,tools:o,context:t,skills:c=[],getKv:u}){const m=t.mcpMode==="code",n=m?N(t):[],d=n.some(e=>e.id===v),{server:r,transport:O}=H(a,m?y(d):void 0),s=e=>_(e,R),E=B(t),p=P(E,{getClientCapabilities:()=>r.server.getClientCapabilities(),getKv:u}),f=async e=>{try{return await C.exec(b,[{toolName:e,context:E}],{timeout:1e4})}catch(i){return h.error(`Failed to check MCP tool availability for "${e}": ${i instanceof Error?i.message:String(i)}`),!1}};if(m){const e=o.filter(l=>!L.has(l.name));r.registerTool(S,{description:D(d),inputSchema:s(U(t)),annotations:x(n)},p(S)),r.registerTool(g,{description:I,inputSchema:s(k(e,n))},w(e,f,n,t));const i=o.find(l=>l.name===A);i&&T(t)&&r.registerTool(i.name,{description:i.description,inputSchema:s(i.schema),annotations:i.annotations??{title:i.name}},p(i.name))}else await Promise.all(o.map(async e=>{const i=r.registerTool(e.name,{description:e.description,inputSchema:s(e.schema),annotations:e.annotations||{title:e.name}},p(e.name));await f(e.name)||i.disable()}));for(const e of c)r.registerResource(e.slug,e.uri,{title:e.name,description:e.description,mimeType:"text/markdown"},async()=>({contents:[{uri:e.uri,mimeType:"text/markdown",text:e.content}]}));return F(r,O)}export{Z as createDocsMcpServer};

package/dist/server/plugins/mcp/servers/mcp-server.d.ts

@@ -1,18 +1,25 @@
-import { McpServer } from '@redocly/mcp-typescript-sdk/server/mcp.js';
-import { StreamableHTTPServerTransport } from '@redocly/mcp-typescript-sdk/server/streamableHttp.js';
-import type { ToolCallback } from '@redocly/mcp-typescript-sdk/server/mcp.js';
-import type { McpToolContext } from '../types.js';
+import { McpServer, WebStandardStreamableHTTPServerTransport } from '@modelcontextprotocol/server';
+import type { McpToolCallback, McpToolContext } from '../types.js';
+import type { KvService } from '@redocly/config';
 export type McpServerInstance = {
     server: McpServer;
-    transport: StreamableHTTPServerTransport;
+    transport: WebStandardStreamableHTTPServerTransport;
     cleanup: () => Promise<void>;
 };
 export declare function createMcpServer(name: string, instructions?: string): {
     server: McpServer;
-    transport: StreamableHTTPServerTransport;
+    transport: WebStandardStreamableHTTPServerTransport;
+};
+export declare function connectMcpServer(server: McpServer, transport: WebStandardStreamableHTTPServerTransport): Promise<McpServerInstance>;
+export type ToolDispatchDeps = {
+    getClientCapabilities: () => {
+        elicitation?: {
+            url?: unknown;
+        };
+    } | undefined;
+    getKv: () => Promise<KvService>;
 };
-export declare function connectMcpServer(server: McpServer, transport: StreamableHTTPServerTransport): Promise<McpServerInstance>;
 /** Build the tool callback that ships a tool call to the worker pool. */
-export declare function createToolDispatch(serializableContext: McpToolContext): (toolName: string) => ToolCallback<Record<string, unknown>>;
+export declare function createToolDispatch(serializableContext: McpToolContext, deps?: ToolDispatchDeps): (toolName: string) => McpToolCallback;
 export declare function extractSerializableContext(context: McpToolContext): McpToolContext;
 //# sourceMappingURL=mcp-server.d.ts.map

package/dist/server/plugins/mcp/servers/mcp-server.js

@@ -1 +1 @@
-import{McpServer as i}from"@redocly/mcp-typescript-sdk/server/mcp.js";import{StreamableHTTPServerTransport as t}from"@redocly/mcp-typescript-sdk/server/streamableHttp.js";import{logger as n}from"../../../tools/notifiers/logger.js";import{mcpToolWorkers as c,MCP_TOOL_WORKER_KEY as u}from"../../../workers/mcp-tool-worker-pool.js";const p=6e4;function T(e,r){const o=new i({name:e,version:new Date().toISOString().slice(0,10)},{capabilities:{logging:{}},...r?{instructions:r}:{}}),a=new t({sessionIdGenerator:void 0});return{server:o,transport:a}}async function g(e,r){return await e.connect(r),{server:e,transport:r,cleanup:async()=>{r.close()}}}function S(e){return r=>async(o,a)=>{n.info(`MCP tool called: ${r}`);const s={toolName:r,args:o,context:e,extra:l(a)};return await c.exec(u,[s],{timeout:p})}}function l(e){return{sessionId:e.sessionId,authInfo:e.authInfo,requestId:e.requestId,requestInfo:e.requestInfo,_meta:e._meta}}function q(e){return{user:e.user,config:e.config,outdir:e.outdir,baseUrl:e.baseUrl,params:e.params,query:e.query,cookies:e.cookies,apiDescriptionsMap:e.apiDescriptionsMap,graphqlDescriptions:e.graphqlDescriptions,products:e.products,accessToken:e.accessToken,metadata:e.metadata,upstreamAuthorization:e.upstreamAuthorization}}export{g as connectMcpServer,T as createMcpServer,S as createToolDispatch,q as extractSerializableContext};
+import{McpServer as b,WebStandardStreamableHTTPServerTransport as M}from"@modelcontextprotocol/server";import{logger as S}from"../../../tools/notifiers/logger.js";import{mcpToolWorkers as y,MCP_TOOL_WORKER_KEY as k}from"../../../workers/mcp-tool-worker-pool.js";import{SSE_KEEPALIVE_INTERVAL_MS as I}from"../constants.js";import{secretStore as q}from"../gateway-mcp/secret-store.js";import{readAuthRequiredMeta as v,stripAuthRequiredMeta as g}from"../gateway-mcp/upstream-auth.js";import{buildUpstreamCredentialFallback as E,buildUpstreamCredentialInputRequired as T,isCredentialElicitationDeclined as R}from"../gateway-mcp/elicitation.js";import{resolveUpstreamAuthScheme as w}from"../gateway-mcp/upstream-auth-scheme.js";import{MISSING_SESSION_HANDLE_MESSAGE as _,resolveSecretSubject as U}from"../gateway-mcp/subject.js";const A=6e4,m=new Map;function D(e,t){const r=m.get(e);if(r)return r;const n=t().finally(()=>{m.delete(e)});return m.set(e,n),n}function V(e,t){const r=new b({name:e,version:new Date().toISOString().slice(0,10)},{capabilities:{logging:{}},...t?{instructions:t}:{}}),n=new M({keepAliveMs:I,sessionIdGenerator:void 0});return{server:r,transport:n}}async function Y(e,t){return await e.connect(t),{server:e,transport:t,cleanup:async()=>{t.close()}}}function J(e,t){return r=>async(n,i)=>{S.info(`MCP tool called: ${r}`);const o=e.elicitationEnabled??!1,d=i.mcpReq.envelope!==void 0,s=o?U(e.user,n.sessionHandle):{kind:"anonymous"},u=s.kind==="resolved"?s.subject:void 0;if(s.kind==="invalid")return{content:[{type:"text",text:s.message}],isError:!0};const h=async()=>{if(!(!o||!u||!t?.getKv))try{const a=await t.getKv();return await q.getSecretsForSubject(a,u)}catch(a){S.warn(`gateway mcp secret store error, continuing unauthenticated: ${String(a)}`);return}},f=async()=>{const a=await h(),p={toolName:r,args:n,context:{...e,upstreamSecrets:a},extra:P(i)};return await y.exec(k,[p],{timeout:A})};let c=await f();const l=v(c);if(l.length>0&&o&&!u)return g({...c,content:[{type:"text",text:_}],isError:!0});if(l.length>0&&o&&u&&t?.getKv){const a=await t.getKv(),p=d?await K(e,i,l,u,a,t):await L(e,l,u,a);switch(p.kind){case"inputRequired":return p.result;case"retry":c=await f();break;case"appendText":c={...c,content:[...c.content,{type:"text",text:p.text}]};break;case"none":break}}return g(c)}}function O(e){return!!e?.getClientCapabilities()?.elicitation?.url}async function K(e,t,r,n,i,o){if(R(t.mcpReq.inputResponses))return{kind:"none"};const d=e.baseUrl??"",s=await w(e,r[0].api);return O(o)?{kind:"inputRequired",result:await T({subject:n,baseUrl:d,events:r,auth:s,kv:i})}:{kind:"appendText",text:await E({subject:n,baseUrl:d,events:r,auth:s,kv:i})}}async function L(e,t,r,n){const i=await w(e,t[0].api);return{kind:"appendText",text:await D(`${r}:${t[0].api}`,()=>E({subject:r,baseUrl:e.baseUrl??"",events:t,auth:i,kv:n}))}}function P(e){return{sessionId:e.sessionId,authInfo:e.http?.authInfo,requestId:e.mcpReq.id,_meta:e.mcpReq._meta}}function Q(e){return{user:e.user,config:e.config,outdir:e.outdir,baseUrl:e.baseUrl,params:e.params,query:e.query,cookies:e.cookies,apiDescriptionsMap:e.apiDescriptionsMap,graphqlDescriptions:e.graphqlDescriptions,products:e.products,accessToken:e.accessToken,metadata:e.metadata,upstreamAuthorization:e.upstreamAuthorization,mcpMode:e.mcpMode,elicitationEnabled:e.elicitationEnabled,gatewayFetchBudgetPerExec:e.gatewayFetchBudgetPerExec,clientIp:e.clientIp,upstreamSecrets:e.upstreamSecrets}}export{Y as connectMcpServer,V as createMcpServer,J as createToolDispatch,Q as extractSerializableContext};