Relevant source files

The following files were used as context for generating this wiki page: - [pkg/github/discussions.go](https://github.com/BablAdm/github-mcp-server/blob/main/pkg/github/discussions.go) - [pkg/github/gists.go](https://github.com/BablAdm/github-mcp-server/blob/main/pkg/github/gists.go) - [pkg/github/discussions_test.go](https://github.com/BablAdm/github-mcp-server/blob/main/pkg/github/discussions_test.go) - [pkg/github/gists_test.go](https://github.com/BablAdm/github-mcp-server/blob/main/pkg/github/gists_test.go) - [cmd/github-mcp-server/generate_docs.go](https://github.com/BablAdm/github-mcp-server/blob/main/cmd/github-mcp-server/generate_docs.go)

# Discussions & Gists 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. ```mermaid classDiagram class DiscussionQueryResult { <> +GetDiscussionFragment() DiscussionFragment } class BasicNoOrder { +Repository repository } class BasicWithOrder { +Repository repository } class WithCategoryAndOrder { +Repository repository } class WithCategoryNoOrder { +Repository repository } DiscussionQueryResult <|-- BasicNoOrder DiscussionQueryResult <|-- BasicWithOrder DiscussionQueryResult <|-- WithCategoryAndOrder DiscussionQueryResult <|-- WithCategoryNoOrder ``` *The diagram shows the polymorphism used to handle different GraphQL query structures depending on whether category filters or ordering are applied.* Sources: [pkg/github/discussions.go:18-65]() ### 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. ```mermaid flowchart TD Start[Call list_discussions] --> Params[Parse owner, repo, category, order] Params --> Pagination[Parse Cursor Pagination] Pagination --> QueryType{Category or Order?} QueryType -- Both --> Q1[WithCategoryAndOrder] QueryType -- Category Only --> Q2[WithCategoryNoOrder] QueryType -- Order Only --> Q3[BasicWithOrder] QueryType -- Neither --> Q4[BasicNoOrder] Q1 & Q2 & Q3 & Q4 --> Exec[Execute GQL Query] Exec --> Map[Map Fragment to Discussion Model] Map --> Response[Return JSON with discussions & pageInfo] ``` *Flow of logic within the ListDiscussions tool handler to determine the appropriate GraphQL operation.* Sources: [pkg/github/discussions.go:91-100](), [pkg/github/discussions.go:145-220]() ## 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. ```go 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]()