From de99b3ccd8bc42751f8853a8975305a36dd4cd0b Mon Sep 17 00:00:00 2001 From: Jiri Spilka Date: Tue, 9 Dec 2025 09:54:25 +0100 Subject: [PATCH 1/2] fix: update AGENTS.md with mcp testing --- AGENTS.md | 24 ++++++++++++++++++++++++ 1 file changed, 24 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index b1c41a3f..c1c8bd54 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -62,6 +62,30 @@ MANDATORY: Always check for TypeScript compilation errors before running tests o - Follow existing test patterns in the codebase - Ensure all tests pass before submitting a PR +### Manual testing as MCP client + +You can manually test the MCP server by acting as an MCP client and invoking tools directly with real API calls. + +**How to test:** +1. Connect to the MCP server (e.g., using `/mcp` command in Claude Code) +2. Test each tool with both valid inputs (happy path) and invalid inputs (edge cases) +3. Verify outputs match expected formats and error messages are clear + +**Available tools to test:** +- **search-actors** - Search Apify Store (test: valid keywords, empty keywords, non-existent platforms) +- **fetch-actor-details** - Get Actor info (test: valid actor, non-existent actor) +- **call-actor** - Execute Actor in two steps: `step="info"` to get schema, then `step="call"` to run +- **apify/rag-web-browser** - Scrape web content (test: URL, search query) +- **get-actor-output** - Retrieve Actor results (test: valid datasetId, field filtering, non-existent dataset) +- **search-apify-docs** - Search documentation (test: relevant terms, non-existent topics) +- **fetch-apify-docs** - Fetch doc page (test: valid URL, non-existent page) + +**Key behaviors to verify:** +- **call-actor** requires two-step workflow (info → call) +- All tools return helpful error messages with suggestions +- **get-actor-output** supports field filtering using dot notation +- Search tools support pagination with `limit` and `offset` + ## Coding guidelines ### Indentation From 68c61f46b1e08f08b4c31e1e58980228993f858a Mon Sep 17 00:00:00 2001 From: Jiri Spilka Date: Sat, 13 Dec 2025 12:35:12 +0100 Subject: [PATCH 2/2] fix: update AGENTS.md with mcp testing --- AGENTS.md | 64 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 50 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c1c8bd54..18ab2a21 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,6 +2,9 @@ ## Overview +This is an MCP (Model Context Protocol) server that exposes [Apify Actors](https://apify.com/store) as tools. +It enables AI assistants to discover and use thousands of web scraping and automation tools from the Apify Store. + The codebase is built with TypeScript using ES modules and follows a modular architecture with clear separation of concerns. The server can run in multiple modes: @@ -9,6 +12,13 @@ The server can run in multiple modes: - **HTTP Streamable**: For hosted deployments and web-based MCP clients - **Legacy SSE over HTTP**: Legacy version of the protocol for hosted deployments and web-based clients (deprecated and will be removed in the future) +### Key concepts + +- **MCP**: Model Context Protocol defines tools, resources, and prompts that AI agents can use +- **Apify Actors**: Reusable automation tools (web scrapers, data extractors) available on Apify Store +- **Tool discovery**: Actors are dynamically converted to MCP tools based on their input schemas +- **Two-step Actor execution**: `call-actor` requires `step="info"` to get schema, then `step="call"` to execute + ### Root directories - `src/`: Main TypeScript source code - `tests/`: Unit and integration tests @@ -62,30 +72,40 @@ MANDATORY: Always check for TypeScript compilation errors before running tests o - Follow existing test patterns in the codebase - Ensure all tests pass before submitting a PR -### Manual testing as MCP client +### Manual testing as an MCP client + +To test the MCP server, a human must first configure the MCP server. +Once configured, the server exposes tools that become available to the coding agent. + +#### 1. Human setup (required before testing) + +1. **Configure the MCP server** in your environment (e.g., Claude code, VS Code, Cursor) +2. **Verify connection**: The client should connect and list available tools automatically +3. **Tools are now available**: Once connected, all MCP tools are exposed and ready to use + +#### 2. Coding agent testing workflow -You can manually test the MCP server by acting as an MCP client and invoking tools directly with real API calls. +**Note**: Only execute this testing workflow when explicitly requested by the user. -**How to test:** -1. Connect to the MCP server (e.g., using `/mcp` command in Claude Code) -2. Test each tool with both valid inputs (happy path) and invalid inputs (edge cases) -3. Verify outputs match expected formats and error messages are clear +Once the server is configured, test the MCP tools by: -**Available tools to test:** +1. **Invoke each tool** through the MCP client (e.g., ask the AI agent to "search for actors" or "fetch actor details for apify/rag-web-browser") +2. **Test with valid inputs** (happy path) – verify outputs match expected formats +3. **Test with invalid inputs** (edge cases) – verify error messages are clear and helpful +4. **Verify key behaviors**: + - **call-actor** requires two-step workflow (`step="info"` then `step="call"`) + - All tools return helpful error messages with suggestions + - **get-actor-output** supports field filtering using dot notation + - Search tools support pagination with `limit` and `offset` + +**Tools to test:** - **search-actors** - Search Apify Store (test: valid keywords, empty keywords, non-existent platforms) - **fetch-actor-details** - Get Actor info (test: valid actor, non-existent actor) - **call-actor** - Execute Actor in two steps: `step="info"` to get schema, then `step="call"` to run -- **apify/rag-web-browser** - Scrape web content (test: URL, search query) - **get-actor-output** - Retrieve Actor results (test: valid datasetId, field filtering, non-existent dataset) - **search-apify-docs** - Search documentation (test: relevant terms, non-existent topics) - **fetch-apify-docs** - Fetch doc page (test: valid URL, non-existent page) -**Key behaviors to verify:** -- **call-actor** requires two-step workflow (info → call) -- All tools return helpful error messages with suggestions -- **get-actor-output** supports field filtering using dot notation -- Search tools support pagination with `limit` and `offset` - ## Coding guidelines ### Indentation @@ -157,6 +177,22 @@ We use **4 spaces** for indentation (configured in `.editorconfig`). - If mutation is necessary, clearly document and explain it with a comment - Clean up temporary files, scripts, or helper files created during development +### Common patterns + +- **Tool implementation**: Tools are defined in `src/tools/` using Zod schemas for validation +- **Actor interaction**: Use `src/utils/apify-client.ts` for Apify API calls, never call Apify API directly +- **Error responses**: Return user-friendly error messages with suggestions +- **Input validation**: Always validate tool inputs with Zod before processing +- **Caching**: Use TTL-based caching for Actor schemas and details (see `src/utils/ttl-lru.ts`) + +### Anti-patterns + +- **Don't** call Apify API directly – always use the Apify client utilities +- **Don't** mutate function parameters without clear documentation +- **Don't** skip input validation – all tool inputs must be validated with Zod +- **Don't** use `Promise.then()` - prefer `async/await` +- **Don't** create tools without proper error handling and user-friendly messages + ## External dependencies ### Important relationship: apify-mcp-server-internal