();
const details = toolOutput?.details;
if (!details) {
return No actor details available
;
}
return ;
};
// 2. 开发/生产环境路由
(async () => {
if (IS_DEV_BUILD) {
const { setupActorDetailWidgetDev } = await import("./actor-detail-widget.dev");
setupActorDetailWidgetDev();
}
renderWidget(ActorDetailWrapper);
})();
```
资料来源：[src/web/src/widgets/actor-detail-widget.tsx](src/web/src/widgets/actor-detail-widget.tsx)
---
## Widget 布局组件
`WidgetLayout` 是所有 Widget 的基础容器组件，提供统一的页面结构：
```mermaid
graph LR
subgraph "WidgetLayout 结构"
Header["Header (标题 + 操作)"]
Content["Content (主内容区)"]
Footer["Footer (可选)"]
end
Widget[""]
Widget --> Header
Widget --> Content
Widget --> Footer
```
**主要属性**：
| 属性名 | 类型 | 说明 |
|--------|------|------|
| title | string | Widget 标题 |
| actions | ReactNode | 右上角操作区域 |
| children | ReactNode | 主内容区 |
| footer | ReactNode | 底部区域（可选） |
资料来源：[src/web/src/components/layout/WidgetLayout.tsx](src/web/src/components/layout/WidgetLayout.tsx)
---
## 业务组件
### ActorCard 组件
用于展示单个 Actor 的搜索结果卡片：
```typescript
interface ActorCardProps {
actor: Actor;
}
export const ActorCard: React.FC = (props: ActorCardProps) => {
const { actor } = props;
// 渲染 Actor 卡片，包含徽章、统计信息等
};
```
**功能特性**：
- 显示 Actor 名称、描述、图标
- 展示使用量、评分等统计信息
- 集成 Badge 组件显示状态
资料来源：[src/web/src/components/actor/ActorCard.tsx](src/web/src/components/actor/ActorCard.tsx)
### ActorStats 组件
展示 Actor 的关键统计数据：
```typescript
interface ActorStatsProps {
stats: {
runsCount?: number;
rating?: number;
// 其他统计字段
};
}
```
**统计维度**：
| 指标 | 说明 |
|------|------|
| runsCount | 运行次数 |
| rating | 平均评分 |
| avgDuration | 平均执行时长 |
资料来源：[src/web/src/components/actor/ActorStats.tsx](src/web/src/components/actor/ActorStats.tsx)
---
## Bundle 优化策略
Widget Bundle 必须保持自包含，但顶层 `@apify/ui-library` 和 `@apify/ui-icons` 的打包成本较高。
### 优化规则
| 策略 | 说明 |
|------|------|
| 优先使用 `dist/src/...` 导入 | 避免导入整个 barrel 文件 |
| 避免重型组件 | 在共享路径使用轻量级本地实现 |
| Markdown 渲染特殊处理 | 变动时需重新测量 bundle 影响 |
### 优化效果
| Widget | 优化前 | 优化后 | 降幅 |
|--------|--------|--------|------|
| actor-run-widget | ~1.86 MB | ~1.16 MB | ~38% |
| actor-detail-widget | ~1.86 MB | ~1.52 MB | ~18% |
| search-actors-widget | ~1.87 MB | ~1.53 MB | ~18% |
资料来源：[res/web-widget-bundle-size.md](res/web-widget-bundle-size.md)
### 导入规范对比
```typescript
// ✅ 优化后的导入方式（推荐）
import { Button } from '@apify/ui-library/dist/src/Button';
import styled from 'styled-components';
// ❌ 不推荐的导入方式
import { Button } from '@apify/ui-library'; // 导入整个库
```
资料来源：[res/web-widget-bundle-size.md](res/web-widget-bundle-size.md)
---
## 开发模式
### 热重载开发
```bash
APIFY_TOKEN='your-apify-token' pnpm run dev
```
开发服务器配置：
| 服务 | 端口 | 说明 |
|------|------|------|
| MCP 服务器 | 3001 | standby 模式 |
| esbuild 开发服务器 | 3226 | widget 热重载 |
### UI 模式
Widget 渲染需要服务器运行在 UI 模式：
- URL 参数：`?ui=true`（如 `/mcp?ui=true`）
- 环境变量：`UI_MODE=true`
### 本地预览
访问 http://localhost:3226/index.html 预览所有可用 Widget：
```html
Actor Search Widget
Actor Run Widget
```
资料来源：[src/web/index.html](src/web/index.html)
---
## 组件开发规范
### 开发检查清单
在提交 UI 代码前，必须完成以下验证：
1. **Token 审计**：搜索代码中是否存在违规值
- 颜色：`['"]#[0-9a-fA-F]{3,8}['"]` — 应为 0 处匹配
- 间距：`['"][0-9]+px['"]` — 应为 0 处匹配
2. **导入检查**：
- 所有 styled-components 必须导入 `theme` from `@apify/ui-library`
- 不得有重复组件实现
3. **模式匹配**：
- 对比相似组件的结构
- 遵循相同的属性命名约定
- 使用相同的变体模式
### 组件结构模板
```typescript
// 1. 导入（分组）
import { forwardRef } from 'react';
import styled from 'styled-components';
import { theme } from '@apify/ui-library';
// 2. 常量与类型
export const COMPONENT_VARIANTS = { ... } as const;
type ComponentVariants = ValueOf;
// 3. 样式组件
const StyledWrapper = styled.div`...`;
// 4. 组件实现
export const Component = forwardRef((props, ref) => {
// implementation
});
// 5. Display Name
Component.displayName = 'Component';
```
资料来源：[DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)
---
## 总结
Apify MCP Server 的组件库与 Widget 系统是一个分层架构：
- **基础层**：通用 UI 组件严格遵循 Design System，确保一致的用户体验
- **业务层**：ActorCard、ActorStats 等组件封装业务逻辑
- **应用层**：Widget 整合所有组件，提供完整的用户交互功能
通过导入优化和热重载开发支持，系统在保持功能完整性的同时，实现了较好的性能和开发效率。
---
## 开发环境配置
### 相关页面
相关主题：[项目简介](#project-introduction)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/apify/apify-mcp-server/blob/main/README.md)
- [CONTRIBUTING.md](https://github.com/apify/apify-mcp-server/blob/main/CONTRIBUTING.md)
- [package.json](https://github.com/apify/apify-mcp-server/blob/main/package.json)
- [tsconfig.json](https://github.com/apify/apify-mcp-server/blob/main/tsconfig.json)
- [vitest.config.ts](https://github.com/apify/apify-mcp-server/blob/main/vitest.config.ts)
- [src/tsconfig.json](https://github.com/apify/apify-mcp-server/blob/main/src/tsconfig.json)
- [.nvmrc](https://github.com/apify/apify-mcp-server/blob/main/.nvmrc)
- [.env.example](https://github.com/apify/apify-mcp-server/blob/main/.env.example)
# 开发环境配置
## 概述
本文档介绍 apify-mcp-server 项目的开发环境配置方法。该项目是一个基于 Model Context Protocol (MCP) 的服务器实现，用于与 Apify 平台进行交互。开发环境配置涵盖了 Node.js 版本管理、环境变量设置、项目构建流程、测试框架配置以及代码规范遵循等核心内容。
## 环境要求
### Node.js 版本
项目要求 Node.js 版本为 22 或更高版本。版本号通过 `.nvmrc` 文件进行统一管理：
```text
22
```
资料来源：[.nvmrc]()
推荐使用 nvm (Node Version Manager) 来管理 Node.js 版本，可通过以下命令切换到正确版本：
```bash
nvm use
```
### 包管理器
项目使用 pnpm 作为包管理器。确保本地已安装 pnpm：
```bash
npm install -g pnpm
```
## 环境变量配置
### 必需的环境变量
在项目根目录创建 `.env` 文件，配置以下环境变量：
```text
APIFY_TOKEN="your-apify-token"
```
资料来源：[README.md:10-12]()
`APIFY_TOKEN` 是访问 Apify API 的认证令牌，用于验证用户身份和授权 API 调用。
### 其他配置项
| 环境变量 | 用途 | 示例值 |
|----------|------|--------|
| `APIFY_TOKEN` | Apify API 访问令牌 | `your-apify-token` |
| `APIFY_META_ORIGIN` | 请求来源标识（用于 Standby 模式） | `STANDBY` |
## 项目构建
### 构建流程
项目使用 TypeScript 构建系统。需要先构建项目再运行：
```bash
pnpm run build
```
资料来源：[README.md:14-16]()
构建过程会将 TypeScript 源码编译为 JavaScript，输出到 `dist` 目录。
### TypeScript 配置
项目采用双层 tsconfig 结构：
#### 根目录配置 (`tsconfig.json`)
```json
{
"compilerOptions": {
"target": "ES2022",
"module": "NodeNext",
"moduleResolution": "NodeNext",
"strict": true
}
}
```
资料来源：[tsconfig.json]()
#### 源码目录配置 (`src/tsconfig.json`)
```json
{
"extends": "../tsconfig.json",
"compilerOptions": {
"outDir": "../dist",
"rootDir": "."
}
}
```
资料来源：[src/tsconfig.json]()
## 服务器运行模式
项目支持两种 MCP 服务器运行模式：
### HTTP Streamable 模式
通过 Apify CLI 启动 HTTP 流式传输服务器：
```bash
export APIFY_TOKEN="your-apify-token"
export APIFY_META_ORIGIN=STANDBY
apify run -p
```
资料来源：[README.md:19-23]()
服务器启动后暴露在 `http://localhost:3001`，可使用 [MCP Inspector](https://github.com/modelcontextprotocol/inspector) 进行调试。
### 标准输入输出 (stdio) 模式
通过 MCP Inspector 启动标准输入输出模式的服务器：
```bash
export APIFY_TOKEN="your-apify-token"
npx @modelcontextprotocol/inspector node ./dist/stdio.js
```
资料来源：[README.md:29-32]()
Inspector 会显示一个 URL，可在浏览器中打开进行调试。
## 测试配置
### Vitest 测试框架
项目使用 Vitest 作为测试框架，配置文件为 `vitest.config.ts`：
```typescript
// vitest.config.ts 配置示例
import { defineConfig } from 'vitest/config';
export default defineConfig({
test: {
environment: 'node',
globals: true,
},
});
```
资料来源：[vitest.config.ts]()
### 运行测试
| 命令 | 描述 |
|------|------|
| `pnpm test` | 运行所有测试 |
| `pnpm test:watch` | 监听模式运行测试 |
| `pnpm test:coverage` | 运行测试并生成覆盖率报告 |
## 代码规范
### 分支命名规范
功能分支必须遵循 `type/short-description` 格式，其中 type 必须匹配 Conventional Commit 类型：
```text
feat/add-dataset-tool
fix/connection-timeout
chore/update-dependencies
refactor/tool-registry
docs/update-readme
```
资料来源：[CONTRIBUTING.md:8-17]()
### 提交信息规范
所有提交和 PR 标题必须遵循 [Conventional Commits](https://www.conventionalcommits.org/) 格式，**type** 和 **scope** 均为必填项：
```text
feat: Add new tool for fetching actor details
feat!: Migrate to new MCP SDK version [internal]
fix: Handle connection errors gracefully
refactor: Improve type definitions [ignore]
chore: Update dependencies
```
资料来源：[CONTRIBUTING.md:19-32]()
使用 `!` 表示破坏性变更，例如 `feat!: ...`。
### 变量命名规范
| 命名类型 | 规范 | 示例 |
|----------|------|------|
| 常量 | 全大写下划线分隔 | `WIDGET_REGISTRY`, `LOG_LEVEL_MAP` |
| 金额/成本 | 添加单位后缀 | `externalCostUsd`, `intervalMillis` |
| 日期/时间 | 使用 `At` 后缀 | `updateStartedAt`, `paidAt` |
| Zod 验证器 | 使用 `Validator` 后缀 | `InputValidator` |
| 用户可见文本 | 使用品牌术语 `Actor`（大写） | Actor、Actor Run |
资料来源：[CONTRIBUTING.md:42-47]()
### 字符串格式化
- 短的一行字符串使用单引号
- 多行或超出 `max-len` 的字符串使用 `dedent` 模板字面量
- 避免在 `dedent` 内插值从列 0 开始的值（如 `JSON.stringify` 输出）
资料来源：[CONTRIBUTING.md:50-58]()
## 集成测试覆盖
项目维护了 MCP 协议各端点的测试覆盖情况，关键测试项包括：
| MCP 协议端点 | 状态 |
|--------------|------|
| `tools/list` | ✅ 已覆盖（约 30 个用例） |
| `tools/call` 正常路径 | ✅ 已覆盖 |
| `tools/call` 错误处理 | ✅ 已覆盖 |
| `prompts/list` | ✅ 已覆盖 |
| `prompts/get` 正常路径 | ✅ 已覆盖 |
| `logging/setLevel` | ❌ 缺少集成测试 |
| `ping` | ❌ 缺少集成测试 |
| `resources/list` | ❌ 仅单元测试 |
| `resources/read` | ❌ 仅单元测试 |
资料来源：[res/integration_test_coverage_audit.md]()
## 快速启动流程
```mermaid
graph TD
A[安装 Node.js 22+] --> B[安装 pnpm]
B --> C[克隆仓库]
C --> D[创建 .env 文件配置 APIFY_TOKEN]
D --> E[运行 pnpm install]
E --> F[运行 pnpm run build]
F --> G[选择运行模式]
G --> H[HTTP Streamable 模式]
G --> I[stdio 模式]
H --> J[使用 MCP Inspector 调试]
I --> J
```
## 未认证访问
当 `tools` 查询参数仅包含明确允许未认证使用的工具时，托管服务器允许无令牌访问。当前允许的工具列表：
| 工具名称 | 描述 |
|----------|------|
| `search-actors` | 搜索 Actors |
| `fetch-actor-details` | 获取 Actor 详情 |
| `search-apify-docs` | 搜索 Apify 文档 |
| `fetch-apify-docs` | 获取 Apify 文档内容 |
资料来源：[README.md:35-38]()
使用示例：
```
https://mcp.apify.com?tools=search-actors
```
## Canary 版本发布
Apify MCP 服务器分为两个代码仓库：
- 本仓库 (`apify-mcp-server`)：核心 MCP 逻辑
- 私有仓库 (`apify-mcp-server-internal`)：托管服务器
创建 canary 版本需要在 PR 分支上添加 `beta` 标签。
资料来源：[README.md:41-47]()
## 总结
开发环境配置的核心要点：
1. **环境版本**：Node.js 22+，pnpm 作为包管理器
2. **认证配置**：在 `.env` 文件中设置 `APIFY_TOKEN`
3. **构建流程**：`pnpm run build` 编译 TypeScript
4. **运行模式**：支持 HTTP Streamable 和 stdio 两种 MCP 协议传输方式
5. **代码规范**：遵循 Conventional Commits 规范，变量命名需符合类型约定
---
---
## Doramagic 踩坑日志
项目：apify/apify-mcp-server
摘要：发现 22 个潜在踩坑项，其中 5 个为 high/blocking；最高优先级：安装坑 - 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode。
## 1. 安装坑 · 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix: Allow calling MCP server actors in normal (one-shot) mode
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_be82315ed0f441ba9d942931d846d78c | https://github.com/apify/apify-mcp-server/issues/857 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. 配置坑 · 来源证据：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`
- 对用户的影响：可能影响升级、迁移或版本选择。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8ec6ff22f24a4bb18b439177f4a8c270 | https://github.com/apify/apify-mcp-server/issues/892 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. 安全/权限坑 · 来源证据：Do not include the rag web browser when ?payment=x402
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Do not include the rag web browser when ?payment=x402
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_23bafe4901554148896241f0a1e183b0 | https://github.com/apify/apify-mcp-server/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. 安全/权限坑 · 来源证据：Perf: `search-actors` tools returns huuuge `inputFields` object
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Perf: `search-actors` tools returns huuuge `inputFields` object
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_af51cb3cbcb3479fbbdf27cedef734aa | https://github.com/apify/apify-mcp-server/issues/888 | 来源类型 github_issue 暴露的待验证使用条件。
## 5. 安全/权限坑 · 来源证据：feat(telemetry): track tool result size in bytes
- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(telemetry): track tool result size in bytes
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9c2ef77c88914458910ae67d9f903931 | https://github.com/apify/apify-mcp-server/issues/838 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. 身份坑 · 仓库名和安装名不一致
- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `apify-mcp-server` 与安装入口 `@apify/actors-mcp-server` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- 复现命令: `npx @apify/actors-mcp-server`
- 防护动作: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- 证据：identity.distribution | github_repo:911256711 | https://github.com/apify/apify-mcp-server | repo=apify-mcp-server; install=@apify/actors-mcp-server
## 7. 安装坑 · 来源证据：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_9c05c17621e3443dad6175f21db31a34 | https://github.com/apify/apify-mcp-server/issues/894 | 来源类型 github_issue 暴露的待验证使用条件。
## 8. 安装坑 · 来源证据：feat: Add structured output to remaining storage tools
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: Add structured output to remaining storage tools
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_c9b7c39f3e8f43e88ee52c2c8ae94b01 | https://github.com/apify/apify-mcp-server/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。
## 9. 安装坑 · 来源证据：feat: migrate direct actor tools to canonical RunResponse shape
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: migrate direct actor tools to canonical RunResponse shape
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_6b304ff2763849fe9b4678cc7bf9f5b2 | https://github.com/apify/apify-mcp-server/issues/852 | 来源类型 github_issue 暴露的待验证使用条件。
## 10. 安装坑 · 来源证据：test: Consolidate duplicated MCP server test fixtures
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：test: Consolidate duplicated MCP server test fixtures
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_5a7a24d9e8ce42468a7775a54dfa8ca6 | https://github.com/apify/apify-mcp-server/issues/847 | 来源类型 github_issue 暴露的待验证使用条件。
## 11. 配置坑 · 来源证据：feat: Dataset tools correctness and coverage
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat: Dataset tools correctness and coverage
- 对用户的影响：可能阻塞安装或首次运行。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_3fa86b498f66434a8f247c1b63fb56c9 | https://github.com/apify/apify-mcp-server/issues/784 | 来源类型 github_issue 暴露的待验证使用条件。
## 12. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作: 假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:911256711 | https://github.com/apify/apify-mcp-server | README/documentation is current enough for a first validation pass.
## 13. 运行坑 · 来源证据：chore: Add mixpanel analytics for storage tools + error rates
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chore: Add mixpanel analytics for storage tools + error rates
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_03dbd8daa0c840d690bddb1d52e189c1 | https://github.com/apify/apify-mcp-server/issues/887 | 来源类型 github_issue 暴露的待验证使用条件。
## 14. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作: 维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | last_activity_observed missing
## 15. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作: 下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium
## 16. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作: 评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium
## 17. 安全/权限坑 · 来源证据：[Bug]: Inconsistent `search-actors` schema and results
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Inconsistent `search-actors` schema and results
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_364bc036f84b42e8b7be6534cb76381e | https://github.com/apify/apify-mcp-server/issues/889 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 18. 安全/权限坑 · 来源证据：design: Calibrate get-dataset-schema output detail
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：design: Calibrate get-dataset-schema output detail
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_8b7a4266d8eb4298919b5cb2a58fa420 | https://github.com/apify/apify-mcp-server/issues/882 | 来源类型 github_issue 暴露的待验证使用条件。
## 19. 安全/权限坑 · 来源证据：refactor: Extract storage tool helpers
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：refactor: Extract storage tool helpers
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_496f0061952341728e4222b961251325 | https://github.com/apify/apify-mcp-server/issues/890 | 来源类型 github_issue 暴露的待验证使用条件。
## 20. 安全/权限坑 · 来源证据：tools/list response contains `type: "unknown"` in an input schema — rejected by ajv-based MCP clients (LibreChat)
- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：tools/list response contains `type: "unknown"` in an input schema — rejected by ajv-based MCP clients (LibreChat)
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- 防护动作: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- 证据：community_evidence:github | cevd_77fae88d35e2486d8125a2ecea9abdc7 | https://github.com/apify/apify-mcp-server/issues/738 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 21. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作: issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | issue_or_pr_quality=unknown
## 22. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作: 发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | release_recency=unknown