@redocly/realm 0.138.0-next.15 → 0.138.0-next.17

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

@@ -0,0 +1,25 @@
+import type { McpErrorCodeTypes, McpMode } from '../types.js';
+export type McpErrorData = {
+    readonly code: McpErrorCodeTypes;
+    readonly message: string;
+    readonly data?: unknown;
+    readonly requestId?: string | number | null;
+};
+export declare class McpError extends Error {
+    readonly code: McpErrorCodeTypes;
+    readonly data?: unknown;
+    readonly requestId?: string | number | null;
+    constructor(code: McpErrorCodeTypes, message: string, data?: unknown, requestId?: string | number | null);
+    createErrorResponse(): Response;
+}
+export declare class McpClientInputError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export declare function createMethodNotAllowedError(requestId?: string | number | null): Response;
+export declare function createInternalServerError(error: Error | string, requestId?: string | number | null): 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>, mode?: McpMode): Promise<T | Response>;
+//# sourceMappingURL=errors.d.ts.map

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

@@ -0,0 +1 @@
+import{telemetry as c}from"../../../telemetry/index.js";import{McpErrorCodes as o,McpServerType as i}from"../constants.js";import{serverAttributes as d}from"../utils/telemetry-attributes.js";class s extends Error{code;data;requestId;constructor(e,t,n,a){super(t),this.name="McpError",this.code=e,this.data=n,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=p(this.code);return new Response(JSON.stringify(e),{status:t,headers:{"Content-Type":"application/json"}})}}class u extends Error{constructor(e,t){super(e,t),this.name="McpClientInputError"}}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 I(r){return new s(o.ServerError,"Method not allowed",void 0,r).createErrorResponse()}function l(r,e){const t=r instanceof Error?r.message:String(r);return new s(o.InternalError,"Internal server error mcp",t,e).createErrorResponse()}function f(r="Invalid request",e){return new s(o.InvalidRequest,r,void 0,e).createErrorResponse()}function v(r="Invalid parameters",e){return new s(o.InvalidParams,r,void 0,e).createErrorResponse()}async function M(r,e="tools"){try{return await r()}catch(t){return c.sendMcpErrorMessage([{...d(i.Docs),message:t?.message||"",stack:t?.stack||"",error_class:t instanceof u?"client_error":"server_error",mode:e}]),l(t)}}export{u as McpClientInputError,s as McpError,l as createInternalServerError,v as createInvalidParamsError,f as createInvalidRequestError,I as createMethodNotAllowedError,M as withErrorHandling};

package/dist/server/plugins/mcp/handlers/handle-mcp-request.d.ts

@@ -0,0 +1,5 @@
+import type { Context } from 'hono';
+import type { ApiRoute } from '../../../types';
+import type { Store } from '../../../store.js';
+export declare function handleMcpRequest(route: ApiRoute, ctx: Context, store: Store): Promise<Response>;
+//# sourceMappingURL=handle-mcp-request.d.ts.map

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

