API Reference - fleXRPL/github-mcp GitHub Wiki

API Reference

This document provides detailed information about the GitHub MCP Server API endpoints and tool definitions.

Base URL

All API endpoints are relative to the base URL:

http://localhost:8000

Authentication

The server uses githubauthlib for authentication, which retrieves GitHub tokens from the system keychain. No additional authentication headers are required for API requests.

Endpoints

GET /

Returns server information and available tools.

Response:

{
  "name": "github-mcp",
  "version": "0.1.0",
  "tools": [
    {
      "name": "tool_name",
      "description": "Tool description",
      "parameters": {
        "type": "object",
        "properties": {
          // Tool parameters schema
        }
      }
    }
  ]
}

POST /tool

Executes a tool call.

Request Body:

{
  "name": "tool_name",
  "parameters": {
    // Tool parameters
  }
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "JSON-formatted response data"
    }
  ]
}

GET /sse

Server-Sent Events endpoint for streaming responses.

Response:

event: ping
data: ""

event: tool_result
data: {
  "content": [
    {
      "type": "text",
      "text": "JSON-formatted response data"
    }
  ]
}

event: error
data: "Error message"

Tool Definitions

Repository Tools

list_repositories

Lists GitHub repositories accessible to the authenticated user.

Parameters:

{
  "type": "object",
  "properties": {
    "visibility": {
      "type": "string",
      "enum": ["all", "public", "private"],
      "default": "all"
    },
    "sort": {
      "type": "string",
      "enum": ["created", "updated", "pushed", "full_name"],
      "default": "updated"
    }
  }
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"name\": \"repo-name\", \"full_name\": \"owner/repo-name\", ...}]"
    }
  ]
}

get_repository

Gets information about a specific repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    }
  },
  "required": ["owner", "repo"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"name\": \"repo-name\", \"full_name\": \"owner/repo-name\", ...}"
    }
  ]
}

Issue Tools

list_issues

Lists issues in a repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "state": {
      "type": "string",
      "enum": ["open", "closed", "all"],
      "default": "open"
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Filter by labels"
    }
  },
  "required": ["owner", "repo"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"number\": 1, \"title\": \"Issue title\", ...}]"
    }
  ]
}

create_issue

Creates a new issue in a repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "title": {
      "type": "string",
      "description": "Issue title"
    },
    "body": {
      "type": "string",
      "description": "Issue description"
    },
    "labels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Issue labels"
    },
    "assignees": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Issue assignees"
    }
  },
  "required": ["owner", "repo", "title"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"number\": 1, \"title\": \"Issue title\", ...}"
    }
  ]
}

Pull Request Tools

list_pull_requests

Lists pull requests in a repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "state": {
      "type": "string",
      "enum": ["open", "closed", "all"],
      "default": "open"
    },
    "sort": {
      "type": "string",
      "enum": ["created", "updated", "popularity", "long-running"],
      "default": "created"
    }
  },
  "required": ["owner", "repo"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"number\": 1, \"title\": \"PR title\", ...}]"
    }
  ]
}

create_pull_request

Creates a new pull request.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "title": {
      "type": "string",
      "description": "Pull request title"
    },
    "body": {
      "type": "string",
      "description": "Pull request description"
    },
    "head": {
      "type": "string",
      "description": "Source branch"
    },
    "base": {
      "type": "string",
      "description": "Target branch",
      "default": "main"
    },
    "draft": {
      "type": "boolean",
      "description": "Create as draft",
      "default": false
    }
  },
  "required": ["owner", "repo", "title", "head"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"number\": 1, \"title\": \"PR title\", ...}"
    }
  ]
}

Content Tools

get_file_content

Gets the content of a file in a repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "path": {
      "type": "string",
      "description": "File path"
    },
    "ref": {
      "type": "string",
      "description": "Branch/tag/commit reference"
    }
  },
  "required": ["owner", "repo", "path"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "{\"name\": \"file.txt\", \"content\": \"file content\", ...}"
    }
  ]
}

list_directory

Lists contents of a directory in a repository.

Parameters:

{
  "type": "object",
  "properties": {
    "owner": {
      "type": "string",
      "description": "Repository owner"
    },
    "repo": {
      "type": "string",
      "description": "Repository name"
    },
    "path": {
      "type": "string",
      "description": "Directory path",
      "default": ""
    },
    "ref": {
      "type": "string",
      "description": "Branch/tag/commit reference"
    }
  },
  "required": ["owner", "repo"]
}

Response:

{
  "content": [
    {
      "type": "text",
      "text": "[{\"name\": \"file.txt\", \"type\": \"file\", ...}]"
    }
  ]
}

Error Handling

Error Response Format

{
  "detail": "Error message"
}

Common Error Codes

  • 400 Bad Request - Invalid parameters
  • 401 Unauthorized - Authentication failed
  • 403 Forbidden - Insufficient permissions
  • 404 Not Found - Resource not found
  • 429 Too Many Requests - Rate limit exceeded
  • 500 Internal Server Error - Server error

Rate Limiting

The server respects GitHub's API rate limits. Rate limit information is included in response headers:

X-RateLimit-Limit: 5000
X-RateLimit-Remaining: 4999
X-RateLimit-Reset: 1620000000

Best Practices

  1. Error Handling

    • Always check for error responses
    • Handle rate limiting appropriately
    • Implement retry logic for transient failures

  2. Performance

    • Use appropriate tool parameters
    • Cache responses when possible
    • Monitor rate limit usage

  3. Security

    • Keep GitHub tokens secure
    • Use appropriate repository permissions
    • Validate all input parameters

Examples

Python

import httpx

async def call_tool(tool_name: str, parameters: dict) -> dict:
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "http://localhost:8000/tool",
            json={
                "name": tool_name,
                "parameters": parameters
            }
        )
        response.raise_for_status()
        return response.json()

JavaScript

async function callTool(toolName, parameters) {
  const response = await fetch("http://localhost:8000/tool", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      name: toolName,
      parameters: parameters,
    }),
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

Related Documentation