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

Related MCP server: mcp-github

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.