Cursor Agent MCP Server

Instructions

Implementation Reference

• server.js:303-318 (handler)

  Handler function for cursor_agent_edit_file tool. Composes a prompt using the file path and edit instruction, optionally including apply/dry_run/prompt flags, then invokes runCursorAgent.

    async (args) => {
      try {
        const { file, instruction, apply, dry_run, prompt, output_format, cwd, executable, model, force, extra_args } = args;
        const composedPrompt =
          `Edit the repository file:\n` +
          `- File: ${String(file)}\n` +
          `- Instruction: ${String(instruction)}\n` +
          (apply ? `- Apply changes if safe.\n` : `- Propose a patch/diff without applying.\n`) +
          (dry_run ? `- Treat as dry-run; do not write to disk.\n` : ``) +
          (prompt ? `- Additional context: ${String(prompt)}\n` : ``);
        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:239-247 (schema)

  Zod input schema for cursor_agent_edit_file tool, defining required file and instruction, optional apply, dry_run, prompt, and common fields.

  const EDIT_FILE_SCHEMA = z.object({
   file: z.string().min(1, 'file is required'),
   instruction: z.string().min(1, 'instruction is required'),
   apply: z.boolean().optional(),
   dry_run: z.boolean().optional(),
   // optional free-form prompt to pass if the CLI supports one
   prompt: z.string().optional(),
   ...COMMON,
  });

• server.js:299-318 (registration)

  MCP server.tool registration for cursor_agent_edit_file, linking name, description, schema, and handler function.

  server.tool(
    'cursor_agent_edit_file',
    'Edit a file with an instruction. Prompt-based wrapper; no CLI subcommand required.',
    EDIT_FILE_SCHEMA.shape,
    async (args) => {
      try {
        const { file, instruction, apply, dry_run, prompt, output_format, cwd, executable, model, force, extra_args } = args;
        const composedPrompt =
          `Edit the repository file:\n` +
          `- File: ${String(file)}\n` +
          `- Instruction: ${String(instruction)}\n` +
          (apply ? `- Apply changes if safe.\n` : `- Propose a patch/diff without applying.\n`) +
          (dry_run ? `- Treat as dry-run; do not write to disk.\n` : ``) +
          (prompt ? `- Additional context: ${String(prompt)}\n` : ``);
        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:152-193 (helper)

  Shared helper invoked by the handler to execute cursor-agent CLI with the composed prompt.

  // Accepts either a flat args object or an object with an "arguments" field (some hosts).
  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;
  }