# 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:
   ```bash
   pnpm install
   ```

2. Copy the example environment file:
   ```bash
   cp .env.example .env
   ```

3. Set your GitHub token in `.env`:
   ```env
   GITHUB_TOKEN=your_github_token_here
   ```

## Run locally

Start the development server:

```bash
pnpm dev
```

Build the project:

```bash
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`:

```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`.