sync_resources

Synchronize subscribed AI resources with hybrid sync strategy. Command and Skill resources: registered as MCP Prompts on the server. Complex skills with scripts download local files to ISOLATED PATH (~/.csp-ai-agent/skills/<name>/) to prevent AI auto-discovery. CRITICAL: .csp-ai-agent MUST be a SIBLING of .cursor (same parent directory). AI Agent on Windows must: (1) find .cursor location (check user home first, then AppData), (2) extract parent directory, (3) create .csp-ai-agent in that parent directory. This ensures telemetry tracking by forcing resolve_prompt_content as entry point. If the user subscribed to a NEW Command or Skill in THIS conversation and you need to execute it immediately, do NOT wait for native prompts/get. After this tool completes, call `resolve_prompt_content` with the new prompt_name or resource_id, then execute the returned content. ⚠️ CRITICAL: HANDLING LARGE RESULTS (>100KB with many local_actions_required) When this tool returns local_actions_required array with many actions (>10) or large content fields: (1) DO NOT try to display or read the full result JSON — it may be 100KB-500KB. (2) DO NOT just read the summary field and stop — local_actions are MANDATORY. (3) IMMEDIATELY start executing actions in order: - Parse each action from local_actions_required array - Execute write_file / merge_mcp_json / delete_file as instructed below - Track success/failure count for each action (4) Report concise summary to user: "Executed 46 local actions: 45 succeeded, 1 failed" (5) Only show failed actions in detail (do not list all successful actions) Rule and MCP resources are returned as `local_actions_required` — an ordered list of write_file, merge_mcp_json, or other actions that the AI Agent MUST execute on the USER'S LOCAL MACHINE after receiving the response. Execute every action in the list in order before reporting success to the user. 📌 SINGLE-RESOURCE SYNC (recommended after subscribe): Pass `resource_ids: ["<id>"]` to sync only specific resource(s). local_actions_required will contain ONLY actions for those resources — drastically reduces context overhead. Use this after manage_subscription(subscribe) to sync just the newly subscribed resource. ⚠️ FULL SYNC CONFIRMATION REQUIRED: Calling with mode="full" without resource_ids requires user confirmation. The server returns error code FULL_SYNC_REQUIRES_CONFIRMATION. Surface the warning to the user, and if confirmed, retry with _confirmed_full_sync: true. Full sync with resource_ids (scoped) does NOT require confirmation. OPTIMIZATION: Before calling this tool in incremental mode, read ~/.cursor/mcp.json and pass Object.keys(mcpServers || {}) as `configured_mcp_servers` parameter. This allows the server to skip downloading MCP resources that are already configured, significantly reducing API calls, network traffic, and local action overhead. ⚠️ BASE64 DECODE — APPLIES TO BOTH write_file AND check_file: When `encoding === "base64"` (write_file) or `expected_content_encoding === "base64"` (check_file), the corresponding `content` / `expected_content` field is base64-encoded by the server. The server does this for ALL non-.md/.mdc files (shell scripts, configs, binary blobs) to keep Cursor's renderer from triggering catastrophic regex backtracking on raw script characters ($(), [[ ]], URLs etc.) — see prior incident notes. AI Agent MUST decode base64 BEFORE writing to disk or comparing against local content: write_file: fileBytes = Buffer.from(action.content, "base64") (write as binary buffer) check_file: decoded = Buffer.from(action.expected_content, "base64").toString("utf8") then string-compare against fs.readFileSync(action.path, "utf8") When the encoding field is "utf8" (or omitted), the value is the literal file body — write or compare as-is, no decoding. For write_file actions: SPECIAL HANDLING FOR COMPLEX SKILLS (when action has `is_skill_manifest: true`): (1) This action is the FIRST script file — check skill version using manifest FIRST. (2) Read manifest file at {CSP_AGENT_ROOT}/.manifests/<skill-name>.md (if exists). Where {CSP_AGENT_ROOT} is a SIBLING of {CURSOR_ROOT} (same parent directory). (3) action.skill_manifest_content is ALWAYS base64-encoded — first decode it: decodedManifest = Buffer.from(action.skill_manifest_content, "base64").toString("utf8") Then compare decodedManifest against the existing manifest file content (string equality). (4) If identical: SKIP this action AND ALL SUBSEQUENT write_file actions for this skill. (5) If different or manifest missing: - PROCEED with this action and all subsequent write_file actions for this skill. - After writing all script files, write decodedManifest (the UTF-8 form, NOT the raw base64 string) to {CSP_AGENT_ROOT}/.manifests/<skill-name>.md (6) NOTE: SKILL.md is NEVER written to the skills directory (only to .manifests/) to prevent Cursor auto-discovery. GENERAL HANDLING (when action has NO `is_skill_manifest` marker): (1) Read the existing file at `path` (if it exists) using fs.readFile() or equivalent. (2) Compare the file content directly (string equality) against the `content` field. (3) SKIP the write if they are EXACTLY equal — the file is already up-to-date. (4) Otherwise, create any missing parent directories and write the file. (5) If `mode` field is present (e.g. "0755"), set file permissions using fs.chmod() on Unix systems. CRITICAL — DUAL-LAYER RULE SYNC (when scope=all): When syncing Rule resources with scope=all, the server generates TWO INDEPENDENT write_file actions: one for global (~/.cursor/rules/) and one for workspace (<workspace>/.cursor/rules/). The AI MUST process EACH action independently with its own content comparison: - Action #1: Compare ~/.cursor/rules/xxx.mdc content → skip if identical, write if different. - Action #2: Compare .cursor/rules/xxx.mdc content → skip if identical, write if different. NEVER assume both locations have the same content. NEVER skip action #2 just because action #1 was skipped. Example: global is v2.0 (skip), workspace is v1.0 (must update) — both actions must be checked separately. For merge_mcp_json actions: (1) If the action has `skip_if_exists: true` AND `mcpServers[server_name]` already exists in ~/.cursor/mcp.json, SKIP this action entirely — the server is already configured and any user-edited env values must not be overwritten. (2) Otherwise read the existing ~/.cursor/mcp.json, smart-merge the provided entry (preserve existing user env values), then write the file back. For check_file actions (check mode only): (1) Read the local file at `path` (if it exists). (2) Compare the local file content directly (string equality) against the `expected_content` field. (3) Report the check result: - "match" if content is identical (resource is up-to-date). - "mismatch" if content differs (resource needs updating). - "missing" if the local file does not exist (resource needs installation). (4) Aggregate all check results and update the sync_resources response: - If ALL files match → report resource as "cached". - If ANY file mismatches or is missing → report resource as "failed" (needs sync).. It is categorised as a Execute tool in the Ai Agent MCP Server, which means it can trigger actions or run processes. Use rate limits and argument validation.

Add a rule in your Intercept YAML policy under the tools section for sync_resources. You can allow, deny, rate-limit, or validate arguments. Then run Intercept as a proxy in front of the Ai Agent MCP server.

sync_resources is a Execute tool with high risk. Execute tools should be rate-limited and have argument validation enabled.

Yes. Add a rate_limit block to the sync_resources rule in your Intercept policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.

Set action: deny in the Intercept policy for sync_resources. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.

sync_resources is provided by the Ai Agent MCP server (@elliotding/ai-agent-mcp). Intercept sits as a proxy in front of this server to enforce policies before tool calls reach the server.