@@ -0,0 +1 @@
+import{withPathPrefix as g}from"@redocly/theme/core/utils";import{importApiRoutesHandler as h}from"../../../api-routes/import-api-routes-handlers.js";import{enhanceContext as D}from"../../../api-routes/helpers/enhance-context.js";import{telemetry as A}from"../../../telemetry/index.js";import{KvService as E}from"../../../persistence/kv/services/kv-service.js";import{envConfig as l}from"../../../config/env-config.js";import{acceptsHtml as R}from"../../../utils/ai-agent-detection.js";import{handleErrorPageRender as T}from"../../../web-server/utils.js";import{MCP_DOCS_SERVER_HANDLER_ID as _,MCP_NOT_ALLOWED_TEMPLATE_ID as w}from"../../../constants/mcp.js";import{resolvePublicBaseUrl as S}from"../../../web-server/utils/resolve-public-base-url.js";import{getForwardedOrigin as q}from"../../../web-server/utils/get-request-origin.js";import{applyEdgeRateLimit as C}from"../gateway-mcp/rate-limit/request-limiter/apply-edge-rate-limit.js";import{fetchCountSecret as O}from"../gateway-mcp/rate-limit/fetch-limiter/fetch-count-secret.js";async function G(a,t,e){const n=t.req.raw;if(a.requestHandlerId===_&&n.method==="GET"&&R(n.headers.get("accept"))&&e.globalData.mcpData?.docs?.enabled)return T(t,e,{slug:a.slug},405,w);const r=t.get("auth"),o=await C(n,e);if(o)return o;const s=await e.resolveRouteStaticData(a)||{},m=g(a.slug),{requestHandlers:c}=await h(e.serverOutDir),p=c[a.requestHandlerId],d=(await p()).default,u=async()=>await E.getInstance({baseDbDir:e.serverOutDir,sqldRemoteDatabaseUrl:l.SQLD_REMOTE_DATABASE_URL,sqldRemoteDatabaseAuthToken:l.SQLD_REMOTE_DATABASE_AUTH_TOKEN}),f=D({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:q(t.req.raw)},telemetry:A,getKv:u}),i=await d(t.req.raw,f,{...s,props:{...s.props,routeSlug:m,outdir:e.outdir,fetchCountSecret:O(),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{G as handleMcpRequest};

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

@@ -0,0 +1,4 @@
+import type { ApiRoutesHandler } from '@redocly/config';
+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 @@
+import{secretStore as d}from"../gateway-mcp/secret-store.js";import{rejectCredential as _}from"../gateway-mcp/credential-validation.js";import{buildAllowedHostMatchers as C}from"../gateway-mcp/fetch/allowed-hosts.js";import{assertUrlAllowed as A}from"../gateway-mcp/fetch/ssrf-guard.js";import{readCappedBody as T,getDefaultAgent as P}from"../gateway-mcp/fetch/fetch-bridge.js";import{logger as x}from"../../../tools/notifiers/logger.js";import{FORM_ACTIONS as k}from"./credentials-page/constants.js";import{credentialSchemesOf as w,schemeFieldName as f}from"./credentials-page/form-contract.js";import{formPage as N}from"./credentials-page/form-page.js";import{htmlDocument as O}from"./credentials-page/layout.js";import{declinedPage as R,expiredPage as I,outcomePage as j}from"./credentials-page/outcome-pages.js";const D={"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'; img-src 'self'; form-action 'self'; frame-ancestors 'none'; base-uri 'none'"},$=3e4,F=64*1024,M=/^bearer\s+/i,U=/^\d+$/,B=async(e,t,o)=>{const n=await t.getKv(),r=L(e,t.baseUrl,o);if(e.method==="GET"){const i=new URL(e.url).searchParams.get("token")??"",c=await d.peekElicitation(n,i);return c?S({kv:n,site:r,token:i,target:c},{},200):p(r)}if(e.method==="POST"){const i=await e.formData(),c=u(i,"token"),a=await d.peekElicitation(n,c);if(!a)return p(r);const s={kv:n,site:r,token:c,target:a,form:i};switch(u(i,"action")){case k.remove:return b(s,z(a,u(i,"scheme")));case k.removeAll:return b(s,w(a));case k.decline:return K(s);default:return H(s)}}return new Response("Method Not Allowed",{status:405,headers:{Allow:"GET, POST"}})};async function H(e){const{target:t,form:o}=e,n=w(t),r=n.map((s,l)=>u(o,f("client_id",l)).trim()),i=s=>S(e,{error:s,clientIds:r},400),c=X(n,o);if("error"in c)return i(c.error);if(c.writes.length===0)return i(G(n));const a=[];for(const s of c.writes){if(s.kind!=="exchange"){a.push(s);continue}const l=await J(s.auth,s.clientId,s.clientSecret);if(!l.ok)return x.warn(`gateway oauth2 client_credentials exchange failed for ${t.api}: ${l.reason}`),i(E(n,s.schemeIndex,"client_id","We could not exchange those client credentials for a token. Check the client ID and secret, then try again."));a.push({kind:"set",scheme:s.scheme,secret:l.secret})}return v(e,a)}function X(e,t){const o=[];for(const[n,r]of e.entries()){const i=u(t,f("secret",n)).trim();if(i){const s=_(r.auth,i);if(s)return{error:E(e,n,"secret",s)};o.push({kind:"set",scheme:r.name,secret:W(r.auth,i)});continue}if(r.auth.kind!=="oauth2ClientCredentials")continue;const c=u(t,f("client_id",n)).trim(),a=u(t,f("client_secret",n)).trim();if(c&&a)o.push({kind:"exchange",scheme:r.name,schemeIndex:n,auth:r.auth,clientId:c,clientSecret:a});else if(c||a)return{error:E(e,n,c?"client_secret":"client_id","Enter both the client ID and the client secret, or leave both blank.")}}return{writes:o}}function G(e){return e.length>1?{message:"Fill in at least one credential before saving."}:{message:e[0].auth.kind==="oauth2ClientCredentials"?"Enter an access token, or the client ID and the client secret, before saving.":"Enter a value before saving.",schemeIndex:0,field:"secret"}}function E(e,t,o,n){return{message:e.length>1?`${e[t].name}: ${n}`:n,schemeIndex:t,field:o}}async function b(e,t){const{kv:o,target:n}=e,r=await d.getStoredSchemes(o,n.subject,n.api),i=t.filter(c=>r[c.name]).map(c=>({kind:"remove",scheme:c.name}));return i.length===0?S(e,{error:{message:"No credential is stored there, so there is nothing to remove."}},400):v(e,i)}function z(e,t){const o=U.test(t)?w(e)[Number(t)]:void 0;return o?[o]:[]}async function K({kv:e,site:t,token:o}){return await d.consumeElicitation(e,o)?h(t,R(),200):p(t)}async function v({kv:e,site:t,token:o},n){const r=await d.consumeElicitation(e,o);if(!r)return p(t);for(const a of n)a.kind==="remove"?await d.deleteSecret(e,r.subject,r.api,a.scheme):await d.setSecret(e,r.subject,r.api,a.scheme,a.secret);const i=await d.getStoredSchemes(e,r.subject,r.api),c={action:n.some(a=>a.kind==="set")?"saved":"removed",schemes:n.map(a=>a.scheme),stored:Object.keys(i).sort()};return h(t,j(r,c),200)}async function S({kv:e,site:t,token:o,target:n},r,i){const c=await d.getStoredSchemes(e,n.subject,n.api);return h(t,N({site:t,target:n,token:o,stored:c,...r}),i)}function L(e,t,o){const n=o?.props?.branding??{},r=t&&URL.canParse(t)?t:e.url;return{...n,host:new URL(r).host}}async function J(e,t,o){try{const n=C([{url:e.tokenUrl}]),r=A(e.tokenUrl,n),i=new AbortController,c=setTimeout(()=>i.abort(),$);let a;try{a=await fetch(r,{method:"POST",headers:{"content-type":"application/x-www-form-urlencoded"},body:new URLSearchParams({grant_type:"client_credentials",client_id:t,client_secret:o}),redirect:"manual",signal:i.signal,dispatcher:P()})}finally{clearTimeout(c)}if(!a.ok)return m(`token endpoint returned ${a.status}`);let s;try{s=await T(a,F)}catch{return m("token response exceeded the size cap")}let l;try{l=JSON.parse(s)}catch{return m("token response was not valid JSON")}const y=typeof l=="object"&&l!==null&&"access_token"in l?l.access_token:void 0,g=typeof y=="string"?y.trim():"";return g?_(e,g)?m("token response had an access_token that cannot be sent in a header"):{ok:!0,secret:{header:"Authorization",value:`Bearer ${g}`}}:m("token response had no access_token")}catch(n){return m(n instanceof Error?n.message:String(n))}}function m(e){return{ok:!1,reason:e}}function u(e,t){const o=e.get(t);return typeof o=="string"?o:""}function h(e,t,o){return new Response(O(t,e.colorScheme),{status:o,headers:D})}function p(e){return h(e,I(),404)}function W(e,t){return e.kind==="apiKey"?{header:e.header,value:t}:e.kind==="cookie"?{header:"Cookie",value:`${e.name}=${t}`}:e.kind==="bearer"||e.kind==="oauth2ClientCredentials"?{header:"Authorization",value:Y(t)}:{header:"Authorization",value:t}}function Y(e){return`Bearer ${e.replace(M,"")}`}var ie=B;export{ie as default};

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

@@ -0,0 +1,4 @@
+import type { LifecyclePluginInstance } from '../../types';
+export declare function mcpServerPlugin(): Promise<LifecyclePluginInstance>;
+export default mcpServerPlugin;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+import{fileURLToPath as U}from"node:url";import{dirname as $,join as D}from"node:path";import{MCP_ROUTE as k,PUBLIC_MCP_ROUTE as M}from"@redocly/theme/core/constants/mcp";import{logger as p}from"../../tools/notifiers/logger.js";import{reporter as F}from"../../tools/notifiers/reporter.js";import{isDefined as B}from"../../../utils/guards/is-defined.js";import{MCP_CREDENTIALS_HANDLER_ID as A,MCP_CREDENTIALS_ROUTE as V,MCP_DOCS_SERVER_HANDLER_ID as T,MCP_NOT_ALLOWED_TEMPLATE_ID as x}from"../../constants/mcp.js";import{bundledOpenApiDocumentsToMcpOpenApi as J,bundledGraphqlDocumentsToMcpOpenApi as W,buildGraphqlDescriptions as X,collectIgnoredRoutes as z,filterIgnoredApiDescriptions as P,getCleanedUpApiDescriptions as K,isMcpInRedirects as Q}from"./utils.js";import{getMcpMode as R,isMcpElicitationEnabled as Y,isMcpGatewayEnabled as Z}from"./utils/mode.js";import{getPublicMcpEndpointStatus as _}from"./utils/public-endpoint.js";import{findGatedToolNames as ee}from"./utils/find-gated-tool-names.js";import{getDefaultToolSchemas as oe}from"./docs-mcp/tool-schemas.js";import{EXECUTE_TOOL_SCHEMA as te}from"./codemode/tools/execute-schema.js";import{isGatewayCapabilityEnabled as ie,isGatewayEligible as re}from"./gateway-mcp/eligibility.js";import{resolveGatewayFetchLimits as se}from"./gateway-mcp/rate-limit/fetch-limiter/fetch-limits.js";import{resetCustomMcpTools as ne,scanCustomMcpTools as ae}from"./custom-tools/scan-custom-tools.js";import{resolveSiteBranding as ce}from"./handlers/credentials-page/site-branding.js";import{telemetryTraceStep as pe}from"../../../cli/telemetry/helpers/trace-step.js";import{DEFAULT_DOCS_MCP_SERVER_NAME as S}from"./constants.js";const b=$(U(import.meta.url));async function de(){let i;const m={registeredToolNames:[],warnedNoOutputSchemaTools:new Set};let u=0,f=!1;return{id:"mcp",async processContent(e,a){await pe("com.redocly.build.plugin.mcp",async s=>{const t=await a.getConfig(),{mcp:r,redirects:g}=t;if(s?.setAttribute("config",JSON.stringify(r||{})),s?.setAttribute("mcpMode",R()),s?.setAttribute("mcpGateway",String(Z())),r?.hide||r?.docs?.hide){ne(e,m);return}Q(g)&&await F.panicOnBuildContentError('The reserved route "/mcp" cannot be used in redirect configuration. Please remove any redirects involving "/mcp" from your redocly.yaml config.'),e.createTemplate(x,"@redocly/theme/layouts/McpNotAllowed");const l=!!t?.access?.requiresLogin,C=t?.access?.rbac||{},d=R(),c=Y(),{budgetPerExec:h}=se();if(!i){p.info("Configuring MCP servers...");const w=J(await e.loadApiDocuments(a)),O=W(await e.loadApiDocuments(a)),v=r?.docs?.ignore||[],L=K(P(w,v)),q=ie(r),E=new Map;for(const o of L){const H=o.definition.info?.title||"",j=o.definition.info?.version||"";E.set(o.relativePath,{name:H,description:typeof o.definition.info?.description=="string"?o.definition.info.description:"",version:j,servers:o.definition.servers||[],relativePath:o.relativePath,...q&&re(o.definition.info)?{fetchEligible:!0}:{}})}const y=X(P(O,v)),G=Object.values(t.products||{}).map(o=>o?.name).filter(B),I=t.l10n?.locales?.map(o=>o.code)??a.fs.localeFolders,N=oe({products:G,locales:I,requiresLogin:l,rbac:C,hasGraphqlApis:y.length>0,elicitationEnabled:c,hasCallableApis:E.values().some(o=>o.fetchEligible),feedbackHidden:t.feedback?.hide===!0});e.addMcpTools(D(b,"./docs-mcp/tools/index.js"),N),d==="code"&&e.addMcpTools(D(b,"./codemode/tools/execute.js"),[te]),i={apiDescriptionsMap:Object.fromEntries(E),graphqlDescriptions:y}}const n=await ae(e,a,m);s?.setAttribute("customToolsCount",String(n)),n!==u&&(u=n,n>0&&p.info(`Registered ${n} custom MCP tool${n===1?"":"s"} from @mcp folders`)),await le({actions:e,handlerPath:D(b,"./handlers/docs-mcp-handler.js"),apiDescriptionsMap:i.apiDescriptionsMap,graphqlDescriptions:i.graphqlDescriptions,mcpConfig:r,mcpMode:d,elicitationEnabled:c,gatewayFetchBudgetPerExec:h,publicEndpointStatus:_(t)}),f||(p.info("Registered Docs MCP Server endpoint at /mcp"),f=!0)})},async afterRoutesCreated(e,a){const s=await a.getConfig(),{mcp:t}=s,r=!t?.hide&&!t?.docs?.hide;e.markGatedMcpTools(await ee(e.getMcpTools())),e.setGlobalData({mcpData:{docs:{enabled:r,name:t?.docs?.name||S,publicEndpoint:_(s)==="served"}}})}}}var Oe=de;async function le({actions:i,handlerPath:m,apiDescriptionsMap:u,graphqlDescriptions:f,mcpConfig:e,mcpMode:a,elicitationEnabled:s,gatewayFetchBudgetPerExec:t,publicEndpointStatus:r}){i.createRequestHandler(T,m);const g=l=>async(C,d)=>{const c=z(d.getAllRoutes(),e?.docs?.ignore||[]);return c.length>0&&p.verbose(`mcp.docs.ignore: hiding ${c.length} page routes from MCP search`),{props:{config:{apiDescriptionsMap:u,graphqlDescriptions:f,mcpDocsServerName:e?.docs?.name||S,mcpMode:a,elicitationEnabled:s,gatewayFetchBudgetPerExec:t,searchIgnoredRoutes:c,...l?{isPublicEndpoint:l}:{}},serverOutDir:i.serverOutDir,tools:i.getMcpTools().map(({importPath:h,...n})=>n)}}};if(i.addApiRoute({slug:k,requestHandlerId:T,httpMethod:"all",getStaticData:g(!1)}),r==="no-protected-content"?p.info(`mcp.docs.publicEndpoint is enabled, but the project has no protected content - /mcp already serves anonymous users, skipping ${M}.`):r==="anonymous-denied"?p.info(`mcp.docs.publicEndpoint is enabled, but anonymous users are denied the MCP feature (rbac.features.mcp or requiresLogin) - skipping ${M}.`):r==="served"&&(i.addApiRoute({slug:M,requestHandlerId:T,httpMethod:"all",getStaticData:g(!0)}),p.verbose(`Registered public Docs MCP Server endpoint at ${M}`)),s){const l=D(b,"./handlers/mcp-credentials-handler.js");i.createRequestHandler(A,l),i.addApiRoute({slug:V,requestHandlerId:A,httpMethod:"all",getStaticData:async(C,d)=>{const{seo:c,colorMode:h}=d.getConfig(),{logo:n}=d.getGlobalData();return{props:{branding:ce({seo:c,logo:n,colorMode:h})}}}}),p.verbose("Registered MCP credentials endpoint at /mcp/credentials")}}export{Oe as default,de as mcpServerPlugin};

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

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

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

@@ -0,0 +1 @@
+import{logger as v}from"../../../tools/notifiers/logger.js";import{mcpToolWorkers as L,MCP_TOOL_IS_AVAILABLE_KEY as k}from"../../../workers/mcp-tool-worker-pool.js";import{CREATE_ANONYMOUS_SESSION_TOOL_NAME as C,MANAGE_API_CREDENTIALS_TOOL_NAME as y}from"../constants.js";import{isAnonymousSessionToolAvailable as D}from"../docs-mcp/tools/core/create-anonymous-session.js";import{isManageApiCredentialsToolAvailable as N,manageApiCredentials as w,manageApiCredentialsSchema as x}from"../codemode/tools/manage-credentials.js";import{EXECUTE_TOOL_SCHEMA as _}from"../codemode/tools/execute-schema.js";import{EXECUTE_TOOL_NAME as I,CODE_MODE_TOOL_NAMES as H,FETCH_TOOL_NAME as P}from"../codemode/constants.js";import{buildCodeModeInstructions as R,buildExecuteDescription as U}from"../codemode/prompts.js";import{toToolListEntries as F}from"../codemode/build-tool-list.js";import{composeExecuteAnnotations as z,getActiveCapabilities as B}from"../codemode/capabilities/index.js";import{describeToolsSchema as W,describeTools as X}from"../codemode/tools/describe-tools.js";import{availableSandboxTools as Y}from"../utils/available-sandbox-tools.js";import{isToolDisabledByCaller as S}from"../utils/disabled-tools.js";import{toRegisterToolConfig as h}from"../utils/tool-registration.js";import{createMcpServer as $,createToolDispatch as j,extractSerializableContext as G}from"./mcp-server.js";function O(r,a){const o=a.schema;if(r)return o;const{sessionHandle:T,...p}=o.properties;return{...o,properties:p}}function K(r){return Object.fromEntries(r.map(a=>[a.name,a.schema]))}async function me({name:r,tools:a,context:o,skills:T=[],getKv:p}){const n=G(o),s=o.mcpMode==="code",l=s?B(o):[],b=l.some(e=>e.id===P),c=s?await Y(a.filter(e=>!H.has(e.name)),n):[],E=F(c,l),d=D(o)&&!S(C,o.metadata),g=s&&N(o)&&!S(y,o.metadata),m=$(r,s?R(b,E):void 0),u={getClientCapabilities:()=>m.server.getClientCapabilities(),getKv:p},f=j(s?{...n,sandboxToolSchemas:K(c)}:n,u),A=async e=>{try{return await L.exec(k,[{toolName:e,context:n}],{timeout:1e4})}catch(i){return v.error(`Failed to check MCP tool availability for "${e}": ${i instanceof Error?i.message:String(i)}`),!1}};if(s){const e=[{tool:{..._,description:U(b,E),schema:O(d,_),annotations:z(c,l,o.config?.mcp)},callback:f(I)},{tool:W(c,l),callback:X(c,A,l,o)}],i=a.find(t=>t.name===C);if(i&&d&&e.push({tool:i,callback:f(i.name)}),g){const t=x(o);e.push({tool:{...t,schema:O(d,t)},callback:w(n,u)})}for(const{tool:t,callback:M}of e)m.registerTool(t.name,h(t),M)}else await Promise.all(a.map(async e=>{const i=m.registerTool(e.name,h({...e,outputSchema:void 0}),f(e.name));await A(e.name)||i.disable()}));for(const e of T)m.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 m}export{me as createDocsMcpServer};

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

@@ -0,0 +1,17 @@
+import { McpServer } from '@modelcontextprotocol/server';
+import type { McpToolCallback, McpToolContext } from '../types.js';
+import type { KvService } from '@redocly/config';
+export declare function createMcpServer(name: string, instructions?: string): McpServer;
+export type ToolDispatchDeps = {
+    getClientCapabilities: () => {
+        elicitation?: {
+            form?: unknown;
+            url?: unknown;
+        };
+    } | undefined;
+    getKv: () => Promise<KvService>;
+};
+/** Build the tool callback that ships a tool call to the worker pool. */
+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

@@ -0,0 +1,3 @@
+import{McpServer as U}from"@modelcontextprotocol/server";import{logger as S}from"../../../tools/notifiers/logger.js";import{mcpToolWorkers as _,MCP_TOOL_WORKER_KEY as O}from"../../../workers/mcp-tool-worker-pool.js";import{secretStore as L}from"../gateway-mcp/secret-store.js";import{readAuthRequiredMeta as D,stripAuthRequiredMeta as E,upstreamAuthKey as b}from"../gateway-mcp/upstream-auth.js";import{acceptedCredentialsLink as K,buildCredentialsAcceptedHint as j,buildCredentialsToolHint as F,buildUpstreamCredentialFallback as q,buildUpstreamCredentialInputRequired as v,credentialElicitationAnswer as H,dedupeElicitation as N,isStatelessRequest as P,schemeLabelOf as $,supportsUrlElicitation as B}from"../gateway-mcp/elicitation.js";import{DEFAULT_SCHEME_NAME as y,resolveUpstreamApiAuth as G}from"../gateway-mcp/upstream-auth-scheme.js";import{MISSING_SESSION_HANDLE_MESSAGE as V,resolveSecretSubject as W}from"../gateway-mcp/subject.js";const Y=6e4;function ue(e,t){return new U({name:e,version:new Date().toISOString().slice(0,10)},{capabilities:{logging:{}},...t?{instructions:t}:{}})}function le(e,t){return r=>async(n,i)=>{S.info(`MCP tool called: ${r}`);const s=e.elicitationEnabled??!1,u=P(i.mcpReq),a=s?W(e.user,n.sessionHandle):{kind:"anonymous"},o=a.kind==="resolved"?a.subject:void 0;if(a.kind==="invalid")return{content:[{type:"text",text:a.message}],isError:!0};const c=async()=>{if(!(!s||!o||!t?.getKv))try{const m=await t.getKv();return await L.getSecretsForSubject(m,o)}catch(m){S.warn(`gateway mcp secret store error, continuing unauthenticated: ${String(m)}`);return}};let l;const d=async()=>{l=await c();const m={toolName:r,args:n,context:{...e,upstreamSecrets:l},extra:ee(i)};return await _.exec(O,[m],{timeout:Y})};let p=await d();const f=D(p);if(f.length>0&&s&&!o)return E(R(p,[{type:"text",text:V}]));if(f.length>0&&s&&o&&t?.getKv){S.info(`gateway mcp credentials prompt: era=${u?"2026-07-28":"2025"} clientElicitation=${J(t)}`);const m=await t.getKv(),h=await Q(e,f),w=f.map(C=>X(C,h)),k=Z(l),g=u?await z(e,i,w,o,m,k,h,t):await x(e,w,o,m,k,h);switch(g.kind){case"inputRequired":return g.result;case"retry":p=await d();break;case"prependText":p=R(p,[{type:"text",text:g.text},...p.content]);break;case"none":break}}return E(p)}}function R(e,t){const{structuredContent:r,...n}=e;return{...n,content:t,isError:!0}}function J(e){const t=e?.getClientCapabilities()?.elicitation;if(!t)return"none";const r=[t.form?"form":void 0,t.url?"url":void 0].filter(Boolean);return r.length>0?r.join("+"):"none"}async function Q(e,t){const r=new Map;for(const n of new Set(t.map(i=>i.api)))r.set(n,await G(e,n));return r}function X(e,t){const r=t.get(e.api);if(!r)return{...e,scheme:e.scheme??y};const n=e.scheme&&r.schemes[e.scheme]?e.scheme:r.defaultScheme;return{...e,scheme:n}}function Z(e){const t=new Set;for(const[r,n]of Object.entries(e??{}))for(const i of Object.keys(n))t.add(b({api:r,scheme:i}));return t}function I(e,t){return e.status===401&&!t.has(b(e))}function T(e,t){const r=t.get(e.api),n=e.sentScheme??e.scheme;return r&&n?$(r.schemes,n):void 0}function M(e,t){return e.map(r=>F(r,T(r,t))).join(`
+
+`)}function A(e,t,r,n,i){const[s,...u]=t,a=i.get(s.api),o=s.scheme??a?.defaultScheme??y,c=s.schemes&&s.schemes.length>1?s.schemes:void 0,l=c?void 0:T(s,i);return{subject:r,baseUrl:e.baseUrl??"",target:{api:s.api,name:s.name,scheme:o,...l?{schemeLabel:l}:{},...c?{acceptedSchemes:c}:{}},auth:a?.schemes[o]??{kind:"raw"},...a?{apiAuth:a}:{},kv:n,hasExistingSecret:!1,reason:{kind:"authFailure",status:s.status,...s.detail?{detail:s.detail}:{},otherApiNames:u.map(d=>d.name)}}}async function z(e,t,r,n,i,s,u,a){const o=H(t.mcpReq.inputResponses);if(o==="declined")return{kind:"none"};const c=r.filter(d=>I(d,s));if(c.length===0)return{kind:"prependText",text:M(r,u)};if(o==="accepted"){const d=await K(t.mcpReq.requestState(),{kv:i,subject:n,baseUrl:e.baseUrl??"",apis:c.map(f=>f.api)}),p=d?.apiName??c[0].name;return{kind:"prependText",text:j(p,d?.url)}}const l=A(e,c,n,i,u);return B(a?.getClientCapabilities())?{kind:"inputRequired",result:await v(l)}:{kind:"prependText",text:await q(l)}}async function x(e,t,r,n,i,s){const u=t.filter(c=>I(c,i));if(u.length===0)return{kind:"prependText",text:M(t,s)};const a=A(e,u,r,n,s);return{kind:"prependText",text:await N(`${r}:${b(u[0])}`,()=>q(a))}}function ee(e){return{sessionId:e.sessionId,authInfo:e.http?.authInfo,requestId:e.mcpReq.id,_meta:e.mcpReq._meta}}function de(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,fetchCountRequest:e.fetchCountRequest,clientIp:e.clientIp,client:e.client,clientVersion:e.clientVersion,requestId:e.requestId,messageId:e.messageId,upstreamSecrets:e.upstreamSecrets,searchIgnoredRoutes:e.searchIgnoredRoutes,internalBaseUrl:e.internalBaseUrl,sandboxToolSchemas:e.sandboxToolSchemas,fs:void 0}}export{ue as createMcpServer,le as createToolDispatch,de as extractSerializableContext};

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

@@ -0,0 +1,154 @@
+import type { ApiFunctionsContext, ApiFunctionsContextMethods, McpToolDefinition, McpToolFileSystem, McpToolJsonValue, PageStaticData } from '@redocly/config';
+import type { AuthInfo, CallToolResult, RequestId, RequestMeta, StandardSchemaWithJSON, ToolCallback } from '@modelcontextprotocol/server';
+import type { OpenAPIPath, OpenAPIServer, OpenAPIOperation } from '@redocly/api-docs';
+import type { McpErrorCodes, McpServerType } from './constants';
+import type { McpToolSchema } from '../../types';
+import type { Skill } from '../../types/plugins/skills.js';
+import type { UpstreamSecrets } from './gateway-mcp/secret-store.js';
+import type { SiteBranding } from './handlers/credentials-page/types.js';
+type ObjectValues<T> = T[keyof T];
+export type McpServerType = ObjectValues<typeof McpServerType>;
+export type McpErrorCodeTypes = ObjectValues<typeof McpErrorCodes>;
+export type ApiDescriptionInfo = {
+    name: string;
+    relativePath: string;
+    description?: string;
+    version?: string;
+    servers?: OpenAPIServer[];
+    fetchEligible?: boolean;
+};
+export type GraphqlDescriptionInfo = {
+    name: string;
+    relativePath: string;
+    description?: string;
+};
+export type McpDocsStaticDataPropsConfig = {
+    mcpDocsServerName: string;
+    apiDescriptionsMap: Record<string, ApiDescriptionInfo>;
+    graphqlDescriptions: GraphqlDescriptionInfo[];
+    mcpMode: McpMode;
+    elicitationEnabled: boolean;
+    gatewayFetchBudgetPerExec: number;
+    searchIgnoredRoutes?: string[];
+    isPublicEndpoint?: boolean;
+};
+export type McpDocsStaticData = PageStaticData & {
+    props: {
+        config: McpDocsStaticDataPropsConfig;
+        serverOutDir?: string;
+        fetchCountSecret?: string;
+        tools?: McpToolSchema[];
+        skills?: Skill[];
+        skillsBaseUrl?: string;
+    };
+};
+export type CredentialsPageStaticData = PageStaticData & {
+    props?: {
+        branding?: SiteBranding;
+    };
+};
+export type SkillMcpResource = {
+    slug: string;
+    name: string;
+    description: string;
+    content: string;
+    uri: string;
+};
+export type McpPath = {
+    'x-mcp'?: XMcpConfig;
+} & OpenAPIPath;
+export type XMcpConfig = {
+    docs?: {
+        hide?: boolean;
+    };
+    apiCalls?: {
+        hide?: boolean;
+    };
+};
+export type XMcpSection = keyof XMcpConfig;
+export type McpEndpoint = OpenAPIOperation & {
+    'x-mcp'?: XMcpConfig;
+};
+export type McpMode = 'tools' | 'code';
+export type SemanticSearchResult = {
+    title: string;
+    url: string;
+    content: string;
+};
+export type McpErrorClass = 'tool_error' | 'sandbox_error' | 'client_error' | 'server_error';
+export type McpToolWorkerResponse = CallToolResult & {
+    errorClass?: McpErrorClass;
+};
+export type ToolArgs = Record<string, unknown>;
+export type McpToolCallback = ToolCallback<StandardSchemaWithJSON<ToolArgs, ToolArgs>>;
+/** The caller and request fields every MCP telemetry event and audit record carries. */
+export type McpCallAttribution = Pick<McpToolContext, 'client' | 'clientVersion' | 'requestId' | 'messageId'>;
+export type McpToolExtra = {
+    sessionId?: string;
+    authInfo?: AuthInfo;
+    requestId: RequestId;
+    _meta?: RequestMeta;
+};
+export type FetchCountRequest = {
+    caller: {
+        subject?: string;
+        ip?: string;
+    };
+    secret: string;
+};
+export type McpToolContext = Omit<ApiFunctionsContext, 'telemetry' | 'getKv' | keyof ApiFunctionsContextMethods> & {
+    apiDescriptionsMap: Record<string, ApiDescriptionInfo>;
+    graphqlDescriptions: GraphqlDescriptionInfo[];
+    products?: string[];
+    accessToken?: string;
+    metadata?: Record<string, unknown>;
+    upstreamAuthorization?: string;
+    mcpMode?: McpMode;
+    elicitationEnabled?: boolean;
+    gatewayFetchBudgetPerExec?: number;
+    fetchCountRequest?: FetchCountRequest;
+    clientIp?: string;
+    client?: string;
+    clientVersion?: string;
+    requestId?: string;
+    messageId?: string;
+    upstreamSecrets?: UpstreamSecrets;
+    searchIgnoredRoutes?: string[];
+    internalBaseUrl?: string;
+    sandboxToolSchemas?: Record<string, Record<string, unknown>>;
+    fs?: McpToolFileSystem;
+};
+export type McpToolHandler<TArgs extends ToolArgs = ToolArgs> = (args: TArgs, context: McpToolContext, extra: McpToolExtra) => Promise<McpToolWorkerResponse | McpToolJsonValue>;
+export type McpToolIsAvailable = (context: McpToolContext) => boolean | Promise<boolean>;
+export type McpToolHandlerExtended<TArgs extends ToolArgs = ToolArgs> = {
+    execute: McpToolHandler<TArgs>;
+    isAvailable?: McpToolIsAvailable;
+};
+export type McpToolExecutionParams = {
+    toolName: string;
+    args: ToolArgs;
+    context: McpToolContext;
+    extra: McpToolExtra;
+};
+export type CustomMcpToolsState = {
+    registeredToolNames: string[];
+    warnedNoOutputSchemaTools: Set<string>;
+};
+export type ToolDefinitionValidationResult = {
+    ok: true;
+    schema: McpToolSchema;
+} | {
+    ok: false;
+    errors: string[];
+};
+export type ToolFileDefaultExport = Partial<McpToolDefinition> | null | undefined;
+export type McpToolModuleGetter = () => Promise<{
+    default: McpToolModuleExport;
+}>;
+export type McpToolMapExport = Record<string, McpToolHandler | McpToolHandlerExtended | undefined>;
+export type McpToolFileExport = McpToolHandlerExtended & {
+    description: string;
+};
+export type McpToolModuleExport = McpToolMapExport | McpToolFileExport;
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/server/plugins/mcp/utils/available-sandbox-tools.d.ts

@@ -0,0 +1,4 @@
+import type { McpToolSchema } from '../../../types';
+import type { McpToolContext } from '../types.js';
+export declare function availableSandboxTools(candidates: McpToolSchema[], context: McpToolContext): Promise<McpToolSchema[]>;
+//# sourceMappingURL=available-sandbox-tools.d.ts.map

package/dist/server/plugins/mcp/utils/available-sandbox-tools.js

@@ -0,0 +1 @@
+import{logger as a}from"../../../tools/notifiers/logger.js";import{mcpToolWorkers as n,MCP_TOOL_AVAILABILITY_KEY as m}from"../../../workers/mcp-tool-worker-pool.js";async function p(t,l){if(t.length===0)return t;const e=t.map(o=>o.name);let r;try{r=await n.exec(m,[{toolNames:e,context:l}],{timeout:1e4})}catch(o){return i(t,o instanceof Error?o.message:String(o))}return!r||typeof r!="object"?i(t,"the worker returned no availability map"):t.filter(o=>r[o.name]!==!1)}function i(t,l){const e=t.filter(r=>r.hasAvailabilityGate);return e.length===0?t:(a.warn(`MCP tool availability is unknown (${l}); the sandbox tool list drops the gated tools: ${e.map(r=>r.name).join(", ")}.`),t.filter(r=>!r.hasAvailabilityGate))}export{p as availableSandboxTools};

package/dist/server/plugins/mcp/utils/disabled-tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpToolContext } from '../types.js';
+export declare function isToolDisabledByCaller(toolName: string, metadata: McpToolContext['metadata']): boolean;
+//# sourceMappingURL=disabled-tools.d.ts.map

package/dist/server/plugins/mcp/utils/disabled-tools.js

@@ -0,0 +1 @@
+function r(o,s){const l=s?.disabledTools;return Array.isArray(l)&&l.includes(o)}export{r as isToolDisabledByCaller};

package/dist/server/plugins/mcp/utils/find-gated-tool-names.d.ts

@@ -0,0 +1,12 @@
+import type { McpToolRegistration } from '../../../types';
+import type { McpToolModuleExport } from '../types.js';
+type ToolModuleLoader = (importPath: string) => Promise<{
+    default: McpToolModuleExport;
+}>;
+/**
+ * Names of the tools whose handler declares an `isAvailable` predicate — the ones the live
+ * server enables per caller. Includes every tool of a handler module that fails to load.
+ */
+export declare function findGatedToolNames(registrations: McpToolRegistration[], load?: ToolModuleLoader): Promise<string[]>;
+export {};
+//# sourceMappingURL=find-gated-tool-names.d.ts.map

package/dist/server/plugins/mcp/utils/find-gated-tool-names.js

@@ -0,0 +1 @@
+import{resolveToolHandler as l}from"../workers/execute-mcp-tool.js";const s=t=>import(t);async function d(t,o=s){const n=[];for(const{name:e,importPath:r,hasAvailabilityGate:a}of t){if(a!==void 0){a&&n.push(e);continue}const i=await c(r,o);(!i||f(l(i,e)))&&n.push(e)}return n}async function c(t,o){try{const{default:n}=await o(t);return n}catch{return}}function f(t){return typeof t=="object"&&typeof t.isAvailable=="function"}export{d as findGatedToolNames};

package/dist/server/plugins/mcp/utils/json-schema-validator.d.ts

@@ -0,0 +1,9 @@
+import type { jsonSchemaValidator } from '@modelcontextprotocol/server';
+/**
+ * Validates tool arguments with the same engine and options the forked SDK
+ * (@redocly/mcp-typescript-sdk) used internally, so migrating to the upstream
+ * v2 SDK does not change which arguments are accepted. The SDK default would
+ * be a lenient draft-2020-12 engine instead.
+ */
+export declare const mcpJsonSchemaValidator: jsonSchemaValidator;
+//# sourceMappingURL=json-schema-validator.d.ts.map

package/dist/server/plugins/mcp/utils/json-schema-validator.js

@@ -0,0 +1 @@
+import{AjvJsonSchemaValidator as a}from"@modelcontextprotocol/server/validators/ajv";import l from"@redocly/ajv";const c=new a(new l({allErrors:!0})),j={getValidator(r){const o=c.getValidator(r),t=Object.keys(r.properties??{});return t.length===0||r.additionalProperties!==!1?o:n=>{const e=o(n),i=Object.keys(n??{}).filter(s=>!t.includes(s));return e.valid||i.length===0?e:{...e,errorMessage:`${e.errorMessage}. Unknown properties: ${i.join(", ")}. Accepted properties: ${t.join(", ")}.`}}}};export{j as mcpJsonSchemaValidator};

package/dist/server/plugins/mcp/utils/jwt.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Extract JWT token from Authorization header
+ */
+export declare function extractTokenFromAuthHeader(authHeader?: string | string[]): string | null;
+//# sourceMappingURL=jwt.d.ts.map

package/dist/server/plugins/mcp/utils/jwt.js

@@ -0,0 +1 @@
+function n(r){if(!r)return null;const e=Array.isArray(r)?r[0]:r;return!e||!e.startsWith("Bearer ")?null:e.replace(/^Bearer /,"")}export{n as extractTokenFromAuthHeader};

package/dist/server/plugins/mcp/utils/mcp-client.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Both markers are parenthesised so neither can collide with a real client: a name is built out
+ * of `[a-z0-9._-]`, which cannot produce a bracket.
+ */
+export declare function resolveMcpClient(request: Request): {
+    client: string;
+    clientVersion?: string;
+};
+export declare function parseUserAgent(userAgent: string | null | undefined): {
+    client: string;
+    clientVersion?: string;
+};
+//# sourceMappingURL=mcp-client.d.ts.map

package/dist/server/plugins/mcp/utils/mcp-client.js

@@ -0,0 +1 @@
+const o="(none)",r="(unparsed)",N=40,i=/^[A-Za-z0-9._\- ]+/,c=/(?<!\s)\s+([0-9]\S*)(?:[^\S\n].*)?$/,l=/^[/\s]+v?([0-9][^\s;,)]*)/;function a(e){return E(e.headers.get("user-agent"))}function E(e){if(e==null)return{client:o};const n=i.exec(e)?.[0]??"",t=n.replace(c,"").trim();if(!t)return{client:r};const s=c.exec(n)?.[1]??l.exec(e.slice(n.length))?.[1];return{client:t.replace(/\s+/g,"-").toLowerCase().slice(0,40),clientVersion:s?.slice(0,40)}}export{E as parseUserAgent,a as resolveMcpClient};

