Grep App MCP Server
A Model Context Protocol (MCP) server that provides powerful code search capabilities across public GitHub repositories using the grep.app API. Perfect for code discovery, learning from open source projects, and finding implementation examples.
🚀 Features
- 🔍 Advanced Code Search: Search across millions of public repositories on GitHub
- 📁 File Retrieval: Fetch specific files or batches of files from GitHub
- 🎯 Flexible Filtering: Filter by language, repository, file path, and more
- 📊 Multiple Output Formats: JSON, numbered lists, or formatted text
- ⚡ Batch Operations: Retrieve multiple files efficiently in parallel
- 🔄 Result Caching: Cache search results for quick file retrieval
- 📝 Comprehensive Logging: Built-in logging with daily rotation
🛠️ Installation & Setup
Prerequisites
- Node.js 18+
- npm or yarn
- Claude Code CLI
Quick Start
-
Clone or download this repository
git clone https://github.com/ai-tools-all/grep_app_mcp.git cd grep_app_mcp -
Install dependencies
npm install -
Build the project
npm run build -
Test the server
# HTTP mode (recommended for development) ./run.sh http dev # or STDIO mode ./run.sh stdio dev
🔧 Adding to Claude Code
Method 1: Using MCP Configuration
Add this server to your Claude Code MCP configuration:
{
"mcpServers": {
"grep_app": {
"command": "node",
"args": ["/path/to/grep_app_mcp/dist/server-stdio.js"],
"env": {}
}
}
}
Method 2: Using HTTP Transport
For HTTP mode, add to your configuration:
{
"mcpServers": {
"grep_app": {
"url": "http://localhost:8603/mcp"
}
}
}
Then start the server:
./run.sh http prod
📖 run.sh Usage
The run.sh script provides convenient ways to start the server:
Basic Usage
./run.sh [mode] [environment]
Modes
http- HTTP server with streaming support (default)stdio- STDIO server for direct MCP integration
Environments
dev- Development mode with hot reload (default)prod- Production mode (requires build step)
Examples
# Development (default) - HTTP server with hot reload
./run.sh
# Development - HTTP server
./run.sh http dev
# Production - HTTP server
./run.sh http prod
# Development - STDIO server
./run.sh stdio dev
# Production - STDIO server
./run.sh stdio prod
# Show help
./run.sh help
HTTP Endpoints (when using HTTP mode)
- HTTP Streaming:
http://localhost:8603/mcp - Server-Sent Events:
http://localhost:8603/sse
🔨 Available Tools
1. searchCode
Search for code across public GitHub repositories.
Parameters:
query(required) - Search query stringjsonOutput- Return JSON format (default: false)numberedOutput- Return numbered list format (default: false)caseSensitive- Case-sensitive searchuseRegex- Treat query as regex patternwholeWords- Search whole words onlyrepoFilter- Filter by repository name patternpathFilter- Filter by file path patternlangFilter- Filter by programming language(s)
Example:
{
"query": "async function fetchData",
"langFilter": "TypeScript,JavaScript",
"numberedOutput": true
}
2. github_file
Fetch a single file from a GitHub repository.
Parameters:
owner(required) - Repository ownerrepo(required) - Repository namepath(required) - File pathref(optional) - Branch/commit/tag reference
Example:
{
"owner": "microsoft",
"repo": "vscode",
"path": "src/vs/editor/editor.api.ts"
}
3. github_batch_files
Fetch multiple files from GitHub repositories in parallel.
Parameters:
files(required) - Array of file objects with owner, repo, path, and optional ref
Example:
{
"files": [
{"owner": "facebook", "repo": "react", "path": "packages/react/index.js"},
{"owner": "microsoft", "repo": "TypeScript", "path": "src/compiler/types.ts"}
]
}
4. batch_retrieve_files
Retrieve files from previously cached search results.
Parameters:
query(required) - Original search queryresultNumbers(optional) - Array of result indices to retrieve
Example:
{
"query": "tower_governor",
"resultNumbers": [1, 2, 3]
}
🎯 Common Workflows
1. Code Discovery
# Search for React hooks examples
searchCode("useEffect cleanup", langFilter: "JavaScript,TypeScript")
# Retrieve specific files from results
batch_retrieve_files(query: "useEffect cleanup", resultNumbers: [1, 3, 5])
2. Learning Patterns
# Find authentication implementations
searchCode("JWT authentication middleware", repoFilter: "*express*")
# Get specific implementation details
github_file(owner: "auth0", repo: "express-jwt", path: "lib/index.js")
3. API Research
# Discover API patterns
searchCode("GraphQL resolver", pathFilter: "*/resolvers/*")
# Compare multiple implementations
github_batch_files([
{owner: "apollographql", repo: "apollo-server", path: "packages/apollo-server-core/src/resolvers.ts"},
{owner: "graphql", repo: "graphql-js", path: "src/execution/execute.js"}
])
📋 Development
Available Scripts
npm run build- Build TypeScript to JavaScriptnpm run start- Start production HTTP servernpm run start-stdio- Start production STDIO servernpm run dev- Start development HTTP server with hot reloadnpm run dev-stdio- Start development STDIO server with hot reloadnpm run test-client- Run test client
Project Structure
src/
├── core/ # Core utilities (logger, types)
├── tools/ # MCP tool implementations
├── server.ts # HTTP server entry point
└── server-stdio.ts # STDIO server entry point
📝 Logging
The server includes comprehensive logging with daily rotation:
- Location:
logs/directory - Rotation: Daily with date-based filenames
- Levels: error, warn, info, debug
- Format: JSON with timestamps
🤝 Contributing
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Submit a pull request
📄 License
ISC License - see package.json for details
🔗 Related
- grep.app - The search service powering this tool
- Model Context Protocol - MCP specification
- Claude Code - Claude's official CLI