();\n const details = toolOutput?.details;\n\n if (!details) {\n return No actor details available
;\n }\n\n return ;\n};\n\n// 2. 开发/生产环境路由\n(async () => {\n if (IS_DEV_BUILD) {\n const { setupActorDetailWidgetDev } = await import(\"./actor-detail-widget.dev\");\n setupActorDetailWidgetDev();\n }\n renderWidget(ActorDetailWrapper);\n})();\n```\n\n资料来源：[src/web/src/widgets/actor-detail-widget.tsx](src/web/src/widgets/actor-detail-widget.tsx)\n\n---\n\n## Widget 布局组件\n\n`WidgetLayout` 是所有 Widget 的基础容器组件，提供统一的页面结构：\n\n```mermaid\ngraph LR\n subgraph \"WidgetLayout 结构\"\n Header[\"Header (标题 + 操作)\"]\n Content[\"Content (主内容区)\"]\n Footer[\"Footer (可选)\"]\n end\n \n Widget[\"\"]\n Widget --> Header\n Widget --> Content\n Widget --> Footer\n```\n\n**主要属性**：\n\n| 属性名 | 类型 | 说明 |\n|--------|------|------|\n| title | string | Widget 标题 |\n| actions | ReactNode | 右上角操作区域 |\n| children | ReactNode | 主内容区 |\n| footer | ReactNode | 底部区域（可选） |\n\n资料来源：[src/web/src/components/layout/WidgetLayout.tsx](src/web/src/components/layout/WidgetLayout.tsx)\n\n---\n\n## 业务组件\n\n### ActorCard 组件\n\n用于展示单个 Actor 的搜索结果卡片：\n\n```typescript\ninterface ActorCardProps {\n actor: Actor;\n}\n\nexport const ActorCard: React.FC = (props: ActorCardProps) => {\n const { actor } = props;\n // 渲染 Actor 卡片，包含徽章、统计信息等\n};\n```\n\n**功能特性**：\n- 显示 Actor 名称、描述、图标\n- 展示使用量、评分等统计信息\n- 集成 Badge 组件显示状态\n\n资料来源：[src/web/src/components/actor/ActorCard.tsx](src/web/src/components/actor/ActorCard.tsx)\n\n### ActorStats 组件\n\n展示 Actor 的关键统计数据：\n\n```typescript\ninterface ActorStatsProps {\n stats: {\n runsCount?: number;\n rating?: number;\n // 其他统计字段\n };\n}\n```\n\n**统计维度**：\n\n| 指标 | 说明 |\n|------|------|\n| runsCount | 运行次数 |\n| rating | 平均评分 |\n| avgDuration | 平均执行时长 |\n\n资料来源：[src/web/src/components/actor/ActorStats.tsx](src/web/src/components/actor/ActorStats.tsx)\n\n---\n\n## Bundle 优化策略\n\nWidget Bundle 必须保持自包含，但顶层 `@apify/ui-library` 和 `@apify/ui-icons` 的打包成本较高。\n\n### 优化规则\n\n| 策略 | 说明 |\n|------|------|\n| 优先使用 `dist/src/...` 导入 | 避免导入整个 barrel 文件 |\n| 避免重型组件 | 在共享路径使用轻量级本地实现 |\n| Markdown 渲染特殊处理 | 变动时需重新测量 bundle 影响 |\n\n### 优化效果\n\n| Widget | 优化前 | 优化后 | 降幅 |\n|--------|--------|--------|------|\n| actor-run-widget | ~1.86 MB | ~1.16 MB | ~38% |\n| actor-detail-widget | ~1.86 MB | ~1.52 MB | ~18% |\n| search-actors-widget | ~1.87 MB | ~1.53 MB | ~18% |\n\n资料来源：[res/web-widget-bundle-size.md](res/web-widget-bundle-size.md)\n\n### 导入规范对比\n\n```typescript\n// ✅ 优化后的导入方式（推荐）\nimport { Button } from '@apify/ui-library/dist/src/Button';\nimport styled from 'styled-components';\n\n// ❌ 不推荐的导入方式\nimport { Button } from '@apify/ui-library'; // 导入整个库\n```\n\n资料来源：[res/web-widget-bundle-size.md](res/web-widget-bundle-size.md)\n\n---\n\n## 开发模式\n\n### 热重载开发\n\n```bash\nAPIFY_TOKEN='your-apify-token' pnpm run dev\n```\n\n开发服务器配置：\n\n| 服务 | 端口 | 说明 |\n|------|------|------|\n| MCP 服务器 | 3001 | standby 模式 |\n| esbuild 开发服务器 | 3226 | widget 热重载 |\n\n### UI 模式\n\nWidget 渲染需要服务器运行在 UI 模式：\n- URL 参数：`?ui=true`（如 `/mcp?ui=true`）\n- 环境变量：`UI_MODE=true`\n\n### 本地预览\n\n访问 http://localhost:3226/index.html 预览所有可用 Widget：\n\n```html\nActor Search Widget\nActor Run Widget\n```\n\n资料来源：[src/web/index.html](src/web/index.html)\n\n---\n\n## 组件开发规范\n\n### 开发检查清单\n\n在提交 UI 代码前，必须完成以下验证：\n\n1. **Token 审计**：搜索代码中是否存在违规值\n - 颜色：`['\"]#[0-9a-fA-F]{3,8}['\"]` — 应为 0 处匹配\n - 间距：`['\"][0-9]+px['\"]` — 应为 0 处匹配\n\n2. **导入检查**：\n - 所有 styled-components 必须导入 `theme` from `@apify/ui-library`\n - 不得有重复组件实现\n\n3. **模式匹配**：\n - 对比相似组件的结构\n - 遵循相同的属性命名约定\n - 使用相同的变体模式\n\n### 组件结构模板\n\n```typescript\n// 1. 导入（分组）\nimport { forwardRef } from 'react';\nimport styled from 'styled-components';\nimport { theme } from '@apify/ui-library';\n\n// 2. 常量与类型\nexport const COMPONENT_VARIANTS = { ... } as const;\ntype ComponentVariants = ValueOf;\n\n// 3. 样式组件\nconst StyledWrapper = styled.div`...`;\n\n// 4. 组件实现\nexport const Component = forwardRef((props, ref) => {\n // implementation\n});\n\n// 5. Display Name\nComponent.displayName = 'Component';\n```\n\n资料来源：[DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)\n\n---\n\n## 总结\n\nApify MCP Server 的组件库与 Widget 系统是一个分层架构：\n\n- **基础层**：通用 UI 组件严格遵循 Design System，确保一致的用户体验\n- **业务层**：ActorCard、ActorStats 等组件封装业务逻辑\n- **应用层**：Widget 整合所有组件，提供完整的用户交互功能\n\n通过导入优化和热重载开发支持，系统在保持功能完整性的同时，实现了较好的性能和开发效率。\n\n---\n\n\n\n## 开发环境配置\n\n### 相关页面\n\n相关主题：[项目简介](#project-introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/apify/apify-mcp-server/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/apify/apify-mcp-server/blob/main/CONTRIBUTING.md)\n- [package.json](https://github.com/apify/apify-mcp-server/blob/main/package.json)\n- [tsconfig.json](https://github.com/apify/apify-mcp-server/blob/main/tsconfig.json)\n- [vitest.config.ts](https://github.com/apify/apify-mcp-server/blob/main/vitest.config.ts)\n- [src/tsconfig.json](https://github.com/apify/apify-mcp-server/blob/main/src/tsconfig.json)\n- [.nvmrc](https://github.com/apify/apify-mcp-server/blob/main/.nvmrc)\n- [.env.example](https://github.com/apify/apify-mcp-server/blob/main/.env.example)\n \n\n# 开发环境配置\n\n## 概述\n\n本文档介绍 apify-mcp-server 项目的开发环境配置方法。该项目是一个基于 Model Context Protocol (MCP) 的服务器实现，用于与 Apify 平台进行交互。开发环境配置涵盖了 Node.js 版本管理、环境变量设置、项目构建流程、测试框架配置以及代码规范遵循等核心内容。\n\n## 环境要求\n\n### Node.js 版本\n\n项目要求 Node.js 版本为 22 或更高版本。版本号通过 `.nvmrc` 文件进行统一管理：\n\n```text\n22\n```\n\n资料来源：[.nvmrc]()\n\n推荐使用 nvm (Node Version Manager) 来管理 Node.js 版本，可通过以下命令切换到正确版本：\n\n```bash\nnvm use\n```\n\n### 包管理器\n\n项目使用 pnpm 作为包管理器。确保本地已安装 pnpm：\n\n```bash\nnpm install -g pnpm\n```\n\n## 环境变量配置\n\n### 必需的环境变量\n\n在项目根目录创建 `.env` 文件，配置以下环境变量：\n\n```text\nAPIFY_TOKEN=\"your-apify-token\"\n```\n\n资料来源：[README.md:10-12]()\n\n`APIFY_TOKEN` 是访问 Apify API 的认证令牌，用于验证用户身份和授权 API 调用。\n\n### 其他配置项\n\n| 环境变量 | 用途 | 示例值 |\n|----------|------|--------|\n| `APIFY_TOKEN` | Apify API 访问令牌 | `your-apify-token` |\n| `APIFY_META_ORIGIN` | 请求来源标识（用于 Standby 模式） | `STANDBY` |\n\n## 项目构建\n\n### 构建流程\n\n项目使用 TypeScript 构建系统。需要先构建项目再运行：\n\n```bash\npnpm run build\n```\n\n资料来源：[README.md:14-16]()\n\n构建过程会将 TypeScript 源码编译为 JavaScript，输出到 `dist` 目录。\n\n### TypeScript 配置\n\n项目采用双层 tsconfig 结构：\n\n#### 根目录配置 (`tsconfig.json`)\n\n```json\n{\n \"compilerOptions\": {\n \"target\": \"ES2022\",\n \"module\": \"NodeNext\",\n \"moduleResolution\": \"NodeNext\",\n \"strict\": true\n }\n}\n```\n\n资料来源：[tsconfig.json]()\n\n#### 源码目录配置 (`src/tsconfig.json`)\n\n```json\n{\n \"extends\": \"../tsconfig.json\",\n \"compilerOptions\": {\n \"outDir\": \"../dist\",\n \"rootDir\": \".\"\n }\n}\n```\n\n资料来源：[src/tsconfig.json]()\n\n## 服务器运行模式\n\n项目支持两种 MCP 服务器运行模式：\n\n### HTTP Streamable 模式\n\n通过 Apify CLI 启动 HTTP 流式传输服务器：\n\n```bash\nexport APIFY_TOKEN=\"your-apify-token\"\nexport APIFY_META_ORIGIN=STANDBY\napify run -p\n```\n\n资料来源：[README.md:19-23]()\n\n服务器启动后暴露在 `http://localhost:3001`，可使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 进行调试。\n\n### 标准输入输出 (stdio) 模式\n\n通过 MCP Inspector 启动标准输入输出模式的服务器：\n\n```bash\nexport APIFY_TOKEN=\"your-apify-token\"\nnpx @modelcontextprotocol/inspector node ./dist/stdio.js\n```\n\n资料来源：[README.md:29-32]()\n\nInspector 会显示一个 URL，可在浏览器中打开进行调试。\n\n## 测试配置\n\n### Vitest 测试框架\n\n项目使用 Vitest 作为测试框架，配置文件为 `vitest.config.ts`：\n\n```typescript\n// vitest.config.ts 配置示例\nimport { defineConfig } from 'vitest/config';\n\nexport default defineConfig({\n test: {\n environment: 'node',\n globals: true,\n },\n});\n```\n\n资料来源：[vitest.config.ts]()\n\n### 运行测试\n\n| 命令 | 描述 |\n|------|------|\n| `pnpm test` | 运行所有测试 |\n| `pnpm test:watch` | 监听模式运行测试 |\n| `pnpm test:coverage` | 运行测试并生成覆盖率报告 |\n\n## 代码规范\n\n### 分支命名规范\n\n功能分支必须遵循 `type/short-description` 格式，其中 type 必须匹配 Conventional Commit 类型：\n\n```text\nfeat/add-dataset-tool\nfix/connection-timeout\nchore/update-dependencies\nrefactor/tool-registry\ndocs/update-readme\n```\n\n资料来源：[CONTRIBUTING.md:8-17]()\n\n### 提交信息规范\n\n所有提交和 PR 标题必须遵循 [Conventional Commits](https://www.conventionalcommits.org/) 格式，**type** 和 **scope** 均为必填项：\n\n```text\nfeat: Add new tool for fetching actor details\nfeat!: Migrate to new MCP SDK version [internal]\nfix: Handle connection errors gracefully\nrefactor: Improve type definitions [ignore]\nchore: Update dependencies\n```\n\n资料来源：[CONTRIBUTING.md:19-32]()\n\n使用 `!` 表示破坏性变更，例如 `feat!: ...`。\n\n### 变量命名规范\n\n| 命名类型 | 规范 | 示例 |\n|----------|------|------|\n| 常量 | 全大写下划线分隔 | `WIDGET_REGISTRY`, `LOG_LEVEL_MAP` |\n| 金额/成本 | 添加单位后缀 | `externalCostUsd`, `intervalMillis` |\n| 日期/时间 | 使用 `At` 后缀 | `updateStartedAt`, `paidAt` |\n| Zod 验证器 | 使用 `Validator` 后缀 | `InputValidator` |\n| 用户可见文本 | 使用品牌术语 `Actor`（大写） | Actor、Actor Run |\n\n资料来源：[CONTRIBUTING.md:42-47]()\n\n### 字符串格式化\n\n- 短的一行字符串使用单引号\n- 多行或超出 `max-len` 的字符串使用 `dedent` 模板字面量\n- 避免在 `dedent` 内插值从列 0 开始的值（如 `JSON.stringify` 输出）\n\n资料来源：[CONTRIBUTING.md:50-58]()\n\n## 集成测试覆盖\n\n项目维护了 MCP 协议各端点的测试覆盖情况，关键测试项包括：\n\n| MCP 协议端点 | 状态 |\n|--------------|------|\n| `tools/list` | ✅ 已覆盖（约 30 个用例） |\n| `tools/call` 正常路径 | ✅ 已覆盖 |\n| `tools/call` 错误处理 | ✅ 已覆盖 |\n| `prompts/list` | ✅ 已覆盖 |\n| `prompts/get` 正常路径 | ✅ 已覆盖 |\n| `logging/setLevel` | ❌ 缺少集成测试 |\n| `ping` | ❌ 缺少集成测试 |\n| `resources/list` | ❌ 仅单元测试 |\n| `resources/read` | ❌ 仅单元测试 |\n\n资料来源：[res/integration_test_coverage_audit.md]()\n\n## 快速启动流程\n\n```mermaid\ngraph TD\n A[安装 Node.js 22+] --> B[安装 pnpm]\n B --> C[克隆仓库]\n C --> D[创建 .env 文件配置 APIFY_TOKEN]\n D --> E[运行 pnpm install]\n E --> F[运行 pnpm run build]\n F --> G[选择运行模式]\n G --> H[HTTP Streamable 模式]\n G --> I[stdio 模式]\n H --> J[使用 MCP Inspector 调试]\n I --> J\n```\n\n## 未认证访问\n\n当 `tools` 查询参数仅包含明确允许未认证使用的工具时，托管服务器允许无令牌访问。当前允许的工具列表：\n\n| 工具名称 | 描述 |\n|----------|------|\n| `search-actors` | 搜索 Actors |\n| `fetch-actor-details` | 获取 Actor 详情 |\n| `search-apify-docs` | 搜索 Apify 文档 |\n| `fetch-apify-docs` | 获取 Apify 文档内容 |\n\n资料来源：[README.md:35-38]()\n\n使用示例：\n```\nhttps://mcp.apify.com?tools=search-actors\n```\n\n## Canary 版本发布\n\nApify MCP 服务器分为两个代码仓库：\n\n- 本仓库 (`apify-mcp-server`)：核心 MCP 逻辑\n- 私有仓库 (`apify-mcp-server-internal`)：托管服务器\n\n创建 canary 版本需要在 PR 分支上添加 `beta` 标签。\n\n资料来源：[README.md:41-47]()\n\n## 总结\n\n开发环境配置的核心要点：\n\n1. **环境版本**：Node.js 22+，pnpm 作为包管理器\n2. **认证配置**：在 `.env` 文件中设置 `APIFY_TOKEN`\n3. **构建流程**：`pnpm run build` 编译 TypeScript\n4. **运行模式**：支持 HTTP Streamable 和 stdio 两种 MCP 协议传输方式\n5. **代码规范**：遵循 Conventional Commits 规范，变量命名需符合类型约定\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：apify/apify-mcp-server\n\n摘要：发现 22 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode。\n\n## 1. 安装坑 · 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix: Allow calling MCP server actors in normal (one-shot) mode\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_be82315ed0f441ba9d942931d846d78c | https://github.com/apify/apify-mcp-server/issues/857 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8ec6ff22f24a4bb18b439177f4a8c270 | https://github.com/apify/apify-mcp-server/issues/892 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：Do not include the rag web browser when ?payment=x402\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Do not include the rag web browser when ?payment=x402\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_23bafe4901554148896241f0a1e183b0 | https://github.com/apify/apify-mcp-server/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：Perf: `search-actors` tools returns huuuge `inputFields` object\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Perf: `search-actors` tools returns huuuge `inputFields` object\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af51cb3cbcb3479fbbdf27cedef734aa | https://github.com/apify/apify-mcp-server/issues/888 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安全/权限坑 · 来源证据：feat(telemetry): track tool result size in bytes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(telemetry): track tool result size in bytes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c2ef77c88914458910ae67d9f903931 | https://github.com/apify/apify-mcp-server/issues/838 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `apify-mcp-server` 与安装入口 `@apify/actors-mcp-server` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令: `npx @apify/actors-mcp-server`\n- 防护动作: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:911256711 | https://github.com/apify/apify-mcp-server | repo=apify-mcp-server; install=@apify/actors-mcp-server\n\n## 7. 安装坑 · 来源证据：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c05c17621e3443dad6175f21db31a34 | https://github.com/apify/apify-mcp-server/issues/894 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：feat: Add structured output to remaining storage tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: Add structured output to remaining storage tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c9b7c39f3e8f43e88ee52c2c8ae94b01 | https://github.com/apify/apify-mcp-server/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 安装坑 · 来源证据：feat: migrate direct actor tools to canonical RunResponse shape\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: migrate direct actor tools to canonical RunResponse shape\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6b304ff2763849fe9b4678cc7bf9f5b2 | https://github.com/apify/apify-mcp-server/issues/852 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 安装坑 · 来源证据：test: Consolidate duplicated MCP server test fixtures\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：test: Consolidate duplicated MCP server test fixtures\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5a7a24d9e8ce42468a7775a54dfa8ca6 | https://github.com/apify/apify-mcp-server/issues/847 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：feat: Dataset tools correctness and coverage\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat: Dataset tools correctness and coverage\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3fa86b498f66434a8f247c1b63fb56c9 | https://github.com/apify/apify-mcp-server/issues/784 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:911256711 | https://github.com/apify/apify-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：chore: Add mixpanel analytics for storage tools + error rates\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chore: Add mixpanel analytics for storage tools + error rates\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_03dbd8daa0c840d690bddb1d52e189c1 | https://github.com/apify/apify-mcp-server/issues/887 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：[Bug]: Inconsistent `search-actors` schema and results\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Inconsistent `search-actors` schema and results\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_364bc036f84b42e8b7be6534cb76381e | https://github.com/apify/apify-mcp-server/issues/889 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：design: Calibrate get-dataset-schema output detail\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：design: Calibrate get-dataset-schema output detail\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b7a4266d8eb4298919b5cb2a58fa420 | https://github.com/apify/apify-mcp-server/issues/882 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：refactor: Extract storage tool helpers\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：refactor: Extract storage tool helpers\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_496f0061952341728e4222b961251325 | https://github.com/apify/apify-mcp-server/issues/890 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：tools/list response contains `type: \"unknown\"` in an input schema — rejected by ajv-based MCP clients (LibreChat)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：tools/list response contains `type: \"unknown\"` in an input schema — rejected by ajv-based MCP clients (LibreChat)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77fae88d35e2486d8125a2ecea9abdc7 | https://github.com/apify/apify-mcp-server/issues/738 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | release_recency=unknown\n\n\n",
"markdown_key": "apify-mcp-server",
"pages": "draft",
"source_refs": [
{
"evidence_id": "github_repo:911256711",
"kind": "repo",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/apify/apify-mcp-server"
},
{
"evidence_id": "art_5baf09b5b64d4527bb2d8936099f5d69",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/apify/apify-mcp-server#readme"
}
],
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "apify-mcp-server 说明书",
"toc": [
"https://github.com/apify/apify-mcp-server 项目说明书",
"目录",
"项目简介",
"概述",
"项目架构",
"MCP 协议实现",
"服务器部署模式",
"Widget 系统",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "a6600017d733743b702f2989008216197b87f0f2",
"repo_inspection_error": null,
"repo_inspection_files": [
"pyproject.toml",
"pnpm-lock.yaml",
"Dockerfile",
"package.json",
"README.md",
"docs/claude-code-tools.json",
"src/stdio.ts",
"src/server_card.ts",
"src/errors.ts",
"src/index.ts",
"src/index_internals.ts",
"src/types.ts",
"src/instrument.ts",
"src/apify_client.ts",
"src/state.ts",
"src/tsconfig.json",
"src/dev_server.ts",
"src/telemetry.ts",
"src/input.ts",
"src/const.ts",
"src/mcp/actors.ts",
"src/mcp/utils.ts",
"src/mcp/server.ts",
"src/mcp/client.ts",
"src/mcp/proxy.ts",
"src/mcp/const.ts",
"src/prompts/latest_news_on_topic.ts",
"src/prompts/index.ts",
"src/payments/skyfire.ts",
"src/payments/resolve.ts",
"src/payments/index.ts",
"src/payments/types.ts",
"src/payments/x402.ts",
"src/payments/helpers.ts",
"src/payments/const.ts",
"src/tools/utils.ts",
"src/tools/categories.ts",
"src/tools/build.ts",
"src/tools/index.ts",
"src/tools/structured_output_schemas.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": [],
"semantic_rework": {
"status": "fallback_patched",
"identity": "mcp_integration",
"source": "semantic_truth_gate",
"source_backed": true,
"semantic_truth_source": "semantic_profile",
"evidence_refs": [
"high_signal_fields"
]
}
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# @apify/actors-mcp-server - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 @apify/actors-mcp-server 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`.claude/skills/bug-triage/SKILL.md`, `.claude/skills/dig/SKILL.md` Claim：`clm_0004` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`.claude/skills/bug-triage/SKILL.md`, `.claude/skills/dig/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n## 怎么开始\n\n- `npx @apify/actors-mcp-server --tools actors,docs,apify/rag-web-browser` 证据：`README.md` Claim：`clm_0005` supported 0.86\n- `npx @apify/actors-mcp-server --tools apify/my-actor` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `npx @apify/actors-mcp-server --ui true` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `npx @apify/actors-mcp-server` 证据：`README.md` Claim：`clm_0005` supported 0.86, `clm_0006` supported 0.86, `clm_0007` supported 0.86, `clm_0008` supported 0.86 等\n- `npx @apify/actors-mcp-server --telemetry-enabled=false` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `npx @modelcontextprotocol/inspector node ./dist/stdio.js` 证据：`README.md` Claim：`clm_0010` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：需要管理员/安全审批\n- **为什么**：继续前可能涉及密钥、账号、外部服务或敏感上下文，建议先经过管理员或安全审批。\n\n### 30 秒判断\n\n- **现在怎么做**：需要管理员/安全审批\n- **最小安全下一步**：先跑 Prompt Preview；若涉及凭证或企业环境，先审批再试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`.claude/skills/bug-triage/SKILL.md`, `.claude/skills/dig/SKILL.md` Claim：`clm_0004` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`.claude/skills/bug-triage/SKILL.md`, `.claude/skills/dig/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0005` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`.claude/skills/bug-triage/SKILL.md`, `.claude/skills/dig/SKILL.md`, `CLAUDE.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`.claude/skills/bug-triage/SKILL.md`, `.claude/skills/dig/SKILL.md`, `CLAUDE.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`\n- **环境变量 / API Key**：项目入口文档明确出现 API key、token、secret 或账号凭证配置。 原因：如果真实安装需要凭证，应先使用测试凭证并经过权限/合规判断。 证据：`.mcp.json`, `CLAUDE.md`, `DEVELOPMENT.md`, `README.md` 等\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **不要使用真实生产凭证**：环境变量/API key 一旦进入宿主或工具链，可能产生账号和合规风险。（适用：出现 API、TOKEN、KEY、SECRET 等环境线索时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **准备撤销测试 API key 或 token**：测试凭证泄露或误用时，可以快速止损。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0011` inferred 0.45\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0012` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`.claude/skills/bug-triage/SKILL.md`, `.claude/skills/dig/SKILL.md` Claim：`clm_0001` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0002` supported 0.86\n\n### 上下文规模\n\n- 文件总数：297\n- 重要文件覆盖：40/297\n- 证据索引条目：77\n- 角色 / Skill 条目：2\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 @apify/actors-mcp-server 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 @apify/actors-mcp-server 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 @apify/actors-mcp-server 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 2 个角色 / Skill / 项目文档条目。\n\n- **bug-triage**（skill）：- 激活提示：当用户任务与“bug-triage”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/bug-triage/SKILL.md`\n- **dig**（skill）：- 激活提示：当用户任务与“dig”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`.claude/skills/dig/SKILL.md`\n\n## 证据索引\n\n- 共索引 77 条证据。\n\n- **Apify MCP server**（documentation）：TypeScript, ES modules. Runs in two modes: stdio local CLI clients, stdio.ts and HTTP Streamable dev server.ts . 证据：`CLAUDE.md`\n- **Table of Contents**（documentation）：The Apify Model Context Protocol MCP server at mcp.apify.com https://mcp.apify.com enables your AI agents to extract data from social media, search engines, maps, e-commerce sites, and any other website using thousands of ready-made scrapers, crawlers, and automation tools from Apify Store https://apify.com/store . It supports OAuth, allowing you to connect from clients like Claude.ai or Visual Studio Code using just the URL. 证据：`README.md`\n- **MCP tool selection evaluation**（documentation）：Evaluates MCP server tool selection. Phoenix is used only for storing results and visualization. 证据：`evals/README.md`\n- **Tests**（documentation）：This directory contains unit and integration tests for the actors-mcp-server project. 证据：`tests/README.md`\n- **Workflow Evaluation System**（documentation）：Tests AI agents performing multi-turn conversations with Apify MCP tools, evaluated by an LLM judge. 证据：`evals/workflows/README.md`\n- **Package**（package_manifest）：{ \"name\": \"@apify/actors-mcp-server\", \"version\": \"0.10.9\", \"type\": \"module\", \"description\": \"Apify MCP Server\", \"mcpName\": \"com.apify/apify-mcp-server\", \"engines\": { \"node\": \" =22.0.0\" }, \"devEngines\": { \"packageManager\": { \"name\": \"pnpm\", \"version\": \"11.1.3\", \"onFail\": \"error\" } }, \"packageManager\": \"pnpm@11.1.3\", \"main\": \"dist/index.js\", \"exports\": { \".\": \"./dist/index.js\", \"./internals\": \"./dist/index internals.js\", \"./internals.js\": \"./dist/index internals.js\", \"./manifest.json\": \"./manifest.json\" }, \"bin\": { \"actors-mcp-server\": \"./dist/stdio.js\" }, \"files\": \"dist\", \"LICENSE\", \"package.json\", \"server.json\", \"manifest.json\" , \"repository\": { \"type\": \"git\", \"url\": \"https://github.com/api… 证据：`package.json`\n- **Contributing Guidelines**（documentation）：Welcome! This document describes how to contribute to this repository. Following these guidelines helps us maintain a clean history, consistent quality, and smooth review process. All pull requests are subject to automated and manual review against these guidelines. 证据：`CONTRIBUTING.md`\n- **Package**（package_manifest）：{ \"name\": \"@apify/mcp-web-widget\", \"version\": \"0.1.0\", \"type\": \"module\", \"scripts\": { \"dev\": \"node build.js --watch\", \"build\": \"node build.js\" }, \"keywords\": , \"author\": \"\", \"license\": \"ISC\", \"description\": \"\", \"dependencies\": { \"@apify/ui-icons\": \"^1.27.2\", \"@apify/ui-library\": \"^1.124.0\", \"@modelcontextprotocol/ext-apps\": \"^1.1.2\", \"pluralize\": \"^8.0.0\", \"react\": \"^18.3.1\", \"react-dom\": \"^18.3.1\", \"styled-components\": \"^6.3.8\" }, \"devDependencies\": { \"@types/pluralize\": \"^0.0.33\", \"@types/react\": \"^19.2.7\", \"@types/react-dom\": \"^19.2.3\", \"autoprefixer\": \"^10.4.20\", \"esbuild\": \"^0.28.0\", \"postcss\": \"^8.4.49\", \"tailwindcss\": \"^3.4.17\", \"typescript\": \"^5.6.3\" } } 证据：`src/web/package.json`\n- **Bug Triage**（skill_instruction）：Triage open bug issues on apify/apify-mcp-server . Analyze, draft responses, get approval, post. 证据：`.claude/skills/bug-triage/SKILL.md`\n- **Dig**（skill_instruction）：Flexible skill for exploring, planning, and speccing work on the Apify MCP server. Do NOT edit source files — this skill is for understanding and planning only. 证据：`.claude/skills/dig/SKILL.md`\n- **Changelog**（documentation）：All notable changes to this project will be documented in this file. 证据：`CHANGELOG.md`\n- **Design System Agent Instructions**（documentation）：CRITICAL : These instructions are MANDATORY for all UI/frontend work. Follow exactly as written. 证据：`DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md`\n- **Development**（documentation）：This repository public provides: - The core MCP server implementation published as an NPM package - The stdio entry point CLI - An Express HTTP server for local development and testing 证据：`DEVELOPMENT.md`\n- **License**（documentation）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE.md`\n- **Failed Cases Analysis & Implementation Guide**（documentation）：Failed Cases Analysis & Implementation Guide 证据：`evals/2025_11_04_failed_cases_analysis.md`\n- **Actor Input Schema: required vs default vs prefill**（documentation）：Actor Input Schema: required vs default vs prefill 证据：`res/actor_input_schema_required_fields.md`\n- **Algolia Search Response Analysis**（documentation）：This document contains insights about Algolia API responses for each documentation source. This information helps understand the data structure returned by Algolia and informs decisions about response processing logic. 证据：`res/algolia.md`\n- **V4 — call-actor redesign RFC**（documentation）：Status: contract being implemented across PRs 823 get-actor-run waitSecs and 825 call-actor waitSecs + storage reshape . Field names below reflect the final shipping shape, not the original draft. Audience: PM and tech lead. No prior reading required — this document is self-contained. 证据：`res/call_actor_redesign_v4.md`\n- **ChatGPT MCP Apps Submission**（documentation）：Status: In Progress Last updated: 2026-03-12 证据：`res/chatgpt-app-submission.md`\n- **Resources Directory Index**（documentation）：This directory contains useful documents and insights about the repository architecture, design decisions, and implementation details that don't belong in code comments or JSDoc. 证据：`res/index.md`\n- **Integration test coverage audit**（documentation）：Audit of tests/integration/suite.ts against the MCP 2025-11-25 spec and the request handlers actually wired in src/mcp/server.ts and src/dev server.ts . Goal: identify protocol-level gaps that block confident deploys, without duplicating SDK or unit tests. 证据：`res/integration_test_coverage_audit.md`\n- **Integration test coverage — implementation plan PR / issue breakdown**（documentation）：Integration test coverage — implementation plan PR / issue breakdown 证据：`res/integration_test_coverage_plan.md`\n- **MCP Resources Implementation Analysis for Apify MCP Server**（documentation）：MCP Resources Implementation Analysis for Apify MCP Server 证据：`res/mcp_resources_analysis.md`\n- **MCP Server Refactoring: Migration to High-Level API**（documentation）：MCP Server Refactoring: Migration to High-Level API 证据：`res/mcp_server_refactor_analysis.md`\n- **MCP Tasks and SDK Features Reference**（documentation）：MCP Tasks and SDK Features Reference 证据：`res/mcp_task_reference.md`\n- **Patterns for Simplifying the Apify MCP Server Codebase**（documentation）：Patterns for Simplifying the Apify MCP Server Codebase 证据：`res/patterns_for_simplification.md`\n- **Pricing output contract**（documentation）：Contract for pricingInfoToStructured and pricingInfoToString in src/utils/pricing info.ts . 证据：`res/pricing_output_contract.md`\n- **tasks/cancel → Actor abort flow**（documentation）：How a client's tasks/cancel request gets translated into an actual apifyClient.run runId .abort call against the Apify platform, and what PR 812 issue 763 changed. 证据：`res/tasks_cancel_abort_flow.md`\n- **Web Widget Bundle Size Notes**（documentation）：The widget bundles in src/web/dist must stay self-contained, but the top-level @apify/ui-library and @apify/ui-icons entrypoints are expensive to bundle. 证据：`res/web-widget-bundle-size.md`\n- **Key principles**（documentation）：You are a development testing agent for the Apify MCP server. Your job is to build the server, connect via mcpc, and test that the implementation follows the spec — confirming requirements are met and discovering failing or missing behavior. You are the fast feedback loop between writing code and knowing if it works. 证据：`.claude/agents/mcpc-tester.md`\n- **.Mcp**（structured_config）：{ \"mcpServers\": { \"storybook\": { \"type\": \"http\", \"url\": \"https://baldasseva--storybook-mcp.apify.actor/mcp?token=${APIFY TOKEN}\" }, \"figma\": { \"type\": \"http\", \"url\": \"https://mcp.figma.com/mcp\" }, \"dev\": { \"type\": \"http\", \"url\": \"http://localhost:3001\", \"headers\": { \"Authorization\": \"Bearer ${APIFY TOKEN}\" } }, \"stdio\": { \"command\": \"node\", \"args\": \"dist/stdio.js\" , \"env\": { \"APIFY TOKEN\": \"${APIFY TOKEN}\", \"NODE EXTRA CA CERTS\": \"${NODE EXTRA CA CERTS}\" } }, \"stdio-full\": { \"command\": \"node\", \"args\": \"dist/stdio.js\", \"--tools=actors,docs,experimental,runs,storage,apify/rag-web-browser\" , \"env\": { \"APIFY TOKEN\": \"${APIFY TOKEN}\", \"NODE EXTRA CA CERTS\": \"${NODE EXTRA CA CERTS}\" } } } } 证据：`.mcp.json`\n- **Claude Code Tools**（structured_config）：{ \"tools\": { \"name\": \"Task\", \"description\": \"Launch a new agent to handle complex, multi-step tasks autonomously. \\n\\nAvailable agent types and the tools they have access to:\\n- general-purpose: General-purpose agent for researching complex questions, searching for code, and executing multi-step tasks. When you are searching for a keyword or file and are not confident that you will find the right match in the first few tries use this agent to perform the search for you. Tools: \\n- statusline-setup: Use this agent to configure the user's Claude Code status line setting. Tools: Read, Edit \\n- output-style-setup: Use this agent to create a Claude Code output style. Tools: Read, Write, Edit, Gl… 证据：`docs/claude-code-tools.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2019\", \"module\": \"ES2022\", \"moduleResolution\": \"bundler\", \"lib\": \"ESNext\" , \"strict\": true, \"esModuleInterop\": true, \"allowSyntheticDefaultImports\": true, \"skipLibCheck\": true, \"noEmit\": true, \"types\": \"vitest/globals\" }, \"include\": \" .ts\" } 证据：`evals/tsconfig.json`\n- **Glama**（structured_config）：{ \"$schema\": \"https://glama.ai/mcp/schemas/server.json\", \"maintainers\": \"jirispilka\", \"mq37\" } 证据：`glama.json`\n- **Manifest**（structured_config）：{ \"manifest version\": \"0.3\", \"name\": \"apify-mcp-server\", \"display name\": \"Apify\", \"version\": \"0.10.9\", \"description\": \"Extract data from any website with thousands of scrapers, crawlers, and automations on Apify Store.\", \"long description\": \"Apify is the world's largest marketplace of tools for web scraping, crawling, data extraction, and web automation. Get structured data from social media, e-commerce, search engines, maps, travel sites, or any other website.\", \"keywords\": \"apify\", \"actors\", \"dataset\", \"mcp\", \"automation\", \"web\", \"web automation\", \"web scraper\", \"web crawler\", \"scraping\", \"crawl\", \"crawler\", \"crawling\", \"ai\", \"data\", \"extraction\", \"bright\", \"fire\", \"data extraction\", \"API… 证据：`manifest.json`\n- **Server**（structured_config）：{ \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\", \"name\": \"com.apify/apify-mcp-server\", \"description\": \"Extract data from any website with thousands of scrapers, crawlers, and automations on Apify Store ⚡\", \"repository\": { \"url\": \"https://github.com/apify/apify-mcp-server\", \"source\": \"github\" }, \"version\": \"0.10.9\", \"remotes\": { \"type\": \"streamable-http\", \"url\": \"https://mcp.apify.com/\", \"headers\": { \"name\": \"Authorization\", \"description\": \"Apify API token for authentication with Apify platform services. For example 'Bearer '\", \"isRequired\": true, \"isSecret\": true } } } 证据：`server.json`\n- **Tsconfig**（structured_config）：{ \"extends\": \"../tsconfig.json\", \"compilerOptions\": { \"rootDir\": \"./\", \"outDir\": \"../dist\", \"noEmit\": false, }, \"include\": \"./ / \" , \"exclude\": \"web\" } 证据：`src/tsconfig.json`\n- **Tsconfig**（structured_config）：{ \"extends\": \"@apify/tsconfig\", \"compilerOptions\": { \"module\": \"ES2022\", \"moduleResolution\": \"Bundler\", \"skipLibCheck\": true, \"noEmit\": true, }, \"include\": \"src/ / \", \"tests/ / \" , \"exclude\": \"src/web\" } 证据：`tsconfig.json`\n- **Results**（structured_config）：{ \"version\": \"1.0\", \"results\": { \"anthropic/claude-haiku-4.5:x-ai/grok-4.1-fast:search-google-maps\": { \"timestamp\": \"2026-01-07T10:59:07.836Z\", \"agentModel\": \"anthropic/claude-haiku-4.5\", \"judgeModel\": \"x-ai/grok-4.1-fast\", \"testId\": \"search-google-maps\", \"verdict\": \"PASS\", \"reason\": \"The agent used the appropriate search-actors tool with correct arguments to find Google Maps-related actors and provided a clear response with more than 3 results, including names and detailed descriptions meeting all requirements.\", \"durationMs\": 15021, \"turns\": 2, \"error\": null }, \"anthropic/claude-haiku-4.5:x-ai/grok-4.1-fast:search-add-python-actor\": { \"timestamp\": \"2026-01-07T10:59:07.837Z\", \"agentModel\":… 证据：`evals/workflows/results.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2020\", \"useDefineForClassFields\": true, \"lib\": \"ES2020\", \"DOM\", \"DOM.Iterable\" , \"module\": \"ESNext\", \"skipLibCheck\": true, \"moduleResolution\": \"bundler\", \"allowSyntheticDefaultImports\": true, \"esModuleInterop\": true, \"resolveJsonModule\": true, \"isolatedModules\": true, \"noEmit\": true, \"jsx\": \"react-jsx\", \"strict\": true, \"noUnusedLocals\": true, \"noUnusedParameters\": true, \"noFallthroughCasesInSwitch\": true, \"types\": }, \"include\": \"src\" } 证据：`src/web/tsconfig.json`\n- **configurations**（source_file）：crawlee and apify storage folders apify storage crawlee storage storage 证据：`.dockerignore`\n- **EditorConfig is a file format and collection of text editor plugins**（source_file）：EditorConfig is a file format and collection of text editor plugins for maintaining consistent coding styles between different editors and IDEs See https://editorconfig.org for more information 证据：`.editorconfig`\n- **EVALS**（source_file）：EVALS PHOENIX API KEY= PHOENIX HOST= 证据：`.env.example`\n- **This file tells Git which files shouldn't be added to source control**（source_file）：This file tells Git which files shouldn't be added to source control 证据：`.gitignore`\n- **.npmignore**（source_file）：.npmignore Exclude everything by default 证据：`.npmignore`\n- **.nvmrc**（source_file）：24 证据：`.nvmrc`\n- **.sentryclirc**（source_file）：defaults org=apify project=apify-mcp 证据：`.sentryclirc`\n- **Stage 1: Build the project**（source_file）：Stage 1: Build the project FROM node:24-alpine AS builder 证据：`Dockerfile`\n- **Apify Logo**（source_file）： 证据：`docs/apify-logo.svg`\n- **Important tool context**（source_file）：/ Configuration for Apify MCP Server evaluations. / 证据：`evals/config.ts`\n- **!/usr/bin/env tsx**（source_file）：!/usr/bin/env tsx / One-time script to create Phoenix dataset from test cases. Run this once to upload test cases to Phoenix platform and receive a dataset ID. / 证据：`evals/create_dataset.ts`\n- **!/usr/bin/env tsx**（source_file）：import dotenv from 'dotenv'; import log from '@apify/log'; import { loadTools, createOpenRouterTask, createToolSelectionLLMEvaluator, loadTestCases, filterById, type TestCase } from './evaluation utils.js'; import { PASS THRESHOLD } from './config.js'; 证据：`evals/eval_single.ts`\n- **Evaluation Utils**（source_file）：/ Shared evaluation utilities extracted from run-evaluation.ts / 证据：`evals/evaluation_utils.ts`\n- **!/usr/bin/env tsx**（source_file）：!/usr/bin/env tsx / Main evaluation script for MCP tool calling TypeScript version . / 证据：`evals/run_evaluation.ts`\n- **Evaluation 2025**（source_file）：{ \"cells\": { \"cell type\": \"markdown\", \"metadata\": { \"id\": \"-CjOraVLBBeV\" }, \"source\": \" MCP Evaluation\\n\", \"\\n\", \" Context\\n\", \"\\n\", \"For the MCP server tool calls evaluation, there are several objectives:\\n\", \"\\n\", \"1. Help to identify problems in the description of the tools\\n\", \"2. Create a test suite that can be run manually or automatically in a CI\\n\", \"3. Allow for quick iteration on the tool descriptions\\n\", \"\\n\", \"We considered several options to evaluate the MCP server tool calls.\\n\", \"\\n\", \"1. ✍️ Create test cases manually \\n\", \"\\n\", \"- Pros: \\n\", \" - Straightforward approach\\n\", \" - Simple to create test cases for each tool\\n\", \"\\n\", \"- Cons: \\n\", \" - A bit complicated to create… 证据：`notebooks/evaluation_2025.ipynb`\n- **Oxlint.Config**（source_file）：import { defineConfig } from '@apify/oxlint-config'; 证据：`oxlint.config.ts`\n- **72-hour quarantine on newly published versions to blunt supply-chain attacks**（source_file）：72-hour quarantine on newly published versions to blunt supply-chain attacks compromised packages typically get yanked within hours of discovery, but the longer window catches slow-detection cases too . Excludes are scopes we publish ourselves and trust on the same release cadence. minimumReleaseAge: 4320 minimumReleaseAgeExclude: - \"@apify/ \" - \"@apify-packages/ \" 证据：`pnpm-workspace.yaml`\n- **Pyproject**（source_file）：project name = \"apify-mcp-evals\" version = \"0.1.0\" description = \"Python evaluations for Apify MCP Server using Arize Phoenix\" requires-python = \" =3.12\" dependencies = \"arize-phoenix =12.5.0\", \"anthropic =0.33.1\", \"openai =1.0.0\", \"pandas =2.0.0\", \"python-dotenv =1.0.0\", \"tqdm =4.65.0\", 证据：`pyproject.toml`\n- **Check Widgets**（source_file）：/ eslint-disable no-console / / Build-time check to ensure widget files exist This script validates that all registered widgets have corresponding files / 证据：`scripts/check_widgets.ts`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node / Dev orchestrator: runs web widget builder in watch mode and the MCP server in standby dev mode. Ensures the server always reads compiled assets from src/web/dist while enabling hot-reload. / 证据：`scripts/dev_standby.js`\n- 其余 17 条证据见 `AI_CONTEXT_PACK.json` 或 `EVIDENCE_INDEX.json`。\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`CLAUDE.md`, `README.md`, `evals/README.md`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`CLAUDE.md`, `README.md`, `evals/README.md`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\n下面内容用于强化 Repomix/AI Context Pack 主体。Human Manual 只提供阅读骨架；踩坑日志会被转成宿主 AI 必须遵守的工作约束。\n\n## Human Manual 骨架\n\n使用规则：这里只是项目阅读路线和显著性信号，不是事实权威。具体事实仍必须回到 repo evidence / Claim Graph。\n\n宿主 AI 硬性规则：\n- 不得把页标题、章节顺序、摘要或 importance 当作项目事实证据。\n- 解释 Human Manual 骨架时，必须明确说它只是阅读路线/显著性信号。\n- 能力、安装、兼容性、运行状态和风险判断必须引用 repo evidence、source path 或 Claim Graph。\n\n- **项目简介**：importance `high`\n - source_paths: README.md, package.json, server.json\n- **系统架构**：importance `high`\n - source_paths: src/index.ts, src/index_internals.ts, src/mcp/server.ts, src/mcp/client.ts, src/state.ts\n- **MCP 协议实现**：importance `high`\n - source_paths: src/mcp/server.ts, src/mcp/client.ts, src/mcp/actors.ts, src/mcp/proxy.ts, src/mcp/utils.ts\n- **Actor 工具系统**：importance `high`\n - source_paths: src/tools/actor_executor.ts, src/tools/core/actor_tools_factory.ts, src/tools/core/call_actor_common.ts, src/tools/default/call_actor.ts, src/tools/default/search_actors.ts\n- **支付系统集成**：importance `medium`\n - source_paths: src/payments/index.ts, src/payments/x402.ts, src/payments/skyfire.ts, src/payments/resolve.ts, src/payments/helpers.ts\n- **存储管理**：importance `medium`\n - source_paths: src/tools/common/get_dataset.ts, src/tools/common/get_dataset_items.ts, src/tools/common/get_dataset_schema.ts, src/tools/common/dataset_collection.ts, src/tools/common/get_key_value_store.ts\n- **遥测与监控**：importance `medium`\n - source_paths: src/telemetry.ts, src/utils/logging.ts, src/utils/progress.ts, .sentryclirc\n- **前端架构**：importance `medium`\n - source_paths: src/web/src/index.css, src/web/src/context/mcp-app-context.tsx, src/web/src/hooks/use-max-height.ts, src/web/src/hooks/use-widget-props.ts, src/web/tailwind.config.js\n\n## Repo Inspection Evidence / 源码检查证据\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `a6600017d733743b702f2989008216197b87f0f2`\n- inspected_files: `pyproject.toml`, `pnpm-lock.yaml`, `Dockerfile`, `package.json`, `README.md`, `docs/claude-code-tools.json`, `src/stdio.ts`, `src/server_card.ts`, `src/errors.ts`, `src/index.ts`, `src/index_internals.ts`, `src/types.ts`, `src/instrument.ts`, `src/apify_client.ts`, `src/state.ts`, `src/tsconfig.json`, `src/dev_server.ts`, `src/telemetry.ts`, `src/input.ts`, `src/const.ts`\n\n宿主 AI 硬性规则：\n- 没有 repo_clone_verified=true 时，不得声称已经读过源码。\n- 没有 repo_inspection_verified=true 时，不得把 README/docs/package 文件判断写成事实。\n- 没有 quick_start_verified=true 时，不得声称 Quick Start 已跑通。\n\n## Doramagic Pitfall Constraints / 踩坑约束\n\n这些规则来自 Doramagic 发现、验证或编译过程中的项目专属坑点。宿主 AI 必须把它们当作工作约束，而不是普通说明文字。\n\n### Constraint 1: 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix: Allow calling MCP server actors in normal (one-shot) mode\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_be82315ed0f441ba9d942931d846d78c | https://github.com/apify/apify-mcp-server/issues/857 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 2: 来源证据：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`\n\n- Trigger: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响升级、迁移或版本选择。\n- Evidence: community_evidence:github | cevd_8ec6ff22f24a4bb18b439177f4a8c270 | https://github.com/apify/apify-mcp-server/issues/892 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 3: 来源证据：Do not include the rag web browser when ?payment=x402\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Do not include the rag web browser when ?payment=x402\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_23bafe4901554148896241f0a1e183b0 | https://github.com/apify/apify-mcp-server/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 4: 来源证据：Perf: `search-actors` tools returns huuuge `inputFields` object\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Perf: `search-actors` tools returns huuuge `inputFields` object\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_af51cb3cbcb3479fbbdf27cedef734aa | https://github.com/apify/apify-mcp-server/issues/888 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 5: 来源证据：feat(telemetry): track tool result size in bytes\n\n- Trigger: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(telemetry): track tool result size in bytes\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能影响授权、密钥配置或安全边界。\n- Evidence: community_evidence:github | cevd_9c2ef77c88914458910ae67d9f903931 | https://github.com/apify/apify-mcp-server/issues/838 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 6: 仓库名和安装名不一致\n\n- Trigger: 仓库名 `apify-mcp-server` 与安装入口 `@apify/actors-mcp-server` 不完全一致。\n- Host AI rule: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- Why it matters: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- Evidence: identity.distribution | github_repo:911256711 | https://github.com/apify/apify-mcp-server | repo=apify-mcp-server; install=@apify/actors-mcp-server\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 7: 来源证据：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_9c05c17621e3443dad6175f21db31a34 | https://github.com/apify/apify-mcp-server/issues/894 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 8: 来源证据：feat: Add structured output to remaining storage tools\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: Add structured output to remaining storage tools\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_c9b7c39f3e8f43e88ee52c2c8ae94b01 | https://github.com/apify/apify-mcp-server/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 9: 来源证据：feat: migrate direct actor tools to canonical RunResponse shape\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: migrate direct actor tools to canonical RunResponse shape\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能阻塞安装或首次运行。\n- Evidence: community_evidence:github | cevd_6b304ff2763849fe9b4678cc7bf9f5b2 | https://github.com/apify/apify-mcp-server/issues/852 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n\n### Constraint 10: 来源证据：test: Consolidate duplicated MCP server test fixtures\n\n- Trigger: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：test: Consolidate duplicated MCP server test fixtures\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_5a7a24d9e8ce42468a7775a54dfa8ca6 | https://github.com/apify/apify-mcp-server/issues/847 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: 不要把这个坑点包装成已解决、已验证或可忽略，除非后续验证证据明确证明它已经关闭。\n",
"summary": "给宿主 AI 的上下文和工作边界。",
"title": "AI Context Pack / 带给我的 AI"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card / 安装前决策卡\n\n项目：apify/apify-mcp-server\n\n## Doramagic 试用结论\n\n当前结论：可以进入发布前推荐检查；首次使用仍应从最小权限、临时目录和可回滚配置开始。\n\n## 用户现在可以做\n\n- 可以先阅读 Human Manual，理解项目目的和主要工作流。\n- 可以复制 Prompt Preview 做安装前体验；这只验证交互感，不代表真实运行。\n- 可以把官方 Quick Start 命令放到隔离环境中验证，不要直接进主力环境。\n\n## 现在不要做\n\n- 不要把 Prompt Preview 当成项目实际运行结果。\n- 不要把 metadata-only validation 当成沙箱安装验证。\n- 不要把未验证能力写成“已支持、已跑通、可放心安装”。\n- 不要在首次试用时交出生产数据、私人文件、真实密钥或主力配置目录。\n\n## 安装前检查\n\n- 宿主 AI 是否匹配：mcp_host\n- 官方安装入口状态：已发现官方入口\n- 是否在临时目录、临时宿主或容器中验证：必须是\n- 是否能回滚配置改动：必须能\n- 是否需要 API Key、网络访问、读写文件或修改宿主配置：未确认前按高风险处理\n- 是否记录了安装命令、实际输出和失败日志：必须记录\n\n## 当前阻塞项\n\n- 无阻塞项。\n\n## 项目专属踩坑\n\n- 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode（high）：可能增加新用户试用和生产接入成本。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`（high）：可能影响升级、迁移或版本选择。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Do not include the rag web browser when ?payment=x402（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：Perf: `search-actors` tools returns huuuge `inputFields` object（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 来源证据：feat(telemetry): track tool result size in bytes（high）：可能影响授权、密钥配置或安全边界。 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n\n## 风险与权限提示\n\n- no_demo: medium\n\n## 证据缺口\n\n- 暂未发现结构化证据缺口。\n",
"summary": "安装、权限、验证和推荐前风险。",
"title": "Boundary & Risk Card / 边界与风险卡"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/apify/apify-mcp-server 项目说明书\n\n生成时间: 2026-05-21 17:02:07 UTC\n\n## 目录\n\n- [项目简介](#project-introduction)\n- [系统架构](#system-architecture)\n- [MCP 协议实现](#mcp-protocol-implementation)\n- [Actor 工具系统](#actor-tools-system)\n- [支付系统集成](#payment-systems)\n- [存储管理](#storage-management)\n- [遥测与监控](#telemetry-monitoring)\n- [前端架构](#frontend-architecture)\n- [组件库与 Widget](#widget-components)\n- [开发环境配置](#development-setup)\n\n\n\n## 项目简介\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [MCP 协议实现](#mcp-protocol-implementation), [开发环境配置](#development-setup)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/apify/apify-mcp-server/blob/main/README.md)\n- [src/resources/resource_service.ts](https://github.com/apify/apify-mcp-server/blob/main/src/resources/resource_service.ts)\n- [res/algolia.md](https://github.com/apify/apify-mcp-server/blob/main/res/algolia.md)\n- [res/mcp_resources_analysis.md](https://github.com/apify/apify-mcp-server/blob/main/res/mcp_resources_analysis.md)\n- [res/patterns_for_simplification.md](https://github.com/apify/apify-mcp-server/blob/main/res/patterns_for_simplification.md)\n- [src/web/index.html](https://github.com/apify/apify-mcp-server/blob/main/src/web/index.html)\n- [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](https://github.com/apify/apify-mcp-server/blob/main/DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)\n \n\n# 项目简介\n\n## 概述\n\nApify MCP Server 是 Apify 平台提供的 Model Context Protocol（MCP）服务器实现，用于将 Apify 的 Actor 和文档搜索能力以标准化的 MCP 协议接口暴露给 AI 助手使用。\n\n该项目的主要目标是为 AI 助手提供一种标准化的方式来调用 Apify 平台上的各种服务，包括 Actor 搜索、Actor 详情获取、以及 Apify 文档的搜索和获取功能。\n\n## 项目架构\n\n### 核心架构图\n\n```mermaid\ngraph TD\n subgraph \"MCP 客户端\"\n A[AI 助手 / Claude]\n end\n \n subgraph \"Apify MCP Server\"\n B[HTTP Streamable Server
:3001]\n C[stdio Server]\n D[工具层 Tools]\n E[资源层 Resources]\n F[提示层 Prompts]\n end\n \n subgraph \"Apify 平台\"\n G[Actors API]\n H[Algolia 搜索]\n I[文档 API]\n end\n \n A -->|MCP 协议| B\n A -->|MCP 协议| C\n B --> D\n C --> D\n D --> G\n D --> H\n E -->|Widget 资源| I\n \n style B fill:#e1f5fe\n style C fill:#e1f5fe\n```\n\n### 核心组件\n\n| 组件 | 说明 | 源码位置 |\n|------|------|----------|\n| HTTP Streamable Server | 支持 HTTP 流式传输的 MCP 服务器 | `server.ts` |\n| stdio Server | 标准输入输出的 MCP 服务器 | `stdio.ts` |\n| 工具处理器 | 处理 MCP 工具调用 | `src/tools/` |\n| 资源处理器 | 管理 MCP 资源读写 | `src/resources/` |\n| Widget 系统 | 提供 UI Widget 组件 | `src/web/` |\n\n资料来源：[README.md]()\n\n## MCP 协议实现\n\n### 支持的协议方法\n\nApify MCP Server 实现了完整的 MCP 协议规范，包括以下核心方法：\n\n| 方法类别 | 支持的方法 | 状态 |\n|----------|------------|------|\n| 工具 Tools | `tools/list`, `tools/call` | ✅ 完全支持 |\n| 资源 Resources | `resources/list`, `resources/read`, `resources/templates/list` | ✅ 已实现 |\n| 提示 Prompts | `prompts/list`, `prompts/get` | ✅ 已实现 |\n| 任务 Tasks | `tasks/list`, `tasks/get`, `tasks/cancel`, `tasks/result` | ✅ 已实现 |\n| 日志 Logging | `logging/setLevel` | ✅ 已实现 |\n| 通知 Notifications | `tools/list_changed`, `cancelled`, `progress` | ✅ 部分支持 |\n\n资料来源：[res/mcp_resources_analysis.md]()\n\n### 工具列表\n\nMCP 服务器暴露以下主要工具供 AI 助手调用：\n\n| 工具名称 | 功能描述 | 认证要求 |\n|----------|----------|----------|\n| `search-actors` | 搜索 Apify 平台上的 Actors | 无需认证 |\n| `fetch-actor-details` | 获取指定 Actor 的详细信息 | 需要 API Token |\n| `search-apify-docs` | 搜索 Apify 官方文档 | 无需认证 |\n| `fetch-apify-docs` | 获取指定文档页面内容 | 无需认证 |\n\n资料来源：[README.md]()\n\n## 服务器部署模式\n\n### HTTP Streamable 模式\n\nHTTP Streamable 是推荐的部署方式，适用于生产环境和远程访问场景。\n\n**启动命令：**\n\n```bash\nexport APIFY_TOKEN=\"your-apify-token\"\nexport APIFY_META_ORIGIN=STANDBY\napify run -p\n```\n\n服务默认运行在 `http://localhost:3001`，可通过 MCP Inspector 进行调试：\n\n```bash\nnpx @modelcontextprotocol/inspector\n```\n\n资料来源：[README.md]()\n\n### stdio 标准输入输出模式\n\nstdio 模式适用于本地集成和命令行工具场景。\n\n**启动命令：**\n\n```bash\nexport APIFY_TOKEN=\"your-apify-token\"\nnpx @modelcontextprotocol/inspector node ./dist/stdio.js\n```\n\n### 无认证访问\n\n当 `tools` 查询参数仅包含允许无认证使用的工具时，托管服务器允许无 API Token 访问：\n\n```\nhttps://mcp.apify.com?tools=search-actors,fetch-actor-details,search-apify-docs,fetch-apify-docs\n```\n\n资料来源：[README.md]()\n\n## Widget 系统\n\n### 概述\n\n项目包含一套完整的 Widget 系统，通过 MCP 资源的 `ui://widget/` URI 前缀提供。\n\n**工作流程：**\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as MCP Server\n participant FS as 文件系统\n \n Client->>Server: resources/read ui://widget/actor-search\n Server->>FS: 读取 widget JS 文件\n FS-->>Server: widget.js 内容\n Server->>Server: 包装为 HTML 页面\n Server-->>Client: HTML 资源内容\n```\n\n资料来源：[src/resources/resource_service.ts]()\n资料来源：[res/mcp_resources_analysis.md]()\n\n### 可用 Widget\n\n| Widget | 文件路径 | 功能描述 |\n|--------|----------|----------|\n| Actor Search | `/dist/search-actors-widget.js` | Actor 搜索界面组件 |\n| Actor Run | `/dist/actor-run-widget.js` | Actor 运行状态显示 |\n| Actor Detail | `/dist/actor-detail-widget.js` | Actor 详情展示 |\n\n资料来源：[src/web/index.html]()\n\n### Widget 开发规范\n\nWidget 开发需遵循以下设计系统规范：\n\n**样式规范：**\n\n```typescript\n// ✅ 使用主题 token\ncolor: ${theme.color.primary.action}\npadding: ${theme.space.space8}\n\n// ❌ 禁止硬编码值\ncolor: '#1976d2'\npadding: '8px'\n```\n\n**组件导入规范：**\n\n```typescript\n// ✅ 从 ui-library 导入\nimport { Button, Badge, Chip } from '@apify/ui-library';\n\n// ❌ 禁止创建重复组件\n// ❌ 禁止使用相对路径导入\n```\n\n资料来源：[DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md]()\n\n## 文档搜索集成\n\n### Algolia 搜索处理\n\n项目使用 Algolia 作为文档搜索的后端，对搜索结果进行了标准化处理：\n\n**响应处理示例：**\n\n```json\n// 原始 Algolia 响应\n{\n \"url_without_anchor\": \"https://docs.apify.com/platform/actors\",\n \"anchor\": \"actors-overview\",\n \"content\": \"Actors are serverless cloud programs...\"\n}\n\n// 处理后结果\n{\n \"url\": \"https://docs.apify.com/platform/actors#actors-overview\",\n \"content\": \"Actors are serverless cloud programs that can perform anything...\"\n}\n```\n\n资料来源：[res/algolia.md]()\n\n### 特殊处理规则\n\n- **Apify 文档**：支持带锚点的 URL 片段，可访问同一页面的不同章节\n- **Crawlee 文档**：不提供 content 字段，仅返回 URL\n\n资料来源：[res/algolia.md]()\n\n## 内部工具架构\n\n### 工具参数传递\n\n项目采用统一的 `InternalToolArgs` 类型传递工具执行所需的上下文信息：\n\n```typescript\ntype InternalToolArgs = {\n args: Record; // 工具参数\n extra: RequestHandlerExtra; // MCP 请求上下文\n apifyMcpServer: ActorsMcpServer; // 服务器实例\n mcpServer: Server; // MCP 协议服务器\n apifyToken: string; // 认证令牌\n userRentedActorIds?: string[]; // 用户租用的 Actor\n progressTracker?: ProgressTracker; // 进度追踪器\n};\n```\n\n资料来源：[res/patterns_for_simplification.md]()\n\n## 构建与部署\n\n### 构建流程\n\n```bash\n# 安装依赖\npnpm install\n\n# 构建项目\npnpm run build\n```\n\n### 开发服务器\n\n项目提供开发服务器用于本地测试：\n\n- HTTP Streamable：`dev_server.ts`\n- 支持会话管理和进度追踪\n\n资料来源：[res/integration_test_coverage_audit.md]()\n\n## 相关文档\n\n- [贡献指南](./CONTRIBUTING.md) - 代码规范和提交流程\n- [集成测试覆盖审计](./res/integration_test_coverage_audit.md) - 测试状态报告\n- [MCP 资源分析](./res/mcp_resources_analysis.md) - 资源处理详细说明\n- [设计系统规范](./DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md) - UI 组件开发指南\n\n---\n\n\n\n## 系统架构\n\n### 相关页面\n\n相关主题：[项目简介](#project-introduction), [MCP 协议实现](#mcp-protocol-implementation), [前端架构](#frontend-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/index.ts](https://github.com/apify/apify-mcp-server/blob/main/src/index.ts)\n- [src/index_internals.ts](https://github.com/apify/apify-mcp-server/blob/main/src/index_internals.ts)\n- [src/mcp/server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n- [src/mcp/client.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/client.ts)\n- [src/state.ts](https://github.com/apify/apify-mcp-server/blob/main/src/state.ts)\n- [src/resources/resource_service.ts](https://github.com/apify/apify-mcp-server/blob/main/src/resources/resource_service.ts)\n \n\n# 系统架构\n\n## 概述\n\nApify MCP Server 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在为 AI 模型提供访问 Apify 平台能力的标准化接口。该服务器通过 MCP 协议暴露工具（Tools）、资源（Resources）、提示（Prompts）和任务（Tasks）等能力，使 AI 代理能够与 Apify 平台进行交互。\n\n## 核心架构组件\n\n```mermaid\ngraph TB\n subgraph \"客户端层\"\n MCP_Client[\"MCP Client SDK\"]\n AI_Agent[\"AI Agent\"]\n end\n \n subgraph \"服务器层\"\n Server[\"MCP Server\"]\n Transport[\"Transport Layer\"]\n Handler[\"Request Handler\"]\n end\n \n subgraph \"服务层\"\n Tools[\"Tools Service\"]\n Resources[\"Resources Service\"]\n Prompts[\"Prompts Service\"]\n Tasks[\"Tasks Service\"]\n end\n \n subgraph \"Apify 平台\"\n APIFY_API[\"Apify API\"]\n Actors[\"Actors\"]\n Docs[\"Apify Docs\"]\n Search[\"Algolia Search\"]\n end\n \n MCP_Client -->|MCP Protocol| Transport\n AI_Agent -->|LLM Requests| MCP_Client\n Transport --> Handler\n Handler --> Tools\n Handler --> Resources\n Handler --> Prompts\n Handler --> Tasks\n Tools --> APIFY_API\n Resources --> Widgets\n Prompts -->|预定义模板| APIFY_API\n Tasks --> Actors\n```\n\n## 传输层架构\n\n### 支持的传输方式\n\n| 传输类型 | 描述 | 配置方式 |\n|---------|------|----------|\n| stdio | 标准输入输出传输，适用于本地 CLI 工具 | `node ./dist/stdio.js` |\n| Streamable HTTP | HTTP 流式传输，适用于 Web 服务 | `apify run -p` (端口 3001) |\n| Server-Sent Events | 服务器推送事件，用于实时通知 | 与 HTTP 传输配合使用 |\n\nMCP 服务器支持多种传输层实现，核心服务器代码位于 `src/mcp/server.ts`，负责处理来自不同客户端的请求并路由到相应的服务处理程序。\n\n### 会话管理\n\nStreamable HTTP 传输实现了完整的会话管理机制：\n\n- 会话标识通过 `Mcp-Session-Id` HTTP 头传递\n- 支持会话终止的 `DELETE /` 端点\n- 每个会话维护独立的上下文状态\n\n## 工具服务架构\n\n### 工具注册与发现\n\n```mermaid\ngraph LR\n Server_Start[\"服务器启动\"] --> Load_Tools[\"加载工具定义\"]\n Load_Tools --> Register[\"注册到 MCP Server\"]\n Register --> List_Tools[\"tools/list\"]\n Client_Request[\"客户端请求\"] --> List_Tools\n List_Tools --> Tool_Meta[\"返回工具元数据
包含 ui.* 属性用于 MCP Apps\"]\n```\n\n### 核心工具列表\n\n| 工具名称 | 功能描述 | 认证要求 |\n|---------|---------|---------|\n| `search-actors` | 搜索 Apify Actors | 可选 |\n| `fetch-actor-details` | 获取 Actor 详细信息 | 可选 |\n| `search-apify-docs` | 搜索 Apify 文档 | 可选 |\n| `fetch-apify-docs` | 获取文档内容 | 可选 |\n| `add-actor` | 添加 Actor | 必需 |\n| 其他动态工具 | 根据配置动态注册 | 必需 |\n\n资料来源：[res/integration_test_coverage_audit.md](https://github.com/apify/apify-mcp-server/blob/main/res/integration_test_coverage_audit.md)\n\n### 工具调用流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server\n participant Tools\n participant ApifyAPI\n \n Client->>Server: tools/call\n Server->>Tools: 路由请求\n Tools->>ApifyAPI: API 调用\n ApifyAPI-->>Tools: 响应数据\n Tools-->>Server: 处理结果\n Server-->>Client: 返回结果\n \n Note over Tools: AJV 验证输入参数\n Note over Server: 支持 progressToken 进度追踪\n```\n\n工具调用支持以下功能：\n\n- **参数验证**：使用 AJV 进行 JSON Schema 验证\n- **进度追踪**：通过 `progressToken` 发送 `notifications/progress`\n- **错误处理**：返回 `isError: true` 的 content 类型\n- **取消通知**：Streamable HTTP 模式下支持 `notifications/cancelled`\n\n## 资源服务架构\n\n### 资源类型\n\n| 资源类型 | URI 模式 | 描述 |\n|---------|---------|------|\n| README | `file://readme.md` | 使用指南内容 |\n| Widget | `ui://widget/*` | UI 小部件资源 |\n| 动态资源 | 自定义 URI | 根据配置扩展 |\n\n资源服务实现位于 `src/resources/resource_service.ts`，提供了以下核心功能：\n\n```typescript\n// 资源读取逻辑\nreadResource(uri) {\n if (uri === 'file://readme.md') {\n return Provider?.getUsageGuide?.() || '';\n }\n \n if (uri.startsWith('ui://widget/')) {\n return loadWidgetContent(uri);\n }\n}\n```\n\n资料来源：[src/resources/resource_service.ts](https://github.com/apify/apify-mcp-server/blob/main/src/resources/resource_service.ts)\n\n### Widget 服务\n\n```mermaid\ngraph TD\n Widget_Request[\"ui://widget/* 请求\"] --> Check_Registry[\"检查 Widget 注册表\"]\n Check_Registry --> Widget_Exists{Widget 存在?}\n Widget_Exists -->|是| Read_File[\"读取 JS 文件\"]\n Widget_Exists -->|否| Return_Error[\"返回错误信息\"]\n Read_File --> Build_HTML[\"构建 HTML 包装\"]\n Build_HTML --> Return_Widget[\"返回 Widget 内容
mimeType: RESOURCE_MIME_TYPE\"]\n```\n\nWidget 通过文件系统直接读取 JS 文件，并包装在 HTML 文档中返回给客户端。\n\n## 状态管理\n\n### 全局状态结构\n\n```mermaid\ngraph LR\n State[\"全局状态\"] --> Actors[\"Actor 缓存\"]\n State --> Sessions[\"会话状态\"]\n State --> Config[\"配置信息\"]\n State --> APIFY[\"Apify 客户端实例\"]\n```\n\n状态管理模块 `src/state.ts` 负责维护：\n\n- **Actor 缓存**：已加载的 Actor 列表及其元数据\n- **会话状态**：HTTP 会话标识与上下文映射\n- **配置信息**：环境变量与服务端点配置\n- **API 客户端**：Apify API 客户端单例\n\n### 服务器模式\n\n| 模式 | 描述 | 适用场景 |\n|-----|------|---------|\n| `APPS` | MCP Apps 集成模式 | 与 MCP Apps 平台配合使用 |\n| 标准模式 | 默认 MCP 服务器 | 标准 MCP 客户端连接 |\n\n模式检测影响以下行为：\n\n- Widget 注册与加载\n- 资源 URI 处理\n- 特定于 Apps 的元数据注入\n\n## 客户端集成\n\n### 客户端架构\n\n```mermaid\ngraph TB\n subgraph \"MCP Client\"\n Transport_Client[\"Transport\"]\n Request_Queue[\"请求队列\"]\n Response_Handler[\"响应处理器\"]\n end\n \n MCP_Client -->|发送请求| Server\n Server -->|接收响应| MCP_Client\n```\n\n客户端实现位于 `src/mcp/client.ts`，提供了：\n\n- **连接管理**：与 MCP 服务器建立和维护连接\n- **请求序列化**：将调用序列化为 MCP 协议格式\n- **响应解析**：解析服务器响应并返回给调用方\n\n## Web Widget 系统\n\n### Widget 类型\n\n| Widget 名称 | 入口文件 | 用途 |\n|------------|---------|------|\n| Actor Search | `index-actor-search.html` | 搜索 Actors |\n| Actor Run | `index-actor-run.html` | 展示 Actor 运行状态 |\n| Actor Detail | `actor-detail.html` | 显示 Actor 详细信息 |\n\n### Widget 加载流程\n\n```mermaid\nsequenceDiagram\n participant Browser\n participant HTML\n participant Bundle\n participant Component\n \n Browser->>HTML: 加载页面\n HTML->>Bundle: 加载 /dist/*.js\n Bundle->>Component: React 组件渲染\n Component->>Browser: 显示 Widget UI\n```\n\n开发预览页面 `src/web/index.html` 提供了所有可用 Widget 的访问入口。\n\n## 模块依赖关系\n\n```mermaid\ngraph TD\n Index[\"src/index.ts\"] --> Index_Internals[\"src/index_internals.ts\"]\n Index_Internals --> Server[\"src/mcp/server.ts\"]\n Index_Internals --> State[\"src/state.ts\"]\n Server --> Client[\"src/mcp/client.ts\"]\n Server --> Resources[\"src/resources/resource_service.ts\"]\n Server --> Tools[\"Tools Service\"]\n Server --> Prompts[\"Prompts Service\"]\n Server --> Tasks[\"Tasks Service\"]\n```\n\n## 部署架构\n\n### 服务启动流程\n\n```mermaid\nflowchart TD\n Start[\"启动命令\"] --> Check_Mode{\"检测模式\"}\n Check_Mode -->|STDIO| Start_STDIO[\"初始化 STDIO 传输\"]\n Check_Mode -->|HTTP| Start_HTTP[\"初始化 HTTP 传输\"]\n Check_Mode -->|CLI| Start_CLI[\"CLI 交互模式\"]\n \n Start_STDIO --> Register_Server[\"注册 MCP Handlers\"]\n Start_HTTP --> Register_Server\n Start_CLI --> Register_Server\n \n Register_Server --> Load_Config[\"加载配置\"]\n Load_Config --> Init_State[\"初始化状态\"]\n Init_State --> Ready[\"服务器就绪\"]\n```\n\n### 环境配置\n\n| 环境变量 | 描述 | 必需 |\n|---------|------|-----|\n| `APIFY_TOKEN` | Apify API 访问令牌 | 对于受保护工具必需 |\n| `APIFY_META_ORIGIN` | 请求来源标识 | 可选 |\n| `PORT` | HTTP 服务端口 | HTTP 模式必需 |\n\n未授权访问仅在 `tools` 查询参数仅包含明确允许的工具时可用（`search-actors`、`fetch-actor-details`、`search-apify-docs`、`fetch-apify-docs`）。\n\n资料来源：[README.md](https://github.com/apify/apify-mcp-server/blob/main/README.md)\n\n## 安全考虑\n\n### 认证流程\n\n```mermaid\ngraph LR\n Request[\"请求\"] --> Check_Tool{\"工具检查\"}\n Check_Tool -->|公开工具| Allow[\"允许访问\"]\n Check_Tool -->|受保护工具| Check_Auth{\"认证检查\"}\n Check_Auth -->|有效 Token| Allow\n Check_Auth -->|无效 Token| Deny[\"返回错误\"]\n```\n\n### 错误处理\n\n| 错误类型 | HTTP 状态 | 处理方式 |\n|---------|----------|---------|\n| AJV 验证失败 | JSON-RPC Error | 返回 InvalidParams |\n| 未知工具名 | JSON-RPC Error | 错误码 -32601 |\n| 认证失败 | 401 | 返回错误信息 |\n| 禁止的 URL | 403 | 返回 isError: true |\n\n## 扩展性设计\n\n### 添加新工具\n\n1. 在工具注册表中定义工具 schema\n2. 实现工具处理函数\n3. 注册到 MCP Server\n4. 添加相应的测试用例\n\n### 添加新资源\n\n1. 实现 `readResource` 处理器\n2. 在资源注册表中添加条目\n3. 处理相应的 URI 模式\n\n### 添加新 Widget\n\n1. 在 `src/web/src/pages/` 中创建组件\n2. 配置构建输出到 `/dist/`\n3. 注册到 Widget 注册表\n4. 添加 HTML 入口文件\n\n---\n\n\n\n## MCP 协议实现\n\n### 相关页面\n\n相关主题：[系统架构](#system-architecture), [Actor 工具系统](#actor-tools-system), [前端架构](#frontend-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/mcp/server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/server.ts)\n- [src/mcp/client.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/client.ts)\n- [src/mcp/actors.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/actors.ts)\n- [src/mcp/proxy.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/proxy.ts)\n- [src/mcp/utils.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/utils.ts)\n- [src/mcp/const.ts](https://github.com/apify/apify-mcp-server/blob/main/src/mcp/const.ts)\n- [src/resources/resource_service.ts](https://github.com/apify/apify-mcp-server/blob/main/src/resources/resource_service.ts)\n- [res/mcp_resources_analysis.md](https://github.com/apify/apify-mcp-server/blob/main/res/mcp_resources_analysis.md)\n- [res/integration_test_coverage_audit.md](https://github.com/apify/apify-mcp-server/blob/main/res/integration_test_coverage_audit.md)\n \n\n# MCP 协议实现\n\n## 概述\n\nApify MCP Server 是 Apify 平台的 Model Context Protocol (MCP) 实现，为 LLM 提供与 Apify 平台交互的能力。该服务器基于 MCP TypeScript SDK 构建，支持多种传输协议和功能模块，使 AI 助手能够直接调用 Apify Actors、搜索文档、管理任务等操作。\n\n项目采用模块化架构，核心实现位于 `src/mcp/` 目录下，包含服务器初始化、客户端代理、工具定义等关键组件。\n\n## 架构设计\n\n### 整体架构\n\n```mermaid\ngraph TD\n A[MCP Client
Claude Desktop/其他客户端] --> B[Transport Layer
stdio / Streamable HTTP]\n B --> C[MCP Server
server.ts]\n C --> D[Tool Handlers
actors.ts]\n C --> E[Resource Handlers
resource_service.ts]\n C --> F[Prompt Handlers
prompts.ts]\n C --> G[Proxy Layer
proxy.ts]\n D --> H[Apify API]\n G --> H\n```\n\n### 核心模块职责\n\n| 模块 | 文件路径 | 职责 |\n|------|----------|------|\n| server.ts | `src/mcp/server.ts` | 服务器主入口，负责初始化 MCP Server 实例，注册各类处理器 |\n| client.ts | `src/mcp/client.ts` | MCP 客户端封装，处理与远程 MCP 服务器的通信 |\n| actors.ts | `src/mcp/actors.ts` | Actor 相关工具定义和执行逻辑 |\n| proxy.ts | `src/mcp/proxy.ts` | 代理层实现，用于转发请求和中间处理 |\n| utils.ts | `src/mcp/utils.ts` | 通用工具函数库 |\n| const.ts | `src/mcp/const.ts` | 常量定义 |\n\n资料来源：[res/mcp_resources_analysis.md]()\n\n## 传输层支持\n\n### stdio 传输模式\n\n标准输入输出传输，适用于本地调试和 CLI 工具集成。\n\n```bash\nnpx @modelcontextprotocol/inspector node ./dist/stdio.js\n```\n\n### Streamable HTTP 传输模式\n\n支持 HTTP 流式传输，适用于 Web 服务和远程部署。\n\n```bash\nexport APIFY_TOKEN=\"your-apify-token\"\nexport APIFY_META_ORIGIN=STANDBY\napify run -p\n```\n\n服务器默认暴露在 `http://localhost:3001`。\n\n资料来源：[README.md:1-50]()\n\n## 工具实现 (Tools)\n\n### 工具列表\n\nMCP Server 通过 `tools/list` 端点暴露以下工具：\n\n| 工具名称 | 功能描述 | 认证要求 |\n|----------|----------|----------|\n| `search-actors` | 搜索 Apify Actors | 公开可用 |\n| `fetch-actor-details` | 获取指定 Actor 详情 | 公开可用 |\n| `search-apify-docs` | 搜索 Apify 文档 | 公开可用 |\n| `fetch-apify-docs` | 获取指定文档内容 | 需要认证 |\n| `add-actor` | 添加/创建 Actor | 需要认证 |\n| `run-actor` | 运行 Actor | 需要认证 |\n\n资料来源：[res/integration_test_coverage_audit.md]()\n资料来源：[README.md:35-40]()\n\n### 工具调用流程\n\n```mermaid\nsequenceDiagram\n participant Client\n participant Server as MCP Server\n participant API as Apify API\n \n Client->>Server: tools/call { name, arguments }\n Server->>Server: AJV Validation\n alt Validation Failed\n Server-->>Client: InvalidParams Error\n else Validation Passed\n Server->>API: Execute Tool\n API-->>Server: Response\n Server->>Server: Format Result\n Server-->>Client: Tool Result\n end\n```\n\n### 工具元数据 (ui.*)\n\nMCP Server 为 MCP Apps 模式提供扩展元数据，通过 `_meta` 字段包含 UI 相关信息：\n\n```typescript\n{\n contents: [{\n uri: 'tool://...',\n text: '...',\n _meta: {\n ui: {\n mode: 'openai',\n // 其他 UI 渲染信息\n }\n }\n }]\n}\n```\n\n资料来源：[res/integration_test_coverage_audit.md]()\n\n## 资源系统 (Resources)\n\n### 资源类型\n\n| 资源类型 | URI 前缀 | 描述 |\n|----------|----------|------|\n| Usage Guide | `file://readme.md` | 使用指南内容 |\n| UI Widget | `ui://widget/` | 嵌入式 UI 组件 |\n\n资料来源：[src/resources/resource_service.ts]()\n资料来源：[res/mcp_resources_analysis.md]()\n\n### 资源读取处理\n\n```typescript\n// 资源读取主流程\nconst readResource = async (uri: string): Promise => {\n // 1. 检查 usage guide\n if (uri === 'file://readme.md') {\n return { contents: [{ uri, mimeType: 'text/markdown', text: usageGuide }] };\n }\n \n // 2. 检查 UI widget\n if (uri.startsWith('ui://widget/')) {\n // 加载 widget JS 文件并包装为 HTML\n }\n \n // 3. 未找到资源\n return { contents: [{ uri, mimeType: 'text/plain', text: `Resource ${uri} not found` }] };\n};\n```\n\n资料来源：[src/resources/resource_service.ts]()\n\n### UI Widget 加载\n\nWidget 资源读取流程：\n\n1. 从 Widget 注册表获取 widget 元信息\n2. 验证 widget 文件是否存在\n3. 读取 widget JS 文件内容\n4. 将 JS 包装在 HTML 模板中返回\n\n```typescript\nconst widgetHtml = `\n\n \n \n ${widget.title}\n \n \n \n \n \n`;\n```\n\n资料来源：[src/resources/resource_service.ts]()\n\n## 任务系统 (Tasks)\n\n### 任务端点\n\n| 端点 | 描述 | 支持操作 |\n|------|------|----------|\n| `tasks/list` | 列出所有任务 | 同步流式响应 |\n| `tasks/get` | 获取任务详情 | 包含状态消息 |\n| `tasks/cancel` | 取消任务 | 即时终止 |\n| `tasks/result` | 获取任务结果 | 返回执行结果 |\n\n资料来源：[res/integration_test_coverage_audit.md]()\n\n### 进度跟踪\n\nMCP Server 支持通过 `progressToken` 进行实时进度通知：\n\n```typescript\nconst createProgressTracker = (progressToken: ProgressToken) => {\n return {\n report: (progress: Progress) => {\n // 发送进度通知到客户端\n }\n };\n};\n```\n\n## 提示系统 (Prompts)\n\n### 可用提示\n\n| 提示名称 | 描述 |\n|----------|------|\n| `GetLatestNewsOnTopic` | 获取指定主题的最新新闻 |\n\n提示系统通过 `prompts/list` 和 `prompts/get` 端点暴露。\n\n资料来源：[res/integration_test_coverage_audit.md]()\n\n## 认证与授权\n\n### 认证模式\n\n1. **完整认证模式**：需要 `APIFY_TOKEN` 环境变量\n2. **公开访问模式**：仅限特定工具\n\n### 公开可用工具\n\n以下工具在无认证情况下也可访问：\n\n- `search-actors`\n- `fetch-actor-details`\n- `search-apify-docs`\n\n资料来源：[README.md:42-46]()\n\n### 托管服务器访问\n\n托管服务器 (`https://mcp.apify.com`) 支持通过 `tools` 查询参数控制访问权限：\n\n```\nhttps://mcp.apify.com?tools=search-actors\n```\n\n## 日志系统\n\n### 日志级别配置\n\n通过 `logging/setLevel` 端点支持动态日志级别调整：\n\n| 日志级别 | 用途 |\n|----------|------|\n| debug | 调试信息 |\n| info | 一般信息 |\n| warn | 警告信息 |\n| error | 错误信息 |\n\n日志系统支持消息过滤，根据设置的日志级别决定是否转发到客户端。\n\n资料来源：[res/integration_test_coverage_audit.md]()\n\n## 配置选项\n\n### 环境变量\n\n| 变量名 | 描述 | 必填 |\n|--------|------|------|\n| `APIFY_TOKEN` | Apify API 访问令牌 | 是（部分功能） |\n| `APIFY_META_ORIGIN` | 请求来源标识 | 可选 |\n\n### 服务器模式\n\n| 模式 | 描述 |\n|------|------|\n| `ServerMode.APPS` | MCP Apps 模式，支持完整功能 |\n| `ServerMode.DEFAULT` | 默认模式 |\n\n## 错误处理\n\n### 错误类型\n\n| 错误场景 | 响应代码 | 说明 |\n|----------|----------|------|\n| 参数验证失败 | InvalidParams | AJV schema 验证失败 |\n| 资源未找到 | NotFound | 指定的资源不存在 |\n| Widget 不可用 | Error | Widget 文件不存在或注册表缺失 |\n| API 调用失败 | ServerError | 底层 Apify API 返回错误 |\n\n### Widget 错误处理\n\n```typescript\ntry {\n const widgetJs = fs.readFileSync(widget.jsPath, 'utf-8');\n // 处理 widget 内容\n} catch (error) {\n return {\n contents: [{\n uri,\n mimeType: 'text/plain',\n text: `Failed to load widget: ${errorMessage}`,\n }],\n };\n}\n```\n\n## 测试覆盖\n\n### 集成测试覆盖状态\n\n| MCP 端点 | 测试状态 | 位置 |\n|----------|----------|------|\n| `tools/list` | ✅ 已覆盖 | server.ts:619 |\n| `tools/call` | ✅ 已覆盖 | server.ts:633 |\n| `resources/list` | ⚠️ 仅单元测试 | - |\n| `resources/read` | ⚠️ 仅单元测试 | - |\n| `tasks/*` | ✅ 已覆盖 | server.ts:524 |\n| `prompts/*` | ✅ 部分覆盖 | server.ts:484 |\n| `logging/setLevel` | ⚠️ 缺失 | - |\n| `ping` | ⚠️ 缺失 | - |\n\n资料来源：[res/integration_test_coverage_audit.md]()\n\n## 扩展指南\n\n### 添加新工具\n\n1. 在 `src/mcp/actors.ts` 中定义工具 schema\n2. 注册工具处理器\n3. 添加对应的单元测试\n4. 更新集成测试覆盖\n\n### 添加新资源\n\n1. 在 `resource_service.ts` 中扩展 `readResource` 函数\n2. 如需列出资源，更新 `listResources` 函数\n3. 添加资源类型的 MIME type 映射\n\n### 注意事项\n\n- **不要使用 `registerResource`**：本项目使用低级别 `Server` API，不使用 `Mc pServer` 高级 API\n- **保持资源处理显式**：通过请求处理器管理资源，而非注册表模式\n- **遵循现有模式**：参考现有组件结构和命名规范\n\n资料来源：[res/mcp_resources_analysis.md]()\n资料来源：[CONTRIBUTING.md]()\n\n## 相关文档\n\n- [官方 MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk)\n- [MCP Inspector 调试工具](https://github.com/modelcontextprotocol/inspector)\n- [Apify 平台文档](https://docs.apify.com)\n\n---\n\n\n\n## Actor 工具系统\n\n### 相关页面\n\n相关主题：[MCP 协议实现](#mcp-protocol-implementation), [存储管理](#storage-management), [支付系统集成](#payment-systems)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/actor_executor.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/actor_executor.ts)\n- [src/tools/core/actor_tools_factory.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/core/actor_tools_factory.ts)\n- [src/tools/core/call_actor_common.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/core/call_actor_common.ts)\n- [src/tools/default/call_actor.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/default/call_actor.ts)\n- [src/tools/default/search_actors.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/default/search_actors.ts)\n- [src/tools/default/fetch_actor_details.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/default/fetch_actor_details.ts)\n- [src/tools/index.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/index.ts)\n- [src/tools/build.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/build.ts)\n \n\n# Actor 工具系统\n\n## 概述\n\nActor 工具系统是 apify-mcp-server 的核心子系统，负责将 Apify 平台上的 Actor（无服务器云程序）封装为 MCP（Model Context Protocol）工具，供 LLM（大语言模型）调用和执行。\n\n该系统的主要职责包括：\n\n- **工具注册**：将 Actor 动态注册为 MCP 可调用工具\n- **参数转换**：将 LLM 生成的 JSON 参数转换为 Actor 输入 schema\n- **执行管理**：启动 Actor 运行、跟踪进度、获取结果\n- **响应构建**：将 Actor 执行结果转换为 MCP 协议格式返回\n\n资料来源：[src/tools/index.ts:1-30]()\n\n## 系统架构\n\n### 整体架构图\n\n```mermaid\ngraph TD\n subgraph \"MCP Server Layer\"\n A[MCP Server] --> B[Tools Index]\n B --> C[Actor Executor]\n end\n\n subgraph \"Tool Factory Layer\"\n C --> D[Actor Tools Factory]\n D --> E[Call Actor Common]\n D --> F[Search Actors]\n D --> G[Fetch Actor Details]\n end\n\n subgraph \"Execution Layer\"\n E --> H[Apify Client]\n H --> I[Actor Run Management]\n I --> J[Dataset Retrieval]\n end\n\n subgraph \"Widget Layer\"\n E --> K[Call Actor Widget]\n end\n```\n\n### 目录结构\n\n```\nsrc/tools/\n├── index.ts # 工具导出索引\n├── build.ts # 工具构建配置\n├── actor_executor.ts # Actor 执行器\n├── core/\n│ ├── actor_tools_factory.ts # Actor 工具工厂\n│ └── call_actor_common.ts # 调用 Actor 通用逻辑\n├── default/\n│ ├── call_actor.ts # call-actor 工具实现\n│ ├── search_actors.ts # search-actors 工具实现\n│ └── fetch_actor_details.ts # fetch-actor-details 工具实现\n└── apps/\n ├── call_actor_widget.ts # call-actor 小部件模式\n └── ...\n```\n\n资料来源：[src/tools/index.ts]()\n\n## 核心组件\n\n### 1. Actor Executor\n\n`ActorExecutor` 是 Actor 工具系统的核心执行器，负责协调 Actor 的启动、进度跟踪和结果获取。\n\n```typescript\n// 伪代码结构\nclass ActorExecutor {\n async execute(\n actorName: string,\n input: Record,\n options: RunOptions\n ): Promise\n \n async getRunResult(runId: string): Promise\n \n trackProgress(runId: string, callback: ProgressCallback): void\n}\n```\n\n**关键职责**：\n\n| 职责 | 描述 |\n|------|------|\n| 运行启动 | 使用 Apify Client 启动 Actor |\n| 进度跟踪 | 实时监听 Actor 执行进度 |\n| 结果获取 | 从 Dataset 获取结构化输出 |\n| 错误处理 | 处理超时、失败等异常情况 |\n\n资料来源：[src/tools/actor_executor.ts:1-80]()\n\n### 2. Actor Tools Factory\n\n`ActorToolsFactory` 是工具工厂类，负责根据 Actor 定义动态生成 MCP 工具配置。\n\n```typescript\ninterface ActorToolConfig {\n name: string;\n description: string;\n inputSchema: z.ZodSchema;\n execute: ToolExecutor;\n}\n\nclass ActorToolsFactory {\n createActorTool(actorDefinition: ActorDefinition): ActorToolConfig\n \n createMCPActorTool(mcpServerUrl: string, mcpToolName: string): ActorToolConfig\n}\n```\n\n**工具命名规范**：遵循 `actor-{name}-by-{author}` 格式\n\n资料来源：[src/tools/core/actor_tools_factory.ts:1-60]()\n\n### 3. Call Actor Common\n\n`call_actor_common.ts` 包含所有 call-actor 工具共享的通用逻辑，包括参数解析、Actor 解析和小部件渲染。\n\n```typescript\n// 主要导出函数\nexport async function callActorPreExecute(\n toolArgs: InternalToolArgs,\n options: { route: HelperTools }\n): Promise\n\nexport async function resolveAndValidateActor(\n params: ResolveActorParams\n): Promise\n\nexport function buildMCPResponse(\n response: ResponseBuilderInput\n): ToolResponse\n```\n\n**预处理流程**：\n\n```mermaid\ngraph TD\n A[输入参数] --> B[参数验证]\n B --> C[Actor 名称解析]\n C --> D[输入 Schema 合并]\n D --> E[Prefill 值注入]\n E --> F[解析结果]\n```\n\n资料来源：[src/tools/core/call_actor_common.ts:1-120]()\n\n## 默认工具实现\n\n### search-actors\n\n搜索 Apify 商店中的 Actors，返回匹配的工具列表供 LLM 选择。\n\n```typescript\ninterface SearchActorsParams {\n query: string; // 搜索关键词\n maxResults?: number; // 最大返回数量，默认 10\n}\n\ninterface SearchActorsResult {\n actors: Actor[];\n total: number;\n}\n```\n\n**工具配置**：\n\n| 参数 | 类型 | 必填 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| query | string | ✅ | - | 搜索查询字符串 |\n| maxResults | integer | ❌ | 10 | 最大结果数量 |\n\n资料来源：[src/tools/default/search_actors.ts:1-80]()\n\n### fetch-actor-details\n\n获取指定 Actor 的详细信息，包括输入 schema、统计信息和定价信息。\n\n```typescript\ninterface FetchActorDetailsParams {\n actorId: string; // Actor ID 或 username/actorName\n}\n\ninterface ActorDetails {\n id: string;\n name: string;\n username: string;\n title: string;\n description: string;\n inputSchema: object;\n stats: ActorStats;\n pricingInfo: PricingInfo;\n}\n```\n\n资料来源：[src/tools/default/fetch_actor_details.ts:1-60]()\n\n### call-actor\n\n执行指定的 Actor，是系统中最核心的工具。\n\n```typescript\ninterface CallActorParams {\n actor: string; // Actor 标识 (username/actorName)\n input?: object; // Actor 输入参数\n build?: string; // Actor 构建版本\n timeout?: number; // 超时时间（秒）\n memory?: number; // 内存限制（MB）\n waitSecs?: number; // 等待运行完成的秒数\n}\n```\n\n**执行流程**：\n\n```mermaid\ngraph TD\n A[call-actor 调用] --> B[参数预处理]\n B --> C[Actor 解析验证]\n C --> D[Schema 验证]\n D --> E[启动 Actor Run]\n E --> F{waitSecs > 0?}\n F -->|是| G[等待运行完成]\n F -->|否| H[立即返回 Run ID]\n G --> I[获取 Dataset 结果]\n H --> J[返回 Run ID 和状态]\n I --> K[构建 MCP 响应]\n J --> K\n```\n\n资料来源：[src/tools/default/call_actor.ts:1-150]()\n\n## 输入 Schema 处理\n\n### Schema 转换流程\n\nActor 工具系统使用 Zod 进行 schema 验证和转换：\n\n```mermaid\ngraph LR\n A[Actor JSON Schema] --> B[Zod Schema]\n B --> C[MCP Tool Schema]\n C --> D[参数验证]\n```\n\n### 必填字段处理\n\n系统会自动过滤 Actor schema 中的必填字段：\n\n1. **保留的必填字段**：无默认值且用户必须提供的参数\n2. **移除的必填字段**：有默认值或 prefill 的参数\n\n| 字段类型 | required | 处理方式 |\n|----------|----------|----------|\n| 无默认值 | ✅ | 保留在 required 中 |\n| 有默认值 | ❌ | 从 required 移除 |\n| 有 prefill | ❌ | 从 required 移除 |\n| proxyConfiguration | ❌ | 强制移除（平台提供） |\n\n资料来源：[res/actor_input_schema_required_fields.md]()\n\n## 工具注册与构建\n\n### 工具构建配置\n\n`build.ts` 定义了所有可用工具的构建配置：\n\n```typescript\nexport const TOOL_CONFIGS: Record = {\n actors: {\n tools: ['search-actors', 'fetch-actor-details', 'call-actor'],\n },\n runs: {\n tools: ['get-actor-run-list', 'get-actor-log'],\n },\n storage: {\n tools: ['get-dataset', 'get-dataset-items', 'get-key-value-store'],\n },\n};\n```\n\n### 注册流程\n\n```mermaid\ngraph TD\n A[Server 初始化] --> B[加载工具配置]\n B --> C[创建 ToolRegistry]\n C --> D[注册默认工具]\n D --> E[注册 Actor MCP 工具]\n E --> F[发布 toolsChanged 事件]\n F --> G[MCP Server 就绪]\n```\n\n资料来源：[src/tools/build.ts:1-50]()\n\n## Widget 模式\n\nActor 工具系统支持 MCP Apps Widget 渲染模式，通过 `call-actor-widget` 工具实现。\n\n### Widget 渲染流程\n\n```mermaid\ngraph TD\n A[Widget 模式启用] --> B[UI_MODE=true]\n B --> C[加载 Widget JS]\n C --> D[生成 Widget HTML]\n D --> E[嵌入 MCP 响应]\n E --> F[App 渲染 Widget]\n```\n\n**Widget HTML 结构**：\n\n```html\n\n```\n\n资料来源：[src/tools/apps/call_actor_widget.ts:1-100]()\n\n### Widget 与标准模式对比\n\n| 特性 | 标准模式 | Widget 模式 |\n|------|----------|-------------|\n| 返回格式 | 纯文本 | HTML + 交互组件 |\n| LLM 可见性 | 直接显示结果 | 渲染后显示 |\n| 用户交互 | 文本反馈 | 可视化组件 |\n| 适用场景 | CLI 工具 | MCP Apps |\n\n## 错误处理\n\n### 错误类型\n\n| 错误类型 | 代码 | 处理方式 |\n|----------|------|----------|\n| Actor 不存在 | `ACTOR_NOT_FOUND` | 返回友好错误信息 |\n| 参数验证失败 | `INVALID_INPUT` | 返回 schema 错误详情 |\n| 运行超时 | `RUN_TIMEOUT` | 支持自定义超时时间 |\n| 认证失败 | `AUTH_FAILED` | 提示配置 APIFY_TOKEN |\n| 网络错误 | `NETWORK_ERROR` | 重试机制 |\n\n### 错误响应格式\n\n```json\n{\n \"content\": [\n {\n \"type\": \"text\",\n \"text\": \"Error: Actor 'xxx' not found or access denied\"\n }\n ],\n \"isError\": true\n}\n```\n\n## 配置选项\n\n### 环境变量\n\n| 变量名 | 必填 | 默认值 | 说明 |\n|--------|------|--------|------|\n| APIFY_TOKEN | ✅ | - | Apify API Token |\n| APIFY_META_ORIGIN | ❌ | - | 请求来源标识 |\n| UI_MODE | ❌ | false | 启用 Widget 模式 |\n\n### 工具参数\n\n| 参数 | 工具 | 说明 |\n|------|------|------|\n| build | call-actor | Actor 构建标签 |\n| timeout | call-actor | 超时秒数 |\n| memory | call-actor | 内存限制 MB |\n| waitSecs | call-actor | 等待完成秒数 |\n\n## 相关文件索引\n\n| 文件路径 | 用途 |\n|----------|------|\n| `src/tools/index.ts` | 工具模块导出 |\n| `src/tools/build.ts` | 工具构建配置 |\n| `src/tools/actor_executor.ts` | Actor 执行引擎 |\n| `src/tools/core/actor_tools_factory.ts` | 工具工厂 |\n| `src/tools/core/call_actor_common.ts` | 通用调用逻辑 |\n| `src/tools/default/call_actor.ts` | call-actor 实现 |\n| `src/tools/default/search_actors.ts` | search-actors 实现 |\n| `src/tools/default/fetch_actor_details.ts` | fetch-actor-details 实现 |\n| `src/tools/apps/call_actor_widget.ts` | Widget 模式实现 |\n\n---\n\n\n\n## 支付系统集成\n\n### 相关页面\n\n相关主题：[Actor 工具系统](#actor-tools-system), [系统架构](#system-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/payments/index.ts](https://github.com/apify/apify-mcp-server/blob/main/src/payments/index.ts)\n- [src/payments/x402.ts](https://github.com/apify/apify-mcp-server/blob/main/src/payments/x402.ts)\n- [src/payments/skyfire.ts](https://github.com/apify/apify-mcp-server/blob/main/src/payments/skyfire.ts)\n- [src/payments/resolve.ts](https://github.com/apify/apify-mcp-server/blob/main/src/payments/resolve.ts)\n- [src/payments/helpers.ts](https://github.com/apify/apify-mcp-server/blob/main/src/payments/helpers.ts)\n- [src/payments/types.ts](https://github.com/apify/apify-mcp-server/blob/main/src/payments/types.ts)\n- [src/payments/const.ts](https://github.com/apify/apify-mcp-server/blob/main/src/payments/const.ts)\n \n\n# 支付系统集成\n\n> **⚠️ 重要提示**：本页面所需的支付系统相关源码文件（`src/payments/` 目录下的所有文件）未包含在当前检索的上下文范围内。以下内容基于预期文件结构进行描述，实际实现细节可能与本文档有所差异。建议开发者直接查阅 `src/payments/` 目录下的源码以获取准确信息。\n\n## 概述\n\n支付系统集成是 Apify MCP Server 中的核心模块之一，负责处理与 HTTP 402 Payment Required 协议相关的支付验证、费用计算和支付解决逻辑。该系统允许 MCP Server 在执行需要付费的操作前验证用户的支付状态。\n\n## 架构设计\n\n### 模块结构\n\n| 模块文件 | 功能描述 |\n|---------|---------|\n| `index.ts` | 主入口，导出支付系统公共 API |\n| `x402.ts` | HTTP 402 协议实现 |\n| `skyfire.ts` | Skyfire 支付网关集成 |\n| `resolve.ts` | 支付解析与验证逻辑 |\n| `helpers.ts` | 支付相关辅助函数 |\n| `types.ts` | 类型定义 |\n| `const.ts` | 常量定义 |\n\n### 核心类型\n\n根据项目结构推测，支付系统应包含以下核心类型定义：\n\n```typescript\n// types.ts (推测)\ninterface PaymentContext {\n userId: string;\n actorId: string;\n paymentRequired: boolean;\n price?: number;\n currency?: string;\n}\n\ninterface PaymentResult {\n success: boolean;\n transactionId?: string;\n error?: string;\n}\n```\n\n## HTTP 402 协议实现\n\n`x402.ts` 模块负责实现 HTTP 402 Payment Required 规范，这是处理付费请求的标准协议。\n\n### 请求流程\n\n```mermaid\ngraph TD\n A[客户端请求] --> B{检查支付状态}\n B -->|已付费| C[执行操作]\n B -->|未付费| D[返回 402 响应]\n D --> E[包含价格信息]\n E --> F[等待客户端支付]\n F --> G{支付成功?}\n G -->|是| C\n G -->|否| H[拒绝请求]\n```\n\n## Skyfire 支付网关\n\nSkyfire 是本系统集成的支付网关之一，负责实际的资金处理。\n\n### 主要功能\n\n- **支付初始化**：创建支付会话\n- **支付验证**：确认支付状态\n- **退款处理**：处理退款请求\n- **交易记录**：记录所有交易详情\n\n## 支付解析模块\n\n`resolve.ts` 负责解析和验证支付相关的请求参数。\n\n### 解析逻辑\n\n| 步骤 | 描述 |\n|-----|------|\n| 1 | 提取支付信息头 |\n| 2 | 验证签名有效性 |\n| 3 | 检查支付金额 |\n| 4 | 返回解析结果 |\n\n## 配置常量\n\n`const.ts` 中定义的常量包括：\n\n- 支付超时时间\n- 重试次数限制\n- 货币类型定义\n- HTTP 状态码常量\n\n## 集成方式\n\n### 初始化支付系统\n\n```typescript\nimport { createPaymentProvider } from '@apify/mcp-server';\n\n// 在服务器配置中启用支付\nconst paymentProvider = createPaymentProvider({\n mode: 'production',\n // 其他配置...\n});\n```\n\n## 错误处理\n\n支付系统可能返回以下错误类型：\n\n| 错误码 | 描述 |\n|-------|------|\n| `PAYMENT_REQUIRED` | 需要支付才能继续 |\n| `PAYMENT_FAILED` | 支付处理失败 |\n| `INVALID_PAYMENT` | 支付信息无效 |\n| `TIMEOUT` | 支付超时 |\n\n## 安全考虑\n\n1. **签名验证**：所有支付请求必须包含有效签名\n2. **超时机制**：防止无限等待支付\n3. **重试限制**：防止恶意重复请求\n4. **日志审计**：记录所有支付相关操作\n\n## 相关资源\n\n- [资源服务文档](./resource_service.md)\n- [工具开发指南](./tools_development.md)\n- [错误处理规范](./error_handling.md)\n\n---\n\n> **维护说明**：本页面基于仓库源码结构自动生成。如发现内容与实际实现不符，请提交 Issue 或 Pull Request 进行更正。\n\n---\n\n\n\n## 存储管理\n\n### 相关页面\n\n相关主题：[Actor 工具系统](#actor-tools-system), [遥测与监控](#telemetry-monitoring)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/tools/common/get_dataset.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_dataset.ts)\n- [src/tools/common/get_dataset_items.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_dataset_items.ts)\n- [src/tools/common/get_dataset_schema.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_dataset_schema.ts)\n- [src/tools/common/dataset_collection.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/dataset_collection.ts)\n- [src/tools/common/get_key_value_store.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_key_value_store.ts)\n- [src/tools/common/get_key_value_store_keys.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_key_value_store_keys.ts)\n- [src/tools/common/get_key_value_store_record.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_key_value_store_record.ts)\n- [src/tools/common/key_value_store_collection.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/key_value_store_collection.ts)\n- [src/apify_client.ts](https://github.com/apify/apify-mcp-server/blob/main/src/apify_client.ts)\n \n\n# 存储管理\n\n## 概述\n\n存储管理是 Apify MCP Server 提供的核心功能模块之一，用于通过 MCP 协议与 Apify 平台的数据存储服务进行交互。该模块支持两种主要存储类型：\n\n| 存储类型 | 用途 | 数据格式 |\n|---------|------|---------|\n| **Dataset（数据集）** | 结构化表格数据存储 | JSON 数组 |\n| **Key-Value Store（键值存储）** | 键值对文件存储 | 任意文件类型 |\n\n资料来源：[src/apify_client.ts](https://github.com/apify/apify-mcp-server/blob/main/src/apify_client.ts)\n\n## 架构设计\n\n### 存储管理模块结构\n\n```mermaid\ngraph TD\n A[MCP Tools] --> B[存储管理模块]\n B --> C[数据集工具]\n B --> D[键值存储工具]\n \n C --> C1[get_dataset]\n C --> C2[get_dataset_items]\n C --> C3[get_dataset_schema]\n C --> C4[dataset_collection]\n \n D --> D1[get_key_value_store]\n D --> D2[get_key_value_store_keys]\n D --> D3[get_key_value_store_record]\n D --> D4[key_value_store_collection]\n \n C1 & C2 & C3 & C4 --> E[Apify API Client]\n D1 & D2 & D3 & D4 --> E\n \n E --> F[Apify Cloud]\n F --> G[Dataset Storage]\n F --> H[Key-Value Storage]\n```\n\n### 客户端初始化\n\n所有存储工具通过统一的 Apify 客户端实例进行操作，客户端在初始化时从环境变量读取认证信息：\n\n```typescript\n// 资料来源：src/apify_client.ts\nconst apifyClient = new ApifyClient({\n token: process.env.APIFY_TOKEN,\n});\n```\n\n## 数据集（Dataset）管理\n\n数据集用于存储 Actor 运行产生的结构化数据，类似于关系型数据库表或电子表格。\n\n资料来源：[src/tools/common/get_dataset.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_dataset.ts)\n\n### 获取数据集信息\n\n`get_dataset` 工具用于获取特定数据集的元数据信息。\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `datasetId` | string | 是 | 数据集唯一标识符 |\n\n**返回字段**：\n\n| 字段 | 说明 |\n|------|------|\n| `id` | 数据集 ID |\n| `name` | 数据集名称 |\n| `createdAt` | 创建时间 |\n| `modifiedAt` | 最后修改时间 |\n| `itemCount` | 数据项总数 |\n| `username` | 所有者用户名 |\n\n资料来源：[src/tools/common/get_dataset.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_dataset.ts)\n\n### 获取数据集项\n\n`get_dataset_items` 工具用于读取数据集中的实际数据内容。\n\n| 参数 | 类型 | 必需 | 默认值 | 说明 |\n|------|------|------|--------|------|\n| `datasetId` | string | 是 | - | 数据集 ID |\n| `offset` | number | 否 | 0 | 数据偏移量 |\n| `limit` | number | 否 | 100 | 返回数据条数限制 |\n| `clean` | boolean | 否 | true | 返回干净数据（非脏数据） |\n| `fields` | string[] | 否 | - | 指定返回的字段 |\n| `unwind` | string | 否 | - | 展开字段（用于嵌套数组） |\n| `flatten` | string[] | 否 | - | 展平的字段列表 |\n| `skipEmpty` | boolean | 否 | - | 跳过空值项 |\n| `skipHidden` | boolean | 否 | - | 跳过隐藏字段 |\n| `desc` | boolean | 否 | false | 降序排列 |\n\n资料来源：[src/tools/common/get_dataset_items.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_dataset_items.ts)\n\n### 获取数据集 Schema\n\n`get_dataset_schema` 工具用于获取数据集的数据结构定义，即所有字段及其类型信息。\n\n**返回结构示例**：\n\n```json\n{\n \"fields\": [\n { \"name\": \"url\", \"type\": \"string\" },\n { \"name\": \"title\", \"type\": \"string\" },\n { \"name\": \"count\", \"type\": \"number\" }\n ]\n}\n```\n\n资料来源：[src/tools/common/get_dataset_schema.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_dataset_schema.ts)\n\n### 数据集集合操作\n\n`dataset_collection` 工具用于列出当前用户拥有的所有数据集。\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `offset` | number | 否 | 列表偏移量 |\n| `limit` | number | 否 | 返回条数限制 |\n| `Clean` | boolean | 否 | 过滤脏数据集 |\n\n资料来源：[src/tools/common/dataset_collection.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/dataset_collection.ts)\n\n### 数据集操作流程\n\n```mermaid\nsequenceDiagram\n participant LLM as 大语言模型\n participant MCP as MCP Server\n participant API as Apify API\n participant DS as Dataset Storage\n \n LLM->>MCP: 调用 get_dataset_items\n MCP->>API: 请求数据集内容\n API->>DS: 查询存储\n DS-->>API: 返回 JSON 数据\n API-->>MCP: 格式化响应\n MCP-->>LLM: 返回数据项\n```\n\n## 键值存储（Key-Value Store）管理\n\n键值存储用于管理 Actor 运行产生的文件数据，支持任意文件类型的读写操作。\n\n资料来源：[src/tools/common/get_key_value_store.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_key_value_store.ts)\n\n### 获取键值存储信息\n\n`get_key_value_store` 工具用于获取特定键值存储的元数据。\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `storeId` | string | 是 | 键值存储 ID |\n\n资料来源：[src/tools/common/get_key_value_store.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_key_value_store.ts)\n\n### 获取键列表\n\n`get_key_value_store_keys` 工具用于列出键值存储中的所有键。\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `storeId` | string | 是 | 键值存储 ID |\n\n**返回字段**：\n\n| 字段 | 说明 |\n|------|------|\n| `keys` | 键名数组 |\n| `count` | 键总数 |\n| `total` | 符合条件的总数 |\n\n资料来源：[src/tools/common/get_key_value_store_keys.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_key_value_store_keys.ts)\n\n### 获取键值记录\n\n`get_key_value_store_record` 工具用于读取特定键对应的值。\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `storeId` | string | 是 | 键值存储 ID |\n| `key` | string | 是 | 数据键名 |\n\n**返回字段**：\n\n| 字段 | 说明 |\n|------|------|\n| `key` | 键名 |\n| `contentType` | 内容 MIME 类型 |\n| `value` | 存储的值（根据 contentType 解码） |\n\n资料来源：[src/tools/common/get_key_value_store_record.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/get_key_value_store_record.ts)\n\n### 键值存储集合操作\n\n`key_value_store_collection` 工具用于列出当前用户拥有的所有键值存储。\n\n| 参数 | 类型 | 必需 | 说明 |\n|------|------|------|------|\n| `offset` | number | 否 | 列表偏移量 |\n| `limit` | number | 否 | 返回条数限制 |\n\n资料来源：[src/tools/common/key_value_store_collection.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/common/key_value_store_collection.ts)\n\n### 键值存储数据结构\n\n```mermaid\ngraph LR\n subgraph Key-Value Store [storeId]\n A[键值存储元数据]\n subgraph Keys\n B[key1] --> C[值 + Content-Type]\n D[key2] --> E[值 + Content-Type]\n F[key3] --> G[值 + Content-Type]\n end\n end\n```\n\n## 存储类型对比\n\n| 特性 | Dataset | Key-Value Store |\n|------|---------|-----------------|\n| 数据结构 | 结构化记录（表格） | 键值对 |\n| 访问方式 | 按偏移量/范围 | 按键名 |\n| 适用场景 | 爬取结果、批量数据 | 配置、状态、文件 |\n| 数据格式 | JSON 数组 | 任意类型 |\n| Schema | 支持自动推断 | 无固定结构 |\n\n## 工具清单\n\n| 工具名称 | 描述 | 主要参数 |\n|---------|------|---------|\n| `get_dataset` | 获取数据集元数据 | `datasetId` |\n| `get_dataset_items` | 获取数据集内容 | `datasetId`, `offset`, `limit` |\n| `get_dataset_schema` | 获取数据集结构 | `datasetId` |\n| `dataset_collection` | 列出数据集 | `offset`, `limit` |\n| `get_key_value_store` | 获取键值存储元数据 | `storeId` |\n| `get_key_value_store_keys` | 获取键列表 | `storeId` |\n| `get_key_value_store_record` | 获取键值记录 | `storeId`, `key` |\n| `key_value_store_collection` | 列出键值存储 | `offset`, `limit` |\n\n## 使用场景\n\n### 场景一：读取爬取结果\n\n```mermaid\ngraph LR\n A[Actor 爬取网页] --> B[存储到 Dataset]\n B --> C[MCP 调用 get_dataset_items]\n C --> D[LLM 分析数据]\n```\n\n### 场景二：获取 Actor 状态\n\n```mermaid\ngraph LR\n A[Actor 运行] --> B[保存状态到 KVS]\n B --> C[MCP 调用 get_key_value_store_record]\n C --> D[读取运行时状态]\n```\n\n## 错误处理\n\n存储工具返回错误时，遵循 MCP 协议的标准错误格式：\n\n```json\n{\n \"contents\": [{\n \"uri\": \"...\",\n \"mimeType\": \"text/plain\",\n \"text\": \"错误描述信息\"\n }]\n}\n```\n\n常见错误场景：\n- 数据集/键值存储不存在\n- 无权限访问指定存储\n- API 请求超时\n- 存储 ID 格式错误\n\n## 认证要求\n\n所有存储操作需要有效的 `APIFY_TOKEN`，该令牌通过环境变量配置：\n\n```bash\nAPIFY_TOKEN=\"your-apify-token\"\n```\n\n无认证令牌时，存储管理工具将无法正常执行。\n\n## 最佳实践\n\n1. **分页读取大数据集**：使用 `offset` 和 `limit` 参数分批获取数据\n2. **指定返回字段**：使用 `fields` 参数减少传输数据量\n3. **检查 Schema**：首次访问新数据集时，先调用 `get_dataset_schema` 了解数据结构\n4. **使用 Content-Type**：读取键值存储记录时，注意解析对应的 MIME 类型\n\n---\n\n\n\n## 遥测与监控\n\n### 相关页面\n\n相关主题：[存储管理](#storage-management)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/telemetry.ts](https://github.com/apify/apify-mcp-server/blob/main/src/telemetry.ts)\n- [src/utils/logging.ts](https://github.com/apify/apify-mcp-server/blob/main/src/utils/logging.ts)\n- [src/utils/progress.ts](https://github.com/apify/apify-mcp-server/blob/main/src/utils/progress.ts)\n- [.sentryclirc](https://github.com/apify/apify-mcp-server/blob/main/.sentryclirc)\n \n\n# 遥测与监控\n\n## 概述\n\nApify MCP Server 的遥测与监控系统负责收集、传输和分析服务器运行过程中的关键指标数据。该系统包含三个核心子模块：\n\n- **工具遥测（Tool Telemetry）**：收集工具执行结果和状态信息，用于 Segment 分析\n- **日志系统（Logging）**：多级别日志记录，支持 Mezmo（LogDNA）集成\n- **进度追踪（Progress Tracking）**：支持长时间运行任务的进度通知\n\n遥测系统采用分层设计，`toolTelemetry` 仅在服务器内部流转，最终被 `extractToolTelemetry()` 提取后剥离，不会暴露给 MCP 客户端。\n\n## 架构概览\n\n```mermaid\ngraph TD\n subgraph \"客户端层\"\n A[MCP Client]\n end\n \n subgraph \"MCP Server\"\n B[工具执行]\n C[buildMCPResponse]\n D[工具遥测收集]\n E[进度追踪器]\n end\n \n subgraph \"日志系统\"\n F[SoftFail]\n G[Exception]\n H[Warn]\n I[Info]\n J[Debug]\n end\n \n subgraph \"外部服务\"\n K[Segment]\n L[Mezmo LogDNA]\n M[Sentry]\n end\n \n B --> C\n C --> D\n D -->|toolTelemetry| K\n B --> E\n E -->|sendNotification| A\n F --> L\n G --> L\n G --> M\n H --> L\n I --> L\n J --> L\n```\n\n## 工具遥测\n\n### 工具响应构建\n\n`buildMCPResponse` 函数是构建 MCP 工具响应的核心，它将文本内容、错误标记、遥测数据和结构化内容整合为统一响应格式。\n\n**函数签名：**\n\n```typescript\nexport function buildMCPResponse(options: {\n texts: string[];\n isError?: boolean;\n telemetry?: ToolTelemetryContext;\n structuredContent?: unknown;\n _meta?: Record;\n})\n```\n\n**返回值结构：**\n\n| 字段 | 类型 | 说明 |\n|------|------|------|\n| `content` | `Array<{ type: 'text'; text: string }>` | 文本内容数组 |\n| `isError` | `boolean` | 是否为错误响应（默认 `false`） |\n| `toolTelemetry` | `ToolTelemetryContext` | 工具遥测数据（内部使用） |\n| `structuredContent` | `unknown` | 结构化响应数据 |\n| `_meta` | `Record` | 元数据 |\n\n### 遥测数据结构\n\n工具遥测包含以下关键指标：\n\n| 字段 | 说明 |\n|------|------|\n| `toolStatus` | 工具执行状态 |\n| `failureCategory` | 失败分类（用于分析错误类型） |\n\n### 响应大小计算\n\n`computeToolResponseSizeBytes` 函数计算工具响应的字节大小，用于限流和监控：\n\n```typescript\nexport function computeToolResponseSizeBytes(result: unknown): number\n```\n\n**计算规则：**\n- 统计 `content[]` 数组中所有文本项的 UTF-8 字节长度\n- 统计 JSON 序列化的 `structuredContent` 字节长度\n- 其他字段（`isError`、`_meta` 等）不计入\n\n## 日志系统\n\n### 日志级别\n\n系统使用五个日志级别，从高到低排列：\n\n| 级别 | 使用场景 | 示例 |\n|------|----------|------|\n| `softFail` | 客户端错误 | 无效输入、权限不足 |\n| `exception` / `error` | 服务器错误 | 内部异常、系统故障 |\n| `warn` | 可疑但非关键行为 | 异常配置、降级处理 |\n| `info` | 重要状态变更 | 工具注册、连接建立 |\n| `debug` | 本地开发调试 | 请求详情、中间状态 |\n\n### Mezmo LogDNA 集成规则\n\nMezmo（LogDNA）会自动将包含 `\"error\"` 关键字的日志提升为 error 级别，可能导致误报。系统制定了以下规则：\n\n```typescript\n// ✅ 正确：使用 errMessage 作为键名\nlog.softFail('Client disconnected', { \n errMessage: err.message.replace(/ error:/gi, ' failure:') \n});\n\n// ❌ 错误：message 中包含 \"error\" 会触发误报\nlog.softFail('Client disconnected', { \n error: err.message \n});\n```\n\n**规则汇总：**\n\n| 规则 | 说明 |\n|------|------|\n| 使用 `errMessage` 替代 `error` 作为数据键 | 避免自动提升为 error 级别 |\n| 清理错误消息中的 \"error\" 字符串 | `.replace(/ error:/gi, ' failure:')` |\n| 避免在消息字符串中使用 \"error\" | 直接使用友好的错误描述 |\n\n## 进度追踪\n\n### 进度追踪器\n\n`ProgressTracker` 用于长时间运行的任务，通过 `sendNotification` 向客户端推送进度更新。\n\n```mermaid\nsequenceDiagram\n participant C as Client\n participant S as Server\n participant P as ProgressTracker\n participant A as Apify API\n \n C->>S: tools/call with progressToken\n S->>P: createProgressTracker\n P->>A: 启动 Actor\n A-->>P: 状态更新\n P-->>C: 进度通知 (progress)\n A-->>P: 完成\n P-->>C: 最终结果\n```\n\n### 进度通知格式\n\n进度通知通过 MCP 的 `notifications/progress` 发送，包含：\n\n| 字段 | 说明 |\n|------|------|\n| `progressToken` | 客户端提供的追踪令牌 |\n| `progress` | 0-1 之间的进度值 |\n| `message` | 当前步骤描述 |\n\n## Sentry 集成\n\n### 配置\n\n`.sentryclirc` 文件定义了 Sentry 的项目配置：\n\n```ini\n[defaults]\nproject=apify-mcp-server\norg=apify\n```\n\n### 错误上报\n\n服务器错误通过 Sentry 自动上报，包含：\n\n- 堆栈跟踪信息\n- 请求上下文\n- 用户环境数据\n\n## 数据流与处理\n\n```mermaid\ngraph LR\n subgraph \"输入\"\n A[用户请求]\n B[工具执行]\n end\n \n subgraph \"处理\"\n C[参数验证]\n D[业务逻辑]\n E[错误处理]\n end\n \n subgraph \"输出\"\n F[响应构建]\n G[遥测收集]\n H[日志记录]\n end\n \n A --> C\n C -->|验证通过| D\n C -->|验证失败| E\n D --> F\n E --> F\n D --> G\n E --> G\n D --> H\n E --> H\n```\n\n## 最佳实践\n\n### 日志记录\n\n1. **选择合适级别**：根据错误的严重程度选择 `softFail`、`error` 或 `warn`\n2. **敏感数据保护**：在记录日志前进行数据脱敏\n3. **错误消息格式化**：使用友好的用户消息，避免暴露内部实现细节\n\n### 遥测数据\n\n1. **填充必填字段**：确保 `toolStatus` 和 `failureCategory` 正确设置\n2. **响应大小控制**：使用 `computeToolResponseSizeBytes` 监控响应大小\n3. **避免泄露内部信息**：遥测数据仅供服务端分析，不暴露给客户端\n\n### 进度追踪\n\n1. **及时更新**：长时间操作应定期发送进度通知\n2. **提供上下文**：进度消息应清晰说明当前步骤\n3. **优雅终止**：支持客户端取消时正确清理资源\n\n## 相关文件\n\n| 文件路径 | 用途 |\n|----------|------|\n| `src/telemetry.ts` | 工具遥测定义与响应构建 |\n| `src/utils/logging.ts` | 日志系统实现 |\n| `src/utils/progress.ts` | 进度追踪器实现 |\n| `src/utils/mcp.ts` | MCP 响应工具函数 |\n| `.sentryclirc` | Sentry 配置 |\n\n---\n\n\n\n## 前端架构\n\n### 相关页面\n\n相关主题：[组件库与 Widget](#widget-components), [系统架构](#system-architecture)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/web/src/pages/ActorSearch/ActorSearch.skeleton.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/pages/ActorSearch/ActorSearch.skeleton.tsx)\n- [src/web/src/pages/ActorSearch/ActorSearch.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/pages/ActorSearch/ActorSearch.tsx)\n- [src/web/src/pages/ActorRun/ActorRun.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/pages/ActorRun/ActorRun.tsx)\n- [src/web/src/context/mcp-app-context.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/context/mcp-app-context.tsx)\n- [src/resources/resource_service.ts](https://github.com/apify/apify-mcp-server/blob/main/src/resources/resource_service.ts)\n- [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](https://github.com/apify/apify-mcp-server/blob/main/DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)\n \n\n# 前端架构\n\n## 概述\n\nApify MCP Server 的前端架构是一套基于 React 的嵌入式 Widget 系统，设计用于在 MCP（Model Context Protocol）环境中提供可交互的 Actors 搜索、运行状态查看和详情展示功能。前端采用组件化架构，遵循设计系统规范，支持动态加载和独立运行。\n\n主要技术栈：\n\n- **React 18** - UI 组件框架\n- **Styled Components** - 样式解决方案\n- **@apify/ui-library** - 共享组件库\n- **Tailwind CSS** - 工具类样式（配置于 `tailwind.config.js`）\n\n## 架构分层\n\n```\n┌─────────────────────────────────────────────────────────────┐\n│ MCP Server Layer │\n│ (resource_service.ts - Widget 动态加载与资源服务) │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ Widget Bundle Layer │\n│ (actor-run-widget.js, actor-detail-widget.js, │\n│ search-actors-widget.js) │\n└─────────────────────────────────────────────────────────────┘\n │\n ▼\n┌─────────────────────────────────────────────────────────────┐\n│ React Component Layer │\n│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │\n│ │ ActorSearch │ │ ActorRun │ │ ActorDetail │ │\n│ └─────────────┘ └─────────────┘ └─────────────┘ │\n│ ┌─────────────────────────────────────────────────┐ │\n│ │ Shared Components & Context │ │\n│ └─────────────────────────────────────────────────┘ │\n└─────────────────────────────────────────────────────────────┘\n```\n\n## Widget 系统\n\n### Widget 类型\n\n| Widget 名称 | 入口文件 | 用途 |\n|------------|---------|------|\n| Actor Search Widget | `src/web/index-actor-search.html` | 搜索和浏览 Actors |\n| Actor Run Widget | `src/web/index-actor-run.html` | 查看 Actor 运行状态 |\n| Actor Detail Widget | `src/web/actor-detail.html` | 展示 Actor 详细信息 |\n\n### Widget 动态加载机制\n\nWidget 通过 MCP Resource 协议动态加载。核心逻辑位于 `src/resources/resource_service.ts`：\n\n1. **URI 模式识别**：检测 `ui://widget/` 前缀的 URI\n2. **Widget 注册表查询**：通过 `getAvailableWidgets()` 获取可用 Widget 列表\n3. **文件系统读取**：使用 `node:fs` 模块读取 Widget 的 JS 文件\n4. **HTML 模板生成**：将 JS 包装在 HTML 模板中返回\n\n```typescript\n// 资料来源：src/resources/resource_service.ts:55-70\nif (getMode() === ServerMode.APPS && uri.startsWith('ui://widget/')) {\n const widget = getAvailableWidgets().get(uri);\n\n if (!widget || !widget.exists) {\n return {\n contents: [{\n uri,\n mimeType: 'text/plain',\n text: `Widget ${uri} is not available. ${!widget ? 'Not found in registry.' : `File not found at ${widget.jsPath}`}`,\n }],\n };\n }\n\n try {\n log.debug('Reading widget file', { uri, jsPath: widget.jsPath });\n const fs = await import('node:fs');\n const widgetJs = fs.readFileSync(widget.jsPath, 'utf-8');\n\n const widgetHtml = `\n\n \n \n \n ${widget.title}\n \n \n \n \n \n`;\n```\n\n### Widget Bundle 体积优化\n\n根据 `res/web-widget-bundle-size.md`，生产环境 Widget Bundle 体积已优化至：\n\n| Widget | 优化前 | 优化后 |\n|--------|-------|-------|\n| actor-run-widget | ~1.86 MB | ~1.16 MB |\n| actor-detail-widget | ~1.86 MB | ~1.52 MB |\n| search-actors-widget | ~1.87 MB | ~1.53 MB |\n\n剩余较大体积主要来自 Markdown 解析依赖。\n\n## 组件架构\n\n### 页面组件\n\n#### ActorSearch 组件\n\nActorSearch 页面负责展示 Actor 搜索结果列表，采用以下结构：\n\n- **ActorSearchResults** - 结果列表容器\n- **ActorContainer** - 单个 Actor 卡片容器\n- **ActorCard** - Actor 信息卡片\n- **EmptyState** - 空状态提示组件\n\n```typescript\n// 资料来源：src/web/src/pages/ActorSearch/ActorSearch.tsx\nconst EmptyState: React.FC = (props: EmptyStateProps) => {\n const { title, description } = props;\n return (\n \n {description ?? \"\"}\n \n );\n};\n```\n\n#### ActorRun 组件\n\nActorRun 页面展示单个 Actor 的运行状态，包含以下关键元素：\n\n- **ActorHeader** - 头部信息区\n- **ActorInfoRow** - Actor 基本信息和状态\n- **StatusMetadataContainer** - 状态徽章和元数据\n- **TableContainer** - 运行数据表格\n\n```typescript\n// 资料来源：src/web/src/pages/ActorRun/ActorRun.tsx\n\n \n \n \n {runData.actorName}\n \n \n\n \n \n {runData.status.charAt(0) + runData.status.slice(1).toLowerCase()}\n \n \n\n```\n\n### Skeleton 加载组件\n\n为每个页面提供骨架屏加载状态，提升用户体验。Skeleton 组件遵循统一的设计模式：\n\n```typescript\n// 资料来源：src/web/src/pages/ActorSearch/ActorSearch.skeleton.tsx\nconst SectionHeaderWrapper = styled(Box)`\n display: flex;\n align-items: center;\n justify-content: space-between;\n background: ${theme.color.neutral.background};\n border-top: 1px solid ${theme.color.neutral.separatorSubtle};\n`;\n\nconst SectionHeaderSkeleton: React.FC = () => {\n return (\n \n \n \n \n );\n};\n```\n\n## 设计系统规范\n\n### 主题令牌\n\n前端使用统一的设计令牌系统，所有样式必须使用 `theme.*` 令牌，禁止硬编码颜色和间距值。\n\n#### 颜色令牌\n\n| 类别 | 用途 | 示例 |\n|------|------|------|\n| `neutral` | 中性色 | `theme.color.neutral.text` |\n| `primary` | 主色调 | `theme.color.primary.action` |\n| `success` | 成功状态 | `theme.color.success.background` |\n| `warning` | 警告状态 | `theme.color.warning.action` |\n| `danger` | 危险状态 | `theme.color.danger.text` |\n\n#### 间距令牌\n\n| 令牌 | 用途 |\n|------|------|\n| `space4`, `space8` | 元素间间隙 |\n| `space12`, `space16` | 组件内边距 |\n| `space24`, `space32` | 区域间距 |\n| `space40`, `space64`, `space80` | 大型布局间距 |\n\n#### 圆角令牌\n\n| 令牌 | 用途 |\n|------|------|\n| `radius4` | 小型元素 |\n| `radius6`, `radius8` | 按钮、输入框 |\n| `radius12` | 卡片 |\n| `radiusFull` | 圆形元素 |\n\n### 组件导入规范\n\n```typescript\n// ✅ 正确：从 ui-library 导入\nimport { Button, Badge, Chip } from '@apify/ui-library';\n\n// ❌ 错误：创建重复组件\n// ❌ 错误：从相对路径导入非 ui-library 组件\n```\n\n### 样式组件编写模式\n\n```typescript\n// 资料来源：DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md\nimport styled from 'styled-components';\nimport { theme } from '@apify/ui-library';\n\nconst StyledComponent = styled.div<{ $variant?: string }>`\n color: ${theme.color.neutral.text};\n padding: ${theme.space.space16};\n\n ${({ $variant }) => $variant === 'primary' && css`\n background: ${theme.color.primary.background};\n `}\n`;\n```\n\n**注意**：使用 `$` 前缀标记瞬态 props（如 `$variant`、`$isActive`）。\n\n## 组件结构规范\n\n组件代码遵循统一的组织顺序：\n\n```typescript\n// 1. Imports (按功能分组)\nimport { forwardRef } from 'react';\nimport styled from 'styled-components';\nimport { theme } from '@apify/ui-library';\n\n// 2. 常量与类型定义\nexport const COMPONENT_VARIANTS = { ... } as const;\ntype ComponentVariants = ValueOf;\n\n// 3. Styled Components\nconst StyledWrapper = styled.div`...`;\n\n// 4. 组件实现\nexport const Component = forwardRef((props, ref) => {\n // implementation\n});\n\n// 5. Display Name\nComponent.displayName = 'Component';\n```\n\n## 状态与上下文\n\n前端使用 React Context 管理全局状态，核心上下文包括：\n\n- **MCP App Context** - 管理 MCP 连接状态和应用配置\n- **Theme Context** - 提供主题令牌访问\n\n### 自定义 Hooks\n\n| Hook | 用途 |\n|------|------|\n| `use-max-height` | 计算元素最大高度 |\n| `use-widget-props` | 解析 Widget 配置属性 |\n\n## 静态资源结构\n\n```\nsrc/web/\n├── index.html # 入口页面\n├── index-actor-search.html # Actor 搜索 Widget 入口\n├── index-actor-run.html # Actor 运行 Widget 入口\n├── actor-detail.html # Actor 详情 Widget 入口\n├── common.css # 共享样式\n└── src/\n ├── index.css # 全局样式\n ├── types.ts # TypeScript 类型定义\n ├── context/ # React Context\n │ └── mcp-app-context.tsx\n ├── hooks/ # 自定义 Hooks\n │ ├── use-max-height.ts\n │ └── use-widget-props.ts\n └── pages/ # 页面组件\n ├── ActorSearch/\n │ ├── ActorSearch.tsx\n │ └── ActorSearch.skeleton.tsx\n └── ActorRun/\n └── ActorRun.tsx\n```\n\n## 开发预览\n\n开发环境下，Widget 通过独立 HTML 文件预览。每个 Widget 入口页面结构相同：\n\n```html\n\n\n\n \n \n \n Actor Search Widget - Test\n \n \n \n \n\n \n \n\n```\n\n主入口页面 `index.html` 提供所有 Widget 的链接导航：\n\n```html\n\nApify Widgets - Dev Preview
\n\n```\n\n## 验证协议\n\n提交前端代码前，必须通过以下检查清单：\n\n### Token 审计\n\n使用正则表达式搜索，禁止硬编码值：\n\n| 检查项 | 正则表达式 | 预期结果 |\n|--------|----------|---------|\n| 颜色值 | `['\"]#[0-9a-fA-F]{3,8}['\"]` | 零匹配 |\n| 像素值 | `['\"][0-9]+px['\"]` | 零匹配 |\n\n### 导入检查\n\n- 所有 styled-components 必须从 `@apify/ui-library` 导入 `theme`\n- 不得存在重复的组件实现\n\n### 模式匹配\n\n- 组件结构与现有组件保持一致\n- Props 命名遵循项目约定\n- Variant 模式保持统一\n\n## 常见问题\n\n### 禁止的写法\n\n```typescript\n// ❌ 混用硬编码和令牌\npadding: ${theme.space.space16} 10px;\n\n// ❌ 使用不存在的颜色属性\ntheme.color.neutral.textLight\ntheme.color.primary.main\n\n// ❌ 创建重复组件\n// 应该从 @apify/ui-library 导入\n```\n\n### 正确做法\n\n```typescript\n// ✅ 所有值使用令牌\npadding: ${theme.space.space16} ${theme.space.space10};\nbackground: ${theme.color.primary.action};\n\n// ✅ 使用实际存在的属性名\ntheme.color.neutral.textMuted\ntheme.color.primary.action\n\n---\n\n\n\n## 组件库与 Widget\n\n### 相关页面\n\n相关主题：[前端架构](#frontend-architecture), [MCP 协议实现](#mcp-protocol-implementation)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [src/web/src/components/ui/Button.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/components/ui/Button.tsx)\n- [src/web/src/components/ui/Card.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/components/ui/Card.tsx)\n- [src/web/src/components/ui/Badge.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/components/ui/Badge.tsx)\n- [src/web/src/components/ui/Alert.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/components/ui/Alert.tsx)\n- [src/web/src/components/ui/JsonPreview.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/components/ui/JsonPreview.tsx)\n- [src/web/src/components/actor/ActorCard.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/components/actor/ActorCard.tsx)\n- [src/web/src/components/actor/ActorStats.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/components/actor/ActorStats.tsx)\n- [src/web/src/components/layout/WidgetLayout.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/components/layout/WidgetLayout.tsx)\n- [src/web/src/widgets/actor-detail-widget.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/widgets/actor-detail-widget.tsx)\n- [src/web/src/widgets/actor-run-widget.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/widgets/actor-run-widget.tsx)\n- [src/web/src/widgets/search-actors-widget.tsx](https://github.com/apify/apify-mcp-server/blob/main/src/web/src/widgets/search-actors-widget.tsx)\n \n\n# 组件库与 Widget\n\n## 概述\n\nApify MCP Server 的前端组件体系由两层核心架构组成：**通用 UI 组件库** 和 **业务 Widget**。这两层相互协作，共同支撑 MCP 服务器在 APPS 模式下的可视化交互能力。\n\n**UI 组件库** 位于 `src/web/src/components/ui/`，提供按钮、卡片、徽章、警告框等基础原子组件，所有样式遵循 Apify Design System 的设计规范。\n\n**Widget** 位于 `src/web/src/widgets/`，是针对特定业务场景（如 Actor 搜索、Actor 运行状态）封装的完整功能单元，每个 Widget 都是一个独立的 React 应用。\n\n资料来源：[DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)\n\n---\n\n## 架构分层\n\nMermaid 架构图展示了组件体系的分层结构：\n\n```mermaid\ngraph TB\n subgraph \"应用层 (Widgets)\"\n W1[search-actors-widget]\n W2[actor-run-widget]\n W3[actor-detail-widget]\n end\n \n subgraph \"页面层 (Pages)\"\n P1[ActorSearch]\n P2[ActorRun]\n P3[ActorSearchDetail]\n end\n \n subgraph \"业务组件 (Business Components)\"\n C1[ActorCard]\n C2[ActorStats]\n end\n \n subgraph \"通用 UI 组件 (Base Components)\"\n B1[Button]\n B2[Card]\n B3[Badge]\n B4[Alert]\n B5[JsonPreview]\n B6[WidgetLayout]\n end\n \n subgraph \"外部依赖\"\n E1[@apify/ui-library]\n E2[styled-components]\n end\n \n W1 --> P1\n W2 --> P2\n W3 --> P3\n \n P1 --> C1\n P3 --> C1\n P1 --> C2\n P2 --> C2\n \n C1 --> B1\n C1 --> B2\n C1 --> B3\n C2 --> B4\n P2 --> B5\n P1 --> B6\n \n B1 --> E1\n B2 --> E1\n B3 --> E1\n B4 --> E1\n B6 --> E1\n B1 --> E2\n B2 --> E2\n B6 --> E2\n```\n\n资料来源：[src/web/src/widgets/actor-detail-widget.tsx](src/web/src/widgets/actor-detail-widget.tsx)\n\n---\n\n## 通用 UI 组件\n\n### 组件列表\n\n| 组件名 | 文件路径 | 用途 |\n|--------|----------|------|\n| Button | `components/ui/Button.tsx` | 可交互按钮，支持多种变体和状态 |\n| Card | `components/ui/Card.tsx` | 容器卡片组件 |\n| Badge | `components/ui/Badge.tsx` | 状态徽章与标签 |\n| Alert | `components/ui/Alert.tsx` | 消息提示与警告 |\n| JsonPreview | `components/ui/JsonPreview.tsx` | JSON 数据可视化展示 |\n| WidgetLayout | `components/layout/WidgetLayout.tsx` | Widget 布局容器 |\n\n### 设计规范遵循\n\n所有 UI 组件必须严格遵循 Apify Design System：\n\n**颜色使用规则**：\n\n| 语义类别 | 使用方式 | 示例 |\n|----------|----------|------|\n| 文本颜色 | `theme.color.{category}.text` | `theme.color.neutral.text` |\n| 背景色 | `theme.color.{category}.background` | `theme.color.primary.background` |\n| 交互色 | `theme.color.{category}.action` | `theme.color.primary.action` |\n| 边框色 | `theme.color.{category}.border` | `theme.color.neutral.border` |\n| 图标色 | `theme.color.{category}.icon` | `theme.color.neutral.icon` |\n\n**状态变体**：\n\n```typescript\n// Default → Hover → Active 状态链\nbackground: ${theme.color.primary.action};\n&:hover { background: ${theme.color.primary.actionHover}; }\n&:active { background: ${theme.color.primary.actionActive}; }\n```\n\n**间距规范**：\n\n| 用途 | 可用值 |\n|------|--------|\n| 元素间间距 | `space4`, `space8`, `space12` |\n| 组件内边距 | `space8`, `space12`, `space16` |\n| 区域外边距 | `space16`, `space24`, `space32` |\n| 大型布局 | `space40`, `space64`, `space80` |\n\n资料来源：[DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)\n\n---\n\n## Widget 系统\n\n### Widget 类型\n\nApify MCP Server 提供三种核心 Widget：\n\n| Widget 名称 | 文件 | 功能描述 |\n|-------------|------|----------|\n| search-actors-widget | `widgets/search-actors-widget.tsx` | 搜索并浏览 Apify Store 中的 Actors |\n| actor-run-widget | `widgets/actor-run-widget.tsx` | 展示 Actor 运行状态与进度 |\n| actor-detail-widget | `widgets/actor-detail-widget.tsx` | 显示单个 Actor 的详细信息 |\n\n### Widget 生命周期\n\n```mermaid\nsequenceDiagram\n participant Client as MCP 客户端\n participant Server as MCP 服务器\n participant Resource as 资源读取
ui://widget/*\n participant FS as 文件系统\n participant Widget as React Widget\n \n Client->>Server: tools/call (widget tool)\n Server->>Server: 获取 toolOutput\n Server->>Resource: 注册 widget 资源\n Client->>Resource: resources/read (ui://widget/...)\n Resource->>FS: 读取 widget.js\n FS-->>Resource: widget JavaScript 代码\n Resource->>Resource: 包装为 HTML 页面\n Resource-->>Client: HTML 页面 (包含 JS bundle)\n Client->>Widget: 浏览器渲染\n Widget->>Server: 获取 toolOutput props\n Widget-->>Client: 渲染可视化界面\n```\n\n资料来源：[src/resources/resource_service.ts](src/resources/resource_service.ts)\n\n### Widget 初始化模式\n\n每个 Widget 采用统一的初始化模式：\n\n```typescript\n// 1. 定义 Wrapper 组件接收工具输出\nconst ActorDetailWrapper = () => {\n const toolOutput = useWidgetProps();\n const details = toolOutput?.details;\n\n if (!details) {\n return No actor details available
;\n }\n\n return ;\n};\n\n// 2. 开发/生产环境路由\n(async () => {\n if (IS_DEV_BUILD) {\n const { setupActorDetailWidgetDev } = await import(\"./actor-detail-widget.dev\");\n setupActorDetailWidgetDev();\n }\n renderWidget(ActorDetailWrapper);\n})();\n```\n\n资料来源：[src/web/src/widgets/actor-detail-widget.tsx](src/web/src/widgets/actor-detail-widget.tsx)\n\n---\n\n## Widget 布局组件\n\n`WidgetLayout` 是所有 Widget 的基础容器组件，提供统一的页面结构：\n\n```mermaid\ngraph LR\n subgraph \"WidgetLayout 结构\"\n Header[\"Header (标题 + 操作)\"]\n Content[\"Content (主内容区)\"]\n Footer[\"Footer (可选)\"]\n end\n \n Widget[\"\"]\n Widget --> Header\n Widget --> Content\n Widget --> Footer\n```\n\n**主要属性**：\n\n| 属性名 | 类型 | 说明 |\n|--------|------|------|\n| title | string | Widget 标题 |\n| actions | ReactNode | 右上角操作区域 |\n| children | ReactNode | 主内容区 |\n| footer | ReactNode | 底部区域（可选） |\n\n资料来源：[src/web/src/components/layout/WidgetLayout.tsx](src/web/src/components/layout/WidgetLayout.tsx)\n\n---\n\n## 业务组件\n\n### ActorCard 组件\n\n用于展示单个 Actor 的搜索结果卡片：\n\n```typescript\ninterface ActorCardProps {\n actor: Actor;\n}\n\nexport const ActorCard: React.FC = (props: ActorCardProps) => {\n const { actor } = props;\n // 渲染 Actor 卡片，包含徽章、统计信息等\n};\n```\n\n**功能特性**：\n- 显示 Actor 名称、描述、图标\n- 展示使用量、评分等统计信息\n- 集成 Badge 组件显示状态\n\n资料来源：[src/web/src/components/actor/ActorCard.tsx](src/web/src/components/actor/ActorCard.tsx)\n\n### ActorStats 组件\n\n展示 Actor 的关键统计数据：\n\n```typescript\ninterface ActorStatsProps {\n stats: {\n runsCount?: number;\n rating?: number;\n // 其他统计字段\n };\n}\n```\n\n**统计维度**：\n\n| 指标 | 说明 |\n|------|------|\n| runsCount | 运行次数 |\n| rating | 平均评分 |\n| avgDuration | 平均执行时长 |\n\n资料来源：[src/web/src/components/actor/ActorStats.tsx](src/web/src/components/actor/ActorStats.tsx)\n\n---\n\n## Bundle 优化策略\n\nWidget Bundle 必须保持自包含，但顶层 `@apify/ui-library` 和 `@apify/ui-icons` 的打包成本较高。\n\n### 优化规则\n\n| 策略 | 说明 |\n|------|------|\n| 优先使用 `dist/src/...` 导入 | 避免导入整个 barrel 文件 |\n| 避免重型组件 | 在共享路径使用轻量级本地实现 |\n| Markdown 渲染特殊处理 | 变动时需重新测量 bundle 影响 |\n\n### 优化效果\n\n| Widget | 优化前 | 优化后 | 降幅 |\n|--------|--------|--------|------|\n| actor-run-widget | ~1.86 MB | ~1.16 MB | ~38% |\n| actor-detail-widget | ~1.86 MB | ~1.52 MB | ~18% |\n| search-actors-widget | ~1.87 MB | ~1.53 MB | ~18% |\n\n资料来源：[res/web-widget-bundle-size.md](res/web-widget-bundle-size.md)\n\n### 导入规范对比\n\n```typescript\n// ✅ 优化后的导入方式（推荐）\nimport { Button } from '@apify/ui-library/dist/src/Button';\nimport styled from 'styled-components';\n\n// ❌ 不推荐的导入方式\nimport { Button } from '@apify/ui-library'; // 导入整个库\n```\n\n资料来源：[res/web-widget-bundle-size.md](res/web-widget-bundle-size.md)\n\n---\n\n## 开发模式\n\n### 热重载开发\n\n```bash\nAPIFY_TOKEN='your-apify-token' pnpm run dev\n```\n\n开发服务器配置：\n\n| 服务 | 端口 | 说明 |\n|------|------|------|\n| MCP 服务器 | 3001 | standby 模式 |\n| esbuild 开发服务器 | 3226 | widget 热重载 |\n\n### UI 模式\n\nWidget 渲染需要服务器运行在 UI 模式：\n- URL 参数：`?ui=true`（如 `/mcp?ui=true`）\n- 环境变量：`UI_MODE=true`\n\n### 本地预览\n\n访问 http://localhost:3226/index.html 预览所有可用 Widget：\n\n```html\nActor Search Widget\nActor Run Widget\n```\n\n资料来源：[src/web/index.html](src/web/index.html)\n\n---\n\n## 组件开发规范\n\n### 开发检查清单\n\n在提交 UI 代码前，必须完成以下验证：\n\n1. **Token 审计**：搜索代码中是否存在违规值\n - 颜色：`['\"]#[0-9a-fA-F]{3,8}['\"]` — 应为 0 处匹配\n - 间距：`['\"][0-9]+px['\"]` — 应为 0 处匹配\n\n2. **导入检查**：\n - 所有 styled-components 必须导入 `theme` from `@apify/ui-library`\n - 不得有重复组件实现\n\n3. **模式匹配**：\n - 对比相似组件的结构\n - 遵循相同的属性命名约定\n - 使用相同的变体模式\n\n### 组件结构模板\n\n```typescript\n// 1. 导入（分组）\nimport { forwardRef } from 'react';\nimport styled from 'styled-components';\nimport { theme } from '@apify/ui-library';\n\n// 2. 常量与类型\nexport const COMPONENT_VARIANTS = { ... } as const;\ntype ComponentVariants = ValueOf;\n\n// 3. 样式组件\nconst StyledWrapper = styled.div`...`;\n\n// 4. 组件实现\nexport const Component = forwardRef((props, ref) => {\n // implementation\n});\n\n// 5. Display Name\nComponent.displayName = 'Component';\n```\n\n资料来源：[DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)\n\n---\n\n## 总结\n\nApify MCP Server 的组件库与 Widget 系统是一个分层架构：\n\n- **基础层**：通用 UI 组件严格遵循 Design System，确保一致的用户体验\n- **业务层**：ActorCard、ActorStats 等组件封装业务逻辑\n- **应用层**：Widget 整合所有组件，提供完整的用户交互功能\n\n通过导入优化和热重载开发支持，系统在保持功能完整性的同时，实现了较好的性能和开发效率。\n\n---\n\n\n\n## 开发环境配置\n\n### 相关页面\n\n相关主题：[项目简介](#project-introduction)\n\n\n相关源码文件
\n\n以下源码文件用于生成本页说明：\n\n- [README.md](https://github.com/apify/apify-mcp-server/blob/main/README.md)\n- [CONTRIBUTING.md](https://github.com/apify/apify-mcp-server/blob/main/CONTRIBUTING.md)\n- [package.json](https://github.com/apify/apify-mcp-server/blob/main/package.json)\n- [tsconfig.json](https://github.com/apify/apify-mcp-server/blob/main/tsconfig.json)\n- [vitest.config.ts](https://github.com/apify/apify-mcp-server/blob/main/vitest.config.ts)\n- [src/tsconfig.json](https://github.com/apify/apify-mcp-server/blob/main/src/tsconfig.json)\n- [.nvmrc](https://github.com/apify/apify-mcp-server/blob/main/.nvmrc)\n- [.env.example](https://github.com/apify/apify-mcp-server/blob/main/.env.example)\n \n\n# 开发环境配置\n\n## 概述\n\n本文档介绍 apify-mcp-server 项目的开发环境配置方法。该项目是一个基于 Model Context Protocol (MCP) 的服务器实现，用于与 Apify 平台进行交互。开发环境配置涵盖了 Node.js 版本管理、环境变量设置、项目构建流程、测试框架配置以及代码规范遵循等核心内容。\n\n## 环境要求\n\n### Node.js 版本\n\n项目要求 Node.js 版本为 22 或更高版本。版本号通过 `.nvmrc` 文件进行统一管理：\n\n```text\n22\n```\n\n资料来源：[.nvmrc]()\n\n推荐使用 nvm (Node Version Manager) 来管理 Node.js 版本，可通过以下命令切换到正确版本：\n\n```bash\nnvm use\n```\n\n### 包管理器\n\n项目使用 pnpm 作为包管理器。确保本地已安装 pnpm：\n\n```bash\nnpm install -g pnpm\n```\n\n## 环境变量配置\n\n### 必需的环境变量\n\n在项目根目录创建 `.env` 文件，配置以下环境变量：\n\n```text\nAPIFY_TOKEN=\"your-apify-token\"\n```\n\n资料来源：[README.md:10-12]()\n\n`APIFY_TOKEN` 是访问 Apify API 的认证令牌，用于验证用户身份和授权 API 调用。\n\n### 其他配置项\n\n| 环境变量 | 用途 | 示例值 |\n|----------|------|--------|\n| `APIFY_TOKEN` | Apify API 访问令牌 | `your-apify-token` |\n| `APIFY_META_ORIGIN` | 请求来源标识（用于 Standby 模式） | `STANDBY` |\n\n## 项目构建\n\n### 构建流程\n\n项目使用 TypeScript 构建系统。需要先构建项目再运行：\n\n```bash\npnpm run build\n```\n\n资料来源：[README.md:14-16]()\n\n构建过程会将 TypeScript 源码编译为 JavaScript，输出到 `dist` 目录。\n\n### TypeScript 配置\n\n项目采用双层 tsconfig 结构：\n\n#### 根目录配置 (`tsconfig.json`)\n\n```json\n{\n \"compilerOptions\": {\n \"target\": \"ES2022\",\n \"module\": \"NodeNext\",\n \"moduleResolution\": \"NodeNext\",\n \"strict\": true\n }\n}\n```\n\n资料来源：[tsconfig.json]()\n\n#### 源码目录配置 (`src/tsconfig.json`)\n\n```json\n{\n \"extends\": \"../tsconfig.json\",\n \"compilerOptions\": {\n \"outDir\": \"../dist\",\n \"rootDir\": \".\"\n }\n}\n```\n\n资料来源：[src/tsconfig.json]()\n\n## 服务器运行模式\n\n项目支持两种 MCP 服务器运行模式：\n\n### HTTP Streamable 模式\n\n通过 Apify CLI 启动 HTTP 流式传输服务器：\n\n```bash\nexport APIFY_TOKEN=\"your-apify-token\"\nexport APIFY_META_ORIGIN=STANDBY\napify run -p\n```\n\n资料来源：[README.md:19-23]()\n\n服务器启动后暴露在 `http://localhost:3001`，可使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 进行调试。\n\n### 标准输入输出 (stdio) 模式\n\n通过 MCP Inspector 启动标准输入输出模式的服务器：\n\n```bash\nexport APIFY_TOKEN=\"your-apify-token\"\nnpx @modelcontextprotocol/inspector node ./dist/stdio.js\n```\n\n资料来源：[README.md:29-32]()\n\nInspector 会显示一个 URL，可在浏览器中打开进行调试。\n\n## 测试配置\n\n### Vitest 测试框架\n\n项目使用 Vitest 作为测试框架，配置文件为 `vitest.config.ts`：\n\n```typescript\n// vitest.config.ts 配置示例\nimport { defineConfig } from 'vitest/config';\n\nexport default defineConfig({\n test: {\n environment: 'node',\n globals: true,\n },\n});\n```\n\n资料来源：[vitest.config.ts]()\n\n### 运行测试\n\n| 命令 | 描述 |\n|------|------|\n| `pnpm test` | 运行所有测试 |\n| `pnpm test:watch` | 监听模式运行测试 |\n| `pnpm test:coverage` | 运行测试并生成覆盖率报告 |\n\n## 代码规范\n\n### 分支命名规范\n\n功能分支必须遵循 `type/short-description` 格式，其中 type 必须匹配 Conventional Commit 类型：\n\n```text\nfeat/add-dataset-tool\nfix/connection-timeout\nchore/update-dependencies\nrefactor/tool-registry\ndocs/update-readme\n```\n\n资料来源：[CONTRIBUTING.md:8-17]()\n\n### 提交信息规范\n\n所有提交和 PR 标题必须遵循 [Conventional Commits](https://www.conventionalcommits.org/) 格式，**type** 和 **scope** 均为必填项：\n\n```text\nfeat: Add new tool for fetching actor details\nfeat!: Migrate to new MCP SDK version [internal]\nfix: Handle connection errors gracefully\nrefactor: Improve type definitions [ignore]\nchore: Update dependencies\n```\n\n资料来源：[CONTRIBUTING.md:19-32]()\n\n使用 `!` 表示破坏性变更，例如 `feat!: ...`。\n\n### 变量命名规范\n\n| 命名类型 | 规范 | 示例 |\n|----------|------|------|\n| 常量 | 全大写下划线分隔 | `WIDGET_REGISTRY`, `LOG_LEVEL_MAP` |\n| 金额/成本 | 添加单位后缀 | `externalCostUsd`, `intervalMillis` |\n| 日期/时间 | 使用 `At` 后缀 | `updateStartedAt`, `paidAt` |\n| Zod 验证器 | 使用 `Validator` 后缀 | `InputValidator` |\n| 用户可见文本 | 使用品牌术语 `Actor`（大写） | Actor、Actor Run |\n\n资料来源：[CONTRIBUTING.md:42-47]()\n\n### 字符串格式化\n\n- 短的一行字符串使用单引号\n- 多行或超出 `max-len` 的字符串使用 `dedent` 模板字面量\n- 避免在 `dedent` 内插值从列 0 开始的值（如 `JSON.stringify` 输出）\n\n资料来源：[CONTRIBUTING.md:50-58]()\n\n## 集成测试覆盖\n\n项目维护了 MCP 协议各端点的测试覆盖情况，关键测试项包括：\n\n| MCP 协议端点 | 状态 |\n|--------------|------|\n| `tools/list` | ✅ 已覆盖（约 30 个用例） |\n| `tools/call` 正常路径 | ✅ 已覆盖 |\n| `tools/call` 错误处理 | ✅ 已覆盖 |\n| `prompts/list` | ✅ 已覆盖 |\n| `prompts/get` 正常路径 | ✅ 已覆盖 |\n| `logging/setLevel` | ❌ 缺少集成测试 |\n| `ping` | ❌ 缺少集成测试 |\n| `resources/list` | ❌ 仅单元测试 |\n| `resources/read` | ❌ 仅单元测试 |\n\n资料来源：[res/integration_test_coverage_audit.md]()\n\n## 快速启动流程\n\n```mermaid\ngraph TD\n A[安装 Node.js 22+] --> B[安装 pnpm]\n B --> C[克隆仓库]\n C --> D[创建 .env 文件配置 APIFY_TOKEN]\n D --> E[运行 pnpm install]\n E --> F[运行 pnpm run build]\n F --> G[选择运行模式]\n G --> H[HTTP Streamable 模式]\n G --> I[stdio 模式]\n H --> J[使用 MCP Inspector 调试]\n I --> J\n```\n\n## 未认证访问\n\n当 `tools` 查询参数仅包含明确允许未认证使用的工具时，托管服务器允许无令牌访问。当前允许的工具列表：\n\n| 工具名称 | 描述 |\n|----------|------|\n| `search-actors` | 搜索 Actors |\n| `fetch-actor-details` | 获取 Actor 详情 |\n| `search-apify-docs` | 搜索 Apify 文档 |\n| `fetch-apify-docs` | 获取 Apify 文档内容 |\n\n资料来源：[README.md:35-38]()\n\n使用示例：\n```\nhttps://mcp.apify.com?tools=search-actors\n```\n\n## Canary 版本发布\n\nApify MCP 服务器分为两个代码仓库：\n\n- 本仓库 (`apify-mcp-server`)：核心 MCP 逻辑\n- 私有仓库 (`apify-mcp-server-internal`)：托管服务器\n\n创建 canary 版本需要在 PR 分支上添加 `beta` 标签。\n\n资料来源：[README.md:41-47]()\n\n## 总结\n\n开发环境配置的核心要点：\n\n1. **环境版本**：Node.js 22+，pnpm 作为包管理器\n2. **认证配置**：在 `.env` 文件中设置 `APIFY_TOKEN`\n3. **构建流程**：`pnpm run build` 编译 TypeScript\n4. **运行模式**：支持 HTTP Streamable 和 stdio 两种 MCP 协议传输方式\n5. **代码规范**：遵循 Conventional Commits 规范，变量命名需符合类型约定\n\n---\n\n---\n\n## Doramagic 踩坑日志\n\n项目：apify/apify-mcp-server\n\n摘要：发现 22 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode。\n\n## 1. 安装坑 · 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix: Allow calling MCP server actors in normal (one-shot) mode\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_be82315ed0f441ba9d942931d846d78c | https://github.com/apify/apify-mcp-server/issues/857 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8ec6ff22f24a4bb18b439177f4a8c270 | https://github.com/apify/apify-mcp-server/issues/892 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：Do not include the rag web browser when ?payment=x402\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Do not include the rag web browser when ?payment=x402\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_23bafe4901554148896241f0a1e183b0 | https://github.com/apify/apify-mcp-server/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：Perf: `search-actors` tools returns huuuge `inputFields` object\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Perf: `search-actors` tools returns huuuge `inputFields` object\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af51cb3cbcb3479fbbdf27cedef734aa | https://github.com/apify/apify-mcp-server/issues/888 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安全/权限坑 · 来源证据：feat(telemetry): track tool result size in bytes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(telemetry): track tool result size in bytes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c2ef77c88914458910ae67d9f903931 | https://github.com/apify/apify-mcp-server/issues/838 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `apify-mcp-server` 与安装入口 `@apify/actors-mcp-server` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令: `npx @apify/actors-mcp-server`\n- 防护动作: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:911256711 | https://github.com/apify/apify-mcp-server | repo=apify-mcp-server; install=@apify/actors-mcp-server\n\n## 7. 安装坑 · 来源证据：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c05c17621e3443dad6175f21db31a34 | https://github.com/apify/apify-mcp-server/issues/894 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：feat: Add structured output to remaining storage tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: Add structured output to remaining storage tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c9b7c39f3e8f43e88ee52c2c8ae94b01 | https://github.com/apify/apify-mcp-server/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 安装坑 · 来源证据：feat: migrate direct actor tools to canonical RunResponse shape\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: migrate direct actor tools to canonical RunResponse shape\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6b304ff2763849fe9b4678cc7bf9f5b2 | https://github.com/apify/apify-mcp-server/issues/852 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 安装坑 · 来源证据：test: Consolidate duplicated MCP server test fixtures\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：test: Consolidate duplicated MCP server test fixtures\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5a7a24d9e8ce42468a7775a54dfa8ca6 | https://github.com/apify/apify-mcp-server/issues/847 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：feat: Dataset tools correctness and coverage\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat: Dataset tools correctness and coverage\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3fa86b498f66434a8f247c1b63fb56c9 | https://github.com/apify/apify-mcp-server/issues/784 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:911256711 | https://github.com/apify/apify-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：chore: Add mixpanel analytics for storage tools + error rates\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chore: Add mixpanel analytics for storage tools + error rates\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_03dbd8daa0c840d690bddb1d52e189c1 | https://github.com/apify/apify-mcp-server/issues/887 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：[Bug]: Inconsistent `search-actors` schema and results\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Inconsistent `search-actors` schema and results\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_364bc036f84b42e8b7be6534cb76381e | https://github.com/apify/apify-mcp-server/issues/889 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：design: Calibrate get-dataset-schema output detail\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：design: Calibrate get-dataset-schema output detail\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b7a4266d8eb4298919b5cb2a58fa420 | https://github.com/apify/apify-mcp-server/issues/882 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：refactor: Extract storage tool helpers\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：refactor: Extract storage tool helpers\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_496f0061952341728e4222b961251325 | https://github.com/apify/apify-mcp-server/issues/890 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：tools/list response contains `type: \"unknown\"` in an input schema — rejected by ajv-based MCP clients (LibreChat)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：tools/list response contains `type: \"unknown\"` in an input schema — rejected by ajv-based MCP clients (LibreChat)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77fae88d35e2486d8125a2ecea9abdc7 | https://github.com/apify/apify-mcp-server/issues/738 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki 完整输出，末尾追加 Discovery Agent 踩坑日志。",
"title": "Human Manual / 人类版说明书"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log / 踩坑日志\n\n项目：apify/apify-mcp-server\n\n摘要：发现 22 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode。\n\n## 1. 安装坑 · 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix: Allow calling MCP server actors in normal (one-shot) mode\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_be82315ed0f441ba9d942931d846d78c | https://github.com/apify/apify-mcp-server/issues/857 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 2. 配置坑 · 来源证据：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`\n- 对用户的影响：可能影响升级、迁移或版本选择。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8ec6ff22f24a4bb18b439177f4a8c270 | https://github.com/apify/apify-mcp-server/issues/892 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 3. 安全/权限坑 · 来源证据：Do not include the rag web browser when ?payment=x402\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Do not include the rag web browser when ?payment=x402\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_23bafe4901554148896241f0a1e183b0 | https://github.com/apify/apify-mcp-server/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. 安全/权限坑 · 来源证据：Perf: `search-actors` tools returns huuuge `inputFields` object\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Perf: `search-actors` tools returns huuuge `inputFields` object\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_af51cb3cbcb3479fbbdf27cedef734aa | https://github.com/apify/apify-mcp-server/issues/888 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 5. 安全/权限坑 · 来源证据：feat(telemetry): track tool result size in bytes\n\n- 严重度：high\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(telemetry): track tool result size in bytes\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c2ef77c88914458910ae67d9f903931 | https://github.com/apify/apify-mcp-server/issues/838 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 6. 身份坑 · 仓库名和安装名不一致\n\n- 严重度：medium\n- 证据强度：runtime_trace\n- 发现：仓库名 `apify-mcp-server` 与安装入口 `@apify/actors-mcp-server` 不完全一致。\n- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。\n- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。\n- 复现命令: `npx @apify/actors-mcp-server`\n- 防护动作: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。\n- 证据：identity.distribution | github_repo:911256711 | https://github.com/apify/apify-mcp-server | repo=apify-mcp-server; install=@apify/actors-mcp-server\n\n## 7. 安装坑 · 来源证据：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_9c05c17621e3443dad6175f21db31a34 | https://github.com/apify/apify-mcp-server/issues/894 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 8. 安装坑 · 来源证据：feat: Add structured output to remaining storage tools\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: Add structured output to remaining storage tools\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_c9b7c39f3e8f43e88ee52c2c8ae94b01 | https://github.com/apify/apify-mcp-server/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 9. 安装坑 · 来源证据：feat: migrate direct actor tools to canonical RunResponse shape\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: migrate direct actor tools to canonical RunResponse shape\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_6b304ff2763849fe9b4678cc7bf9f5b2 | https://github.com/apify/apify-mcp-server/issues/852 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 10. 安装坑 · 来源证据：test: Consolidate duplicated MCP server test fixtures\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：test: Consolidate duplicated MCP server test fixtures\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_5a7a24d9e8ce42468a7775a54dfa8ca6 | https://github.com/apify/apify-mcp-server/issues/847 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 11. 配置坑 · 来源证据：feat: Dataset tools correctness and coverage\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat: Dataset tools correctness and coverage\n- 对用户的影响：可能阻塞安装或首次运行。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_3fa86b498f66434a8f247c1b63fb56c9 | https://github.com/apify/apify-mcp-server/issues/784 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 12. 能力坑 · 能力判断依赖假设\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：README/documentation is current enough for a first validation pass.\n- 对用户的影响：假设不成立时，用户拿不到承诺的能力。\n- 建议检查：将假设转成下游验证清单。\n- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。\n- 证据：capability.assumptions | github_repo:911256711 | https://github.com/apify/apify-mcp-server | README/documentation is current enough for a first validation pass.\n\n## 13. 运行坑 · 来源证据：chore: Add mixpanel analytics for storage tools + error rates\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chore: Add mixpanel analytics for storage tools + error rates\n- 对用户的影响：可能增加新用户试用和生产接入成本。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_03dbd8daa0c840d690bddb1d52e189c1 | https://github.com/apify/apify-mcp-server/issues/887 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 14. 维护坑 · 维护活跃度未知\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：未记录 last_activity_observed。\n- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。\n- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | last_activity_observed missing\n\n## 15. 安全/权限坑 · 下游验证发现风险项\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：下游已经要求复核，不能在页面中弱化。\n- 建议检查：进入安全/权限治理复核队列。\n- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。\n- 证据：downstream_validation.risk_items | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium\n\n## 16. 安全/权限坑 · 存在评分风险\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：no_demo\n- 对用户的影响：风险会影响是否适合普通用户安装。\n- 建议检查：把风险写入边界卡，并确认是否需要人工复核。\n- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。\n- 证据：risks.scoring_risks | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium\n\n## 17. 安全/权限坑 · 来源证据：[Bug]: Inconsistent `search-actors` schema and results\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Inconsistent `search-actors` schema and results\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_364bc036f84b42e8b7be6534cb76381e | https://github.com/apify/apify-mcp-server/issues/889 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 18. 安全/权限坑 · 来源证据：design: Calibrate get-dataset-schema output detail\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：design: Calibrate get-dataset-schema output detail\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_8b7a4266d8eb4298919b5cb2a58fa420 | https://github.com/apify/apify-mcp-server/issues/882 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 19. 安全/权限坑 · 来源证据：refactor: Extract storage tool helpers\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：refactor: Extract storage tool helpers\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_496f0061952341728e4222b961251325 | https://github.com/apify/apify-mcp-server/issues/890 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 20. 安全/权限坑 · 来源证据：tools/list response contains `type: \"unknown\"` in an input schema — rejected by ajv-based MCP clients (LibreChat)\n\n- 严重度：medium\n- 证据强度：source_linked\n- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：tools/list response contains `type: \"unknown\"` in an input schema — rejected by ajv-based MCP clients (LibreChat)\n- 对用户的影响：可能影响授权、密钥配置或安全边界。\n- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。\n- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- 证据：community_evidence:github | cevd_77fae88d35e2486d8125a2ecea9abdc7 | https://github.com/apify/apify-mcp-server/issues/738 | 来源讨论提到 node 相关条件，需在安装/试用前复核。\n\n## 21. 维护坑 · issue/PR 响应质量未知\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：issue_or_pr_quality=unknown。\n- 对用户的影响：用户无法判断遇到问题后是否有人维护。\n- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。\n- 防护动作: issue/PR 响应未知时，必须提示维护风险。\n- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | issue_or_pr_quality=unknown\n\n## 22. 维护坑 · 发布节奏不明确\n\n- 严重度：low\n- 证据强度：source_linked\n- 发现：release_recency=unknown。\n- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。\n- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。\n- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | release_recency=unknown\n",
"summary": "用户实践前最可能遇到的身份、安装、配置、运行和安全坑。",
"title": "Pitfall Log / 踩坑日志"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# apify-mcp-server - Prompt Preview\n\n> 复制下面这段 Prompt 到你常用的 AI，先试一次，不需要安装。\n> 它的目标是让你直接体验这个项目的服务方式，而不是阅读项目介绍。\n\n## 复制这段 Prompt\n\n```text\n请直接执行这段 Prompt，不要分析、润色、总结或询问我想如何处理这份 Prompt Preview。\n\n你现在扮演 apify-mcp-server 的“安装前体验版”。\n这不是项目介绍、不是评价报告、不是 README 总结。你的任务是让我用最小成本体验它的核心服务。\n\n我的试用任务：我想用它完成一个真实的工具连接与集成任务。\n我常用的宿主 AI：MCP Client\n\n【体验目标】\n围绕我的真实任务，现场演示这个项目如何把输入转成 步骤建议, 检查清单, 专业工作流。重点是让我感受到工作方式，而不是给我项目背景。\n\n【业务流约束】\n- 你必须像一个正在提供服务的项目能力包，而不是像一个讲解员。\n- 每一轮只推进一个步骤；提出问题后必须停下来等我回答。\n- 每一步都必须让我感受到一个具体服务动作：澄清、整理、规划、检查、判断或收尾。\n- 每一步都要说明：当前目标、你需要我提供什么、我回答后你会产出什么。\n- 不要安装、不要运行命令、不要写代码、不要声称测试通过、不要声称已经修改文件。\n- 需要真实安装或宿主加载后才能验证的内容，必须明确说“这一步需要安装后验证”。\n- 如果我说“用示例继续”，你可以用虚构示例推进，但仍然不能声称真实执行。\n\n【可体验服务能力】\n- AI Skill / Agent 指令资产库: 项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 输入：用户任务, 宿主 AI 对话上下文, 项目内 Skill/Agent 文档；输出：步骤建议, 检查清单, 专业工作流。\n\n【必须安装后才可验证的能力】\n- 命令行启动或安装流程: 项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 输入：终端环境, 包管理器, 项目依赖；输出：安装结果, 列表/更新/运行结果。\n\n【核心服务流】\n请严格按这个顺序带我体验。不要一次性输出完整流程：\n1. project-introduction：项目简介。围绕“项目简介”模拟一次用户任务，不展示安装或运行结果。\n2. system-architecture：系统架构。围绕“系统架构”模拟一次用户任务，不展示安装或运行结果。\n3. mcp-protocol-implementation：MCP 协议实现。围绕“MCP 协议实现”模拟一次用户任务，不展示安装或运行结果。\n4. actor-tools-system：Actor 工具系统。围绕“Actor 工具系统”模拟一次用户任务，不展示安装或运行结果。\n5. development-setup：开发环境配置。围绕“开发环境配置”模拟一次用户任务，不展示安装或运行结果。\n\n【核心能力体验剧本】\n每一步都必须按“输入 -> 服务动作 -> 中间产物”执行。不要只说流程名：\n1. project-introduction\n输入：用户提供的“项目简介”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n2. system-architecture\n输入：用户提供的“系统架构”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n3. mcp-protocol-implementation\n输入：用户提供的“MCP 协议实现”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n4. actor-tools-system\n输入：用户提供的“Actor 工具系统”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n5. development-setup\n输入：用户提供的“开发环境配置”相关信息。\n服务动作：模拟项目在这一步的核心判断和整理方式。\n中间产物：一个可检查的小结果。\n\n【项目服务规则】\n这些规则决定你如何服务用户。不要解释规则本身，而要在每一步执行时遵守：\n- 先确认用户任务、输入材料和成功标准，再模拟项目能力。\n- 每一步都必须形成可检查的小产物，并等待用户确认后再继续。\n- 凡是需要安装、调用工具或访问外部服务的能力，都必须标记为安装后验证。\n\n【每一步的服务约束】\n- Step 1 / project-introduction：Step 1 必须围绕“项目简介”形成一个小中间产物，并等待用户确认。\n- Step 2 / system-architecture：Step 2 必须围绕“系统架构”形成一个小中间产物，并等待用户确认。\n- Step 3 / mcp-protocol-implementation：Step 3 必须围绕“MCP 协议实现”形成一个小中间产物，并等待用户确认。\n- Step 4 / actor-tools-system：Step 4 必须围绕“Actor 工具系统”形成一个小中间产物，并等待用户确认。\n- Step 5 / development-setup：Step 5 必须围绕“开发环境配置”形成一个小中间产物，并等待用户确认。\n\n【边界与风险】\n- 不要声称已经安装、运行、调用 API、读写本地文件或完成真实任务。\n- 安装前预览只能展示工作方式，不能证明兼容性、性能或输出质量。\n- 涉及安装、插件加载、工具调用或外部服务的能力必须安装后验证。\n\n【可追溯依据】\n这些路径只用于你内部校验或在我追问“依据是什么”时简要引用。不要在首次回复主动展开：\n- https://github.com/apify/apify-mcp-server\n- https://github.com/apify/apify-mcp-server#readme\n- .claude/skills/bug-triage/SKILL.md\n- .claude/skills/dig/SKILL.md\n- README.md\n- package.json\n- server.json\n- src/index.ts\n- src/index_internals.ts\n- src/mcp/server.ts\n- src/mcp/client.ts\n- src/state.ts\n\n【首次问题规则】\n- 首次三问必须先确认用户目标、成功标准和边界，不要提前进入工具、安装或实现细节。\n- 如果后续需要技术条件、文件路径或运行环境，必须等用户确认目标后再追问。\n\n首次回复必须只输出下面 4 个部分：\n1. 体验开始：用 1 句话说明你将带我体验 apify-mcp-server 的核心服务。\n2. 当前步骤：明确进入 Step 1，并说明这一步要解决什么。\n3. 你会如何服务我：说明你会先改变我完成任务的哪个动作。\n4. 只问我 3 个问题，然后停下等待回答。\n\n首次回复禁止输出：后续完整流程、证据清单、安装命令、项目评价、营销文案、已经安装或运行的说法。\n\nStep 1 / brainstorming 的二轮协议：\n- 我回答首次三问后，你仍然停留在 Step 1 / brainstorming，不要进入 Step 2。\n- 第二次回复必须产出 6 个部分：澄清后的任务定义、成功标准、边界条件、\n 2-3 个可选方案、每个方案的权衡、推荐方案。\n- 第二次回复最后必须问我是否确认推荐方案；只有我明确确认后，才能进入下一步。\n- 第二次回复禁止输出 git worktree、代码计划、测试文件、命令或真实执行结果。\n\n后续对话规则：\n- 我回答后，你先完成当前步骤的中间产物并等待确认；只有我确认后，才能进入下一步。\n- 每一步都要生成一个小的中间产物，例如澄清后的目标、计划草案、测试意图、验证清单或继续/停止判断。\n- 所有演示都写成“我会建议/我会引导/这一步会形成”，不要写成已经真实执行。\n- 不要声称已经测试通过、文件已修改、命令已运行或结果已产生。\n- 如果某个能力必须安装后验证，请直接说“这一步需要安装后验证”。\n- 如果证据不足，请明确说“证据不足”，不要补事实。\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start / 官方入口\n\n项目：apify/apify-mcp-server\n\n## 官方安装入口\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx @apify/actors-mcp-server\n```\n\n来源：https://github.com/apify/apify-mcp-server#readme\n\n## 来源\n\n- repo: https://github.com/apify/apify-mcp-server\n- docs: https://github.com/apify/apify-mcp-server#readme\n",
"summary": "从项目官方 README 或安装文档提取的开工入口。",
"title": "Quick Start / 官方入口"
}
},
"validation_id": "dval_3c0090282d844cdcb2eaae0b56d117e6"
}