cursor_agent_search_repo

Instructions

Implementation Reference

• server.js:343-358 (handler)

  The handler function composes a prompt from the query, include, and exclude parameters and invokes the shared runCursorAgent executor to perform the repo search via the cursor-agent CLI.

  async (args) => {
    try {
      const { query, include, exclude, output_format, cwd, executable, model, force, extra_args } = args;
      const inc = include == null ? [] : (Array.isArray(include) ? include : [include]);
      const exc = exclude == null ? [] : (Array.isArray(exclude) ? exclude : [exclude]);
      const composedPrompt =
        `Search the repository for occurrences relevant to:\n` +
        `- Query: ${String(query)}\n` +
        (inc.length ? `- Include globs:\n${inc.map((p)=>`  - ${String(p)}`).join('\n')}\n` : '') +
        (exc.length ? `- Exclude globs:\n${exc.map((p)=>`  - ${String(p)}`).join('\n')}\n` : '') +
        `Return concise findings with file paths and line references.`;
      return await runCursorAgent({ prompt: composedPrompt, output_format, extra_args, cwd, executable, model, force });
    } catch (e) {
      return { content: [{ type: 'text', text: `Invalid params: ${e?.message || e}` }], isError: true };
    }
  },

• server.js:255-260 (schema)

  Zod schema defining the input parameters: required 'query' string, optional 'include' and 'exclude' as string or array of globs, plus shared COMMON fields like output_format, model, etc.

  const SEARCH_REPO_SCHEMA = z.object({
    query: z.string().min(1, 'query is required'),
    include: z.union([z.string(), z.array(z.string())]).optional(),
    exclude: z.union([z.string(), z.array(z.string())]).optional(),
    ...COMMON,
  });

• server.js:339-359 (registration)

  Registration of the 'cursor_agent_search_repo' tool on the MCP server, providing name, description, schema, and inline handler function.

  server.tool(
    'cursor_agent_search_repo',
    'Search repository code with include/exclude patterns. Prompt-based wrapper.',
    SEARCH_REPO_SCHEMA.shape,
    async (args) => {
      try {
        const { query, include, exclude, output_format, cwd, executable, model, force, extra_args } = args;
        const inc = include == null ? [] : (Array.isArray(include) ? include : [include]);
        const exc = exclude == null ? [] : (Array.isArray(exclude) ? exclude : [exclude]);
        const composedPrompt =
          `Search the repository for occurrences relevant to:\n` +
          `- Query: ${String(query)}\n` +
          (inc.length ? `- Include globs:\n${inc.map((p)=>`  - ${String(p)}`).join('\n')}\n` : '') +
          (exc.length ? `- Exclude globs:\n${exc.map((p)=>`  - ${String(p)}`).join('\n')}\n` : '') +
          `Return concise findings with file paths and line references.`;
        return await runCursorAgent({ prompt: composedPrompt, output_format, extra_args, cwd, executable, model, force });
      } catch (e) {
        return { content: [{ type: 'text', text: `Invalid params: ${e?.message || e}` }], isError: true };
      }
    },
  );

• server.js:153-193 (helper)

  Shared helper function that normalizes arguments and spawns the cursor-agent CLI process, used by all tools including search_repo.

  async function runCursorAgent(input) {
    const source = (input && typeof input === 'object' && input.arguments && typeof input.prompt === 'undefined')
      ? input.arguments
      : input;
  
    const {
      prompt,
      output_format = 'text',
      extra_args,
      cwd,
      executable,
      model,
      force,
    } = source || {};
  
    const argv = [...(extra_args ?? []), String(prompt)];
    const usedPrompt = argv.length ? String(argv[argv.length - 1]) : '';
   
    // Optional prompt echo and debug diagnostics
    if (process.env.DEBUG_CURSOR_MCP === '1') {
      try {
        const preview = usedPrompt.slice(0, 400).replace(/\n/g, '\\n');
        console.error('[cursor-mcp] prompt:', preview);
        if (extra_args?.length) console.error('[cursor-mcp] extra_args:', JSON.stringify(extra_args));
        if (model) console.error('[cursor-mcp] model:', model);
        if (typeof force === 'boolean') console.error('[cursor-mcp] force:', String(force));
      } catch {}
    }
   
    const result = await invokeCursorAgent({ argv, output_format, cwd, executable, model, force });
   
    // Echo prompt either when env is set or when caller provided echo_prompt: true (if host forwards unknown args it's fine)
    const echoEnabled = process.env.CURSOR_AGENT_ECHO_PROMPT === '1' || source?.echo_prompt === true;
    if (echoEnabled) {
      const text = `Prompt used:\n${usedPrompt}`;
      const content = Array.isArray(result?.content) ? result.content : [];
      return { ...result, content: [{ type: 'text', text }, ...content] };
    }
   
    return result;
  }