package/dist/server/plugins/mcp/utils/mode.d.ts

@@ -0,0 +1,20 @@
+import type { McpMode } from '../types.js';
+/**
+ * Codemode - `execute` sandbox and `describeTools`. Gated by the org-level `mcpMode`
+ * entitlement (GrowthBook `mcp-mode` flag → PLAN_GATES JWT).
+ *
+ * Read the VALUE, never `canAccessFeature('mcpMode')` — 'tools' is truthy.
+ * Only call these helpers where EntitlementsProvider is initialized: the build lifecycle
+ * and web-server routes. Request handlers and workers run in module graphs with an
+ * UNINITIALIZED provider copy — they must read the build-stamped `mcpMode` from static
+ * data / McpToolContext instead (see docs-mcp-handler / execute-mcp-tool).
+ */
+export declare function isMcpCodeModeEnabled(): boolean;
+/**
+ * The gateway capability: a guarded `fetch` in the `execute` sandbox. Requires code mode and a
+ * project database.
+ */
+export declare function isMcpGatewayEnabled(): boolean;
+export declare function isMcpElicitationEnabled(): boolean;
+export declare function getMcpMode(): McpMode;
+//# sourceMappingURL=mode.d.ts.map

package/dist/server/plugins/mcp/utils/mode.js

