npm package: @purpledotstudio/git-gogo-mcp
Description: GitHub workflow automation MCP server with project management integration
Author: Andy James
Latest version: 1.3.0

# git-gogo MCP Server

> GitHub workflow automation MCP server with project management integration

A Model Context Protocol (MCP) server that streamlines GitHub project workflows by integrating issue management, project boards, and git operations into a conversational AI interface.

## Features

- 🎯 **Project Management** - Show tasks, start issues, track progress
- 📝 **Issue Management** - Create, list, and manage GitHub issues
- 🏷️ **Milestone Management** - Create and manage project milestones
- 💬 **Discussion Management** - Create and manage GitHub discussions with category support
- 🔄 **Workflow Automation** - Automated commit messages with issue linking
- 📊 **Project Board Integration** - Update issue status across project boards
- ⚙️ **Configuration Management** - Persistent project and discussion settings

## Prerequisites

- **Node.js** >= 18.0.0
- **GitHub CLI** (`gh`) >= 2.0.0
  ```bash
  # macOS
  brew install gh
  
  # Other platforms: https://cli.github.com/
  ```
- **GitHub Authentication**
  ```bash
  gh auth login
  gh auth refresh -s project  # Required for project board access
  ```

## Installation

> **👥 Team Members:** See [SETUP.md](./SETUP.md) for a quick setup guide!

### As MCP Server

1. **Install the package:**
   ```bash
   npm install -g @purpledotstudio/git-gogo-mcp
   ```

2. **Add to your MCP configuration:**
   
   <details>
   <summary><b>Windsurf</b></summary>
   
   **File:** `~/.codeium/windsurf/mcp_config.json`
   ```json
   {
     "mcpServers": {
       "git-gogo": {
         "command": "git-gogo-mcp"
       }
     }
   }
   ```
   </details>
   
   <details>
   <summary><b>Claude Desktop</b></summary>
   
   **File (macOS):** `~/Library/Application Support/Claude/claude_desktop_config.json`  
   **File (Windows):** `%APPDATA%\Claude\claude_desktop_config.json`
   ```json
   {
     "mcpServers": {
       "git-gogo": {
         "command": "git-gogo-mcp"
       }
     }
   }
   ```
   </details>
   
   <details>
   <summary><b>Claude Code (VS Code)</b></summary>
   
   **Option 1: Using CLI (Recommended)**
   ```bash
   claude mcp add git-gogo "npx -y @purpledotstudio/git-gogo-mcp"
   ```
   
   **Option 2: Manual Configuration**
   
   **File (macOS/Linux):** `~/.claude/mcp_config.json`  
   **File (Windows):** `%USERPROFILE%\.claude\mcp_config.json`
   ```json
   {
     "mcpServers": {
       "git-gogo": {
         "command": "git-gogo-mcp"
       }
     }
   }
   ```
   </details>
   
   <details>
   <summary><b>Trae (VS Code)</b></summary>
   
   **File:** `~/.trae/mcp_config.json`
   ```json
   {
     "mcpServers": {
       "git-gogo": {
         "command": "git-gogo-mcp"
       }
     }
   }
   ```
   </details>

3. **Restart your AI client**

## Available Tools

### Quick Reference

| Tool | Description | Key Parameters |
|------|-------------|----------------|
| **Workflow** | | |
| `show_my_work` | Show tasks in 'Ready' status assigned to you | None |
| `start_issue` | Start work on an issue, move to 'In Progress' | `issue_number` |
| `commit_changes` | Commit with auto-generated message & issue link | `files`, `message?`, `type?` |
| **Issues** | | |
| `get_my_issues` | List issues assigned to you | `repo?`, `state?`, `limit?` |
| `create_issue_from_todo` | Create issue from TODO, add to project | `title`, `body`, `repo`, `assignee`, `projectOwner`, `projectNumber` |
| **Milestones** | | |
| `get_milestones` | List repository milestones | `repo`, `state?` |
| `create_milestone` | Create a new milestone | `repo`, `title`, `description?`, `due_on?` |
| **Discussions** | | |
| `configure_discussion_categories` | Fetch and store discussion categories | `repo` |
| `get_discussion_categories` | View configured discussion categories | None |
| `create_discussion` | Create a new discussion | `repo`, `title`, `body`, `category?` |
| `add_discussion_to_issue` | Link a discussion to an issue | `repo`, `issue_number`, `discussion_url` |
| **Configuration** | | |
| `configure_project` | Set default project settings | `owner`, `number`, `repo`, `assignee`, `projectId?` |
| `get_project_config` | View current project configuration | None |

