DotNetSearch

DotNetSearch — MCP 搜索与 PDF 服务

MCP 服务标识符： mcp-name: io.github.puneethdc99/dotnetsearch
（作为纳入 GitHub MCP Registry 的软件包所有权证明）

DotNetSearch 是一款独立的 MCP（Model Context Protocol）服务，可为 GitHub Copilot、Claude、Cursor 和其他 AI Agent 提供高性能代码库搜索、NuGet 软件包反编译、空白字符 Token 压缩，以及深入的 PDF 文档阅读与分析：

核心工具概览

类别	工具	用途
代码搜索	search	查找包含关键字或自然语言查询匹配内容的文件和行——仅返回匹配行（约 110 个 Token，而完整读取文件约需 2500 个 Token）
代码搜索	search_related	查找与已知位置结构相似的代码块——非常适合发现调用方、实现或模式
反编译	decompile_type	从引用的 NuGet 软件包程序集反编译任意 .NET 类型——无需源代码即可返回完整的 C# 类定义
优化	compress_code	将 C# 代码的缩进从每级 4 个空格缩减为 1 个空格，并移除空行——语义零变化，可节省 10–20% 的 Token
文件读取	read_file	从磁盘读取文件，并可按需返回指定行范围——在使用 search 后需要完整文件上下文时非常实用
PDF 阅读	read_pdf_text	从任意 PDF 文档逐页或按指定页码范围提取清晰、结构化的文本
PDF 阅读	get_pdf_info	查看 PDF 元数据、总页数、各页尺寸、作者、主题、创建日期和结构
PDF 视觉内容	render_pdf_page_as_image	将任意 PDF 页面按自定义 DPI 光栅化为高分辨率 PNG 图像——非常适合检查图表、示意图、表格和扫描文档
PDF 视觉内容	extract_pdf_images	从 PDF 页面提取嵌入的栅格图像，并连同像素坐标一起保存到磁盘
PDF 结构	get_pdf_bookmarks	提取分层目录、书签和文档大纲，并包含目标页面链接
PDF 表单	get_pdf_form_fields	读取交互式 AcroForm 表单字段（文本框、复选框、单选按钮、下拉列表）及其值
PDF 资源	extract_pdf_attachments	从 PDF 文档提取嵌入的文件附件并保存到磁盘
PDF 链接	get_pdf_hyperlinks	提取所有可点击的网页 URL、内部页面跳转和外部文档链接，并提供边界框

相比读取完整文件（每个约 2500 个 Token），Agent 只会获得匹配行（约 110 个 Token）——每次查询最多可节省 98% 的上下文窗口。对于必须完整读取的文件，请先使用 compress_code 移除空白字符开销，额外节省 10–20% 的 Token。对于 PDF 文档、技术手册和规格说明，专用工具可提取指定文本、图像和表格，不会让模型的上下文窗口不堪重负。

---

第 1 步 — 安装

选项 A：通过 .NET CLI 安装（NuGet 工具）

如果已安装 .NET SDK（推荐 .NET 开发者使用）：

dotnet tool install -g PuneethDC.DotNetSearch

安装后，即可在任意终端中全局使用 dotnetsearch 命令。

今后如需更新到最新版本：

dotnet tool update -g PuneethDC.DotNetSearch

选项 B：下载独立可执行文件（无需 .NET）

前往最新版本，下载适用于你平台的自包含可执行文件：

平台	要下载的文件
Windows x64	DotNetSearch-win-x64.exe
Linux x64	DotNetSearch-linux-x64
macOS ARM64	DotNetSearch-osx-arm64

无需安装 .NET。运行时已捆绑在可执行文件中。

将其保存在固定位置，例如：

• Windows： C:\Tools\DotNetSearch.exe
• Linux/macOS： /usr/local/bin/DotNetSearch

在 Linux/macOS 上，使其可执行：

chmod +x /usr/local/bin/DotNetSearch

---

第 2 步 — 添加到 MCP 配置

打开（或创建）全局 MCP 配置文件：

客户端	配置文件位置
Visual Studio	%USERPROFILE%\.mcp.json
VS Code + Copilot	%USERPROFILE%\.mcp.json
Claude Desktop	%APPDATA%\Claude\claude_desktop_config.json
Cursor	%USERPROFILE%\.cursor\mcp.json

如果通过 NuGet（.NET Tool）安装：

在 Windows、Linux 和 macOS 上的运行方式完全一致，无需调整路径：

{
  "servers": {
    "DotNetSearch": {
      "type": "stdio",
      "command": "dotnetsearch"
    }
  }
}

如果使用独立可执行文件：

Windows：

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

Linux / macOS：

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

替代方案：使用 dnx 按需运行（零安装）：

{
  "servers": {
    "DotNetSearch": {
      "type": "stdio",
      "command": "dnx",
      "args": ["PuneethDC.DotNetSearch"]
    }
  }
}

如果文件中已有其他服务，只需将 "DotNetSearch" 块添加到现有的 "servers" 对象中。

