@slinerodev/github-releases-mcp/README.md

A Model Context Protocol (MCP) toolkit for GitHub releases management. Features include detailed release information, version comparison, and release listing with rich formatting. Perfect for changelog generation, version tracking, and release documentati

# GitHub Releases MCP Server

A powerful Model Context Protocol (MCP) toolkit for GitHub releases management. This server provides comprehensive tools for accessing, comparing, and analyzing GitHub repository releases with rich formatting and detailed information.

## Features

- 🔍 **Detailed Release Information**: Get comprehensive details about specific releases
- 📊 **Version Comparison**: Compare changes between any two versions
- 📋 **Release Listing**: Get formatted lists of releases with filtering options
- 🏷️ **Semantic Version Support**: Handles various version formats (v1.0.0, @1.0.0, 1.0.0)
- 🎯 **Pre-release Filtering**: Option to include or exclude pre-releases
- 📝 **Rich Formatting**: Emoji-enhanced output for better readability
- 🔄 **Pagination Support**: Handles repositories with many releases
- 🔒 **Authentication**: Optional GitHub token support for private repositories and extended rate limit

## Configuration

The server accepts the following optional environment variables:

- `GITHUB_PERSONAL_ACCESS_TOKEN`: GitHub Personal Access Token (optional). If provided, it will be used to authenticate API requests, allowing for higher rate limits and access to private repositories.

## Quick Start

You can run this MCP server using npx:

```bash
# Using environment variables
GITHUB_PERSONAL_ACCESS_TOKEN=your_token npx @slinerodev/github-releases-mcp

# Or using a .env file
echo "GITHUB_PERSONAL_ACCESS_TOKEN=your_token" > .env
npx @slinerodev/github-releases-mcp
```

## Client Configuration

The server can be used with various MCP clients. Add the following configuration to your client's config file:

- Cursor: `~/.cursor/mcp.json`
- VS Code: `.vscode/settings.json` (use `mcp.servers` instead of `mcpServers`)
- Claude Desktop: `claude_desktop_config.json`
- Windsurf: `windsurf_config.json`

### Using Published Version

```json
{
  "mcpServers": {
    "github-releases": {
      "command": "npx",
      "args": [
        "-y",
        "@slinerodev/github-releases-mcp"
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your_token_here"
      }
    }
  }
}
```

### Using Local Development Version

```json
{
  "mcpServers": {
    "github-releases": {
      "command": "npx",
      "args": [
        "-y",
        "tsx",
        "${workspaceRoot}/main.ts"
      ]
    }
  }
}
```

Note:

- For VS Code, replace `mcpServers` with `mcp.servers` in the configuration.
- Replace `your_token_here` with your GitHub Personal Access Token if you want to access private repositories or need higher rate limits.

## Available Tools

The server provides three specialized tools for working with GitHub releases:

### 1. github_release_info

Get detailed information about a specific release version.

```typescript
const result = await mcp.invoke("github_release_info", {
  owner: "owner-name",
  repo: "repo-name",
  version: "1.0.0" // Supports v1.0.0, @1.0.0, 1.0.0
});
```

Perfect for:

- Understanding what changed in a specific version
- Documentation purposes
- Release note retrieval

### 2. github_releases_compare

Compare changes between two versions.

```typescript
const result = await mcp.invoke("github_releases_compare", {
  owner: "owner-name",
  repo: "repo-name",
  fromVersion: "1.0.0",
  toVersion: "2.0.0"
});
```

Perfect for:

- Generating changelogs
- Understanding feature evolution
- Migration guides
- Breaking change analysis

### 3. github_releases_list

List all releases with filtering options.

```typescript
const result = await mcp.invoke("github_releases_list", {
  owner: "owner-name",
  repo: "repo-name",
  limit: 10, // Optional: limit number of releases
  includePreReleases: false // Optional: include pre-releases
});
```

Perfect for:

- Project release history overview
- Finding latest versions
- Release frequency monitoring
- Pre-release tracking

### Example Response Format

All tools return responses in a consistent, emoji-enhanced format:

```
🔖 v1.0.0 (First stable release)
🗓️ 2024-03-15T10:30:00Z
📝 This is the release description...

---

🔖 v0.9.0 (Beta) (Pre-release)
🗓️ 2024-03-01T08:15:00Z
📝 Beta version with new features...
```

## Error Handling

The tools handle various error cases gracefully:

- Invalid repository names
- Non-existent versions
- Invalid version formats
- API rate limits
- Network issues
- Authentication errors

Each error returns a clear message explaining what went wrong.

## Development

1. Install dependencies:

    ```bash
    pnpm install
    ```

2. Run the server:

    ```bash
    pnpm start
    ```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

ISC

## Author

Sergio Linero