@@ -0,0 +1 @@
+import{EntitlementsProvider as e}from"../../../entitlements/entitlements-provider.js";import{hasProjectDatabase as n}from"../../../providers/database/has-project-database.js";function t(){return e.instance().entitlements?.mcpMode==="code"}function o(){return!!e.instance().canAccessFeature("mcpGateway")&&t()&&n()}function i(){return o()}function a(){return t()?"code":"tools"}export{a as getMcpMode,t as isMcpCodeModeEnabled,i as isMcpElicitationEnabled,o as isMcpGatewayEnabled};

package/dist/server/plugins/mcp/utils/public-endpoint.d.ts

@@ -0,0 +1,9 @@
+import type { RedoclyConfig } from '@redocly/config';
+export type PublicMcpEndpointStatus = 'served' | 'disabled' | 'no-protected-content' | 'anonymous-denied';
+/**
+ * Whether `/mcp-public` is served for this config, and why not when it is not.
+ * Ignores the `mcp` entitlement, so it is safe in request handlers; build-time callers
+ * that need the full answer must also check the entitlement.
+ */
+export declare function getPublicMcpEndpointStatus(config: Pick<RedoclyConfig, 'mcp' | 'access'>): PublicMcpEndpointStatus;
+//# sourceMappingURL=public-endpoint.d.ts.map