---

第 3 步 — 确认已启用

Visual Studio / VS Code：

1. 打开 GitHub Copilot Chat
2. 切换到 Agent Mode
3. 点击 扳手 / 选择工具图标
4. 确认列表中显示 DotNetSearch 工具且已启用：
   • 代码与导航： search、search_related、decompile_type、compress_code、read_file
   • PDF 文档检查： 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

---

第 4 步 — 更新 Copilot 指令

若要让 Copilot 自动优先使用 DotNetSearch，而不是内置文件读取功能，请将以下指令添加到 Copilot 指令文件中。可以选择两个位置之一：仓库级别（仅对该仓库生效）或全局级别（对所有仓库生效）。

---

选项 A — 仓库级指令（推荐）

文件位置：

<your-repo-root>\.github\copilot-instructions.md

GitHub Copilot 在该仓库的每次对话中都会读取此文件。如果你希望 DotNetSearch 仅在特定项目中优先使用，推荐选择此位置。

如何查找或创建该文件：

• 导航到仓库根文件夹
• 查找 .github 子文件夹；如果不存在，请创建
• 在 .github 中查找 copilot-instructions.md；如果不存在，请创建该文件

---

选项 B — 全局指令（适用于所有仓库）

文件位置：

客户端	全局指令文件
Visual Studio	%APPDATA%\Microsoft\VisualStudio\Copilot\copilot-instructions.md
VS Code + Copilot	%USERPROFILE%\.github\copilot-instructions.md

如何查找或创建该文件：

• 在文件资源管理器中打开上述路径（将路径粘贴到地址栏）
• 如果文件夹不存在，请创建
• 如果文件夹中不存在 copilot-instructions.md，请创建该文件

注意： 如果在两个文件中都添加指令，Copilot 会将它们合并，并同时启用。

---

要添加的指令

将以下内容粘贴到上方选择的文件中：

## 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`.

---

步骤 5 — 完成

无需特殊命令或更改工作流。只需继续在 Copilot Agent Mode 中执行常规编码任务 — 每当 Copilot 需要搜索代码库或检查 PDF 文档时，都会自动使用 DotNetSearch。

随着时间推移，你会发现每次对话的 token 用量有所减少。这是因为 DotNetSearch 只返回匹配的行（通常约 110 个 token），而不是完整的文件内容（约 2500 个 token），每次搜索最多可节省 98% 的上下文窗口。

---

工具参考

search

在本地目录中搜索内容与关键词或自然语言查询相匹配的文件。使用 BM25 排名，并扩展 CamelCase 和 snake_case token。

参数	类型	默认值	描述
query	string	必填	关键词、标识符或自然语言短语
repo	string	必填	要搜索的目录的绝对或相对路径
top_k	int	5	要返回的最大结果数（1–100）
context_lines	int	0	每个匹配项上下方的上下文行数（0–5）

---

search_related

查找与文件中特定位置在结构上相似的代码块。在 search 之后使用，可探索相关实现、调用方或模式。

参数	类型	默认值	描述
file_path	string	必填	先前 search 结果中返回的文件路径
line	int	必填	先前 search 结果中的行号（从 1 开始计数）
repo	string	必填	要搜索的目录的绝对或相对路径
top_k	int	5	要返回的相似代码块数量（1–100）

---

read_file

从磁盘读取文本文件并返回其内容。在已知目标文件且需要完整上下文时，可在 search 之后使用。支持绝对或相对路径，以及可选的 start_line 和 end_line 范围参数。

参数	类型	默认值	描述
path	string	必填	要读取的文件的绝对或相对路径
start_line	int	1	开始读取的行号（从 1 开始计数）
end_line	int	0	停止读取的行号（从 1 开始计数；0 = 读取至文件末尾）

---

read_pdf_text

从 PDF 文件中提取整洁、格式化的文本，并附带页码标记。适用于文档、技术规范、论文和架构指南。支持提取整份文档或指定页码范围。

参数	类型	默认值	描述
path	string	必填	PDF 文件的绝对或相对路径
startPage	int	1	开始提取文本的页码（从 1 开始计数）
endPage	int	0	停止提取文本的页码（从 1 开始计数；0 = 读取至最后一页）

---

get_pdf_info

获取 PDF 文件的全面元数据和物理布局信息，而无需读取其完整文本内容。可先使用此工具规划有针对性的提取。

参数	类型	默认值	描述
path	string	必填	PDF 文件的绝对或相对路径

返回： 总页数、每页的尺寸（widthPt、heightPt）、文档标题、作者、主题、关键词、创建程序、生成程序、创建日期和修改日期。

---

render_pdf_page_as_image

将 PDF 的指定页面栅格化为磁盘上的高分辨率 PNG 图像。对于包含复杂图形、架构流程图、示意图、表格或扫描文档等原始文本提取效果不佳的页面，此工具必不可少。

