MCP Grep

🚀 Grep的MCP服务器

这是一个基于grep命令行工具的模型上下文协议（MCP）服务器，具备强大的文本搜索能力。支持使用自然语言描述和直接的正则表达式模式在文件和目录中搜索指定模式。

🚀 快速开始

本项目是一个模型上下文协议（MCP）服务器，它借助grep命令行工具，提供强大的文本搜索能力。你可以使用自然语言描述或直接的正则表达式模式，在文件和目录中进行搜索。

✨ 主要特性

🧠 自然语言搜索

• 能用简洁的英文描述搜索内容。
• 自动将自然语言转换为合适的正则表达式模式。
• 内置常见搜索模式（如电子邮件、URL、电话号码等）。

🔍 高级搜索功能

• 支持直接的正则表达式模式匹配。
• 可递归搜索目录。
• 能按文件扩展名过滤。
• 支持区分大小写或不区分大小写搜索。
• 支持全词匹配。
• 可显示匹配上下文行。
• 能统计匹配数量。
• 可列出包含匹配项的文件。

🛡️ 安全至上

• 使用child_process.spawn安全执行命令。
• 利用Zod模式进行输入验证。
• 无shell注入漏洞。
• 对路径进行验证和清理。

📦 安装指南

方法一：NPM安装（推荐）

# 全局安装
npm install -g @247arjun/mcp-grep

# 或在项目中本地安装
npm install @247arjun/mcp-grep

方法二：从源码安装

# 克隆仓库
git clone https://github.com/247arjun/mcp-grep.git
cd mcp-grep

# 安装依赖
npm install

# 构建项目
npm run build

# 可选：全局链接
npm link

方法三：直接从GitHub安装

# 直接从GitHub安装
npm install -g git+https://github.com/247arjun/mcp-grep.git

📚 详细文档

配置

Claude桌面设置

将以下内容添加到Claude桌面配置文件中： 位置：

• macOS：~/Library/Application Support/Claude/claude_desktop_config.json
• Windows：%APPDATA%/Claude/claude_desktop_config.json

配置内容：

{
  "mcpServers": {
    "mcp-grep": {
      "command": "mcp-grep",
      "args": []
    }
  }
}

替代方法：使用npx（无需全局安装）

{
  "mcpServers": {
    "mcp-grep": {
      "command": "npx",
      "args": ["@247arjun/mcp-grep"]
    }
  }
}

本地开发设置

{
  "mcpServers": {
    "mcp-grep": {
      "command": "node",
      "args": ["/绝对路径/mcp-grep/build/index.js"]
    }
  }
}

添加配置后，重启Claude桌面以加载MCP服务器。

验证

测试服务器是否正常工作：

# 测试构建好的服务器
node build/index.js

# 应显示："Grep MCP Server running on stdio"
# 按Ctrl+C退出

可用工具

1. grep_search_intent

使用自然语言描述进行搜索。 参数：

• intent（字符串）：简洁的英文描述（如 "email addresses", "TODO comments"）
• target（字符串）：要搜索的文件或目录路径
• case_sensitive（布尔值，可选）：区分大小写搜索（默认：false）
• max_results（数字，可选）：限制结果数量
• show_context（布尔值，可选）：显示周围的行（默认：false）
• context_lines（数字，可选）：上下文行数（默认：2）

示例：

{
  "intent": "email addresses",
  "target": "./src",
  "show_context": true,
  "context_lines": 1
}

2. grep_regex

使用直接的正则表达式模式进行搜索。 参数：

• pattern（字符串）：正则表达式模式
• target（字符串）：要搜索的文件或目录路径
• case_sensitive（布尔值，可选）：区分大小写搜索
• whole_words（布尔值，可选）：仅匹配全词
• invert_match（布尔值，可选）：显示不匹配的行
• max_results（数字，可选）：限制结果数量
• show_context（布尔值，可选）：显示上下文行
• context_lines（数字，可选）：上下文行数量
• file_extensions（数组，可选）：按文件扩展名过滤

示例：

{
  "pattern": "function\\s+\\w+\\s*\\(",
  "target": "./src",
  "file_extensions": ["js", "ts"],
  "show_context": true
}

