kodegen_tools_github-0.2.3 has been yanked.

kodegen_github

GitHub API operations via Octocrab with MCP tool wrappers for AI agents.

Features

Async-first: Built on tokio for efficient async operations
Clean API: Wraps octocrab with ergonomic interfaces
MCP Tools: 12 GitHub tools for AI agent integration (7 issue + 5 pull request tools)
Type-safe: Full Rust type safety throughout
Streaming: Efficient streaming for large result sets

MCP Tools

Issue Operations

create_issue

Create a new issue in a GitHub repository.

Arguments:

owner (string): Repository owner (user or organization)
repo (string): Repository name
title (string): Issue title
body (string, optional): Issue description (Markdown supported)
labels (array, optional): Labels to apply
assignees (array, optional): Users to assign

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "title": "Bug: Login fails",
  "body": "When I try to login, the form doesn't submit...",
  "labels": ["bug", "priority-high"],
  "assignees": ["octocat"]
}

Requirements:

GITHUB_TOKEN environment variable must be set
Token needs 'repo' scope for private repos, 'public_repo' for public
User must have write access to the repository
Labels must already exist in the repository
Assignees must be collaborators on the repository

get_issue

Fetch a single issue by number.

Arguments:

owner (string): Repository owner
repo (string): Repository name
issue_number (number): Issue number

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "issue_number": 42
}

Returns:

number: Issue number
title: Issue title
body: Issue description
state: "open" or "closed"
labels: Array of label objects
assignees: Array of assigned users
created_at: Creation timestamp
updated_at: Last update timestamp
comments: Number of comments
html_url: Link to issue on GitHub

Note: issue_number is the issue number (e.g., #42), NOT the internal ID. Works for both issues and pull requests.

list_issues

List and filter repository issues.

Arguments:

owner (string): Repository owner
repo (string): Repository name
state (string, optional): "open" (default), "closed", or "all"
labels (array, optional): Filter by labels (AND logic)
assignee (string, optional): Filter by assignee username
page (number, optional): Page number for pagination
per_page (number, optional): Results per page (max 100, default 30)

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "state": "open",
  "labels": ["bug"],
  "per_page": 50
}

Filter behavior:

Multiple labels match issues with ALL labels (AND logic, not OR)
State defaults to "open" if not specified
Returns issues in most recent order

update_issue

Update an existing issue.

Arguments:

owner (string): Repository owner
repo (string): Repository name
issue_number (number): Issue number
title (string, optional): New title
body (string, optional): New body
state (string, optional): "open" or "closed"
labels (array, optional): Replace labels
assignees (array, optional): Replace assignees

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "issue_number": 42,
  "state": "closed",
  "labels": ["bug", "resolved"]
}

Important notes:

All fields are optional - only specified fields are updated
labels and assignees REPLACE existing values (not additive)
To clear labels or assignees, pass empty array: []
Set state to "closed" to close an issue, "open" to reopen

search_issues

Search issues across GitHub using GitHub's search syntax.

Arguments:

query (string): GitHub search query (supports complex syntax)
sort (string, optional): "comments", "reactions", "created", "updated"
order (string, optional): "asc" or "desc"
page (number, optional): Page number
per_page (number, optional): Results per page (max 100)

Search Query Syntax:

repo:owner/repo - Search in specific repository
is:open / is:closed - Filter by state
label:bug - Filter by label
assignee:username - Filter by assignee
author:username - Filter by author
involves:username - User is author, assignee, or mentioned
created:>=2024-01-01 - Created after date
created:2024-01-01..2024-12-31 - Date range
Text without prefix searches title and body

Example:

{
  "query": "repo:octocat/hello-world is:open label:bug created:>=2024-01-01",
  "sort": "created",
  "order": "desc",
  "per_page": 20
}

Combined filters example:

repo:octocat/hello-world is:open label:bug assignee:alice created:>=2024-01-01

Important notes:

Search API has stricter rate limits (30 requests/minute authenticated)
Results are relevance-ranked by default
Use quotes for multi-word searches: "bug report"
Date format: YYYY-MM-DD

add_issue_comment

Add a comment to an existing issue.

Arguments:

owner (string): Repository owner
repo (string): Repository name
issue_number (number): Issue number
body (string): Comment text (Markdown supported)

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "issue_number": 42,
  "body": "This has been fixed in the latest release."
}

Markdown features:

Full Markdown support (headings, code blocks, lists, etc.)
@mention users to notify them
Reference other issues/PRs with #number
Link commits with SHA hashes
Add emojis with :emoji_name:

Important notes:

This tool CREATES a new comment each time (not idempotent)
Cannot edit existing comments (separate tool needed)
Works for both issues and pull requests