### Workflow Tools

#### `show_my_work`
Show tasks assigned to you in 'Ready' status from the configured project.

**Requirements:**
- ⚠️ **Project must be configured**: Use `configure_project` first if not set up
- Looks for tasks with **Status = "Ready"**
- Filters by assignee from configured project

**What it returns:**
- Numbered list of ready tasks
- Issue number, title, labels, milestone, URL
- Prompt to select which task to work on

**Usage:**
```
"Show my work"
"What tasks are ready for me?"
```

**Note:** If no tasks found, check:
- Tasks exist in project with "Ready" status
- Tasks are assigned to you
- Project configuration is correct (`get_project_config`)

#### `start_issue`
Start working on a GitHub issue by fetching details, moving to 'In Progress', and loading context.

**Parameters:**
- `issue_number` (required): Issue number to start working on

**What it does:**
1. Fetches issue details using `gh issue view`
2. Finds the issue in the configured project
3. Updates project status to **"In Progress"**
4. Saves issue to `currentIssue` in config (for `commit_changes`)
5. Returns formatted issue details with title, description, labels, milestone, comments

**Requirements:**
- ⚠️ **Project must be configured**: Use `configure_project` first
- Issue must exist in the repository
- Project must have "Status" field with "In Progress" option

**Usage:**
```
"Start issue 42"
"Begin work on issue #15"
```

**Typical workflow:**
1. `show_my_work` → See ready tasks
2. `start_issue 42` → Begin working on issue #42
3. Make code changes
4. `commit_changes` → Commit with auto-generated message

#### `commit_changes`
Commit changes with auto-generated conventional commit message linked to current issue.

**Parameters:**
- `files` (required): Array of modified file paths
- `message` (optional): Custom commit message. If not provided, will be auto-generated from issue title
- `type` (optional): Commit type - `feat`, `fix`, `chore`, `docs`, `style`, `refactor`, `test`, `perf`. Default: `feat`

**Important Notes:**
- ⚠️ **Requires active issue**: Must call `start_issue` first to set the current issue
- Automatically adds `Closes #<issue_number>` to commit message
- Stages specified files with `git add`
- Clears current issue after successful commit
- Uses conventional commit format: `type: message`

**Auto-generated commit message format:**
```
<type>: <issue title in lowercase>

Closes #<issue_number>
```

**Usage:**
```
"Commit these changes"
"Create a commit for the current issue"
"Commit with type fix"
```

**Example:**
If current issue is #42 "Add User Authentication":
- Without custom message: `feat: add user authentication\n\nCloses #42`
- With custom message: `<your message>\n\nCloses #42`

### Issue Management

#### `get_my_issues`
Get GitHub issues assigned to you using the GitHub CLI.

**Parameters:**
- `repo` (optional): Repository in format 'owner/repo'. If not provided, uses current directory's repository
- `state` (optional): Filter by state - `open`, `closed`, or `all` (default: `open`)
- `limit` (optional): Maximum number of issues to return (default: `30`)

**Requirements:**
- GitHub CLI (`gh`) must be installed and authenticated
- Repository access (if `repo` parameter specified)

**Returns:**
- Formatted list with issue number, title, state, labels, created/updated dates, URL
- Empty message if no issues found

