Adam Holt
fa2d802912
Build and Test Go Project / build (windows-latest) (push) Has been cancelled
CodeQL / Analyze (go) (push) Has been cancelled
CodeQL / Analyze (actions) (push) Has been cancelled
Docker / build (push) Has been cancelled
Build and Test Go Project / build (macos-latest) (push) Has been cancelled
Build and Test Go Project / build (ubuntu-latest) (push) Has been cancelled
GoReleaser Release / release (push) Has been cancelled
License Check / license-check (push) Has been cancelled
Publish to MCP Registry / publish (push) Has been cancelled
Port resource completion from the remote GitHub MCP Server --- Co-authored-by: Ksenia Bobrova <almaleksia@github.com>
446 lines
14 KiB
Go
446 lines
14 KiB
Go
package github
|
|
|
|
import (
|
|
"context"
|
|
"encoding/json"
|
|
"errors"
|
|
"fmt"
|
|
"strconv"
|
|
"strings"
|
|
|
|
"github.com/github/github-mcp-server/pkg/utils"
|
|
"github.com/google/go-github/v79/github"
|
|
"github.com/google/jsonschema-go/jsonschema"
|
|
"github.com/modelcontextprotocol/go-sdk/mcp"
|
|
)
|
|
|
|
// NewServer creates a new GitHub MCP server with the specified GH client and logger.
|
|
|
|
func NewServer(version string, opts *mcp.ServerOptions) *mcp.Server {
|
|
if opts == nil {
|
|
// Add default options
|
|
opts = &mcp.ServerOptions{
|
|
HasTools: true,
|
|
HasResources: true,
|
|
HasPrompts: true,
|
|
}
|
|
}
|
|
|
|
// Create a new MCP server
|
|
s := mcp.NewServer(&mcp.Implementation{
|
|
Name: "github-mcp-server",
|
|
Title: "GitHub MCP Server",
|
|
Version: version,
|
|
}, opts)
|
|
|
|
return s
|
|
}
|
|
|
|
func CompletionsHandler(getClient GetClientFn) func(ctx context.Context, req *mcp.CompleteRequest) (*mcp.CompleteResult, error) {
|
|
return func(ctx context.Context, req *mcp.CompleteRequest) (*mcp.CompleteResult, error) {
|
|
switch req.Params.Ref.Type {
|
|
case "ref/resource":
|
|
if strings.HasPrefix(req.Params.Ref.URI, "repo://") {
|
|
return RepositoryResourceCompletionHandler(getClient)(ctx, req)
|
|
}
|
|
return nil, fmt.Errorf("unsupported resource URI: %s", req.Params.Ref.URI)
|
|
case "ref/prompt":
|
|
return nil, nil
|
|
default:
|
|
return nil, fmt.Errorf("unsupported ref type: %s", req.Params.Ref.Type)
|
|
}
|
|
}
|
|
}
|
|
|
|
// OptionalParamOK is a helper function that can be used to fetch a requested parameter from the request.
|
|
// It returns the value, a boolean indicating if the parameter was present, and an error if the type is wrong.
|
|
func OptionalParamOK[T any, A map[string]any](args A, p string) (value T, ok bool, err error) {
|
|
// Check if the parameter is present in the request
|
|
val, exists := args[p]
|
|
if !exists {
|
|
// Not present, return zero value, false, no error
|
|
return
|
|
}
|
|
|
|
// Check if the parameter is of the expected type
|
|
value, ok = val.(T)
|
|
if !ok {
|
|
// Present but wrong type
|
|
err = fmt.Errorf("parameter %s is not of type %T, is %T", p, value, val)
|
|
ok = true // Set ok to true because the parameter *was* present, even if wrong type
|
|
return
|
|
}
|
|
|
|
// Present and correct type
|
|
ok = true
|
|
return
|
|
}
|
|
|
|
// isAcceptedError checks if the error is an accepted error.
|
|
func isAcceptedError(err error) bool {
|
|
var acceptedError *github.AcceptedError
|
|
return errors.As(err, &acceptedError)
|
|
}
|
|
|
|
// RequiredParam is a helper function that can be used to fetch a requested parameter from the request.
|
|
// It does the following checks:
|
|
// 1. Checks if the parameter is present in the request.
|
|
// 2. Checks if the parameter is of the expected type.
|
|
// 3. Checks if the parameter is not empty, i.e: non-zero value
|
|
func RequiredParam[T comparable](args map[string]any, p string) (T, error) {
|
|
var zero T
|
|
|
|
// Check if the parameter is present in the request
|
|
if _, ok := args[p]; !ok {
|
|
return zero, fmt.Errorf("missing required parameter: %s", p)
|
|
}
|
|
|
|
// Check if the parameter is of the expected type
|
|
val, ok := args[p].(T)
|
|
if !ok {
|
|
return zero, fmt.Errorf("parameter %s is not of type %T", p, zero)
|
|
}
|
|
|
|
if val == zero {
|
|
return zero, fmt.Errorf("missing required parameter: %s", p)
|
|
}
|
|
|
|
return val, nil
|
|
}
|
|
|
|
// RequiredInt is a helper function that can be used to fetch a requested parameter from the request.
|
|
// It does the following checks:
|
|
// 1. Checks if the parameter is present in the request.
|
|
// 2. Checks if the parameter is of the expected type.
|
|
// 3. Checks if the parameter is not empty, i.e: non-zero value
|
|
func RequiredInt(args map[string]any, p string) (int, error) {
|
|
v, err := RequiredParam[float64](args, p)
|
|
if err != nil {
|
|
return 0, err
|
|
}
|
|
return int(v), nil
|
|
}
|
|
|
|
// RequiredBigInt is a helper function that can be used to fetch a requested parameter from the request.
|
|
// It does the following checks:
|
|
// 1. Checks if the parameter is present in the request.
|
|
// 2. Checks if the parameter is of the expected type (float64).
|
|
// 3. Checks if the parameter is not empty, i.e: non-zero value.
|
|
// 4. Validates that the float64 value can be safely converted to int64 without truncation.
|
|
func RequiredBigInt(args map[string]any, p string) (int64, error) {
|
|
v, err := RequiredParam[float64](args, p)
|
|
if err != nil {
|
|
return 0, err
|
|
}
|
|
|
|
result := int64(v)
|
|
// Check if converting back produces the same value to avoid silent truncation
|
|
if float64(result) != v {
|
|
return 0, fmt.Errorf("parameter %s value %f is too large to fit in int64", p, v)
|
|
}
|
|
return result, nil
|
|
}
|
|
|
|
// OptionalParam is a helper function that can be used to fetch a requested parameter from the request.
|
|
// It does the following checks:
|
|
// 1. Checks if the parameter is present in the request, if not, it returns its zero-value
|
|
// 2. If it is present, it checks if the parameter is of the expected type and returns it
|
|
func OptionalParam[T any](args map[string]any, p string) (T, error) {
|
|
var zero T
|
|
|
|
// Check if the parameter is present in the request
|
|
if _, ok := args[p]; !ok {
|
|
return zero, nil
|
|
}
|
|
|
|
// Check if the parameter is of the expected type
|
|
if _, ok := args[p].(T); !ok {
|
|
return zero, fmt.Errorf("parameter %s is not of type %T, is %T", p, zero, args[p])
|
|
}
|
|
|
|
return args[p].(T), nil
|
|
}
|
|
|
|
// OptionalIntParam is a helper function that can be used to fetch a requested parameter from the request.
|
|
// It does the following checks:
|
|
// 1. Checks if the parameter is present in the request, if not, it returns its zero-value
|
|
// 2. If it is present, it checks if the parameter is of the expected type and returns it
|
|
func OptionalIntParam(args map[string]any, p string) (int, error) {
|
|
v, err := OptionalParam[float64](args, p)
|
|
if err != nil {
|
|
return 0, err
|
|
}
|
|
return int(v), nil
|
|
}
|
|
|
|
// OptionalIntParamWithDefault is a helper function that can be used to fetch a requested parameter from the request
|
|
// similar to optionalIntParam, but it also takes a default value.
|
|
func OptionalIntParamWithDefault(args map[string]any, p string, d int) (int, error) {
|
|
v, err := OptionalIntParam(args, p)
|
|
if err != nil {
|
|
return 0, err
|
|
}
|
|
if v == 0 {
|
|
return d, nil
|
|
}
|
|
return v, nil
|
|
}
|
|
|
|
// OptionalBoolParamWithDefault is a helper function that can be used to fetch a requested parameter from the request
|
|
// similar to optionalBoolParam, but it also takes a default value.
|
|
func OptionalBoolParamWithDefault(args map[string]any, p string, d bool) (bool, error) {
|
|
_, ok := args[p]
|
|
v, err := OptionalParam[bool](args, p)
|
|
if err != nil {
|
|
return false, err
|
|
}
|
|
if !ok {
|
|
return d, nil
|
|
}
|
|
return v, nil
|
|
}
|
|
|
|
// OptionalStringArrayParam is a helper function that can be used to fetch a requested parameter from the request.
|
|
// It does the following checks:
|
|
// 1. Checks if the parameter is present in the request, if not, it returns its zero-value
|
|
// 2. If it is present, iterates the elements and checks each is a string
|
|
func OptionalStringArrayParam(args map[string]any, p string) ([]string, error) {
|
|
// Check if the parameter is present in the request
|
|
if _, ok := args[p]; !ok {
|
|
return []string{}, nil
|
|
}
|
|
|
|
switch v := args[p].(type) {
|
|
case nil:
|
|
return []string{}, nil
|
|
case []string:
|
|
return v, nil
|
|
case []any:
|
|
strSlice := make([]string, len(v))
|
|
for i, v := range v {
|
|
s, ok := v.(string)
|
|
if !ok {
|
|
return []string{}, fmt.Errorf("parameter %s is not of type string, is %T", p, v)
|
|
}
|
|
strSlice[i] = s
|
|
}
|
|
return strSlice, nil
|
|
default:
|
|
return []string{}, fmt.Errorf("parameter %s could not be coerced to []string, is %T", p, args[p])
|
|
}
|
|
}
|
|
|
|
func convertStringSliceToBigIntSlice(s []string) ([]int64, error) {
|
|
int64Slice := make([]int64, len(s))
|
|
for i, str := range s {
|
|
val, err := convertStringToBigInt(str, 0)
|
|
if err != nil {
|
|
return nil, fmt.Errorf("failed to convert element %d (%s) to int64: %w", i, str, err)
|
|
}
|
|
int64Slice[i] = val
|
|
}
|
|
return int64Slice, nil
|
|
}
|
|
|
|
func convertStringToBigInt(s string, def int64) (int64, error) {
|
|
v, err := strconv.ParseInt(s, 10, 64)
|
|
if err != nil {
|
|
return def, fmt.Errorf("failed to convert string %s to int64: %w", s, err)
|
|
}
|
|
return v, nil
|
|
}
|
|
|
|
// OptionalBigIntArrayParam is a helper function that can be used to fetch a requested parameter from the request.
|
|
// It does the following checks:
|
|
// 1. Checks if the parameter is present in the request, if not, it returns an empty slice
|
|
// 2. If it is present, iterates the elements, checks each is a string, and converts them to int64 values
|
|
func OptionalBigIntArrayParam(args map[string]any, p string) ([]int64, error) {
|
|
// Check if the parameter is present in the request
|
|
if _, ok := args[p]; !ok {
|
|
return []int64{}, nil
|
|
}
|
|
|
|
switch v := args[p].(type) {
|
|
case nil:
|
|
return []int64{}, nil
|
|
case []string:
|
|
return convertStringSliceToBigIntSlice(v)
|
|
case []any:
|
|
int64Slice := make([]int64, len(v))
|
|
for i, v := range v {
|
|
s, ok := v.(string)
|
|
if !ok {
|
|
return []int64{}, fmt.Errorf("parameter %s is not of type string, is %T", p, v)
|
|
}
|
|
val, err := convertStringToBigInt(s, 0)
|
|
if err != nil {
|
|
return []int64{}, fmt.Errorf("parameter %s: failed to convert element %d (%s) to int64: %w", p, i, s, err)
|
|
}
|
|
int64Slice[i] = val
|
|
}
|
|
return int64Slice, nil
|
|
default:
|
|
return []int64{}, fmt.Errorf("parameter %s could not be coerced to []int64, is %T", p, args[p])
|
|
}
|
|
}
|
|
|
|
// WithPagination adds REST API pagination parameters to a tool.
|
|
// https://docs.github.com/en/rest/using-the-rest-api/using-pagination-in-the-rest-api
|
|
func WithPagination(schema *jsonschema.Schema) *jsonschema.Schema {
|
|
schema.Properties["page"] = &jsonschema.Schema{
|
|
Type: "number",
|
|
Description: "Page number for pagination (min 1)",
|
|
Minimum: jsonschema.Ptr(1.0),
|
|
}
|
|
|
|
schema.Properties["perPage"] = &jsonschema.Schema{
|
|
Type: "number",
|
|
Description: "Results per page for pagination (min 1, max 100)",
|
|
Minimum: jsonschema.Ptr(1.0),
|
|
Maximum: jsonschema.Ptr(100.0),
|
|
}
|
|
|
|
return schema
|
|
}
|
|
|
|
// WithUnifiedPagination adds REST API pagination parameters to a tool.
|
|
// GraphQL tools will use this and convert page/perPage to GraphQL cursor parameters internally.
|
|
func WithUnifiedPagination(schema *jsonschema.Schema) *jsonschema.Schema {
|
|
schema.Properties["page"] = &jsonschema.Schema{
|
|
Type: "number",
|
|
Description: "Page number for pagination (min 1)",
|
|
Minimum: jsonschema.Ptr(1.0),
|
|
}
|
|
|
|
schema.Properties["perPage"] = &jsonschema.Schema{
|
|
Type: "number",
|
|
Description: "Results per page for pagination (min 1, max 100)",
|
|
Minimum: jsonschema.Ptr(1.0),
|
|
Maximum: jsonschema.Ptr(100.0),
|
|
}
|
|
|
|
schema.Properties["after"] = &jsonschema.Schema{
|
|
Type: "string",
|
|
Description: "Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs.",
|
|
}
|
|
|
|
return schema
|
|
}
|
|
|
|
// WithCursorPagination adds only cursor-based pagination parameters to a tool (no page parameter).
|
|
func WithCursorPagination(schema *jsonschema.Schema) *jsonschema.Schema {
|
|
schema.Properties["perPage"] = &jsonschema.Schema{
|
|
Type: "number",
|
|
Description: "Results per page for pagination (min 1, max 100)",
|
|
Minimum: jsonschema.Ptr(1.0),
|
|
Maximum: jsonschema.Ptr(100.0),
|
|
}
|
|
|
|
schema.Properties["after"] = &jsonschema.Schema{
|
|
Type: "string",
|
|
Description: "Cursor for pagination. Use the endCursor from the previous page's PageInfo for GraphQL APIs.",
|
|
}
|
|
|
|
return schema
|
|
}
|
|
|
|
type PaginationParams struct {
|
|
Page int
|
|
PerPage int
|
|
After string
|
|
}
|
|
|
|
// OptionalPaginationParams returns the "page", "perPage", and "after" parameters from the request,
|
|
// or their default values if not present, "page" default is 1, "perPage" default is 30.
|
|
// In future, we may want to make the default values configurable, or even have this
|
|
// function returned from `withPagination`, where the defaults are provided alongside
|
|
// the min/max values.
|
|
func OptionalPaginationParams(args map[string]any) (PaginationParams, error) {
|
|
page, err := OptionalIntParamWithDefault(args, "page", 1)
|
|
if err != nil {
|
|
return PaginationParams{}, err
|
|
}
|
|
perPage, err := OptionalIntParamWithDefault(args, "perPage", 30)
|
|
if err != nil {
|
|
return PaginationParams{}, err
|
|
}
|
|
after, err := OptionalParam[string](args, "after")
|
|
if err != nil {
|
|
return PaginationParams{}, err
|
|
}
|
|
return PaginationParams{
|
|
Page: page,
|
|
PerPage: perPage,
|
|
After: after,
|
|
}, nil
|
|
}
|
|
|
|
// OptionalCursorPaginationParams returns the "perPage" and "after" parameters from the request,
|
|
// without the "page" parameter, suitable for cursor-based pagination only.
|
|
func OptionalCursorPaginationParams(args map[string]any) (CursorPaginationParams, error) {
|
|
perPage, err := OptionalIntParamWithDefault(args, "perPage", 30)
|
|
if err != nil {
|
|
return CursorPaginationParams{}, err
|
|
}
|
|
after, err := OptionalParam[string](args, "after")
|
|
if err != nil {
|
|
return CursorPaginationParams{}, err
|
|
}
|
|
return CursorPaginationParams{
|
|
PerPage: perPage,
|
|
After: after,
|
|
}, nil
|
|
}
|
|
|
|
type CursorPaginationParams struct {
|
|
PerPage int
|
|
After string
|
|
}
|
|
|
|
// ToGraphQLParams converts cursor pagination parameters to GraphQL-specific parameters.
|
|
func (p CursorPaginationParams) ToGraphQLParams() (*GraphQLPaginationParams, error) {
|
|
if p.PerPage > 100 {
|
|
return nil, fmt.Errorf("perPage value %d exceeds maximum of 100", p.PerPage)
|
|
}
|
|
if p.PerPage < 0 {
|
|
return nil, fmt.Errorf("perPage value %d cannot be negative", p.PerPage)
|
|
}
|
|
first := int32(p.PerPage)
|
|
|
|
var after *string
|
|
if p.After != "" {
|
|
after = &p.After
|
|
}
|
|
|
|
return &GraphQLPaginationParams{
|
|
First: &first,
|
|
After: after,
|
|
}, nil
|
|
}
|
|
|
|
type GraphQLPaginationParams struct {
|
|
First *int32
|
|
After *string
|
|
}
|
|
|
|
// ToGraphQLParams converts REST API pagination parameters to GraphQL-specific parameters.
|
|
// This converts page/perPage to first parameter for GraphQL queries.
|
|
// If After is provided, it takes precedence over page-based pagination.
|
|
func (p PaginationParams) ToGraphQLParams() (*GraphQLPaginationParams, error) {
|
|
// Convert to CursorPaginationParams and delegate to avoid duplication
|
|
cursor := CursorPaginationParams{
|
|
PerPage: p.PerPage,
|
|
After: p.After,
|
|
}
|
|
return cursor.ToGraphQLParams()
|
|
}
|
|
|
|
func MarshalledTextResult(v any) *mcp.CallToolResult {
|
|
data, err := json.Marshal(v)
|
|
if err != nil {
|
|
return utils.NewToolResultErrorFromErr("failed to marshal text result to json", err)
|
|
}
|
|
|
|
return utils.NewToolResultText(string(data))
|
|
}
|