package/dist/server/plugins/mcp/utils/public-endpoint.js

@@ -0,0 +1 @@
+import{canAnonymousAccessMcpFeature as c}from"../../../utils/rbac/can-anonymous-access-mcp-feature.js";import{shouldHandleMcpAuth as i}from"../../../utils/rbac/should-handle-mcp-auth.js";function d(t){const{mcp:n,access:e}=t;if(n?.hide||n?.docs?.hide||!n?.docs?.publicEndpoint)return"disabled";const o=!!e?.requiresLogin,r=e?.rbac||{};return i(o,r)?c(r,o)?"served":"anonymous-denied":"no-protected-content"}export{d as getPublicMcpEndpointStatus};

package/dist/server/plugins/mcp/utils/telemetry-attributes.d.ts

@@ -0,0 +1,9 @@
+import type { McpCallAttribution, McpServerType, McpToolContext } from '../types.js';
+/** CloudEvent resource attributes shared by every `mcpServer` telemetry event. */
+export declare function serverAttributes(serverType: McpServerType): {
+    id: "docs";
+    object: 'mcpServer';
+    uri: string;
+};
+export declare function callAttribution(context: McpToolContext | undefined): McpCallAttribution;
+//# sourceMappingURL=telemetry-attributes.d.ts.map

package/dist/server/plugins/mcp/utils/telemetry-attributes.js

