MCP Demo Server

This repository is a minimal Model Context Protocol (MCP) server that exposes GitHub issue, pull request, and Actions operations as tools over a Streamable HTTP transport.

Overview

The server uses:

• @modelcontextprotocol/sdk for MCP server and transport support
• express to expose a /mcp HTTP endpoint
• octokit to communicate with GitHub
• zod to define tool input schemas

The server organizes code into two domains:

• src/github/: GitHub helper functions grouped by domain (client, issues, pullRequests, actions)
• src/tools/: MCP tool registration for issues, pull requests, and actions

Project structure

• src/main.ts: MCP server setup, Express app, and tool registration
• src/github/client.ts: Octokit client initialization and token validation
• src/github/issues.ts: GitHub issue helpers
• src/github/pullRequests.ts: GitHub pull request helpers
• src/github/actions.ts: GitHub Actions workflow helpers
• src/tools/issues.ts: issue-related MCP tools
• src/tools/pullRequests.ts: pull-request-related MCP tools
• src/tools/actions.ts: action-related MCP tools
• .env: local environment variables (ignored in git)
• .env.example: example environment variables
• .github/important-files.mdc: important file list for repo metadata

Requirements

• Node.js 20+ (recommended)
• corepack / pnpm
• GitHub Personal Access Token with repo and workflow permissions

Setup

1. Install dependencies:

   pnpm install
   

2. Copy the example environment file:

   cp .env.example .env
   

3. Set your GitHub token in .env:

   GITHUB_TOKEN=your_github_token_here
   

Run locally

Start the development server:

pnpm dev

Build the project:

pnpm build

Server endpoint

The MCP server listens on the port set by PORT or 8080 by default.

• HTTP endpoint: POST /mcp

This route accepts MCP requests from a compatible client and forwards them to the Streamable HTTP transport.

Connecting from VS Code

Create .vscode/mcp.json:

{
  "servers": {
    "github": { "type": "http", "url": "http://localhost:8080/mcp" }
  }
}

Ensure the server is running (pnpm dev) first, then start it via:

Command Palette → MCP: List Servers → Restart.

Available tools

Issues

• getIssue
• createIssueComment
• updateIssue
• listIssues

Pull Requests

• getPullRequest
• createPullRequestComment
• updatePullRequest
• listPullRequests

Actions

• listActions
• getActionStatus
• getActionDetails
• cancelAction
• retryAction

How it works

1. src/main.ts creates an McpServer instance.
2. Domain-specific tool registrars attach GitHub tools to the server.
3. Express exposes /mcp and each request creates a fresh StreamableHTTPServerTransport.
4. The transport handles the incoming request and sends the MCP response back to the client.
5. GitHub functions use Octokit with GITHUB_TOKEN from .env.