# Agent Ransack MCP for Cursor

Give **Cursor's AI agent** supercharged local file search on Windows by connecting it to [Agent Ransack](https://www.mythicsoft.com/agentransack/) via MCP.

Instead of relying only on Cursor's built-in search, the agent can call `search_files_content` and run headless searches through `flpsearch.exe` — ideal for large codebases, regex-heavy queries, and deep folder scans.

> **Windows only.** Requires Node.js 18+ and a licensed Agent Ransack build that supports command-line export (`-o`).

---

## Features

- **`search_files_content` MCP tool** — Cursor's agent invokes Agent Ransack autonomously
- **Content search** — find text or regex inside files
- **Filename search** — omit `containingText` to search by file name pattern only
- **Headless** — no Agent Ransack window pops up; results are parsed from CSV output
- **Auto-detects** common `flpsearch.exe` install paths

---

## Prerequisites

| Requirement | Notes |
|---|---|
| **Windows** | Uses `flpsearch.exe` (Agent Ransack console tool) |
| **Node.js 18+** | [nodejs.org](https://nodejs.org/) |
| **Agent Ransack (licensed)** | Free edition blocks headless `-o` export. Premium / trial required. |
| **Cursor** | With MCP support enabled |

### Find your `flpsearch.exe` path

Common locations:

```
C:\Program Files\Mythicsoft\Agent Ransack\flpsearch.exe
C:\Program Files\Agent Ransack\flpsearch.exe
```

---

## Installation

### 1. Clone the repo

```bash
git clone https://github.com/amrsohil/Agent-Ransack-MCP-Cursor.git
cd Agent-Ransack-MCP-Cursor
```

### 2. Install dependencies

```bash
npm install
```

### 3. Add to Cursor MCP config

Open (or create) your global MCP config:

```
C:\Users\YOUR_USER\.cursor\mcp.json
```

Add the server (adjust paths to match your machine):

```json
{
  "mcpServers": {
    "agent-ransack": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["C:\\path\\to\\Agent-Ransack-MCP-Cursor\\index.js"],
      "env": {
        "FLPSEARCH_PATH": "C:\\Program Files\\Mythicsoft\\Agent Ransack\\flpsearch.exe"
      }
    }
  }
}
```

See [`mcp.json.example`](mcp.json.example) for a copy-paste template.

### 4. Reload Cursor

Open **Settings → MCP**. You should see **agent-ransack** with the `search_files_content` tool available.

---

## Usage

Once configured, ask Cursor's agent naturally:

- *"Search `D:\Projects\MyApp` for every reference to `WorkOrderStatus`"*
- *"Find all `.tsx` files containing `useEffect` in my repo"*
- *"List every `.config` file under `C:\Projects`"*

The agent will call the MCP tool automatically.

### Tool parameters

| Parameter | Required | Description |
|---|---|---|
| `folder` | Yes | Absolute path to search |
| `containingText` | No | Text or regex inside files. Omit for filename-only search. |
| `filePattern` | No | e.g. `*.cs`, `*.tsx`. Default: `*.*` |
| `subfolders` | No | Search recursively. Default: `true` |
| `regex` | No | Treat `containingText` as regex. Default: `false` |
| `matchCase` | No | Case-sensitive content search. Default: `false` |
| `maxLinesPerFile` | No | Cap matching lines per file |

---

## How it works

```
Cursor Agent  →  MCP Server (Node.js)  →  flpsearch.exe  →  CSV results  →  Agent
```

1. Cursor's agent calls `search_files_content`
2. The MCP server runs `flpsearch.exe` headlessly with `-o` to a temp CSV file
3. Results are parsed and returned as formatted text
4. No Agent Ransack UI window appears

---

## Troubleshooting

| Problem | Fix |
|---|---|
| Tool not listed in Cursor | Reload Cursor; check `mcp.json` syntax and paths |
| `flpsearch.exe not found` | Set `FLPSEARCH_PATH` in `mcp.json` `env` block |
| `not available in the free version` | Upgrade to Agent Ransack premium / FileLocator Pro |
| `node` not found | Use full path to `node.exe` in MCP config |
| No results | Verify the `folder` path exists and `filePattern` is correct |

---

## Professional setup & custom MCP development

**Need help setting this up for your team or building custom MCP integrations?**

**Amr Sohil**  
📧 [amr.sohil@gmail.com](mailto:amr.sohil@gmail.com)

Available for:

- Agent Ransack + Cursor MCP setup for teams
- Custom MCP server development
- Windows dev workflow automation
- Enterprise Cursor tooling

---

## License

This MCP server is released under the [MIT License](LICENSE).

**Agent Ransack** is commercial software by [Mythicsoft](https://www.mythicsoft.com/). This project does not include or redistribute Agent Ransack. Each user must install and license Agent Ransack separately.

---

## Author

**Amr Sohil**  
📧 amr.sohil@gmail.com

If this project helps you, consider starring the repo on GitHub.