@@ -0,0 +1 @@
+function r(e){return{id:e,object:"mcpServer",uri:`urn:redocly:realm:mcp:server:${e}`}}function i(e){return{client:e?.client,clientVersion:e?.clientVersion,requestId:e?.requestId,messageId:e?.messageId}}export{i as callAttribution,r as serverAttributes};

package/dist/server/plugins/mcp/utils/tool-registration.d.ts

@@ -0,0 +1,18 @@
+import type { McpToolSchema } from '../../../types';
+import type { ToolArgs } from '../types.js';
+export declare function normalizeToolDisplayName(tool: McpToolSchema): McpToolSchema;
+/** The `registerTool` config for a tool schema, with its input and output schemas compiled for validation. */
+export declare function toRegisterToolConfig(tool: McpToolSchema): {
+    title: string | undefined;
+    description: string;
+    inputSchema: import("@modelcontextprotocol/server").StandardSchemaWithJSON<ToolArgs, ToolArgs>;
+    outputSchema?: import("@modelcontextprotocol/server").StandardSchemaWithJSON<unknown, unknown> | undefined;
+    annotations: {
+        title?: string | undefined;
+        readOnlyHint?: boolean | undefined;
+        destructiveHint?: boolean | undefined;
+        idempotentHint?: boolean | undefined;
+        openWorldHint?: boolean | undefined;
+    } | undefined;
+};
+//# sourceMappingURL=tool-registration.d.ts.map

