Discussions & Gists

Relevant source files

The following files were used as context for generating this wiki page:

• pkg/github/discussions.go
• pkg/github/gists.go
• pkg/github/discussions_test.go
• pkg/github/gists_test.go
• cmd/github-mcp-server/generate_docs.go

The Discussions and Gists modules within the GitHub MCP server provide a Model Context Protocol (MCP) interface for interacting with GitHub's community-driven discussion forums and code snippet repository (Gists). These modules translate MCP tool calls into specific GitHub API requests—utilizing GraphQL for discussions and REST for gists—allowing LLMs and other agentic workflows to list, retrieve, and manage these community resources.

The Discussions module is primarily focused on read-only exploration of repository or organization-level conversations, while the Gists module supports full lifecycle management, including listing, creating, and updating code snippets.

Sources: pkg/github/discussions.go, pkg/github/gists.go

GitHub Discussions

The Discussions feature implementation leverages the GitHub GraphQL API (v4) to handle complex filtering and pagination requirements. It supports querying at both the repository level and the organization level (by defaulting to the .github repository).

Sources: pkg/github/discussions.go:130-135

Data Architecture and Query Types

Because GraphQL requires specific structures for different combinations of filters and ordering, the system implements a DiscussionQueryResult interface and several query structs to handle various parameter combinations.

Key Discussion Tools

The module exposes several tools to the MCP server:

Tool Name	Description	Key Parameters
list_discussions	Lists discussions for a repo or org.	owner, repo, category, orderBy, direction
get_discussion	Retrieves detailed content of one discussion.	owner, repo, discussionNumber
get_discussion_comments	Fetches comments for a specific discussion.	owner, repo, discussionNumber
list_discussion_categories	Lists available categories (e.g., Q&A, Ideas).	owner, repo

Sources: pkg/github/discussions.go:102-125, pkg/github/discussions.go:230-250, pkg/github/discussions.go:300-315, pkg/github/discussions.go:380-395

Logic Flow for Listing Discussions

The ListDiscussions handler dynamically selects the GraphQL query type and variables based on user input.

GitHub Gists

Unlike Discussions, the Gists module interacts with GitHub via the REST API. It allows users to manage snippets of code that are not necessarily tied to a specific repository.

Sources: pkg/github/gists.go

Gist Lifecycle Management

The Gist module provides standard CRUD (Create, Read, Update) functionality through three primary tools.

1. Listing Gists

The list_gists tool allows users to see gists for a specific user or the currently authenticated user. It supports filtering by the since timestamp to find recently updated snippets.

Sources: pkg/github/gists.go:16-30

2. Creating Gists

The create_gist tool handles the creation of a new gist. In this implementation, it is optimized for "simple single-file gist creation," requiring a filename and content.

files := make(map[github.GistFilename]github.GistFile)
files[github.GistFilename(filename)] = github.GistFile{
    Filename: github.Ptr(filename),
    Content:  github.Ptr(content),
}

gist := &github.Gist{
    Files:       files,
    Public:      github.Ptr(public),
    Description: github.Ptr(description),
}

Sources: pkg/github/gists.go:115-128

3. Updating Gists

The update_gist tool allows modifying the description or the content of a specific file within an existing gist using the gist_id.

Sources: pkg/github/gists.go:160-175

Gist API Parameters

Parameter	Type	Required	Description
username	string	No	Target user (defaults to self).
since	string	No	ISO 8601 timestamp filter.
gist_id	string	Yes (Update)	The unique ID of the gist.
filename	string	Yes (Create/Update)	Name of the file.
content	string	Yes (Create/Update)	Content of the file.
public	boolean	No	Visibility (default: false).

Sources: pkg/github/gists.go:22-28, pkg/github/gists.go:90-105, pkg/github/gists.go:165-180

Common Implementation Details

Pagination

Both modules implement standardized pagination patterns used across the GitHub MCP server.

• Discussions uses Cursor-based pagination (using after and endCursor) to align with GraphQL standards.
• Gists uses Offset-based pagination (using page and perPage) common in REST APIs.

Sources: pkg/github/discussions.go:126, pkg/github/gists.go:29

Documentation Generation

The tools in these modules are automatically documented via the generate_docs.go utility. This utility inspects the mcp.Tool definitions (like names, descriptions, and input schemas) to generate the README and other documentation files.

Sources: cmd/github-mcp-server/generate_docs.go:145-185

Conclusion

The Discussions & Gists modules extend the GitHub MCP server's capabilities beyond standard repository management. Discussions provide a way for AI agents to participate in and retrieve information from community knowledge bases, while Gists offer a lightweight mechanism for persistent code snippet storage and sharing. By wrapping GraphQL and REST calls into a unified MCP interface, these modules allow for seamless integration of GitHub community features into agentic workflows.

Sources: pkg/github/discussions.go, pkg/github/gists.go