# MCP keyword search

A Model Context Protocol (MCP) server that provides keyword search functionality within files

## 🚀 Installation

### Step 1: Clone or Create Project

```bash
git clone https://github.com/alfaarghya/mcp-keyword-search
cd mcp-keyword-search
```

### Step 2: Install Dependencies

```bash
pnpm install
```

This will install:

- `@modelcontextprotocol/sdk` - MCP SDK
- `@types/node` - TypeScript definitions for Node.js
- `typescript` - TypeScript compiler

## 🔨 Building the Project

Compile TypeScript to JavaScript:

```bash
pnpm run build
```

This creates a `dist/` folder with compiled JavaScript files.

**Development Mode** (auto-rebuild on changes):

```bash
pnpm run dev
```

## 🧪 Testing

### Using MCP Inspector

The MCP Inspector provides a visual web interface for testing.

#### Step 1: Start the Inspector

```bash
npx @modelcontextprotocol/inspector node dist/index.js
```

#### Step 2: Open in Browser

Navigate to the URL shown

#### Step 3: Test the Tool

1. In the web interface, you'll see **"search_file"** in the tools list
2. Click on it to expand the input form
3. Enter the following test data:

```json
{
  "file_path": "./sample.txt",
  "keyword": "Hello",
  "case_sensitive": false
}
```

4. Click **"Execute"** or **"Run Tool"**

#### Expected Output:

```
Found 3 match(es) for "hello" in ./test.txt:

Line 1 (position 0): Hello World! This is a test file.
Line 3 (position 0): Hello again on line 3.
Line 5 (position 0): HELLO in uppercase.
```

![](./public/demo-mcp.png)

## 🔧 API Reference

### Server Information

- **Name**: `file-search-server`
- **Version**: `1.0.0`
- **Protocol**: Model Context Protocol (MCP)
- **Transport**: stdio

### Available Tools

#### `search_file`

Searches for a keyword within a file.

**Input Schema:**

```typescript
{
  file_path: string;      // Required: Path to file
  keyword: string;        // Required: Search keyword
  case_sensitive?: boolean; // Optional: Case sensitivity (default: false)
}
```

**Output:**

- List of matching lines with line numbers and positions
- Or error message if file not found or other issues