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:

git clone https://github.com/kh-mahmoud/streamable-mcp.git
cd streamable-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build

🎯 Usage

HTTP Mode (Web Server)

Start the server in HTTP mode:

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:

node build/index.js stdio

Development Mode

Run with hot-reload during development:

npm run server

MCP Inspector

Inspect the MCP server:

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: MCP server implementation
• Express: HTTP server framework
• TypeScript: Type-safe JavaScript
• Zod: Schema validation
• 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:

{
  "mcpServers": {
    "http_mcp": {
      "command": "node",
      "args": ["path/to/build/index.js"]
    }
  }
}

For HTTP mode:

npm i mcp-remote

"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)

⭐ If you find this project useful, please consider giving it a star!