();
const details = toolOutput?.details;
if (!details) {
return No actor details available
;
}
return ;
};
(async () => {
if (IS_DEV_BUILD) {
const { setupActorDetailWidgetDev } = await import("./actor-detail-widget.dev");
setupActorDetailWidgetDev();
}
renderWidget(ActorDetailWrapper);
})();
```
## Resource Service Integration
### URI Scheme
Widgets are exposed as MCP resources using the `ui://widget/` URI scheme:
```
ui://widget/actor-search.html
ui://widget/actor-detail.html
ui://widget/actor-run.html
```
Source: `src/resources/resource_service.ts`
### Resource Handler Logic
```typescript
// src/resources/resource_service.ts
if (getMode() === ServerMode.APPS && uri.startsWith('ui://widget/')) {
const widget = getAvailableWidgets().get(uri);
if (!widget || !widget.exists) {
return {
contents: [{
uri,
mimeType: 'text/plain',
text: `Widget ${uri} is not available. ${!widget ? 'Not found in registry.' : `File not found at ${widget.jsPath}`}`,
}],
};
}
try {
const fs = await import('node:fs');
const widgetJs = fs.readFileSync(widget.jsPath, 'utf-8');
const widgetHtml = `
${widget.title}
`;
const widgetContent: ExtendedResourceContents = {
uri,
mimeType: RESOURCE_MIME_TYPE,
text: widgetHtml,
html: widgetHtml,
_meta: widget.meta,
};
return { contents: [widgetContent] };
} catch (error) {
return {
contents: [{
uri,
mimeType: 'text/plain',
text: `Failed to load widget: ${errorMessage}`,
}],
};
}
}
```
## Bundle Size Optimization
### Optimization Strategy
Widget bundles are optimized through narrow imports from `@apify/ui-library`. The top-level barrel import pulls in heavy transitive dependencies (floating UI, markdown helpers), which are avoided by importing specific modules.
### Import Patterns
```typescript
// ❌ AVOID - Pulls entire library
import { Button } from '@apify/ui-library';
// ✅ PREFER - Narrow import
import { Button } from '@apify/ui-library/dist/src/...';
```
Source: `res/web-widget-bundle-size.md`
### Verified Bundle Sizes
| Widget | Before | After | Reduction |
|--------|--------|-------|-----------|
| 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% |
Source: `res/web-widget-bundle-size.md`
### Special Cost Center: Markdown
Markdown rendering is treated as a special cost center. Changes to markdown processing require re-measuring bundle size impact.
## Development Workflow
### Hot-Reload Development
The development server supports hot-reload for widgets:
```bash
APIFY_TOKEN='your-apify-token' pnpm run dev
```
This starts:
1. Web widget builder in watch mode
2. MCP server in standby mode on port `3001`
3. Local esbuild dev server at `http://localhost:3226`
Source: `DEVELOPMENT.md`
### Preview Widgets
Widgets can be previewed locally via:
```
http://localhost:3226/index.html
```
The preview page links to:
- Actor Search Widget: `/index-actor-search.html`
- Actor Run Widget: `/index-actor-run.html`
### UI Mode Requirement
Widget rendering requires the server to run in UI mode. Enable via:
- Query parameter: `/mcp?ui=true`
- Environment variable: `UI_MODE=true`
## Widget Tool Output Interface
Each widget expects a specific output structure from the invoking tool:
```typescript
interface WidgetToolOutput extends Record {
details?: ActorDetails;
}
interface ActorDetails {
name: string;
description: string;
pricing: PricingInfo;
inputSchema: InputSchema;
// ... other properties
}
```
## Design System Compliance
Widgets must follow the Apify design system rules defined in `DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md`:
### Token Usage
| Token Category | Usage | Example |
|---------------|-------|---------|
| Colors | Use `theme.color.*` | `theme.color.neutral.text` |
| Spacing | Use `theme.space.*` | `theme.space.space16` |
| Shadows | Use `theme.shadow.*` | `theme.shadow.shadow2` |
### Component Structure
```typescript
// 1. Imports
import styled from 'styled-components';
import { theme } from '@apify/ui-library';
// 2. Constants & Types
export const COMPONENT_VARIANTS = { ... } as const;
// 3. Styled Components
const StyledWrapper = styled.div`...`;
// 4. Component Implementation
export const Component = forwardRef((props, ref) => {
// implementation
});
// 5. Display Name
Component.displayName = 'Component';
```
## Skeleton Loading States
Widgets implement skeleton loading states for async content:
```typescript
// src/web/src/pages/ActorSearch/ActorSearch.skeleton.tsx
const SectionHeaderSkeleton: React.FC = () => {
return (
);
};
```
## Configuration
### Widget Registry
Widgets are registered in the `availableWidgets` registry, which tracks:
- Widget URI path
- JavaScript file path
- Title for HTML template
- Existence status
- Metadata
### Server Mode
Widget resources are only available when `getMode() === ServerMode.APPS`. In default mode, requests to `ui://widget/*` URIs return an error message.
---
## UI Components Library
### Related Pages
Related topics: [Widget System](#widget-system)
Relevant source files
The following source files were used to generate this page:
- [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](https://github.com/apify/apify-mcp-server/blob/main/DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)
- [src/web/package.json](https://github.com/apify/apify-mcp-server/blob/main/src/web/package.json)
- [res/web-widget-bundle-size.md](https://github.com/apify/apify-mcp-server/blob/main/res/web-widget-bundle-size.md)
- [src/tools/structured_output_schemas.ts](https://github.com/apify/apify-mcp-server/blob/main/src/tools/structured_output_schemas.ts)
- [src/resources/resource_service.ts](https://github.com/apify/apify-mcp-server/blob/main/src/resources/resource_service.ts)
- [src/utils/server-instructions/index.ts](https://github.com/apify/apify-mcp-server/blob/main/src/utils/server-instructions/index.ts)
# UI Components Library
## Overview
The Apify MCP Server utilizes a dedicated UI Components Library to render interactive widgets within the MCP Apps environment. These components enable the server to deliver rich, styled user interfaces for displaying Actor information, search results, and run progress directly within AI assistant applications.
The UI components are built using **React 18.3.1** and **styled-components 6.3.8**, with design tokens sourced from the `@apify/ui-library` package. Source: [src/web/package.json](src/web/package.json)
## Architecture
### Component Location and Structure
UI widgets reside in `src/web/src/widgets/` and leverage shared components from `src/web/src/components/ui/`. The component library follows a consistent pattern where all styled components import the `theme` object from `@apify/ui-library` to ensure design consistency across the application. Source: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)
### Widget Rendering Pipeline
The following diagram illustrates how UI components integrate with the MCP server:
```mermaid
graph TD
A[MCP Client Request] --> B[Server Handler]
B --> C{Server Mode}
C -->|APPS| D[Widget Registry]
C -->|DEFAULT| E[Standard Response]
D --> F[Read Widget JS Bundle]
F --> G[Wrap in HTML Template]
G --> H[Return HTML via Resource]
H --> I[MCP Apps Renderer]
I --> J[React Components Mount]
```
Source: [src/resources/resource_service.ts](src/resources/resource_service.ts)
### Bundle Optimization Strategy
The widget bundles must remain self-contained while minimizing payload size. The system uses direct module imports from `@apify/ui-library/dist/src/...` instead of top-level imports to avoid pulling in heavy transitive dependencies. Source: [res/web-widget-bundle-size.md](res/web-widget-bundle-size.md)
**Bundle size improvements achieved:**
| Widget | Before | After | Reduction |
|--------|--------|-------|-----------|
| actor-run-widget | ~1.86 MB | ~1.16 MB | 37.6% |
| actor-detail-widget | ~1.86 MB | ~1.52 MB | 18.3% |
| search-actors-widget | ~1.87 MB | ~1.53 MB | 18.2% |
## Design System Compliance
All UI components must adhere to strict design system rules defined in `DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md`. These rules ensure visual consistency and maintainability across all widgets. Source: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)
### Design Tokens
Components **must** use `theme.*` tokens exclusively for all styling values. Hardcoded values are strictly forbidden.
```typescript
// ❌ FORBIDDEN
color: '#1976d2'
padding: '8px'
border-radius: '4px'
// ✅ REQUIRED
color: ${theme.color.primary.action}
padding: ${theme.space.space8}
border-radius: ${theme.radius.radius2}
```
**Available token categories:**
| Category | Examples | Purpose |
|----------|----------|---------|
| Colors | `theme.color.primary.action`, `theme.color.neutral.textMuted` | Brand colors and semantic variants |
| Spacing | `theme.space.space8`, `theme.space.space16`, `theme.space.space40` | Padding, margins, gaps |
| Border Radius | `theme.radius.radius2`, `theme.radius.radius3` | Component corners |
| Shadows | `theme.shadow1`, `theme.shadow3`, `theme.shadowActive` | Elevation and depth |
Source: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)
### Component Import Pattern
All shared UI components should be imported from `@apify/ui-library`. Components must never be duplicated locally or imported from arbitrary relative paths.
```typescript
// ✅ Correct
import { Button, Badge, Chip, Text, Heading } from '@apify/ui-library';
// ❌ Never create duplicate implementations
```
## Component Patterns
### Styled Components Structure
The project follows a standardized component structure to ensure consistency across all UI elements. Source: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)
**Component file organization:**
```typescript
// 1. Imports (grouped)
import { forwardRef } from 'react';
import styled from 'styled-components';
import { theme } from '@apify/ui-library';
// 2. Constants & Types
export const COMPONENT_VARIANTS = { ... } as const;
type ComponentVariants = ValueOf;
// 3. Styled Components
const StyledWrapper = styled.div`...`;
// 4. Component Implementation
export const Component = forwardRef((props, ref) => {
// implementation
});
// 5. Display Name
Component.displayName = 'Component';
```
### Transient Props Convention
Component props that should not be passed to the underlying DOM element must use the `$` prefix:
```typescript
const StyledButton = styled.button<{ $variant?: string }>`
background: ${({ $variant }) =>
$variant === 'primary'
? theme.color.primary.action
: theme.color.neutral.background
};
`;
```
**Common transient props:** `$variant`, `$isActive`, `$size`
Source: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)
### Typography Components
Typography must use the `Text` and `Heading` components from `@apify/ui-library` rather than direct styling:
```typescript
// ✅ Correct
import { Text, Heading } from '@apify/ui-library';
Content here
Title here
// ❌ Never style text elements directly
// ❌ Never use typography tokens
```
Source: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)
## Spacing System
The design system defines a consistent spacing scale that must be used for all layout measurements:
| Token | Usage | Example |
|-------|-------|---------|
| `space4` | Inline elements, icon gaps | `gap: ${theme.space.space4}` |
| `space8` | Button padding, small gaps | `padding: ${theme.space.space8}` |
| `space12` | Component internal spacing | `padding: ${theme.space.space12}` |
| `space16` | Standard component padding | `padding: ${theme.space.space16}` |
| `space24` | Section margins | `margin: ${theme.space.space24}` |
| `space32` | Section separators | `margin: ${theme.space.space32}` |
| `space40`, `space64`, `space80` | Large layouts | Container margins |
**Rule:** Never use arbitrary values like `gap: 10px` — always round to the nearest design token.
Source: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)
## Common Pitfalls
### Token Misuse
Avoid mixing hardcoded values with design tokens in the same property:
```typescript
// ❌ WRONG
padding: ${theme.space.space16} 10px;
// ✅ CORRECT
padding: ${theme.space.space16} ${theme.space.space10};
```
### Non-existent Token Properties
Always verify token property names exist in the theme object:
```typescript
// ❌ WRONG - These properties don't exist
theme.color.neutral.textLight
theme.color.primary.main
// ✅ CORRECT - Use actual property names
theme.color.neutral.textMuted
theme.color.primary.action
```
Source: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)
## Widget Output Schemas
UI components receive data through structured output schemas that define the expected data format:
### Actor Details Widget Schema
```typescript
export const actorDetailsWidgetOutputSchema = {
type: 'object',
properties: {
actorDetails: {
type: 'object',
properties: {
actorInfo: {
type: 'object',
description: 'Widget-formatted Actor info (tier-aware pricing, widget display fields).'
},
actorCard: {
type: 'string',
description: 'Rendered Actor card markdown for widget display.'
},
readme: {
type: 'string',
description: 'Formatted Actor README for widget display.'
},
},
required: ['actorInfo', 'actorCard', 'readme'],
},
},
required: ['actorDetails'],
};
```
Source: [src/tools/structured_output_schemas.ts](src/tools/structured_output_schemas.ts)
### Actor Search Widget Schema
```typescript
export const actorSearchOutputSchema = {
type: 'object',
properties: {
actors: {
type: 'array',
items: actorInfoSchema,
description: 'List of Actor cards matching the search query',
},
query: { type: 'string', description: 'The search query used' },
count: { type: 'number', description: 'Number of Actors returned' },
instructions: { type: 'string', description: 'Additional instructions for the LLM.' },
},
required: ['actors', 'query', 'count'],
};
```
Source: [src/tools/structured_output_schemas.ts](src/tools/structured_output_schemas.ts)
## Widget Configuration
### Server Mode Detection
The UI components library operates differently based on the server mode:
| Mode | Behavior | Widget Tools Available |
|------|----------|------------------------|
| `DEFAULT` | Standard MCP response | No widget tools exposed |
| `APPS` | Widget rendering enabled | `search-actors-widget`, `fetch-actor-details-widget`, `actor-run-widget` |
Source: [src/utils/server-instructions/index.ts](src/utils/server-instructions/index.ts)
### Resource URI Scheme
Widgets are accessed via the `ui://widget/` URI scheme in APPS mode:
```
ui://widget/search-actors.html
ui://widget/actor-detail.html
ui://widget/actor-run.html
```
Source: [src/resources/resource_service.ts](src/resources/resource_service.ts)
## Development Workflow
### Pre-Work Checklist
Before any UI component work, developers should:
1. **Check MCP availability** — Search for `mcp__storybook__*` and `mcp__figma__*` tools
2. **Load design context** — Call `mcp__storybook__get-ui-building-instructions` if available
3. **Read existing patterns** — Find 1-3 similar components in `src/web/src/**/*{keyword}*.{tsx,ts}`
4. **Use Grep for patterns** — Search for `theme\.color\.|theme\.space\.|theme\.radius\.`
### Verification Protocol
Before submitting UI changes, verify:
| Check | Command/Method | Expected Result |
|-------|----------------|-----------------|
| Color audit | Regex `['"]#[0-9a-fA-F]{3,8}['"]` | Zero matches |
| Spacing audit | Regex `['"][0-9]+px['"]` | Zero matches |
| Import check | All styled-components import `theme` | 100% compliance |
| Pattern match | Compare to 1-3 similar components | Consistent structure |
Source: [DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md](DESIGN_SYSTEM_AGENT_INSTRUCTIONS.md)
## Bundle Optimization Guidelines
### Import Optimization
The `@apify/ui-library` package uses a barrel export pattern. Direct module imports significantly reduce bundle size:
```typescript
// ❌ Heavy - pulls entire library
import { Button } from '@apify/ui-library';
// ✅ Optimized - only includes Button
import { Button } from '@apify/ui-library/dist/src/primitives/Button';
```
### Cost Centers
| Component/Feature | Bundle Impact | Notes |
|-------------------|---------------|-------|
| Floating UI | High | Heavy transitive dependency |
| Markdown rendering | High | Special cost center - measure impact on changes |
| Convenience components | Medium | Prefer narrow imports |
| Primitive components | Low | Direct module imports sufficient |
Source: [res/web-widget-bundle-size.md](res/web-widget-bundle-size.md)
## Dependencies
### Core UI Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| `react` | ^18.3.1 | UI framework |
| `react-dom` | ^18.3.1 | React DOM rendering |
| `styled-components` | ^6.3.8 | CSS-in-JS styling |
| `@apify/ui-library` | ^1.124.0 | Design system tokens and primitives |
| `@apify/ui-icons` | ^1.27.2 | Icon components |
### Build Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| `esbuild` | ^0.28.0 | Fast bundler for widgets |
| `typescript` | ^5.6.3 | Type safety |
| `tailwindcss` | ^3.4.17 | Utility CSS (used sparingly) |
Source: [src/web/package.json](src/web/package.json)
---
## Development Setup
Relevant source files
The following source files were used to generate this page:
- [DEVELOPMENT.md](https://github.com/apify/apify-mcp-server/blob/main/DEVELOPMENT.md)
- [CONTRIBUTING.md](https://github.com/apify/apify-mcp-server/blob/main/CONTRIBUTING.md)
- [README.md](https://github.com/apify/apify-mcp-server/blob/main/README.md)
- [manifest.json](https://github.com/apify/apify-mcp-server/blob/main/manifest.json)
- [src/dev_server.ts](https://github.com/apify/apify-mcp-server/blob/main/src/dev_server.ts)
# Development Setup
This guide covers everything needed to set up a local development environment for the Apify MCP Server project.
## Prerequisites
### System Requirements
| Requirement | Minimum Version | Notes |
|-------------|-----------------|-------|
| Node.js | 20.0.0+ | Required runtime |
| pnpm | 11+ | Package manager |
| Claude Desktop | 0.2.16+ | For desktop integration |
**Supported Platforms:** macOS (darwin), Windows (win32), Linux (linux)
Source: [manifest.json:15-24](https://github.com/apify/apify-mcp-server/blob/main/manifest.json)
### Repository Architecture
The project uses a monorepo structure with the following key directories:
```
apify-mcp-server/
├── src/ # Main MCP server source code
│ ├── mcp/ # MCP protocol implementation
│ └── web/ # React widgets for MCP Apps UI
├── tests/
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
└── res/ # Resource documentation
```
Source: [DEVELOPMENT.md:50-57](https://github.com/apify/apify-mcp-server/blob/main/DEVELOPMENT.md)
## Installation
### 1. Enable Corepack
The project uses pnpm 11+ as specified in `package.json#packageManager`. Corepack (bundled with Node 16+) automatically manages the pnpm version:
```bash
corepack enable
```
This is a one-time setup that makes pnpm available system-wide.
### 2. Install Dependencies
Install all project dependencies in a single command:
```bash
pnpm install
```
This command installs dependencies for both the root workspace and the `src/web` workspace package simultaneously.
> **Note:** The `devEngines.packageManager` is pinned with `onFail: "error"`, which means running `npm install` or `yarn install` will fail. This ensures lockfile consistency.
Source: [DEVELOPMENT.md:41-45](https://github.com/apify/apify-mcp-server/blob/main/DEVELOPMENT.md)
## Environment Configuration
### APIFY_TOKEN Setup
The `APIFY_TOKEN` is required for most server operations.
#### For Claude Code
Create or edit `.claude/settings.local.json`:
```json
{
"env": {
"APIFY_TOKEN": ""
}
}
```
Restart Claude Code for the changes to take effect. The token is automatically picked up by both Claude Code MCP servers (defined in `.mcp.json`) and mcpc.
#### For Local Development
Create an environment file `.env` in the project root:
```text
APIFY_TOKEN="your-apify-token"
```
Source: [DEVELOPMENT.md:14-24](https://github.com/apify/apify-mcp-server/blob/main/DEVELOPMENT.md)
### Environment Variables Reference
| Variable | Required | Description |
|----------|----------|-------------|
| `APIFY_TOKEN` | Yes | Apify API authentication token |
| `APIFY_META_ORIGIN` | No | Meta origin for tracking (e.g., `STANDBY`) |
| `UI_MODE` | No | Enable UI mode for widget rendering (`true`/`false`) |
## Building the Project
### Production Build
To build the MCP server for production:
```bash
pnpm run build
```
This compiles the TypeScript source and produces output in the `dist/` directory.
Source: [DEVELOPMENT.md:64-68](https://github.com/apify/apify-mcp-server/blob/main/DEVELOPMENT.md)
### Development Server
For active development with hot-reload capabilities, the project includes a development server at `src/dev_server.ts`. This server provides:
- Automatic recompilation on file changes
- Debugging endpoints for MCP protocol inspection
- Live widget preview at `http://localhost:3001`
## Running the Server
### HTTP Streamable Mode
Run the server as an HTTP server using Apify CLI:
```bash
export APIFY_TOKEN="your-apify-token"
export APIFY_META_ORIGIN=STANDBY
apify run -p
```
The server will be exposed at `http://localhost:3001`.
Source: [README.md:28-34](https://github.com/apify/apify-mcp-server/blob/main/README.md)
### Standard I/O (stdio) Mode
For use with the MCP Inspector or local clients:
```bash
export APIFY_TOKEN="your-apify-token"
npx @modelcontextprotocol/inspector node ./dist/stdio.js
```
The Inspector will display a URL for browser-based debugging.
Source: [README.md:40-46](https://github.com/apify/apify-mcp-server/blob/main/README.md)
## Testing
### Testing Layers
The project implements a multi-layer testing strategy:
| Layer | Command | Coverage |
|-------|---------|----------|
| Unit Tests | `pnpm run test:unit` | Individual modules in isolation |
| Integration Tests | `pnpm run test:integration` | Full server over all transports against real Apify API |
| Interactive Verification | `mcpc @stdio tools-call ...` | End-to-end during development |
| LLM Evaluations | CI only | Multiple models via OpenRouter |
Source: [DEVELOPMENT.md:26-36](https://github.com/apify/apify-mcp-server/blob/main/DEVELOPMENT.md)
### Unit Tests
Unit tests verify individual modules without external dependencies:
```bash
pnpm run test:unit
```
No credentials are required for unit tests.
### Integration Tests
Integration tests verify the complete MCP server functionality:
```bash
pnpm run test:integration
```
**Requirements:**
- Valid `APIFY_TOKEN` environment variable
- Compiled production build (`pnpm run build`)
### Interactive Probing with mcpc
For manual verification during development:
```bash
mcpc @stdio tools-call ...
```
### LLM Evaluations
LLM evaluations run in CI and require the `validated` label on the PR:
```bash
# Trigger eval workflow
# 1. Apply the 'validated' label to your PR
# Environment variables required in CI:
PHOENIX_* # Phoenix evaluation platform credentials
OPENROUTER_* # OpenRouter API credentials
```
Evaluations run automatically:
- When `validated` label is applied to a PR
- On every merge to the `master` branch
Results are posted to Phoenix for analysis.
Source: [DEVELOPMENT.md:35-38](https://github.com/apify/apify-mcp-server/blob/main/DEVELOPMENT.md)
## Development Workflow
### Mermaid: Development Workflow
```mermaid
graph TD
A[Clone Repository] --> B[Enable corepack]
B --> C[pnpm install]
C --> D[Configure APIFY_TOKEN]
D --> E{Development Mode}
E -->|HTTP Stream| F[apify run -p]
E -->|stdio| G[node ./dist/stdio.js]
E -->|Widget Dev| H[src/web dev server]
F --> I[Debug with MCP Inspector]
G --> I
H --> J[Browser Preview: localhost:3001]
I --> K{Testing}
K -->|Unit| L[pnpm run test:unit]
K -->|Integration| M[pnpm run test:integration]
K -->|Manual| N[mcpc probing]
L --> O[Validate & Submit PR]
M --> O
N --> O
```
### Branch Naming
All feature branches must follow the format:
```
/
```
Where `` matches conventional commit types:
| Type | Use Case |
|------|----------|
| `feat` | New features |
| `fix` | Bug fixes |
| `chore` | Maintenance tasks |
| `refactor` | Code refactoring |
| `docs` | Documentation updates |
**Examples:**
- `feat/add-dataset-tool`
- `fix/connection-timeout`
- `chore/update-dependencies`
Source: [CONTRIBUTING.md:8-13](https://github.com/apify/apify-mcp-server/blob/main/CONTRIBUTING.md)
### Commit Messages
All commits and PR titles must follow the **Conventional Commits** format:
```
()!:
```
| Component | Required | Description |
|-----------|----------|-------------|
| type | Yes | feat, fix, chore, refactor, docs, etc. |
| scope | Yes | The affected component/module |
| `!` | No | Indicates breaking change |
| description | Yes | Brief summary of changes |
**Examples:**
```
feat: Add new tool for fetching actor details
feat!: Migrate to new MCP SDK version
fix: Handle connection errors gracefully
chore: Update dependencies
```
Source: [CONTRIBUTING.md:17-35](https://github.com/apify/apify-mcp-server/blob/main/CONTRIBUTING.md)
## UI Widget Development
### Widget Architecture
The MCP Apps (ChatGPT Apps) UI widgets are built as a separate React project within `src/web/`. Widgets are rendered based on tool output—modifying widget data requires changing the corresponding tool's return value.
### UI Mode
Widget rendering requires the server to run in UI mode:
**Via Query Parameter:**
```
/mcp?ui=true
```
**Via Environment Variable:**
```bash
export UI_MODE=true
```
**Via CLI Flag:**
```bash
npx @apify/actors-mcp-server --ui true
```
### Widget Preview
Preview widgets during development:
```bash
# Actor Search Widget
# Open: http://localhost:3001/index-actor-search.html
# Actor Run Widget
# Open: http://localhost:3001/index-actor-run.html
```
Source: [DEVELOPMENT.md:58-62](https://github.com/apify/apify-mcp-server/blob/main/DEVELOPMENT.md)
## Code Quality Standards
### Naming Conventions
| Element | Convention | Example |
|---------|------------|---------|
| Types/Interfaces | PascalCase | `ActorDetails`, `ToolConfig` |
| Variables/Functions | camelCase | `actorName`, `fetchActorDetails()` |
| Constants | SCREAMING_SNAKE_CASE | `MAX_RETRIES`, `WIDGET_REGISTRY` |
| Zod Validators | Suffix with `Validator` | `ActorValidator` |
### String Formatting
**Single-line strings:** Use single quotes
```typescript
const message = 'Operation completed';
```
**Multi-line strings:** Use `dedent` for LLM-facing content
```typescript
import dedent from 'dedent';
const description = dedent`
Line 1
Line 2
`;
```
**Avoid:**
- `[].join('\n')` for multiline strings
- Hardcoded hex colors or pixel values in UI code
Source: [CONTRIBUTING.md:56-75](https://github.com/apify/apify-mcp-server/blob/main/CONTRIBUTING.md)
## Troubleshooting
### Common Issues
| Issue | Solution |
|-------|----------|
| `pnpm install` fails | Ensure Node.js 20+ is installed |
| Wrong pnpm version | Run `corepack enable` |
| Tests fail with "Token required" | Set `APIFY_TOKEN` environment variable |
| Widgets not rendering | Verify `UI_MODE=true` is set |
### Node Version Management
The `.nvmrc` file pins the development tooling Node version (currently 24). This is intentionally higher than the published floor to support modern tooling features.
```bash
# Check current Node version
node --version
# Switch to project-required version (requires nvm)
nvm use
```
### Verifying Installation
Run the following commands to verify your setup:
```bash
# Verify pnpm version
pnpm --version # Should be 11+
# Verify Node version
node --version # Should be 20+
# Run unit tests
pnpm run test:unit
# Build project
pnpm run build
```
If all commands succeed, your development environment is properly configured.
---
---
## Doramagic Pitfall Log
Project: apify/apify-mcp-server
Summary: Found 22 potential pitfall items; 5 are high/blocking. Highest priority: installation - 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode.
## 1. installation · 来源证据：fix: Allow calling MCP server actors in normal (one-shot) mode
- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：fix: Allow calling MCP server actors in normal (one-shot) mode
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_be82315ed0f441ba9d942931d846d78c | https://github.com/apify/apify-mcp-server/issues/857 | 来源类型 github_issue 暴露的待验证使用条件。
## 2. configuration · 来源证据：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`
- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Remove the flat-fields back-compat shim from `_meta.x402` once all consumers read `accepts[]`
- User impact: 可能影响升级、迁移或版本选择。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_8ec6ff22f24a4bb18b439177f4a8c270 | https://github.com/apify/apify-mcp-server/issues/892 | 来源类型 github_issue 暴露的待验证使用条件。
## 3. security_permissions · 来源证据：Do not include the rag web browser when ?payment=x402
- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Do not include the rag web browser when ?payment=x402
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_23bafe4901554148896241f0a1e183b0 | https://github.com/apify/apify-mcp-server/issues/875 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. security_permissions · 来源证据：Perf: `search-actors` tools returns huuuge `inputFields` object
- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Perf: `search-actors` tools returns huuuge `inputFields` object
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_af51cb3cbcb3479fbbdf27cedef734aa | https://github.com/apify/apify-mcp-server/issues/888 | 来源类型 github_issue 暴露的待验证使用条件。
## 5. security_permissions · 来源证据：feat(telemetry): track tool result size in bytes
- Severity: high
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：feat(telemetry): track tool result size in bytes
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_9c2ef77c88914458910ae67d9f903931 | https://github.com/apify/apify-mcp-server/issues/838 | 来源类型 github_issue 暴露的待验证使用条件。
## 6. identity · 仓库名和安装名不一致
- Severity: medium
- Evidence strength: runtime_trace
- Finding: 仓库名 `apify-mcp-server` 与安装入口 `@apify/actors-mcp-server` 不完全一致。
- User impact: 用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- Suggested check: 在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
- Reproduction command: `npx @apify/actors-mcp-server`
- Guardrail action: 页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
- Evidence: identity.distribution | github_repo:911256711 | https://github.com/apify/apify-mcp-server | repo=apify-mcp-server; install=@apify/actors-mcp-server
## 7. installation · 来源证据：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：chore(core): collapse array indices in dataset fields to prevent nextStep schema bloat
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_9c05c17621e3443dad6175f21db31a34 | https://github.com/apify/apify-mcp-server/issues/894 | 来源类型 github_issue 暴露的待验证使用条件。
## 8. installation · 来源证据：feat: Add structured output to remaining storage tools
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: Add structured output to remaining storage tools
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_c9b7c39f3e8f43e88ee52c2c8ae94b01 | https://github.com/apify/apify-mcp-server/issues/884 | 来源类型 github_issue 暴露的待验证使用条件。
## 9. installation · 来源证据：feat: migrate direct actor tools to canonical RunResponse shape
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：feat: migrate direct actor tools to canonical RunResponse shape
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_6b304ff2763849fe9b4678cc7bf9f5b2 | https://github.com/apify/apify-mcp-server/issues/852 | 来源类型 github_issue 暴露的待验证使用条件。
## 10. installation · 来源证据：test: Consolidate duplicated MCP server test fixtures
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安装相关的待验证问题：test: Consolidate duplicated MCP server test fixtures
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_5a7a24d9e8ce42468a7775a54dfa8ca6 | https://github.com/apify/apify-mcp-server/issues/847 | 来源类型 github_issue 暴露的待验证使用条件。
## 11. configuration · 来源证据：feat: Dataset tools correctness and coverage
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个配置相关的待验证问题：feat: Dataset tools correctness and coverage
- User impact: 可能阻塞安装或首次运行。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_3fa86b498f66434a8f247c1b63fb56c9 | https://github.com/apify/apify-mcp-server/issues/784 | 来源类型 github_issue 暴露的待验证使用条件。
## 12. capability · 能力判断依赖假设
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: 假设不成立时，用户拿不到承诺的能力。
- Suggested check: 将假设转成下游验证清单。
- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。
- Evidence: capability.assumptions | github_repo:911256711 | https://github.com/apify/apify-mcp-server | README/documentation is current enough for a first validation pass.
## 13. runtime · 来源证据：chore: Add mixpanel analytics for storage tools + error rates
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：chore: Add mixpanel analytics for storage tools + error rates
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_03dbd8daa0c840d690bddb1d52e189c1 | https://github.com/apify/apify-mcp-server/issues/887 | 来源类型 github_issue 暴露的待验证使用条件。
## 14. maintenance · 维护活跃度未知
- Severity: medium
- Evidence strength: source_linked
- Finding: 未记录 last_activity_observed。
- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。
- Evidence: evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | last_activity_observed missing
## 15. security_permissions · 下游验证发现风险项
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 下游已经要求复核，不能在页面中弱化。
- Suggested check: 进入安全/权限治理复核队列。
- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。
- Evidence: downstream_validation.risk_items | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium
## 16. security_permissions · 存在评分风险
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 风险会影响是否适合普通用户安装。
- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。
- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。
- Evidence: risks.scoring_risks | github_repo:911256711 | https://github.com/apify/apify-mcp-server | no_demo; severity=medium
## 17. security_permissions · 来源证据：[Bug]: Inconsistent `search-actors` schema and results
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug]: Inconsistent `search-actors` schema and results
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_364bc036f84b42e8b7be6534cb76381e | https://github.com/apify/apify-mcp-server/issues/889 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 18. security_permissions · 来源证据：design: Calibrate get-dataset-schema output detail
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：design: Calibrate get-dataset-schema output detail
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_8b7a4266d8eb4298919b5cb2a58fa420 | https://github.com/apify/apify-mcp-server/issues/882 | 来源类型 github_issue 暴露的待验证使用条件。
## 19. security_permissions · 来源证据：refactor: Extract storage tool helpers
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：refactor: Extract storage tool helpers
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_496f0061952341728e4222b961251325 | https://github.com/apify/apify-mcp-server/issues/890 | 来源类型 github_issue 暴露的待验证使用条件。
## 20. security_permissions · 来源证据：tools/list response contains `type: "unknown"` in an input schema — rejected by ajv-based MCP clients (LibreChat)
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：tools/list response contains `type: "unknown"` in an input schema — rejected by ajv-based MCP clients (LibreChat)
- User impact: 可能影响授权、密钥配置或安全边界。
- Suggested check: 来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_77fae88d35e2486d8125a2ecea9abdc7 | https://github.com/apify/apify-mcp-server/issues/738 | 来源讨论提到 node 相关条件，需在安装/试用前复核。
## 21. maintenance · issue/PR 响应质量未知
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: 用户无法判断遇到问题后是否有人维护。
- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。
- Guardrail action: issue/PR 响应未知时，必须提示维护风险。
- Evidence: evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | issue_or_pr_quality=unknown
## 22. maintenance · 发布节奏不明确
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。
- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。
- Evidence: evidence.maintainer_signals | github_repo:911256711 | https://github.com/apify/apify-mcp-server | release_recency=unknown