# HTTP MCP Server
A Model Context Protocol (MCP) server that provides GitHub repository information via both HTTP and stdio transports. This server enables AI assistants and other MCP clients to fetch GitHub repositories for any user.
## 🚀 Features
- **GitHub Repository Fetcher**: Retrieve all repositories for any GitHub username
- **Dual Transport Modes**:
- **HTTP Mode**: Run as a web server for remote access
- **stdio Mode**: Run locally for MCP client integration
- **Type-Safe**: Built with TypeScript and Zod for schema validation
- **Express Integration**: Modern HTTP server with JSON support
## 📋 Prerequisites
- Node.js (v18 or higher)
- npm or yarn
## 🔧 Installation
1. Clone the repository:
```bash
git clone https://github.com/kh-mahmoud/streamable-mcp.git
cd streamable-mcp
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
## 🎯 Usage
### HTTP Mode (Web Server)
Start the server in HTTP mode:
```bash
npm run server
```
The server will start on `http://localhost:3000` (or the port specified in `PORT` environment variable).
**API Endpoint:**
- **POST** `/mcp` - MCP JSON-RPC endpoint
### stdio Mode (Local MCP Client)
For local MCP client integration:
```bash
node build/index.js stdio
```
### Development Mode
Run with hot-reload during development:
```bash
npm run server
```
### MCP Inspector
Inspect the MCP server:
```bash
npm run inspect
```
## 🛠️ Available Tools
### `get_repos`
Fetches all public repositories for a given GitHub username.
**Parameters:**
- `username` (string): GitHub username to fetch repositories for
**Returns:**
- List of all repositories with their names
```
## 📁 Project Structure
```bash
http_mcp/
├── src/
│ └── index.ts # Main server implementation
├── build/
│ └── index.js # Compiled JavaScript
├── package.json # Dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── Readme.md # This file
```
## 🛠️ Technologies Used
- **[Model Context Protocol SDK](https://github.com/modelcontextprotocol/sdk)**: MCP server implementation
- **[Express](https://expressjs.com/)**: HTTP server framework
- **[TypeScript](https://www.typescriptlang.org/)**: Type-safe JavaScript
- **[Zod](https://zod.dev/)**: Schema validation
- **[tsx](https://github.com/esbuild-kit/tsx)**: TypeScript execution
## 📝 Scripts
- `npm run build`: Compile TypeScript to JavaScript
- `npm start`: Start the HTTP server
- `npm run server`: Start development server with hot-reload
- `npm run inspect`: Inspect MCP server with MCP Inspector
## 🔌 MCP Client Integration
To use this server with an MCP client, configure it in your MCP client settings:
**For stdio mode:**
```json
{
"mcpServers": {
"http_mcp": {
"command": "node",
"args": ["path/to/build/index.js"]
}
}
}
```
**For HTTP mode:**
```bash
npm i mcp-remote
```
```bash
"http-mcp": {
"command": "mcp-remote",
"args": [
"http://localhost:3000/mcp" or "your/deployment/link/mcp"
],
"env":{
"NODE_OPTIONS":"--no-deprecation"
}
}
```
---
## 🔗 Resources
- [Building an MCP Server (Heroku Builder)](https://content.herokubuilder.com/mcp-node/building-an-mcp.html)
⭐ If you find this project useful, please consider giving it a star!
