Grep MCP Server - TypeScript implementation for grep.app GitHub code search
npm install grep-mcpsrc/server.ts 中版本号为 '1.0.0'，与 package.json 中的 '1.1.0' 不一致
src/server.ts 中的版本号更新为 '1.1.0'
server.ts 只注册了 grep_query 工具，但代码中包含 gitee_query 处理逻辑
ListToolsRequestSchema 处理器中添加 gitee_query 工具注册
grep_query 和 gitee_query
bin/grep-mcp.js 调用 dist/server.js，但实际入口文件是 dist/index.js
dist/index.js
npm run build 成功，无编译错误
node bin/grep-mcp.js --help 正常显示帮助信息
bash
npm install -g grep-mcp-ts
`
$3
`bash
git clone https://github.com/your-username/grep-mcp-ts.git
cd grep-mcp-ts
npm install
npm run build
npm link
`
Usage
$3
`bash
Start with stdio transport (default)
grep-mcp
Start with specific transport mode
grep-mcp --transport stdio
Show help
grep-mcp --help
`
$3
`typescript
import { runServer } from 'grep-mcp-ts';
// Start the server
await runServer();
`
$3
Add to your MCP client configuration:
`json
{
"mcpServers": {
"grep": {
"command": "grep-mcp",
"args": ["--transport", "stdio"]
}
}
}
`
Available Tools
$3
Search GitHub code using grep.app API.
Parameters:
- query (required): The search query string to find in GitHub repositories
- language (optional): Programming language filter (e.g., "Python", "JavaScript", "TypeScript")
- repo (optional): Repository filter in format "owner/repo" (e.g., "microsoft/vscode")
- path (optional): Path filter to search within specific directories (e.g., "src/", "lib/")
Example:
`json
{
"name": "grep_query",
"arguments": {
"query": "async function",
"language": "TypeScript",
"repo": "microsoft/vscode",
"path": "src/"
}
}
`
$3
Search Gitee code using Gitee search API (https://so.gitee.com).
Parameters:
- query (required): The search query string to find in Gitee repositories
- language (optional): Programming language filter (e.g., "Python", "JavaScript", "TypeScript")
- repo (optional): Repository filter in format "owner/repo" (e.g., "openeuler/kernel")
- path (optional): Path filter to search within specific directories (e.g., "src/", "lib/")
Example:
`json
{
"name": "gitee_query",
"arguments": {
"query": "异步函数",
"language": "JavaScript",
"repo": "openeuler/kernel",
"path": "src/"
}
}
`
Search Examples
$3
`json
{
"query": "useState"
}
`
$3
`json
{
"query": "class Component",
"language": "JavaScript"
}
`
$3
`json
{
"query": "import React",
"repo": "facebook/react"
}
`
$3
`json
{
"query": "export default",
"path": "src/components/"
}
`
$3
`json
{
"query": "async/await error handling",
"language": "TypeScript",
"path": "src/"
}
`
API Response Format
The server returns formatted search results including:
- Repository information (name, description, stars, language)
- File paths and line numbers
- Code snippets with context
- Syntax highlighting information
- Direct links to GitHub
Example response:
`
Search Results for: "async function"
$3
Language: TypeScript | Description: Visual Studio Code
File: src/vs/base/common/async.ts (Lines 15-20)
`typescript
export async function timeout(ms: number): Promise {
return new Promise(resolve => {
setTimeout(resolve, ms);
});
}
`
View on GitHub
---
`
Configuration
$3
- GREP_API_TIMEOUT: Request timeout in milliseconds (default: 10000)
- GREP_MAX_RESULTS: Maximum number of results to return (default: 10)
$3
- --transport : Transport mode (default: stdio)
- --host : Host for SSE transport (default: localhost)
- --port : Port for SSE transport (default: 3000)
- --help: Show help message
Development
$3
- Node.js 18.0.0 or higher
- npm or yarn
$3
`bash
git clone https://github.com/your-username/grep-mcp-ts.git
cd grep-mcp-ts
npm install
`
$3
`bash
npm run build
`
$3
`bash
npm run dev
`
$3
`bash
npm test
`
Project Structure
`
grep-mcp-ts/
├── src/
│ ├── index.ts # Entry point
│ ├── server.ts # MCP server implementation
│ ├── types.ts # TypeScript type definitions
│ ├── tools/
│ │ └── grep-query.ts # Grep query tool implementation
│ └── utils/
│ ├── api.ts # HTTP client for grep.app API
│ ├── formatting.ts # Result formatting utilities
│ └── validation.ts # Input validation
├── bin/
│ └── grep-mcp.js # Executable script
├── dist/ # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md
`
$3
#### 核心模块
- src/server.ts: MCP服务器核心实现，处理协议通信和工具注册
- src/index.ts: 应用入口点，启动服务器和命令行处理
- src/types.ts: 完整的TypeScript类型定义
#### 工具模块
- src/tools/grep-query.ts: 核心搜索工具实现，集成所有功能组件
#### 工具类模块
- src/utils/api.ts: HTTP客户端，处理grep.app API通信
- src/utils/formatting.ts: 结果格式化，HTML清理和代码高亮
- src/utils/validation.ts: 输入验证和参数处理
📦 依赖管理
$3
`json
{
"dependencies": {
"@modelcontextprotocol/sdk": "^0.5.0",
"axios": "^1.6.0",
"commander": "^11.0.0"
}
}
`
$3
`json
{
"devDependencies": {
"@types/node": "^20.0.0",
"typescript": "^5.0.0"
}
}
`
✅ 质量保证
$3
- ✅ TypeScript编译无错误
- ✅ 类型检查通过
- ✅ 所有模块正确导入导出
$3
- ✅ 命令行参数解析正常
- ✅ 帮助信息显示正确
- ✅ MCP协议实现完整
- ✅ 错误处理机制完善
$3
- ✅ 遵循TypeScript最佳实践
- ✅ 清晰的代码组织和注释
- ✅ 完整的类型定义
- ✅ 统一的错误处理
🎯 发布准备
项目已完全准备好发布到npm:
- ✅ package.json配置完整
- ✅ 构建脚本配置正确
- ✅ 文件包含列表设置
- ✅ 版本和依赖管理
- ✅ 可执行文件配置
发布命令: npm publish
Contributing
1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)