**Usage:**
```
"Show my GitHub issues"
"Get my open issues from owner/repo"
"List all my closed issues"
```

#### `create_issue_from_todo`
Create a GitHub issue from a TODO comment and add to project board.

**Parameters:**
- `title` (required): Issue title (extracted from TODO)
- `body` (required): Issue description with context
- `repo` (required): Repository in format 'owner/repo'
- `assignee` (required): GitHub username to assign the issue to
- `projectOwner` (required): Project owner (org or user)
- `projectNumber` (required): Project number (e.g., 1)
- `milestone` (optional): Milestone title to add the issue to
- `statusValue` (optional): Status to set (e.g., 'Backlog', 'Ready', 'In progress'). Default: `Backlog`
- `statusFieldId` (optional): Field ID for status. Auto-detected if not provided
- `filePath` (optional): Absolute path to file containing the TODO comment
- `todoComment` (optional): Exact TODO comment text to replace (including comment markers like `//` or `#`)
- `conversationContext` (optional): Additional context from conversation (added to issue body under "Discussion Context")

**Requirements:**
- ⚠️ **GitHub CLI with project scope**: Run `gh auth refresh -s project`
- ⚠️ **Get milestones first**: Use `get_milestones` to fetch available milestones, then let user select one (or create with `create_milestone`)

**TODO Comment Examples:**

```javascript
// TODO: Add user authentication to this endpoint
// Need to implement JWT token validation and role-based access control

// TODO: Refactor this function to use async/await
// Current callback-based approach is hard to maintain

// FIXME: Memory leak in event listener cleanup
// Event listeners are not being properly removed on component unmount
```

```python
# TODO: Implement caching for database queries
# This query runs on every request and is slowing down the API

# TODO: Add input validation
# Need to validate email format and password strength

# FIXME: Race condition in concurrent requests
# Multiple simultaneous requests can cause data corruption
```

```typescript
// TODO: Add TypeScript types for API responses
// Currently using 'any' which defeats the purpose of TypeScript

// TODO: Implement error boundary for this component
// Uncaught errors crash the entire application
```

**Usage:**
```
"Create an issue from this TODO comment"
"Convert this TODO to a GitHub issue and add it to the project"
```

The tool will:
1. Extract the TODO comment and context
2. Create a GitHub issue with the TODO as the title
3. Add surrounding code context to the issue body
4. Assign to specified user
5. Add to project board with chosen status
6. Optionally replace the TODO comment with a link to the created issue

### Milestone Management

#### `get_milestones`
Get list of milestones for a repository.

**Parameters:**
- `repo` (required): Repository in format 'owner/repo'
- `state` (optional): Filter by state - `open`, `closed`, or `all` (default: `open`)

**Returns:**
- List of milestones with title, state, description, due date, open/closed issue counts

**Usage:**
```
"Get milestones for owner/repo"
"Show all milestones including closed ones"
```

**Note:** Call this before `create_issue_from_todo` to let user select appropriate milestone.

#### `create_milestone`
Create a new milestone in a repository.

**Parameters:**
- `repo` (required): Repository in format 'owner/repo'
- `title` (required): Milestone title
- `description` (optional): Milestone description
- `due_on` (optional): Due date in ISO 8601 format (YYYY-MM-DD)

**Returns:**
- Created milestone details with number, title, URL

**Usage:**
```
"Create milestone 'Sprint 1' for owner/repo"
"Create milestone with due date 2025-12-31"
```

### Discussion Management

#### `configure_discussion_categories`
Fetch and store discussion categories for a repository.

**Parameters:**
- `repo` (required): Repository in format 'owner/repo'

**What it does:**
1. Fetches all available discussion categories from the repository using GitHub GraphQL API
2. Stores category IDs, names, descriptions, and emojis in `config.json`
3. Saves repository ID for efficient discussion creation

