DotNetSearch

# DotNetSearch — MCP Search & PDF Server

**DotNetSearch** is a self-contained MCP (Model Context Protocol) server that empowers GitHub Copilot, Claude, Cursor, and other AI agents with high-performance codebase search, NuGet package decompilation, whitespace token reduction, and **deep PDF document reading and analysis**:

### Key Tools Overview

| Category | Tool | Purpose |
|---|---|---|
| **Code Search** | `search` | Find files and lines matching a keyword or natural-language query — returns only matching lines (~110 tokens vs ~2500 for a full file read) |
| **Code Search** | `search_related` | Find code chunks structurally similar to a known location — ideal for discovering callers, implementations, or patterns |
| **Decompilation** | `decompile_type` | Decompile any .NET type from referenced NuGet package assemblies — returns the full C# class definition without needing the source code |
| **Optimization** | `compress_code` | Reduce C# code indentation from 4-space to 1-space per indent level and remove blank lines — saves 10–20% tokens with zero semantic change |
| **File Reading** | `read_file` | Read a file from disk and optionally return a specific line range — useful after `search` when you need full file context |
| **PDF Reading** | `read_pdf_text` | Extract clean, structured text page-by-page or across targeted page ranges from any PDF document |
| **PDF Reading** | `get_pdf_info` | Inspect PDF metadata, total page count, per-page dimensions, author, subject, creation date, and structure |
| **PDF Visuals** | `render_pdf_page_as_image` | Rasterize any PDF page into a high-resolution PNG image at custom DPI — ideal for inspecting charts, diagrams, tables, and scanned documents |
| **PDF Visuals** | `extract_pdf_images` | Extract embedded raster images from PDF pages and save to disk with pixel coordinates |
| **PDF Structure** | `get_pdf_bookmarks` | Extract the hierarchical table of contents, bookmarks, and document outline with target page links |
| **PDF Forms** | `get_pdf_form_fields` | Read interactive AcroForm form fields (text boxes, checkboxes, radio buttons, dropdowns) and their values |
| **PDF Assets** | `extract_pdf_attachments` | Extract embedded file attachments from PDF documents and save them to disk |
| **PDF Links** | `get_pdf_hyperlinks` | Extract all clickable web URLs, internal page jumps, and external document links with bounding boxes |

Instead of reading full files (~2500 tokens each), the agent gets back only the matching lines (~110 tokens) — saving up to 98% of context window per query. For files that must be read in full, use `compress_code` first to strip whitespace overhead and save an additional 10–20% of tokens. For PDF documentation, technical manuals, and specifications, dedicated tools extract targeted text, images, and tables without overwhelming the model context window.

---

## Step 1 — Download the executable