3. grep_count

统计模式的匹配数量。 参数：

• pattern（字符串）：要统计的模式
• target（字符串）：搜索目标
• case_sensitive（布尔值，可选）：区分大小写
• whole_words（布尔值，可选）：全词匹配
• by_file（布尔值，可选）：显示每个文件的匹配数量
• file_extensions（数组，可选）：文件扩展名过滤

4. grep_files_with_matches

列出包含指定模式的文件。 参数：

• pattern（字符串）：搜索模式
• target（字符串）：要搜索的目录
• case_sensitive（布尔值，可选）：区分大小写
• whole_words（布尔值，可选）：全词匹配
• file_extensions（数组，可选）：要包含的文件扩展名
• exclude_patterns（数组，可选）：要排除的文件模式

5. grep_advanced

使用自定义参数执行grep（适用于高级用户）。 参数：

• args（数组）：grep参数数组（不包括 'grep' 本身）

内置自然语言模式

服务器识别以下自然语言意图：

通信

• "email", "email address", "emails" → 电子邮件地址模式
• "url", "urls", "website", "link", "links" → URL模式
• "phone", "phone number", "phone numbers" → 电话号码模式

网络

• "ip", "ip address", "ip addresses" → IPv4地址模式

数据类型

• "number", "numbers", "integer", "integers" → 数字模式
• "date", "dates" → 日期模式

代码模式

• "function", "functions" → 函数声明
• "class", "classes" → 类定义
• "import", "imports" → 导入语句
• "export", "exports" → 导出语句
• "comment", "comments" → 注释行
• "todo", "todos" → TODO/FIXME/HACK注释

错误模式

• "error", "errors" → 错误消息
• "warning", "warnings" → 警告消息

💻 使用示例

在项目中搜索电子邮件地址

{
  "tool": "grep_search_intent",
  "intent": "email addresses",
  "target": "./src",
  "show_context": true
}

查找所有TODO注释

{
  "tool": "grep_search_intent", 
  "intent": "todo comments",
  "target": "./",
  "file_extensions": ["js", "ts", "py"]
}

使用正则表达式搜索函数定义

{
  "tool": "grep_regex",
  "pattern": "^\\s*function\\s+\\w+",
  "target": "./src",
  "file_extensions": ["js"]
}

统计单词出现次数

{
  "tool": "grep_count",
  "pattern": "async",
  "target": "./src",
  "by_file": true
}

列出包含导入语句的文件

{
  "tool": "grep_files_with_matches",
  "pattern": "^import",
  "target": "./src",
  "file_extensions": ["js", "ts"]
}

开发

构建和运行

# 开发时自动重建
npm run dev

# 生产环境构建
npm run build

# 启动服务器
npm start

项目结构

mcp-grep/
├── src/
│   └── index.ts          # 主服务器实现
├── build/                # 编译后的JavaScript输出
├── package.json          # 项目配置
├── tsconfig.json         # TypeScript配置
└── README.md            # 本文件

故障排除

常见问题

1. "Command not found" 错误

   • 确保全局安装了mcp-grep：npm install -g @247arjun/mcp-grep
   • 或使用npx："command": "npx", "args": ["@247arjun/mcp-grep"]

2. "Permission denied" 错误

   • 检查文件权限：chmod +x build/index.js
   • 重新构建项目：npm run build

3. MCP服务器未在Claude中显示

   • 验证配置文件中的JSON语法。
   • 完全重启Claude桌面。
   • 检查命令路径是否正确。

4. "grep command not found"

   • 在系统上安装grep（通常macOS/Linux预装）。
   • Windows用户：通过WSL安装或使用Git Bash。

调试

通过设置环境变量启用详细日志记录：

# 开发时使用
DEBUG=1 node build/index.js

# 使用示例输入进行测试
echo '{"jsonrpc": "2.0", "method": "initialize", "params": {}}' | node build/index.js

🔧 技术细节

• 使用spawn且shell: false来防止命令注入。
• 在执行前验证所有文件路径。
• 在高级模式下阻止潜在危险的grep标志。
• 使用Zod模式进行输入验证。
• 不允许访问指定目标之外的系统文件。

📄 许可证

文档中未提及相关信息。