Skip to content

index.md

Latest commit

 

History

History
103 lines (80 loc) · 5.35 KB

index.md

File metadata and controls

103 lines (80 loc) · 5.35 KB

Resources Directory Index

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.

Files

algolia.md

Technical analysis of Algolia search API responses for each documentation source.

  • Data structure overview for each doc source (apify, crawlee-js, crawlee-py)
  • Field availability patterns (content, hierarchy, anchors)
  • Example response payloads
  • Recommendations for response processing logic
  • Use case: Understand what data is actually returned by Algolia to inform simplification decisions

mcp_server_refactor_analysis.md

Implementation plan for migrating from low-level Server to high-level McpServer API.

Structure:

  1. Executive Summary - High-level overview for stakeholders
  2. Executive Implementation Plan - Technical summary for developers
  3. Detailed Implementation Guide - Step-by-step guide for coding agents

Key approach: Callback-per-tool architecture where each tool's callback encapsulates its execution logic.

Estimated effort: 8-13 developer days

  • Feature preservation matrix
  • Code examples (before/after)
  • Migration steps with specific file changes
  • Testing strategy
  • Use case: Reference for implementing the MCP SDK migration

mcp_resources_analysis.md

MCP resources behavior and constraints (Skyfire readme and UI widgets), low-level Server API usage.

  • Handler wiring and delegation to resource_service
  • Resource list/read behavior and error handling
  • Use case: Baseline for how resources are exposed and why

mcp_task_reference.md

MCP task lifecycle, SDK features, and protocol reference for the Apify MCP server.

  • Task states, protocol flow, key SDK types (Task, TaskStore, ResponseMessage)
  • How executeToolAndUpdateTask() implements tasks with mcpTaskExecution flag
  • Available but unused SDK features: resource links, dynamic resources, elicitation, completion
  • Current server capabilities declaration
  • Related issues: #582 (async call-actor), #587 (roadmap), #588 (tool naming)
  • Use case: Reference when working on MCP task integration, resource links, or protocol-level features

patterns_for_simplification.md

Analysis of patterns from the official TypeScript MCP SDK and FastMCP framework that could simplify the codebase.

Key patterns identified:

  1. Callback-Per-Tool Registration - Eliminate central dispatcher (~250 LOC reduction)
  2. Unified Tool Context - Cleaner tool execution interface
  3. Zod-First Validation - Replace AJV with direct Zod validation
  4. Automatic Notifications - Self-managing tool list changes
  5. Progress via Context - Simplified progress reporting
  6. Structured Error Handling - Consistent UserError pattern
  7. Type-Safe Registration - Generic tool definitions
  8. Session-Aware Operations - Context-based session access

Estimated total effort: 10-14 days for full implementation

  • Prioritized implementation phases
  • Before/after code examples
  • Benefits for each pattern
  • Use case: Reference for incremental codebase improvements

actor_input_schema_required_fields.md

Apify input-schema spec semantics (required vs default vs prefill), the root cause of #637 (phantom default: undefined keys from filterSchemaProperties), before/after examples for apify/rag-web-browser, a table of 6 real Actor fields, and the follow-up cleanup plan (#675).

  • Use case: Reference when touching fixZodSchemaRequired, filterSchemaProperties, or any Actor input-schema normalisation logic.

web-widget-bundle-size.md

Notes on keeping widget bundles small (narrow @apify/ui-library imports, markdown stack cost).

  • Use case: When changing widget dependencies or markdown rendering, re-measure bundle impact

chatgpt-app-submission.md

Checklist and notes for ChatGPT MCP Apps store submission (verify line references against current source before relying on them).

  • Use case: Submission prep and audits

tasks_cancel_abort_flow.md

How tasks/cancel propagates from the SDK through the polling watcher to apifyClient.run(runId).abort(). Mermaid sequence diagrams for before/after PR #812 (issue #763), end-to-end signal path, multi-node rationale, hardening notes (tickInProgress, transient-error swallowing).

  • Use case: Reference when touching createTaskCancellationWatcher, executeToolAndUpdateTask, or callActorGetDataset cancellation paths.

Purpose

Resources in this directory serve as:

  • Technical references for complex subsystems (e.g., Algolia integration)
  • Decision documentation explaining why certain approaches were chosen
  • Data analysis for optimization and refactoring efforts
  • Integration guides for external services and APIs

Guidelines

  • Keep documents short and technical - avoid duplicating code logic
  • Focus on insights and patterns rather than implementation details
  • Use tables, examples, and structured data for clarity
  • Link to relevant source files when explaining code flow
  • Update when making significant changes to documented systems