// Explore, analyze, plan, or spec features for the Apify MCP server. Adapts to what the user asks — from quick code exploration to full GitHub issue specs. Use when the user asks to explore code, understand behavior, plan a change, design a feature, or create an issue spec.
| name | dig |
| description | Explore, analyze, plan, or spec features for the Apify MCP server. Adapts to what the user asks — from quick code exploration to full GitHub issue specs. Use when the user asks to explore code, understand behavior, plan a change, design a feature, or create an issue spec. |
| argument-hint | <your request> [--sdk <path>] [--ext-apps <path>] [--internal <path>] |
| allowed-tools | ["Read","Glob","Grep","Bash","WebFetch","WebSearch","Agent"] |
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.
$ARGUMENTS contains the user's request and optional repo path overrides.
Flags (optional):
| Flag | Default | Purpose |
|---|---|---|
--sdk | ../typescript-sdk | MCP SDK source repo path |
--ext-apps | ../ext-apps | MCP Apps SDK source repo path |
--internal | ../apify-mcp-server-internal | Internal server repo path |
Everything not matching a flag is the user's request.
Resolution order for source repos: flag path → default sibling path → node_modules/ (compiled types only) → GitHub URL (last resort). Always verify the path exists before using it.
Infer the intent from the user's natural language. There are three modes:
| Intent | What you do | Examples |
|---|---|---|
| Explore | Read code, explain findings, answer questions | "how does tool naming work", "look at the widget code", "why is this broken", "what would break if we change X" |
| Plan | Enter plan mode, design the approach, assess impact | "plan implementing resource links", "figure out how to refactor metadata", "design the simplification" |
| Spec | Plan + create GitHub issues | "write an issue for X", "create a spec for Y", "spec out resource links" |
Rules:
Read the relevant source files and explain your findings. This is the baseline for all intents.
What to do:
Stop here if the intent is Explore.
Use the EnterPlanMode tool, then design the approach.
What to do:
../apify-mcp-server-internal if available)mcpc @stdio tools-call to probe current behavior if useful (requires pnpm run build)Key conventions:
tests/integration/suite.tsapify-mcp-server-internal — always assess impactCLAUDE.md § Public/internal repo separationCLAUDE.md, CONTRIBUTING.md, and DEVELOPMENT.md for full conventionsStop here if the intent is Plan. Exit plan mode with ExitPlanMode.
Create GitHub issues. First exit plan mode with ExitPlanMode.
Search for duplicates and related issues:
gh issue list -R apify/apify-mcp-server --search "<keywords>" --json number,title,state
gh issue list -R apify/ai-team --search "<keywords>" --json number,title,state
gh issue list -R apify/apify-mcp-server-internal --search "<keywords>" --json number,title,state
If a matching issue exists, update it with gh issue edit instead of creating a new one.
One issue per implementation phase. A phase = one PR-sized unit of work (~50-200 lines changed). Each issue should be independently implementable.
Use the repo's feature_spec.yml template. Only the Problem and Proposed solution fields are required. Include Plan and Alternatives considered only when they add real value. No fluff, no filler — straight to the point.
## Problem
[Concrete evidence: error messages, user reports, issue links. Not "users are confused" — instead "3 users reported X in #channel".]
## Proposed solution
[Short. Reference existing code paths. List files inline if needed.]
## Plan
- [ ] Step 1
- [ ] Step 2
## Alternatives considered
[Only if you actually evaluated other approaches.]
Style (applies to issues AND all dig output — explanations, plans, specs):
CLAUDE.md § Communication styleSelf-review before presenting:
Present issue content to the user for review before creating. Use gh issue create with t-ai label.
| Resource | Path / URL | Use for |
|---|---|---|
| Public repo | . (this repo root) | Main codebase — tools, widgets, tests |
| Internal repo | ../apify-mcp-server-internal (if available) | Hosted server — assess impact of changes |
| MCP SDK (types) | node_modules/@modelcontextprotocol/sdk | Protocol types, server/client APIs (compiled only) |
| MCP SDK (source) | ../typescript-sdk (if available) | Examples, tests, full source — faster than GitHub |
| MCP spec | https://modelcontextprotocol.io/specification/2025-11-25 | Protocol-level features |
| MCP Apps SDK (types) | node_modules/@modelcontextprotocol/ext-apps | MCP Apps types, React hooks, server helpers (compiled only) |
| MCP Apps SDK (source) | ../ext-apps (if available) | Examples, tests, spec, full source — faster than GitHub |
| MCP Apps spec | https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx | MCP Apps extension specification |
| Dev server (no UI) | http://localhost:3001/ / tools: mcp__apify-dev__* | Test tools without widgets |
| Dev server (UI) | http://localhost:3001/?ui=true / tools: mcp__apify-dev-ui__* | Test tools with widget rendering |
| mcpc stdio | mcpc @stdio tools-call ... (requires pnpm run build) | Test tools — no running server needed |