深入解读 apify-mcp-server 源码地图：src 目录入口点、架构分层与两阶段工具加载机制

【免费下载链接】apify-mcp-serverThe Apify MCP server enables your AI agents to extract data from social media, search engines, maps, e-commerce sites, or any other website using thousands of ready-made scrapers, crawlers, and automation tools available on the Apify Store.项目地址https://gitcode.com/gh_mirrors/ac/apify-mcp-server点击查看免费下载src/AGENTS.md是 apify-mcp-server 仓库的源码导览文档它回答了任何一个开发者进入项目后最关心的问题代码从哪个文件开始执行、每个顶层文件与子目录各自承担什么职责、MCP 协议双版本2025 时代有状态协议与 2026-07-28 无状态协议如何在同一套核心上并存。本文以该文档为骨架结合仓库内真实源码逐层展开帮助读者在阅读完本文后能够直接对照 src/AGENTS.md 在仓库中快速定位入口、理解目录边界并掌握影响工具注册成败的两阶段工具加载机制与强制验证流程。总览多个入口点一个核心src/AGENTS.md 用一句话概括了整个包的设计哲学The package has several entry points over one core——即一个核心之上挂载多个入口。顶层文件只负责接线wiring把某个传输方式stdio / HTTP与核心服务ActorsMcpServer连接起来真正的业务逻辑全部沉淀在mcp/、tools/、payments/、resources/、web/等子目录中。每个子目录都有各自的AGENTS.md作为子文档因此改动代码前应先阅读对应目录的子文档。这一设计也直接反映在 package.json 的exports字段上包的公开面不止一个入口而是按消费场景拆成了多个导出子路径exports: { .: ./dist/index.js, ./internals: ./dist/index_internals.js, ./internals.js: ./dist/index_internals.js, ./internals/test-kit: ./dist/index_internals_test_kit.js, ./internals/test-kit.js: ./dist/index_internals_test_kit.js, ./test-kit: ./dist/test_kit/index.js, ./manifest.json: ./manifest.json }三个主要导出面分别对应三个顶层文件index.ts公共库面、index_internals.ts内部仓库消费面、index_internals_test_kit.ts仅供本仓库测试自用面。下面逐一剖析。顶层入口文件详解index.ts公开的库导出面npm 发布面src/index.ts 是整个包作为npm 库使用时导入的入口其注释明确要求Keep this surface minimal保持该面最小化。它只导出两样东西import { ActorsMcpServer } from ./mcp/server.js; import { createStatelessServer } from ./mcp/stateless_server.js; export { ActorsMcpServer, createStatelessServer };ActorsMcpServer位于 src/mcp/server.ts 的共享门面facade聚合了工具、服务模式server mode、服务、widgets、支付与遥测是整个包的核心类。createStatelessServer来自 src/mcp/stateless_server.ts 的逐请求注册工厂——宿主服务用它来承载 2026-07-28 协议时代的流量每个请求独立构建一个 v2 SDKServer无握手、无会话。它是 2026-07-28 流量能被同一个门面服务的关键。index_internals.ts内部仓库消费面src/index_internals.ts 是私有仓库apify-mcp-server-internal托管版服务器通过./internals导入的表面。src/AGENTS.md 强调它要keep it minimal保持最小。它导出ApifyClient、getServerCard、TTLLRUCache、getDefaultTools、getCategoryTools、resolvePaymentProvider、parseQueryParamList等内部工具并保留了两个向后兼容的别名/** deprecated Use HELPER_TOOLS / HelperToolName. Kept for backward compatibility with apify-mcp-server-internal. */ export const HelperTools HELPER_TOOLS; /** deprecated Use HelperToolName. */ export type HelperTools HelperToolName;注意 src/AGENTS.md 有一条硬性边界不要往这里添加 internal 仓库不消费的东西——apify-mcp-server-internal是./internals.js的唯一消费方扩充该面会徒增耦合。index_internals_test_kit.ts仅供本仓库测试自用src/index_internals_test_kit.ts 是与index_internals.ts刻意分离的第二个内部面./internals/test-kit.js只服务于tests/test_kit/**的自引用导入internal 仓库不消费它。它导出HELPER_TOOLS、MAX_LIMIT_WITH_INPUT_SCHEMA、SKYFIRE_ENABLED_TOOLS、RESOURCE_MIME_TYPE、actorRunOutputSchema、AUTO_INJECTED_TOOLS等测试需要的常量与 schema。stdio.tsCLI 入口Docker 使用src/stdio.ts 是标准的命令行入口也是 Docker 镜像启动时运行的脚本package.json的bin字段指向./dist/stdio.js。它有两个必须遵守的约束Sentry 必须第一个导入import ./instrument.js;位于文件最顶部以保证错误监控在其它任何模块加载前完成初始化。src/AGENTS.md 明确警告keep that import order保持该导入顺序不可调整。命令行参数通过yargs解析完整参数如下参数类型说明默认值--actorsstring逗号分隔的 Actor 全名列表例如apify/google-search-scraper,apify/instagram-scraper也可通过环境变量ACTORS设置无--toolsstring逗号分隔的工具选择器可以是工具类别、具体工具名或 Apify Actor例如actors,docs,apify/rag-web-browser,apify/web-fetch也可通过TOOLS环境变量设置无--telemetry-enabledboolean是否开启工具调用的遥测追踪true开启--telemetry-envstring遥测环境PROD生产 Segment workspace或DEV开发 workspace仅在遥测开启时生效PROD--uistring/boolean服务模式--ui apps/--ui true/--ui on强制 MCP Apps widget 渲染--ui default/--ui false/--ui off强制标准工具集--ui auto默认根据客户端initialize能力自动解析openai为已废弃的apps别名也可通过UI_MODE环境变量设置auto--help/-h-显示帮助---version-显示版本号来自getPackageVersion()-stdio.ts的启动流程可以概括为以下调用链与 src/mcp/server.ts 的loadToolsFromInput联动读取 token优先process.env.APIFY_TOKEN其次尝试从~/.apify/auth.json读取getTokenFromAuthFile见 src/stdio.ts。鉴权判断isApiTokenRequired({ toolCategoryKeys, actorList })决定是否需要 token——只有纯公开工具如 docs可以在无 token 下运行需要鉴权而缺失 token 时直接process.exit(1)。Node.js 版本守卫要求Node.js 22 及以上engines.node 22.0.0见 package.json低于 22 会输出明确错误并退出。构造ActorsMcpServer用processInput(input)归一化输入actors会按向后兼容语义合并进tools详见下文input.ts一节再mcpServer.loadToolsFromInput(normalizedInput, apifyClient)拉取 Actor 元数据。创建StdioServerTransport并connect随后通过包装transport.onmessage用injectMcpSessionId为所有请求注入一个 UUID4 会话 IDstdio 传输没有严格的会话概念此 ID 仅用于遥测追踪与任务隔离。dev_server.tsExpress 本地开发 / standby Actor 模式服务器src/dev_server.ts 是 Express 实现的 HTTP 服务器用于本地开发与 standby Actor 模式pnpm start/pnpm run dev启动监听127.0.0.1:3001。它的核心特征是在同一个POST /端点上同时服务两个协议时代if (await isStatelessRequest(req)) { await serveStatelessRequest(req, res, taskStore); return; }路由分流的判别函数是isStatelessRequest()src/dev_server.ts它复用 v2 SDK 的isLegacyRequestfalse表示该请求属于 2026-07-28 无状态条目包括其自身的校验拒绝true则落到 2025 时代有状态流程initialize握手、带mcp-session-id的会话复用、GET SSE 流与 DELETE 会话等。有状态分支通过extractInitializeMessage()按method initialize标签匹配可能含批处理请求识别握手消息并用StreamableHTTPServerTransport管理会话生命周期。其余值得注意的实现细节认证extractApiTokenFromRequest()按Authorization: Bearer token头优先、?tokentoken查询参数兜底的顺序提取 token与生产内部仓库行为一致缺失 token 时返回 401并附带WWW-Authenticate: Bearer errorinvalid_token, ...质询头RFC 6750 §3 格式见 src/dev_server.ts。支付模式?paymentprovider如?paymentskyfire激活第三方支付提供者后不再要求 Apify tokenresolveRequestAuth返回{ apifyToken: undefined }。DNS 重绑定防护在解析任何 body 之前用localhostHostValidation()/localhostOriginValidation()拒绝非本地 Host 与非本地 Origin对应安全修复 apify/apify-mcp-server#1140。无状态分支的认证时序401 在 server 工厂内部解析SEP-2243 要求无论鉴权状态如何都要先完成框架校验server/discover探测请求被放行无 token 也能发现能力其fetch包装器把工厂抛出的 500 替换为 401。开发专用定位文件顶部注释明确声明它是DEV ONLY的本地开发/standby 仿真服务器生产级 Streamable HTTP鉴权、限流、Redis 会话生命周期、多节点位于apify-mcp-server-internal不要在本文件里镜像生产行为。URL 参数?telemetry-enabled、?ui、?payment、?client均在此解析同时默认把TELEMETRY_ENV设为DEVprocess.env.TELEMETRY_ENV ?? DEV确保本地工具调用不会污染生产分析数据但仍可用显式的TELEMETRY_ENVPROD覆盖。input.ts输入归一化src/input.ts 提供processInput()被stdio.ts和 HTTP URL 参数解析器src/mcp/utils.ts 的processParamsGetTools共同使用。它只做规范化、不加载任何工具语义如下normalizeList()把逗号分隔字符串或数组统一裁剪为字符串数组undefined保持undefined表示用默认值空串/空数组归一为[]表示明确不选。processInput()把actors合并进tools使工具选择只存在于一个地方向后兼容若tools未定义则直接用actors作为工具列表。源码注释还指出了未来的差异化思路Actor 名包含/而内部工具名/类别不含未来可用此特征区分两者src/input.ts。apify_client.tsApify API 客户端包装src/apify_client.ts 是对apify-client官方 SDK 的封装src/AGENTS.md 明确要求use it rather than calling the API directly用它而不是直接调 API。它做了三件事兜底 baseUrlgetApifyAPIBaseUrl()在 Actor 平台内APIFY_IS_AT_HOME强制使用https://api.apify.com否则回退到APIFY_API_BASE_URL环境变量或默认值。User-Agent 溯源通过userAgentSuffix: Origin/mcp-server标识请求来源。静态请求头每个请求注入X-Apify-Request-Origin默认MCP可传APIFY_AI以及支付提供者返回的paymentHeaders通过 axiosrequestInterceptors实现src/apify_client.ts。另外它处理了一个真实踩坑若 token 是占位值your-apify-token或null会将其删除以无鉴权客户端启动服务器、仅用于工具列表展示DockerHub 构建任务会发送这个 dummy token。state.tsTTL 缓存src/state.ts 集中管理 TTL LRU 缓存实现类是 src/utils/ttl_lru.ts 的TTLLRUCache缓存最大条目数TTLactorDefinitionCache50030 分钟searchApifyDocsCache5001 小时fetchApifyDocsCache已处理的 Markdown 内容5001 小时共享骨干const.ts/errors.ts/types.ts/telemetry.ts/instrument.ts/server_card.tssrc/const.ts全包常量单一来源包括HELPER_TOOLSas const对象代码中引用工具名必须通过它而非硬编码字符串、MAX_INLINE_BYTES256 KB超限内容改为链接外发而非内联、DATASET_SIZE_HINT_BYTES50 KB 大输出提示阈值、SERVER_MODE_AUTO_DETECTION_ENABLED等。src/errors.ts共享错误定义。src/types.ts共享类型Input、ToolEntry、SERVER_MODE、TelemetryEnv等。src/telemetry.ts 与 src/instrument.ts遥测与 Sentry 初始化。src/server_card.ts服务器卡片server info生成供resources与server/discover使用。子目录职责边界src/AGENTS.md 用一张子目录 → 子文档的映射表划定了每个子系统的边界每个子目录都有独立的AGENTS.md子目录职责子文档src/mcp/MCP 协议核心即 npm 发布面。两个协议时代的适配器都在这里src/mcp/AGENTS.mdsrc/tools/MCP 工具实现Actor、builds、runs、schedules、tasks、widgets 等src/tools/AGENTS.mdsrc/payments/Skyfire / x402 支付提供者src/payments/AGENTS.mdsrc/resources/MCP resources widget 注册表src/resources/AGENTS.mdsrc/web/widget UI独立构建 设计系统src/web/AGENTS.mdsrc/utils/广泛辅助函数集合无单一概念无子文档直接 grep—src/prompts/提示词注册表index.ts与prompt_service.tscreatePromptService抛出协议无关的领域错误无子文档—mcp/双协议时代并存的协议核心src/mcp/AGENTS.md 揭示了整包最重要的架构事实两个 MCP 协议修订版本各有自己的适配器它们是同一 Apify 核心上的兄弟而不是层层叠叠的上下层2025 时代有状态协议规范版本 2025-11-25由 v1 SDKmodelcontextprotocol/sdk承载适配器为legacy_server.tssrc/mcp/legacy_server.ts有initialize握手与mcp-session-id会话生命周期。2026-07-28 无状态修订版由 v2 SDKmodelcontextprotocol/server承载适配器为stateless_server.tssrc/mcp/stateless_server.ts。没有initialize握手每个请求自带_meta信封协议版本、客户端信息、能力声明因此客户端身份与auto模式解析都是逐请求完成的。src/mcp/AGENTS.md 还列出了几条必须遵守的不变量gotchas门面 → 适配器单向依赖ActorsMcpServer构造并委托给LegacyMcpServercreateStatelessServer从同一个门面逐请求构建无状态适配器但门面从不构造它。两个适配器只能通过各自的窄宿主接口LegacyMcpServerHost/StatelessMcpServerHost读取共享状态绝不 import 具体门面类共享同步执行模块tool_call_engine.ts、tool_dispatch.ts只接收普通值不 importActorsMcpServer、v1RequestHandlerExtra或 v1McpError。逐请求状态放在快照里绝不写在门面上无状态路径通过createRequestSnapshot从该请求的_meta信封解析auto模式与 report-problem 可见性快照不回写任何请求特定状态到门面——并发请求写共享门面会互相污染。工具名上限MAX_TOOL_NAME_LENGTH被截断的名字用户名、尾部或两者必须带TOOL_NAME_HASH_LENGTH长度的哈希后缀对未截断名取哈希仅截断会产生碰撞任何代理名超限时所有兄弟工具的用户名统一截断到MAX_TOOL_NAME_USERNAME_LENGTH碰撞在getToolsForServerMode中先到先得。永远不要放宽该上限——客户端依赖它。代理服务器 ID 按 URL 而非 Actor ID 键控getMCPServerID(url)是对 URL 取 sha256 后切片到SERVER_ID_LENGTH暴露的工具名格式为{username}--{actor-name}--{originToolName}。传输协商 streamable 优先、SSE 兜底src/mcp/client.ts 的connectMCPClient协议失败回退 SSE但连接超时返回null且不做 SSE 兜底超时意味着不可达而不是传输选错。getActorMCPServerPath()在多端点时优先/mcpstreamable 端点。resources/API 资源代理与 widget 注册表src/resources/AGENTS.md 说明该目录由三个文件构成resource_service.ts处理ListResources/ListResourceTemplates/ read-resource 请求读取时按_meta.apifyToken || options.token构建按请求隔离的 Apify 客户端。Token-only 设计没有支付头因此纯支付会话x402/Skyfire拿不到客户端所有读取都会以InvalidParamsError失败。抛出的都是协议无关领域错误InvalidParamsError/InternalError来自 src/mcp/errors.ts由server.ts边界在序列化前 1:1 映射为McpError。api_resources.ts薄流式 MCP 资源代理——任何 Apify API GET 端点都能作为资源读取资源 URI 就是真实 API URLhttps://api.apify.com/v2/...与平台 URL 的身份一致性正是该设计的特点isApifyApiUri()限制读取必须指向配置的 API 源并拒绝带 userinfo 的 URLaxios 会悄悄丢弃这类 URL 的Authorization头。readApiResource()用responseType: streammaxContentLength: MAX_INLINE_BYTES流式转发文本类型以text返回并保留完整响应头其它类型含无 Content-Type以 base64blob返回空 body 以空text返回超限时链接外发KVS 记录给出签名recordPublicUrl否则给出 token 门控的 API URL并附带limit/offset分页提示。widgets.ts只含元数据——注册与定位 widget实际的 React widget 代码在 src/web/AGENTS.md两者必须保持同步。tools/与其它src/tools/AGENTS.md 承载全部 MCP 工具实现actors、builds、runs、schedules、tasks、widgets、dev/report_problem、docs 等类别是工具工厂的所在地payments/实现 Skyfire / x402 提供者CallToolRequest在tool_dispatch层解析支付上下文prompts/提供提示词注册表与createPromptService。两阶段工具加载机制开发前必读src/AGENTS.md 特别强调两阶段工具加载模式无关的getActors()与模式相关的getToolsForServerMode()在 DEVELOPMENT.md 中只记录一次改动工具加载逻辑前必须先读它。该机制是serverMode: auto能够工作的基石。第一阶段getActors()是async、模式无关的拉取 Actor 元数据保留调用者请求的工具/Actor 选择但不挑选任何模式相关的工具变体。第二阶段getToolsForServerMode()是sync、模式相关的接收预取资源与已解析的SERVER_MODE产出要暴露给客户端的具体工具条目。两者都位于 src/utils/tools_loader.ts。为什么必须分两阶段因为在serverMode: auto下initialize之前服务器不知道客户端是否支持 MCP Apps。因此ActorsMcpServer.loadToolsByName()/loadToolsFromUrl()等公开预载助手先排队模式无关资源Actor 工具因为是模式无关的可以立即加载。在initialize期间一旦客户端能力已知服务器把排队的资源解析为有状态连接的模式相关工具集。更关键的是资源在两个地方被消费DEVELOPMENT.md有状态2025 时代路径在initialize时解析一次写入存活于整个连接的共享ActorsMcpServer.tools映射。无状态2026-07-28路径没有initializeActorsMcpServer.createRequestSnapshot()针对每一个请求用该请求自己解析出的模式与声明的客户端身份把所有保留资源重新组合成一个快照——共享映射永远看不到它。判断规则Rule of thumb如果代码可能在auto模式下、initialize之前运行它就必须留在模式无关阶段只有模式解析后的代码才允许调用getToolsForServerMode()或选择具体的模式相关变体。改动后的强制验证流程src/AGENTS.md 的收尾要求是任何改动之后都要运行根 AGENTS.md 的 Verification 步骤。根文档给出了零容忍的验证清单pnpm run type-check # 类型检查比 build 快不生成 JS 输出 pnpm run lint # oxlint 静态检查 pnpm run test:unit # 单元测试无需凭据 pnpm run format # oxfmt 格式化 pnpm run check:agents # 校验 AGENTS.md 链接树与验证相关的重要约束还包括不要用pnpm run build做类型检查只有明确需要编译产物如 mcpc 探测前才用pnpm run build。不要在 Agent 流程中跑集成测试pnpm run test:integration需要有效APIFY_TOKEN且很慢人类专属。集成测试tests/integration/suite.ts把stdio、2025-11-25streamable HTTP、2026-07-28stateless HTTP 三个传输维度编织进同一个共享套件新增用例应加到 tests/test_kit 的*.cases.ts而不是直接改suite.ts。一致性测试pnpm run test:conformance会先构建然后按2026-07-28→2025-11-25的顺序对编译后的 dev server 各跑一遍官方 MCP 一致性套件--suite all以第一个非零退出码结束排除场景与原因记录在 scripts/conformance_expected_failures_2026_07_28.yaml 与 scripts/conformance_expected_failures_2025_11_25.yaml。Node.js 版本策略最低支持Node 22engines.node 22.0.0CI 测试矩阵运行在[22, 24, 26].nvmrc把开发工具链固定在 24。原因包括 pnpm 11锁定的包管理器devEngines.packageManager以onFail: error钉死npm/yarn 在仓库内会被拒绝本身要求 Node 22.13。小结src/AGENTS.md作为源码导览文档用一张入口点 子目录 两阶段加载 验证流程的地图把 apify-mcp-server 的代码组织讲得清清楚楚index.ts/stdio.ts/dev_server.ts等入口各司其职mcp/tools/payments/resources/web子目录边界分明2025 时代与 2026-07-28 两个协议时代在同一门面下和平共处而两阶段工具加载保证了auto模式在握手前不做过早决策。对于想要为这个仓库贡献代码、或者想理解 MCP 服务器如何组织多协议实现的开发者来说先对照本文走一遍 src/AGENTS.md 及其链接的子文档是成本最低、也最符合项目维护者预期的切入点。赞分享【免费下载链接】apify-mcp-serverThe Apify MCP server enables your AI agents to extract data from social media, search engines, maps, e-commerce sites, or any other website using thousands of ready-made scrapers, crawlers, and automation tools available on the Apify Store.项目地址https://gitcode.com/gh_mirrors/ac/apify-mcp-server点击查看免费下载相关推荐3分钟掌握PowerToys FancyZones彻底改变你的Windows窗口管理习惯3分钟掌握PowerToys FancyZones彻底改变你的Windows窗口管理习惯 还在为杂乱的桌面窗口而烦恼吗Microsoft PowerToys桌面应用开发工具OneUptime BrowserRecorder客户站点会话录制器的安装、隐私模型与两层加载架构深度解析OneUptime BrowserRecorder客户站点会话录制器的安装、隐私模型与两层加载架构深度解析 本文以 OneUptime 仓库中 App/Fea可观测性后端运维前端云原生微服务AI AgentMatter 源码核心目录架构全解析connectedhomeip src 目录分层导览与模块拆解Matter 源码核心目录架构全解析connectedhomeip src 目录分层导览与模块拆解 导读 本文以 src/README.md https://物联网智能家居嵌入式通信上一篇如何5分钟快速上手Codelin从安装到首次AI代码生成的完整教程下一篇3分钟学会用ncmdump快速解密网易云音乐NCM文件创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考