get_issue_comments

Fetch all comments for an issue.

Arguments:

owner (string): Repository owner
repo (string): Repository name
issue_number (number): Issue number

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "issue_number": 42
}

Returns: Array of comment objects with:

id: Comment ID
body: Comment text (Markdown)
user: Author information (login, avatar_url, etc.)
created_at: When comment was created
updated_at: When comment was last edited
html_url: Link to comment on GitHub
author_association: Relationship to repo (OWNER, CONTRIBUTOR, etc.)

Comment ordering:

Comments are returned in chronological order (oldest first)
Use created_at timestamp to determine comment age
Check author_association to see if author is repo owner/maintainer
updated_at differs from created_at if comment was edited

Pull Request Operations

create_pull_request

Create a new pull request in a GitHub repository.

Arguments:

owner (string): Repository owner (user or organization)
repo (string): Repository name
title (string): Pull request title
body (string, optional): Pull request description (Markdown supported)
head (string): Name of the branch where changes are implemented (head branch)
base (string): Name of the branch to merge into (base branch)
draft (boolean, optional): Create as draft PR (default: false)
maintainer_can_modify (boolean, optional): Allow maintainer edits (default: true)

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "title": "Add new feature",
  "body": "This PR adds...\n\nCloses #123",
  "head": "feature-branch",
  "base": "main",
  "draft": false
}

Cross-fork PRs: For PRs from a fork, use format: fork-owner:branch-name for head:

{
  "owner": "upstream-owner",
  "repo": "project",
  "title": "Fix authentication bug",
  "head": "fork-owner:fix-auth-bug",
  "base": "main"
}

Requirements:

GITHUB_TOKEN with appropriate permissions
Head branch must exist
Base branch must exist
User must have push access to head repository
User needs write access for non-fork PRs

update_pull_request

Update an existing pull request.

Arguments:

owner (string): Repository owner
repo (string): Repository name
pr_number (number): Pull request number
title (string, optional): New title
body (string, optional): New description
state (string, optional): "open" or "closed"
base (string, optional): New base branch
maintainer_can_modify (boolean, optional): Allow maintainer edits

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "pr_number": 42,
  "title": "Updated: Add new feature",
  "state": "open"
}

Important notes:

All fields are optional except owner, repo, and pr_number
Only specified fields are updated
Changing base branch retargets the PR
Set state to "closed" to close without merging

merge_pull_request

Merge a pull request in a GitHub repository.

Arguments:

owner (string): Repository owner
repo (string): Repository name
pr_number (number): Pull request number
commit_title (string, optional): Merge commit title
commit_message (string, optional): Merge commit message
merge_method (string, optional): "merge", "squash", or "rebase"
sha (string, optional): SHA of PR head for safety check

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "pr_number": 42,
  "merge_method": "squash",
  "commit_title": "Add authentication feature"
}

Merge methods:

merge: Creates merge commit, preserves all commits
squash: Combines all commits into one
rebase: Rebases commits onto base branch

Safety: Use sha parameter to ensure PR hasn't changed:

{
  "pr_number": 42,
  "sha": "6dcb09b5b57875f334f61aebed695e2e4193db5e"
}

Requirements:

PR must be in mergeable state
All required checks must pass
Sufficient review approvals
No merge conflicts
User must have write access

Warning: This is a destructive operation that modifies the base branch.

get_pull_request_status

Get detailed status information about a pull request.

Arguments:

owner (string): Repository owner
repo (string): Repository name
pr_number (number): Pull request number

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "pr_number": 42
}

Returns comprehensive status:

Basic info: number, title, state, author
Merge status: mergeable, merge conflicts
Base/head branches and SHAs
CI/CD check status and results
Review state (approved, changes requested, pending)
Labels and assignees
Draft status
Mergeable state (clean, dirty, blocked, unstable, etc.)

Use cases:

Pre-merge validation
CI/CD monitoring
Review requirement checks
Conflict detection
Workflow automation
Status dashboards

Important fields:

mergeable: true/false/null (null = still calculating)
mergeable_state: "clean", "dirty", "blocked", "unstable"
draft: true if still in draft mode
merged: true if already merged

get_pull_request_files

Get all files changed in a pull request with diff stats.

Arguments:

owner (string): Repository owner
repo (string): Repository name
pr_number (number): Pull request number

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "pr_number": 42
}

Returns for each file:

filename: Path to the file
status: "added", "modified", "removed", "renamed", "copied"
additions: Lines added
deletions: Lines deleted
changes: Total changes (additions + deletions)
patch: Actual diff content
blob_url: URL to view file
raw_url: URL to download raw file
previous_filename: Original name (for renamed files)