• server.js:38-149 (helper)

  Low-level helper that spawns the cursor-agent CLI subprocess, handles output capture, timeouts, and error conditions; called by runCursorAgent.

  async function invokeCursorAgent({ argv, output_format = 'text', cwd, executable, model, force, print = true }) {
   const cmd = resolveExecutable(executable);
  
   // Compute model/force from args/env
   const userArgs = [...(argv ?? [])];
   const hasModelFlag = userArgs.some((a) => a === '-m' || a === '--model' || /^(?:-m=|--model=)/.test(String(a)));
   const envModel = process.env.CURSOR_AGENT_MODEL && process.env.CURSOR_AGENT_MODEL.trim();
   const effectiveModel = model?.trim?.() || envModel;
  
   const hasForceFlag = userArgs.some((a) => a === '-f' || a === '--force');
   const envForce = (() => {
     const v = (process.env.CURSOR_AGENT_FORCE || '').toLowerCase();
     return v === '1' || v === 'true' || v === 'yes' || v === 'on';
   })();
   const effectiveForce = typeof force === 'boolean' ? force : envForce;
  
   const finalArgv = [
     ...(print ? ['--print', '--output-format', output_format] : []),
     ...userArgs,
     ...(hasForceFlag || !effectiveForce ? [] : ['-f']),
     ...(hasModelFlag || !effectiveModel ? [] : ['-m', effectiveModel]),
   ];
  
   return new Promise((resolve) => {
     let settled = false;
     let out = '';
     let err = '';
     let idleTimer = null;
     let killedByIdle = false;
  
     const cleanup = () => {
       if (mainTimer) clearTimeout(mainTimer);
       if (idleTimer) clearTimeout(idleTimer);
     };
  
     if (process.env.DEBUG_CURSOR_MCP === '1') {
       try {
         console.error('[cursor-mcp] spawn:', cmd, ...finalArgv);
       } catch {}
     }
  
     const child = spawn(cmd, finalArgv, {
       shell: false, // safer across platforms; rely on PATH/PATHEXT
       cwd: cwd || process.cwd(),
       env: process.env,
     });
     try { child.stdin?.end(); } catch {}
  
     const idleMs = Number.parseInt(process.env.CURSOR_AGENT_IDLE_EXIT_MS || '0', 10);
     const scheduleIdleKill = () => {
       if (!Number.isFinite(idleMs) || idleMs <= 0) return;
       if (idleTimer) clearTimeout(idleTimer);
       idleTimer = setTimeout(() => {
         killedByIdle = true;
         try { child.kill('SIGKILL'); } catch {}
       }, idleMs);
     };
  
     child.stdout.on('data', (d) => {
       out += d.toString();
       scheduleIdleKill();
     });
  
     child.stderr.on('data', (d) => {
       err += d.toString();
     });
  
     child.on('error', (e) => {
       if (settled) return;
       settled = true;
       cleanup();
       if (process.env.DEBUG_CURSOR_MCP === '1') {
         try { console.error('[cursor-mcp] error:', e); } catch {}
       }
       const msg =
         `Failed to start "${cmd}": ${e?.message || e}\n` +
         `Args: ${JSON.stringify(finalArgv)}\n` +
         (process.env.CURSOR_AGENT_PATH ? `CURSOR_AGENT_PATH=${process.env.CURSOR_AGENT_PATH}\n` : '');
       resolve({ content: [{ type: 'text', text: msg }], isError: true });
     });
  
     const defaultTimeout = 30000;
     const timeoutMs = Number.parseInt(process.env.CURSOR_AGENT_TIMEOUT_MS || String(defaultTimeout), 10);
     const mainTimer = setTimeout(() => {
       try { child.kill('SIGKILL'); } catch {}
       if (settled) return;
       settled = true;
       cleanup();
       resolve({
         content: [{ type: 'text', text: `cursor-agent timed out after ${Number.isFinite(timeoutMs) ? timeoutMs : defaultTimeout}ms` }],
         isError: true,
       });
     }, Number.isFinite(timeoutMs) ? timeoutMs : defaultTimeout);
  
     child.on('close', (code) => {
       if (settled) return;
       settled = true;
       cleanup();
       if (process.env.DEBUG_CURSOR_MCP === '1') {
         try { console.error('[cursor-mcp] exit:', code, 'stdout bytes=', out.length, 'stderr bytes=', err.length); } catch {}
       }
       if (code === 0 || (killedByIdle && out)) {
         resolve({ content: [{ type: 'text', text: out || '(no output)' }] });
       } else {
         resolve({
           content: [{ type: 'text', text: `cursor-agent exited with code ${code}\n${err || out || '(no output)'}` }],
           isError: true,
         });
       }
     });
   });
  }