package/dist/server/plugins/mcp/utils/tool-registration.js

@@ -0,0 +1 @@
+import{fromJsonSchema as i}from"@modelcontextprotocol/server";import{mcpJsonSchemaValidator as e}from"./json-schema-validator.js";function c(t){const n=t.title??t.annotations?.title;return n?{...t,title:n,annotations:{...t.annotations,title:n}}:t}function u(t){const{title:n,description:a,schema:r,outputSchema:o,annotations:m}=c(t);return{title:n,description:a,inputSchema:i(r,e),...o?{outputSchema:i(o,e)}:{},annotations:m}}export{c as normalizeToolDisplayName,u as toRegisterToolConfig};

package/dist/server/plugins/mcp/utils/xmcp-utils.d.ts

@@ -0,0 +1,9 @@
+import type { OpenAPIDefinition } from '@redocly/api-docs';
+import type { XMcpConfig, XMcpSection } from '../types.js';
+/** Whether the path item or operation is hidden for `section`. */
+export declare function isEndpointHidden(endpoint: {
+    'x-mcp'?: XMcpConfig;
+} | undefined, section: XMcpSection): boolean;
+/** Whether the definition's info-level x-mcp hides it for `section`. */
+export declare function isDefinitionHidden(info: OpenAPIDefinition['info'] | undefined, section: XMcpSection): boolean;
+//# sourceMappingURL=xmcp-utils.d.ts.map

package/dist/server/plugins/mcp/utils/xmcp-utils.js

@@ -0,0 +1 @@
+function e(i,n){return i?.["x-mcp"]?.[n]?.hide===!0}function t(i,n){return i?.["x-mcp"]?.[n]?.hide===!0}export{t as isDefinitionHidden,e as isEndpointHidden};

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

@@ -0,0 +1,94 @@
+import type { DocumentNode } from 'graphql';
+import type { ApiFunctionsUser, RbacConfig, RedirectConfig } from '@redocly/config';
+import type { ApiDescriptionInfo, GraphqlDescriptionInfo } from './types.js';
+import type { OpenAPIDefinition } from '@redocly/api-docs';
+import type { BundledApiDefinition } from '../api-docs/loader.js';
+/** OpenAPI specs only; MCP lists paths/servers from OpenAPI documents. */
+export type McpOpenApiSpec = {
+    relativePath: string;
+    definition: OpenAPIDefinition;
+};
+export type McpGraphqlSpec = {
+    relativePath: string;
+    definition: DocumentNode;
+    options: BundledApiDefinition['options'];
+};
+export declare function bundledOpenApiDocumentsToMcpOpenApi(bundled: BundledApiDefinition[]): McpOpenApiSpec[];
+export declare function bundledGraphqlDocumentsToMcpOpenApi(bundled: BundledApiDefinition[]): McpGraphqlSpec[];
+/**
+ * Filters out localizations and definitions with no public paths.
+ *
+ * This function removes definitions that are localization files (starting with 'l10n' or 'i18n')
+ * and definitions that don't have any public API paths. It also cleans up the remaining
+ * definitions by removing internal parsing artifacts.
+ *
+ * @param apiDescriptions - Array of OpenAPI definitions to filter.
+ * @returns Filtered array of definitions with only those containing public paths.
+ *
+ * @example
+ * getCleanedUpDefinitions([
+ *   { relativePath: 'l10n/en.yaml', definition: { paths: {} } },
+ *   { relativePath: 'api.yaml', definition: { paths: { '/users': {} } } }
+ * ]); // Returns only the api.yaml definition
+ */
+export declare function getCleanedUpApiDescriptions(apiDescriptions: McpOpenApiSpec[]): McpOpenApiSpec[];
+/**
+ * Filters OpenAPI definitions based on user RBAC permissions.
+ *
+ * This function checks each definition against the user's role-based access control
+ * permissions and filters out definitions the user doesn't have access to. It also
+ * applies deep filtering to the definition content based on the user's permissions.
+ *
+ * @param apiDescriptions - Array of OpenAPI definitions to filter.
+ * @param user - The user object containing role and permission information.
+ * @param rbac - RBAC configuration defining access rules.
+ * @param requiresLogin - Whether login is required for access.
+ * @returns Array of definitions the user has access to with filtered content.
+ *
+ * @example
+ * filterDefinitionsByRbac(definitions, user, rbac, true);
+ * // Returns only definitions the user can access with filtered content
+ */
+export declare function filterApiDescriptionsByRbac(apiDescriptions: Record<string, ApiDescriptionInfo>, user: ApiFunctionsUser, rbac: RbacConfig, requiresLogin: boolean): Record<string, ApiDescriptionInfo>;
+export declare function filterGraphqlDescriptionsByRbac(graphqlDescriptions: GraphqlDescriptionInfo[], user: ApiFunctionsUser, rbac: RbacConfig, requiresLogin: boolean): GraphqlDescriptionInfo[];
+export declare function buildGraphqlDescriptions(definitions: McpGraphqlSpec[]): GraphqlDescriptionInfo[];
+export declare function filterIgnoredApiDescriptions<T extends {
+    relativePath: string;
+}>(apiDescriptions: T[], ignoredPaths: string[]): T[];
+/**
+ * Registered page routes whose source file `mcp.docs.ignore` matches, as exact route slugs
+ * for the `search` tool to drop. The catalog tools filter definitions by path; `search` reads
+ * the site-wide semantic index, which only knows page URLs — so the affected routes are looked
+ * up in the route table at static-data time rather than derived from file paths (a derived
+ * slug bypasses the content-slugs transforms and cannot see operation pages).
+ */
+export declare function collectIgnoredRoutes(routes: {
+    fsPath?: string;
+    slug: string;
+}[], ignoredPaths: string[]): string[];
+/**
+ * Checks if the MCP route (/mcp) appears in redirect configuration.
+ *
+ * This function checks if the reserved MCP route is used as either a source
+ * or target in any redirect configuration. Returns true if found.
+ *
+ * @param config - The Redocly configuration containing redirects.
+ * @returns true if /mcp is found in redirects, false otherwise.
+ *
+ * @example
+ * isMcpInRedirects({ redirects: { '/mcp': '/docs' } }); // true
+ * isMcpInRedirects({ redirects: { '/docs': '/mcp' } }); // true
+ * isMcpInRedirects({ redirects: { '/docs': '/api' } }); // false
+ */
+export declare function isMcpInRedirects(redirects?: {
+    [key: string]: RedirectConfig;
+}): boolean;
+/** Whether an API definition is part of the Docs MCP catalog (not a localized copy, has public paths, not ignored via mcp.docs.ignore). */
+export declare function isApiIncludedInDocsMcp(relativePath: string, definition: {
+    paths?: Record<string, unknown>;
+} | undefined, mcpConfig: {
+    docs?: {
+        ignore?: readonly string[];
+    };
+} | undefined): boolean;
+//# sourceMappingURL=utils.d.ts.map

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