Response format:

{
  "files": [
    {
      "filename": "src/main.rs",
      "status": "modified",
      "additions": 15,
      "deletions": 3,
      "changes": 18,
      "patch": "@@ -10,7 +10,19 @@..."
    }
  ],
  "count": 5
}

Use cases:

Code review preparation
Impact analysis and scope assessment
Automated PR checks
Test coverage verification
Documentation update checks
File type filtering
Change size metrics

Pull Request Review Operations

get_pull_request_reviews

Get all reviews for a pull request.

Arguments:

owner (string): Repository owner
repo (string): Repository name
pull_number (number): PR number

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "pull_number": 42
}

Returns: Array of reviews with:

id: Review ID
user: Reviewer username and profile
body: Review comment text
state: "APPROVED", "CHANGES_REQUESTED", "COMMENTED", "DISMISSED", "PENDING"
submitted_at: When review was submitted
commit_id: SHA the review is associated with

Use cases:

Check approval status before merging
See who has reviewed and their feedback
Understand what changes were requested
Track review history over time

create_pull_request_review

Create a review on a pull request (approve, request changes, or comment).

Arguments:

owner (string): Repository owner
repo (string): Repository name
pull_number (number): PR number
event (string): "APPROVE", "REQUEST_CHANGES", or "COMMENT"
body (string, optional): Review comment
commit_id (string, optional): Specific commit to review

Example (approve):

{
  "owner": "octocat",
  "repo": "hello-world",
  "pull_number": 42,
  "event": "APPROVE",
  "body": "Looks good to me!"
}

Example (request changes):

{
  "owner": "octocat",
  "repo": "hello-world",
  "pull_number": 42,
  "event": "REQUEST_CHANGES",
  "body": "Please address the comments before merging."
}

Event types:

APPROVE: Approve the PR (allows merging if required reviews are met)
REQUEST_CHANGES: Block PR until changes are made
COMMENT: Leave review comments without approval/blocking

Note: This creates a REVIEW, not individual line comments. Use add_pull_request_review_comment for inline comments.

add_pull_request_review_comment

Add an inline review comment to a PR (comment on specific lines of code).

Arguments:

owner (string): Repository owner
repo (string): Repository name
pull_number (number): PR number
body (string): Comment text
commit_id (string, optional): Commit SHA
path (string, optional): File path
line (number, optional): Line number in diff
side (string, optional): "LEFT" or "RIGHT"
start_line (number, optional): For multi-line comments
start_side (string, optional): Side of start line
subject_type (string, optional): Subject type
in_reply_to (number, optional): Comment ID to reply to

Example (inline comment):

{
  "owner": "octocat",
  "repo": "hello-world",
  "pull_number": 42,
  "body": "Consider using const here",
  "commit_id": "abc123",
  "path": "src/main.rs",
  "line": 45,
  "side": "RIGHT"
}

Example (multi-line comment):

{
  "owner": "octocat",
  "repo": "hello-world",
  "pull_number": 42,
  "body": "This entire function could be simplified",
  "commit_id": "abc123",
  "path": "src/utils.rs",
  "start_line": 20,
  "line": 25,
  "side": "RIGHT"
}

Example (reply to comment):

{
  "owner": "octocat",
  "repo": "hello-world",
  "pull_number": 42,
  "body": "Good point, will fix",
  "in_reply_to": 123456789
}

Comment types:

New inline comment: Requires commit_id, path, line, and optionally side
Multi-line comment: Requires commit_id, path, start_line, line, and optionally sides
Threaded reply: Only requires in_reply_to (inherits position from parent)

Tips:

Use RIGHT side for commenting on new/changed code (most common)
Use LEFT side for commenting on old code being removed
Multi-line comments span from start_line to line (inclusive)
Thread replies create conversations on specific code sections

request_copilot_review

Request GitHub Copilot to review a pull request (experimental).

Arguments:

owner (string): Repository owner
repo (string): Repository name
pull_number (number): PR number

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "pull_number": 42
}

What Copilot reviews:

Code quality and best practices
Potential bugs and issues
Security vulnerabilities
Performance improvements
Code style and conventions

Important notes:

This is an EXPERIMENTAL feature that may change
Requires GitHub Copilot access on the repository
The request triggers the review but doesn't return the review content
Check PR comments after a short delay to see Copilot's feedback
Not all repositories have Copilot review enabled

Example workflow:

Create or update a pull request
Request Copilot review: request_copilot_review({...})
Wait a few moments for Copilot to analyze
Check PR comments: get_pull_request_reviews({...})
Review Copilot's suggestions and feedback

Repository Operations

create_repository