**Requirements:**
- GitHub CLI (`gh`) must be installed and authenticated
- Discussions must be enabled for the repository
- Repository access required

**Returns:**
- List of available categories with names, descriptions, emojis, and IDs

**Usage:**
```
"Configure discussion categories for owner/repo"
"Fetch discussion categories"
```

**Note:** Run this once per repository before creating discussions. Categories are stored in config for reuse.

#### `get_discussion_categories`
View the configured discussion categories.

**Returns:**
- List of stored discussion categories with names, descriptions, emojis, and IDs
- Repository name for which categories are configured

**Usage:**
```
"Show discussion categories"
"What discussion categories are available?"
```

**Note:** If no categories are configured, prompts to use `configure_discussion_categories` first.

#### `create_discussion`
Create a new GitHub discussion in a repository. **This tool automatically asks the user to select a category.**

**Parameters:**
- `repo` (required): Repository in format 'owner/repo'
- `title` (required): Discussion title
- `body` (required): Discussion body/content (supports Markdown)
- `category` (optional): Category name or number. If not provided, the tool will show available categories and ask the user to select one

**What it does:**
1. Automatically fetches and stores discussion categories if not already configured
2. Shows available categories to the user with emojis and descriptions
3. Asks user to select a category by name or number
4. Creates the discussion once category is selected

**Requirements:**
- GitHub CLI with authentication
- Discussions enabled for repository
- Permission to create discussions

**Returns:**
- Discussion number, title, category, and URL

**Usage:**
```
"Create a discussion called 'Hello World'"
"Start a new discussion about feature requests"
```

**Example Workflow:**
```
User: "Create a discussion called 'Feature Ideas'"
AI: [Calls create_discussion, shows categories]
   
   Select a category for your discussion
   
   Title: Feature Ideas
   
   Available Categories:
   1. 📣 Announcements - Updates from maintainers
   2. 💬 General - Chat about anything and everything here
   3. 💡 Ideas - Share ideas for new features
   4. 🙏 Q&A - Ask the community for help
   
   Please reply with the category name or number (1-4)

User: "Ideas" or "3"
AI: [Creates discussion in Ideas category]
   ✅ Discussion created successfully!
   Title: Feature Ideas
   Number: #42
   Category: 💡 Ideas
   URL: https://github.com/...
```

**Advanced Usage:**
You can also provide the category directly to skip the selection step:
```
"Create a discussion called 'Bug Report' in the General category"
```

#### `add_discussion_to_issue`
Add a discussion link to an issue by updating the issue's body. The discussion link will be added at the top of the issue body as a blockquote.

**Parameters:**
- `repo` (required): Repository in format 'owner/repo'
- `issue_number` (required): Issue number to update
- `discussion_url` (required): Full discussion URL (e.g., 'https://github.com/owner/repo/discussions/42')

**What it does:**
1. Fetches the current issue details
2. Extracts the discussion number from the URL
3. Adds or updates a discussion link at the top of the issue body
4. Updates the issue with the new body

**Format:**
The discussion link is added as a blockquote at the top:
```markdown
> **💬 Discussion:** [#42](https://github.com/owner/repo/discussions/42)

[Original issue body content...]
```

**Requirements:**
- GitHub CLI with authentication
- Permission to edit the issue
- Valid issue number and discussion URL

**Returns:**
- Confirmation with issue number, title, discussion number, and issue URL

**Usage:**
```
"Add discussion #42 to issue #15"
"Link the discussion to issue #20"
```

**Example:**
```
User: "Add discussion https://github.com/owner/repo/discussions/42 to issue #15"
AI: [Calls add_discussion_to_issue]
   ✅ Discussion link added to issue!
   Issue: #15 - Fix authentication bug
   Discussion: #42
   Issue URL: https://github.com/owner/repo/issues/15
```

**Notes:**
- If the issue already has a discussion link, it will be replaced with the new one
- The discussion link is added as a blockquote for visual distinction
- The original issue body content is preserved