@@ -0,0 +1 @@
+import u,{join as l}from"node:path";import s from"picomatch";import{PUBLIC_API_DEFINITIONS_FOLDER as m,L10N_DIR_NAME as p,I18N_DIR_NAME as c}from"../../constants/common.js";import{RESERVED_ROUTES as h}from"../../plugins/get-reserved-routes.js";import{removeL10nPrefix as D}from"../../fs/utils/remove-l10n-prefix.js";import{removeTrailingSlash as g}from"../../../utils/url/remove-trailing-slash.js";import{slash as A}from"../../../utils/path/slash.js";import{canDownloadApiDefinition as d}from"../../utils/rbac.js";function T(e){return e.filter(t=>t.type==="openapi").map(t=>({relativePath:t.relativePath,definition:t.document}))}function W(e){return e.filter(t=>t.type==="graphql").map(t=>({relativePath:t.relativePath,definition:t.document,options:t.options}))}function f(e){if(typeof e!="object"||e===null)return e;if(Array.isArray(e))return e.map(f);const t={};for(const i in e)if(Object.hasOwn(e,i)){if(i.toString().startsWith("x-parsed-"))continue;t[i]=f(e[i])}return t}function b(e){return e.reduce((t,i)=>(i.relativePath.startsWith(p)||i.relativePath.startsWith(c)||!i.definition||typeof i.definition!="object"||!("paths"in i.definition)||i.definition?.paths&&Object.keys(i.definition.paths).length>0&&t.push({...i,definition:f(i.definition)}),t),[])}function M(e,t,i,r){const n={};for(const[o,a]of Object.entries(e))d(l(m,a.relativePath),i,r,t)&&(n[o]=a);return n}function N(e,t,i,r){return e.filter(n=>d(l(m,n.relativePath),i,r,t))}function S(e){return e.filter(({relativePath:t})=>!t.startsWith(p)&&!t.startsWith(c)).map(({relativePath:t,options:i})=>({name:i.info?.title||u.basename(t,u.extname(t)),description:i.info?.description,relativePath:t}))}function v(e,t){const i=s(t||[]);return e.filter(({relativePath:r})=>!i(r))}function k(e,t){if(!t?.length)return[];const i=s(t),r=e.filter(({fsPath:n})=>{if(!n)return!1;const o=A(n);return i(o)||i(D(o))}).map(({slug:n})=>g(n));return[...new Set(r)].sort()}function q(e={}){for(const[t,i]of Object.entries(e))if(t===h.mcp||(typeof i=="string"?i:i.to)===h.mcp)return!0;return!1}function w(e,t,i){return e.startsWith(p)||e.startsWith(c)||!t?.paths||Object.keys(t.paths).length===0?!1:!s(i?.docs?.ignore||[])(e)}export{S as buildGraphqlDescriptions,W as bundledGraphqlDocumentsToMcpOpenApi,T as bundledOpenApiDocumentsToMcpOpenApi,k as collectIgnoredRoutes,M as filterApiDescriptionsByRbac,N as filterGraphqlDescriptionsByRbac,v as filterIgnoredApiDescriptions,b as getCleanedUpApiDescriptions,w as isApiIncludedInDocsMcp,q as isMcpInRedirects};

package/dist/server/plugins/mcp/workers/execute-mcp-tool.d.ts

@@ -0,0 +1,9 @@
+import type { McpToolContext, McpToolExecutionParams, McpToolHandler, McpToolHandlerExtended, McpToolModuleExport, McpToolWorkerResponse } from '../types.js';
+export declare function executeMcpTool(params: McpToolExecutionParams): Promise<McpToolWorkerResponse>;
+export declare function resolveToolHandler(moduleDefault: McpToolModuleExport, toolName: string): McpToolHandler | McpToolHandlerExtended | undefined;
+export declare function isMcpToolAvailable(params: Omit<McpToolExecutionParams, 'args' | 'extra'>): Promise<boolean>;
+export declare function mcpToolAvailability(params: {
+    toolNames: string[];
+    context: McpToolContext;
+}): Promise<Record<string, boolean>>;
+//# sourceMappingURL=execute-mcp-tool.d.ts.map

package/dist/server/plugins/mcp/workers/execute-mcp-tool.js

@@ -0,0 +1 @@
+import{telemetry as h}from"../../../telemetry/index.js";import{McpServerType as c}from"../constants.js";import{EXECUTE_TOOL_NAME as w}from"../codemode/constants.js";import{isPlainObject as p}from"../../../../utils/guards/is-plain-object.js";import{logMcpToolCallAudit as g,reportMcpToolCalled as b,reportMcpToolError as u}from"./mcp-tool-telemetry.js";import{isToolDisabledByCaller as S}from"../utils/disabled-tools.js";import{attachToolFileSystem as E}from"./tool-file-system.js";import{callAttribution as M}from"../utils/telemetry-attributes.js";import{importMcpToolHandlers as A}from"./import-mcp-tool-handlers.js";function O(e){return e.content.map(t=>t.type==="text"?t.text:"")}async function X(e){h.initialize();const{toolName:t,args:o,extra:s}=e,r=E(e.context),n=r?.mcpMode??"tools",a=M(r),d=performance.now();try{const i=await C(t);if(!i)throw new Error(`MCP tool "${t}" is not registered or its module does not export a handler for "${t}". Expected \`export default { '${t}': handler }\` or a single tool definition with \`description\` and \`execute\` as the default export.`);const v=typeof i=="function"?i:i.execute,l=L(t,await v(o,r,s),n),m=Math.round(performance.now()-d),{errorClass:y}=l;delete l.errorClass;const f=l.isError?y??(t===w?"sandbox_error":"tool_error"):void 0,_=t===w&&y==="tool_error",x=O(l),T=x.join("");return g({tool:t,mode:n,serverType:c.Docs,args:o,result:T,errorClass:f,...a}),f?_||u({tool:t,message:x.join(" "),mode:n,serverType:c.Docs,durationMs:m,errorClass:f,...a}):b({tool:t,mode:n,serverType:c.Docs,durationMs:m,outputLength:T.length,...a}),l}catch(i){throw g({tool:t,mode:n,serverType:c.Docs,args:o,errorClass:"server_error",...a}),u({tool:t,message:i instanceof Error?i.message:String(i),mode:n,serverType:c.Docs,durationMs:Math.round(performance.now()-d),stack:i instanceof Error&&i.stack||"",errorClass:"server_error",...a}),i}}function P(e){return"execute"in e&&typeof e.execute=="function"&&"description"in e&&typeof e.description=="string"}async function C(e){const t=(await A())[e];if(!t)return;const{default:o}=await t();return k(o,e)}function k(e,t){return P(e)?e:e[t]}function L(e,t,o){if(N(t))return t;if(typeof t=="string")return{content:[{type:"text",text:t}]};let s;try{s=JSON.stringify(t)}catch(n){throw new Error(`MCP tool "${e}" returned a value that cannot be serialized to JSON: `+(n instanceof Error?n.message:String(n)))}if(s===void 0)throw new Error(`MCP tool "${e}" returned an invalid result.`);const r=o==="code"?JSON.parse(s):void 0;return p(r)?{content:[{type:"text",text:s}],structuredContent:r}:{content:[{type:"text",text:s}]}}const j=new Set(["text","image","audio","resource","resource_link"]);function N(e){if(!p(e))return!1;const{content:t}=e;return Array.isArray(t)&&t.every(o=>p(o)&&j.has(o.type))}async function $(e){h.initialize();const{toolName:t}=e;if(S(t,e.context.metadata))return!1;const o=E(e.context),s=performance.now();try{const r=await C(t);return r?typeof r=="object"&&typeof r.isAvailable=="function"?await r.isAvailable(o):!0:!1}catch(r){throw u({tool:t,message:"Failed to check if MCP tool is available: "+(r instanceof Error?r.message:String(r)),mode:o?.mcpMode??"tools",serverType:c.Docs,durationMs:Math.round(performance.now()-s),stack:r instanceof Error&&r.stack||"",errorClass:"server_error",...M(o)}),r}}async function Y(e){const{toolNames:t,context:o}=e,s=await Promise.all(t.map(r=>$({toolName:r,context:o}).catch(()=>!1)));return Object.fromEntries(t.map((r,n)=>[r,s[n]]))}export{X as executeMcpTool,$ as isMcpToolAvailable,Y as mcpToolAvailability,k as resolveToolHandler};

package/dist/server/plugins/mcp/workers/import-mcp-tool-handlers.d.ts

@@ -0,0 +1,5 @@
+import type { McpToolModuleGetter } from '../types.js';
+type McpToolHandlers = Record<string, McpToolModuleGetter | undefined>;
+export declare function importMcpToolHandlers(): Promise<McpToolHandlers>;
+export {};
+//# sourceMappingURL=import-mcp-tool-handlers.d.ts.map