Go to the [latest release](https://github.com/puneethdc99/DotNetSearch/releases/latest) and download the file for your platform:

| Platform    | File to download          |
|-------------|---------------------------|
| Windows x64 | `DotNetSearch-win-x64.exe` |
| Linux x64   | `DotNetSearch-linux-x64`   |
| macOS ARM64 | `DotNetSearch-osx-arm64`   |

> No .NET installation required. The runtime is bundled inside the executable.

Save it somewhere permanent, e.g.:
- **Windows:** `C:\Tools\DotNetSearch.exe`
- **Linux/macOS:** `/usr/local/bin/DotNetSearch`

On Linux/macOS, make it executable:
```bash
chmod +x /usr/local/bin/DotNetSearch
```

---

## Step 2 — Add to your MCP config

Open (or create) your global MCP config file:

| Client | Config file location |
|--------|---------------------|
| Visual Studio | `%USERPROFILE%\.mcp.json` |
| VS Code + Copilot | `%USERPROFILE%\.mcp.json` |
| Claude Desktop | `%APPDATA%\Claude\claude_desktop_config.json` |
| Cursor | `%USERPROFILE%\.cursor\mcp.json` |

### Windows configuration

Add this to the `servers` section:

```json
{
  "servers": {
    "DotNetSearch": {
      "type": "stdio",
      "command": "C:\\Tools\\DotNetSearch.exe"
    }
  }
}
```

### Linux / macOS configuration

```json
{
  "servers": {
    "DotNetSearch": {
      "type": "stdio",
      "command": "/usr/local/bin/DotNetSearch"
    }
  }
}
```

If you already have other servers in the file, just add the `"DotNetSearch"` block inside the existing `"servers"` object.

---

## Step 3 — Verify it is active

**Visual Studio / VS Code:**
1. Open GitHub Copilot Chat
2. Switch to **Agent Mode**
3. Click the **wrench / Select Tools** icon
4. Confirm the DotNetSearch tools appear in the list and are enabled:
   - **Code & Navigation:** `search`, `search_related`, `decompile_type`, `compress_code`, `read_file`
   - **PDF Document Inspection:** `read_pdf_text`, `get_pdf_info`, `render_pdf_page_as_image`, `extract_pdf_images`, `get_pdf_bookmarks`, `get_pdf_form_fields`, `extract_pdf_attachments`, `get_pdf_hyperlinks`

---

## Step 4 — Update your Copilot instructions

To make Copilot automatically prefer DotNetSearch over built-in file reading, add the instructions below to your Copilot instructions file. There are two places you can put this — repo-level (affects only that repo) or global (affects all repos).

---

### Option A — Repo-level instructions (recommended)

**File location:**
```
<your-repo-root>\.github\copilot-instructions.md
```

This file is read by GitHub Copilot for every conversation in that repository. It is the recommended place if you want DotNetSearch to be preferred only for a specific project.

**How to find or create it:**
- Navigate to your repository root folder
- Look for a `.github` subfolder — if it doesn't exist, create it
- Inside `.github`, look for `copilot-instructions.md` — if it doesn't exist, create the file

---

### Option B — Global instructions (applies to all repos)

**File location:**

| Client | Global instructions file |
|--------|--------------------------|
| Visual Studio | `%APPDATA%\Microsoft\VisualStudio\Copilot\copilot-instructions.md` |
| VS Code + Copilot | `%USERPROFILE%\.github\copilot-instructions.md` |

**How to find or create it:**
- Open the path above in File Explorer (paste into the address bar)
- If the folder doesn't exist, create it
- If `copilot-instructions.md` doesn't exist in the folder, create the file

> **Note:** If you add instructions to both files, Copilot merges them — both will be active at the same time.

---

### Instructions to add

Paste the following into whichever file you chose above:

```markdown
## Search Preference
When searching for code, symbols, or text in this repository, always prefer
the `DotNetSearch` MCP tool (`search` and `search_related`) over reading full
files or using built-in workspace search. DotNetSearch returns only matching
lines and is significantly more token-efficient (~98% fewer tokens per query).
Do not call DotNetSearch tools in parallel — run one search at a time.

## PDF Document Reading
When reading, analyzing, or searching PDF documents:
- Always prefer `read_pdf_text` and `get_pdf_info` over raw file operations.
- First call `get_pdf_info` to inspect total pages and document metadata.
- Call `read_pdf_text` with specific page ranges (`startPage`, `endPage`) to avoid token overflow.
- If the PDF contains visual charts, flowcharts, architectural diagrams, or scanned pages, use `render_pdf_page_as_image` to rasterize the page.
- For interactive PDF forms, use `get_pdf_form_fields` to extract user inputs.

## NuGet Type Inspection
When the user asks about a third-party or NuGet type and the source code is not
available in the workspace, use the `DotNetSearch` MCP tool `decompile_type` to
decompile the type from the project's referenced assemblies. Pass the short or
fully qualified type name and the absolute path to the .csproj file. The project
must have been built at least once before calling this tool.

## Code Compression
When reading source files to minimize context window usage, use the
`DotNetSearch` MCP tool `compress_code` — BUT ONLY for the following fully-safe
languages where indentation is cosmetic and braces/keywords define scope:

  C#, Java, JavaScript, TypeScript, C, C++, Kotlin, Swift, Rust, Scala,
  PHP, Ruby, CSS, SCSS, Less, JSON, XML

NEVER call `compress_code` on any other language. In particular, NEVER use it on
Python, YAML, CoffeeScript, Pug/Jade, HAML, or Makefile — these are
indentation-sensitive and compression WILL silently corrupt the file structure.

Before calling `compress_code`, check the file extension:
- Allowed:  .cs .java .js .ts .jsx .tsx .kt .swift .rs .scala .php .rb .css .scss .less .json .xml .c .cpp .h
- Blocked:  .py .yaml .yml .coffee .pug .jade .haml  (and Makefiles with no extension)

Pass the absolute file path. For JavaScript/TypeScript projects using 2-space
indentation, set `sourceIndentSize=2`.
```

---

## Step 5 — You're done

No special commands or workflow changes are needed. Just continue your normal coding tasks in Copilot Agent Mode — DotNetSearch will be used automatically whenever Copilot needs to search your codebase or inspect PDF documents.

Over time you will notice a reduction in token usage per conversation. This is because DotNetSearch returns only the matching lines (typically ~110 tokens) instead of full file contents (~2500 tokens), saving up to 98% of context window per search operation.

---

## Tool reference

### `search`

Searches a local directory for files whose content matches a keyword or natural-language query. Uses BM25 ranking with CamelCase and snake_case token expansion.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `query` | string | required | Keyword, identifier, or natural-language phrase |
| `repo` | string | required | Absolute or relative path to the directory to search |
| `top_k` | int | `5` | Max results to return (1–100) |
| `context_lines` | int | `0` | Lines of context above/below each match (0–5) |

---

### `search_related`