参数	类型	默认值	描述
path	string	必填	PDF 文件的绝对或相对路径
pageNumber	int	1	要渲染的页面索引（从 1 开始计数）
dpi	int	150	渲染分辨率，单位为 DPI（例如，72 = 草稿，150 = 标准，300 = 印刷/高分辨率）

返回： 渲染后的 .png 图像的路径和图像像素尺寸。

---

extract_pdf_images

从 PDF 页面中提取所有嵌入的栅格图像（例如照片、示意图、嵌入的 JPEG/PNG），并直接保存到磁盘。

参数	类型	默认值	描述
path	字符串	必填	PDF 文件的绝对或相对路径
pageNumber	整数	0	从 1 开始计数的页码（0 = 提取所有页面中的嵌入图像）
outputDirectory	字符串	null	图像保存文件夹（默认为 <pdf-folder>/<pdf-name>_images/）

---

get_pdf_bookmarks

从 PDF 中提取分层书签大纲（目录树），帮助 Agent 在请求特定章节或页面前了解文档的完整结构。

参数	类型	默认值	描述
path	字符串	必填	PDF 文件的绝对或相对路径

**返回：**包含标题和目标页码的递归书签树。

---

get_pdf_form_fields

读取 PDF 文档中嵌入的所有交互式 AcroForm 表单字段。

参数	类型	默认值	描述
path	字符串	必填	PDF 文件的绝对或相对路径

**返回：**表单字段列表，包含字段名称、字段类型（文本框、复选框、组合框、单选按钮）和当前值。

---

extract_pdf_attachments

提取直接嵌入 PDF 目录中的文件（例如附带的源代码、示例数据、架构或配套文件），并将其写入磁盘。

参数	类型	默认值	描述
path	字符串	必填	PDF 文件的绝对或相对路径
outputDirectory	字符串	null	提取的附件的保存目录

---

get_pdf_hyperlinks

提取 PDF 页面上的所有超链接和可点击注释。

参数	类型	默认值	描述
path	字符串	必填	PDF 文件的绝对或相对路径
pageNumber	整数	0	从 1 开始计数的页码（0 = 提取所有页面中的链接）

**返回：**每个超链接的 URL 目标、目标页面跳转信息和边界坐标。

---

decompile_type

反编译 .NET 项目引用的 NuGet 包程序集中的 .NET 类型（类、接口、枚举、结构体或委托）。当你需要在没有源代码的情况下了解第三方 API 时，此工具很有用。

参数	类型	默认值	描述
typeName	字符串	必填	短名称（Session）或完全限定名称（Opc.Ua.Client.Session）
projectPath	字符串	必填	引用 NuGet 包的 .csproj 的绝对路径
maxResults	整数	1	名称在多个程序集中存在歧义时，返回的最大匹配数

**注意：**项目必须至少构建一次，以便在 bin\ 输出文件夹中生成 NuGet 程序集。

---

compress_code

将代码缩进从每级 4 个空格（或可配置）减少至 1 个空格，并移除空行。可节省 10–20% 的 token，且不改变语义——对于按大括号或关键字划分作用域的语言，缩进只是格式，因此这种处理是安全的。接受绝对文件路径或原始代码字符串。返回压缩后的代码以及以下指标：originalLength、compressedLength、savingsPercent 和行数。

✅ 适用（按大括号或关键字划分作用域的语言）： C#、Java、JavaScript、TypeScript、C、C++、Kotlin、Swift、Rust、Scala、PHP、Ruby、CSS、SCSS、Less、JSON、XML

❌ 请勿用于（依赖缩进的语言——会破坏代码）： Python、YAML、CoffeeScript、Pug/Jade、HAML、Makefile

⚠️ 有条件适用：

• Go——适合 LLM 阅读；Go 原生使用制表符，因此请将 sourceIndentSize=4（制表符宽度）。如需往返编译，则需要使用 gofmt。
• Markdown——请避免使用；在 Markdown 规范中，4 个空格的缩进表示代码块。
• JavaScript/TypeScript——对于使用 2 空格缩进的项目，请设置 sourceIndentSize=2。
• 多行字符串字面量（C# 逐字字符串、Java """、JS 模板字面量）——内部空白也会被缩减。代码仍便于 LLM 阅读，但如果字符串依赖精确的内部缩进，则无法安全地往返处理。

参数	类型	默认值	说明
filePath	string	null	要压缩的源文件绝对路径。请提供此项或 code。
code	string	null	要压缩的原始源代码字符串。未提供 filePath 时使用。
sourceIndentSize	int	4	源代码中表示一级缩进的空格数。对于 JS/TS/Ruby/Scala 项目，请设为 2。
targetIndentSize	int	1	输出中每级缩进使用的空格数。

---

支持的文件类型

.pdf .cs .ts .js .jsx .tsx .json .md .txt .xml .yaml .yml .html .css .py .java .cpp .c .h .go .rs .sh .ps1 .psm1 .psd1 .toml .ini .env .config .csproj .props .targets .razor .vue .svelte

---

许可证

MIT——详情请参阅 LICENSE。