### Configuration

#### `configure_project`
Configure default project settings for this repository.

**Parameters:**
- `owner` (required): Project owner (org or user, e.g., 'PurpleDotStudio')
- `number` (required): Project number (e.g., 1)
- `repo` (required): Repository in format 'owner/repo' (e.g., 'PurpleDotStudio/my-repo')
- `assignee` (required): Default assignee username (e.g., 'andyjamesn')
- `projectId` (optional): Project's GraphQL node ID (e.g., 'PVT_kwDOBmeIvM4BGkkM'). Auto-detected if not provided

**What it does:**
1. Saves project settings to `config.json`
2. If `projectId` not provided, looks it up via GraphQL
3. Used by `show_my_work`, `start_issue`, and `create_issue_from_todo`

**Stored configuration:**
```json
{
  "defaultProject": {
    "owner": "PurpleDotStudio",
    "number": 1,
    "repo": "PurpleDotStudio/my-repo",
    "assignee": "username",
    "projectId": "PVT_kwDOBmeIvM4BGkkM"
  }
}
```

**Usage:**
```
"Configure project for PurpleDotStudio/my-repo, project #1, assign to username"
```

**Note:** Run this once per repository to set up your workflow.

#### `get_project_config`
Get the current default project configuration.

**Returns:**
- Current project settings including owner, number, repo, assignee, projectId
- Current issue (if one is active from `start_issue`)

**Usage:**
```
"Show project config"
"What's my current project configuration?"
```

## Workflow Example

```
User: "Show my work"
AI: [Lists tasks in Ready status]

User: "Start issue 42"
AI: [Fetches issue, moves to In Progress, loads context]

User: [Makes code changes]

AI: [Detects changes and suggests commit]
"I've updated the authentication flow. Ready to commit?"

User: "Yes, commit these changes"
AI: [Creates commit with message: "feat: update authentication flow\n\nCloses #42"]
```

## Configuration File

The server stores configuration in `config.json`:

```json
{
  "defaultProject": {
    "owner": "PurpleDotStudio",
    "number": 1,
    "repo": "PurpleDotStudio/my-repo",
    "assignee": "username",
    "projectId": "PVT_kwDOBmeIvM4BGkkM"
  },
  "currentIssue": {
    "number": 42,
    "title": "Update authentication flow",
    "url": "https://github.com/..."
  },
  "discussionCategories": {
    "repo": "PurpleDotStudio/my-repo",
    "repositoryId": "R_kgDOBmeIvM",
    "categories": [
      {
        "id": "DIC_kwDOBmeIvM4CXxyz",
        "name": "General",
        "description": "General discussions",
        "emoji": "💬"
      },
      {
        "id": "DIC_kwDOBmeIvM4CXxab",
        "name": "Ideas",
        "description": "Share ideas for new features",
        "emoji": "💡"
      },
      {
        "id": "DIC_kwDOBmeIvM4CXxcd",
        "name": "Q&A",
        "description": "Ask the community for help",
        "emoji": "❓"
      }
    ]
  }
}
```

## Development

```bash
# Clone repository
git clone https://github.com/PurpleDotStudio/git-gogo-mcp
cd git-gogo-mcp

# Install dependencies
npm install

# Run locally
node index.js
```

## Troubleshooting

### "gh: command not found"
Install GitHub CLI: https://cli.github.com/

### "insufficient OAuth scopes"
Refresh authentication with project scope:
```bash
gh auth refresh -s project
```

### "No current issue found"
Use `start_issue` before calling `commit_changes`:
```
"Start issue 42"
[Make changes]
"Commit changes"
```

### Config not persisting
Ensure the server has write permissions to its directory.

## Contributing

Contributions welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

## License

MIT © Purple Dot Studio

## Links

- [GitHub Repository](https://github.com/PurpleDotStudio/git-gogo-mcp)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [GitHub CLI Documentation](https://cli.github.com/manual/)