Create a new repository under the authenticated user's account.

Arguments:

name (string): Repository name
description (string, optional): Repository description
private (boolean, optional): Make private
auto_init (boolean, optional): Initialize with README

Example:

{
  "name": "my-project",
  "description": "My awesome project",
  "private": false,
  "auto_init": true
}

fork_repository

Fork a repository.

Arguments:

owner (string): Repository owner to fork from
repo (string): Repository name
organization (string, optional): Fork to organization

Example:

{
  "owner": "octocat",
  "repo": "hello-world"
}

list_branches

List branches in a repository.

Arguments:

owner (string): Repository owner
repo (string): Repository name
page (number, optional): Page number
per_page (number, optional): Results per page

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "per_page": 50
}

create_branch

Create a new branch from a commit SHA.

Arguments:

owner (string): Repository owner
repo (string): Repository name
branch_name (string): New branch name
sha (string): Commit SHA to branch from

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "branch_name": "feature/new-feature",
  "sha": "abc123def456"
}

list_commits

List commits in a repository with filtering options.

Arguments:

owner (string): Repository owner
repo (string): Repository name
sha (string, optional): Branch or SHA to start from
path (string, optional): Only commits affecting this path
author (string, optional): Filter by author
since (string, optional): Only after this date (ISO 8601)
until (string, optional): Only before this date (ISO 8601)
page (number, optional): Page number
per_page (number, optional): Results per page

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "sha": "main",
  "author": "octocat",
  "since": "2024-01-01T00:00:00Z",
  "per_page": 25
}

get_commit

Get detailed information about a specific commit.

Arguments:

owner (string): Repository owner
repo (string): Repository name
commit_sha (string): Commit SHA
page (number, optional): Page for files list
per_page (number, optional): Results per page

Example:

{
  "owner": "octocat",
  "repo": "hello-world",
  "commit_sha": "abc123def456"
}

Search Operations

search_code

Search code across GitHub repositories.

Arguments:

query (string): Search query (GitHub code search syntax)
sort (string, optional): Sort by "indexed"
order (string, optional): "asc" or "desc"
page (number, optional): Page number
per_page (number, optional): Results per page

Query Syntax:

repo:owner/repo - Search in repository
language:rust - Filter by language
path:src/ - Search in path
extension:rs - Filter by extension
Text without prefix searches code content

Example:

{
  "query": "repo:octocat/hello-world async fn language:rust",
  "per_page": 20
}

search_repositories

Search GitHub repositories.

Arguments:

query (string): Search query (GitHub repository search syntax)
sort (string, optional): "stars", "forks", or "updated"
order (string, optional): "asc" or "desc"
page (number, optional): Page number
per_page (number, optional): Results per page

Query Syntax:

language:rust - Filter by language
stars:>1000 - Star count filter
forks:>100 - Fork count filter
topic:async - Filter by topic
user:octocat - By user
org:github - By organization

Example:

{
  "query": "language:rust stars:>100 topic:async",
  "sort": "stars",
  "order": "desc",
  "per_page": 10
}

search_users

Search GitHub users.

Arguments:

query (string): Search query
sort (string, optional): "followers", "repositories", or "joined"
order (string, optional): "asc" or "desc"
page (number, optional): Page number
per_page (number, optional): Results per page

Example:

{
  "query": "location:\"San Francisco\" language:rust",
  "sort": "followers",
  "order": "desc"
}

Environment Variables

All tools require:

GITHUB_TOKEN: Personal access token or app token

Token scopes:

Public repos: public_repo scope
Private repos: repo scope

Usage in Rust

use kodegen_github::GitHubClient;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = GitHubClient::with_token("ghp_...")?;
    
    let issue = client.get_issue("octocat", "hello-world", 42).await?;
    println!("Issue: {:?}", issue);
    
    Ok(())
}

MCP Integration

These tools are automatically available when the github feature is enabled in the kodegen server:

# Enable GitHub tools
kodegen --tool github

# List available categories
kodegen --list-categories

License

MIT

kodegen_tools_github 0.2.3

kodegen_github

Features

MCP Tools

Issue Operations

create_issue

get_issue

list_issues

update_issue

search_issues

add_issue_comment

get_issue_comments

Pull Request Operations

create_pull_request

update_pull_request

merge_pull_request

get_pull_request_status

get_pull_request_files

Pull Request Review Operations

get_pull_request_reviews

create_pull_request_review

add_pull_request_review_comment

request_copilot_review

Repository Operations

create_repository

fork_repository

list_branches

create_branch

list_commits

get_commit

Search Operations

search_code

search_repositories

search_users

Environment Variables

Usage in Rust

MCP Integration

License