# github-mcp-server

A lightweight **Model Context Protocol (MCP) server** that exposes three GitHub utility tools to AI agents (such as IBM Bob).

## Tools

| Tool | Description |
|------|-------------|
| `search_repositories` | Search GitHub repos by keyword — returns name, description, URL, stars, forks, language |
| `list_issues` | List issues for any public (or accessible private) repo — filter by state and labels |
| `read_file_contents` | Read the raw text of any file in a repo — specify an optional branch/tag/commit ref |

## Requirements

- Node.js ≥ 20
- A GitHub [Personal Access Token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens) with at least the `public_repo` (or `repo` for private repos) scope

## Installation

```bash
git clone https://github.com/kevinshim/github-mcp-server.git
cd github-mcp-server
npm install
npm run build
```

## Usage

Start the server manually (for testing):

```bash
GITHUB_TOKEN=ghp_your_token node build/index.js
```

### Register with IBM Bob

Add the following to your Bob `mcp.json` (global: `~/.bob/mcp.json`, or workspace: `.bob/mcp.json`):

```json
{
  "mcpServers": {
    "github-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/github-mcp-server/build/index.js"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}
```

Replace `/absolute/path/to/github-mcp-server` with the actual path on your machine.

## Example prompts (inside Bob)

```
Search for TypeScript MCP server repositories with more than 100 stars.

List the open bug issues in IBM/galaxium-travels.

Read the contents of src/index.ts from my-org/my-repo on branch main.
```

## Project structure

```
github-mcp-server/
├── src/
│   └── index.ts        # Server implementation
├── build/              # Compiled output (generated by npm run build)
├── package.json
├── tsconfig.json
└── README.md
```

## License

MIT