# API Reference
This document provides a complete reference for the GitHub MCP Control Plane API.
## Overview
The GitHub MCP Control Plane implements the Model Context Protocol (MCP) specification. All requests follow the JSON-RPC 2.0 format.
### Base URL
```
https://your-worker-url.workers.dev
```
### Request Format
All requests must be POST requests with `Content-Type: application/json`:
```json
{
"jsonrpc": "2.0",
"id": "request-id",
"method": "tool_name",
"params": {
// Tool-specific parameters
}
}
```
### Response Format
Successful responses:
```json
{
"jsonrpc": "2.0",
"id": "request-id",
"result": {
// Tool-specific result
}
}
```
Error responses:
```json
{
"jsonrpc": "2.0",
"id": "request-id",
"error": {
"code": -32602,
"message": "Invalid params",
"data": {
// Error details
}
}
}
```
## Authentication
All requests must include an `Authorization` header:
```
Authorization: Bearer <token>
```
or
```
Authorization: token <token>
```
### Token Types
1. **GitHub Personal Access Token** - Direct GitHub token
2. **JWT Token** - Encoded JWT containing GitHub token and user info
## Read-Only Tools
### list_repositories
List repositories accessible to the authenticated user.
**Method**: `list_repositories`
**Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| perPage | integer | No | 30 | Number of repositories per page (1-100) |
| page | integer | No | 1 | Page number |
| visibility | string | No | all | Filter by visibility: `all`, `public`, `private` |
| type | string | No | all | Filter by type: `all`, `owner`, `member` |
**Response**:
```json
{
"repositories": [
{
"id": 123456,
"name": "example-repo",
"fullName": "user/example-repo",
"owner": "user",
"private": false,
"description": "Example repository",
"language": "JavaScript",
"url": "https://github.com/user/example-repo",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-02T00:00:00Z"
}
],
"totalCount": 10,
"page": 1,
"perPage": 30
}
```
### fetch_file
Fetch file contents from a repository.
**Method**: `fetch_file`
**Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| owner | string | Yes | Repository owner |
| repo | string | Yes | Repository name |
| path | string | Yes | File path |
| ref | string | No | Branch, tag, or commit SHA |
**Response**:
```json
{
"name": "README.md",
"path": "README.md",
"size": 1024,
"sha": "abc123...",
"content": "File contents here",
"encoding": "utf-8",
"type": "file",
"url": "https://github.com/user/repo/blob/main/README.md"
}
```
### list_files
List files in a directory.
**Method**: `list_files`
**Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| owner | string | Yes | | Repository owner |
| repo | string | Yes | | Repository name |
| path | string | No | "" | Directory path |
| ref | string | No | | Branch, tag, or commit SHA |
**Response**:
```json
{
"files": [
{
"name": "README.md",
"path": "README.md",
"type": "file",
"size": 1024,
"sha": "abc123...",
"url": "https://github.com/user/repo/blob/main/README.md"
}
],
"count": 1
}
```
### get_repository_info
Get repository metadata.
**Method**: `get_repository_info`
**Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| owner | string | Yes | Repository owner |
| repo | string | Yes | Repository name |
**Response**:
```json
{
"id": 123456,
"name": "example-repo",
"fullName": "user/example-repo",
"owner": {
"login": "user",
"type": "User"
},
"private": false,
"description": "Example repository",
"language": "JavaScript",
"defaultBranch": "main",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-02T00:00:00Z",
"pushedAt": "2024-01-03T00:00:00Z",
"size": 1024,
"stars": 10,
"watchers": 5,
"forks": 2,
"openIssues": 3,
"url": "https://github.com/user/example-repo",
"cloneUrl": "https://github.com/user/example-repo.git",
"permissions": {
"admin": false,
"push": true,
"pull": true
}
}
```
## Write-Controlled Tools
### create_branch
Create a new branch from an existing branch.
**Method**: `create_branch`
**Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| owner | string | Yes | | Repository owner |
| repo | string | Yes | | Repository name |
| branch | string | Yes | | New branch name |
| fromBranch | string | No | main | Source branch |
**Response**:
```json
{
"branch": "feature/test",
"ref": "refs/heads/feature/test",
"sha": "def456...",
"url": "https://api.github.com/repos/user/repo/git/refs/heads/feature/test"
}
```
### create_commit
Create a commit with file changes.
**Method**: `create_commit`
**Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| owner | string | Yes | Repository owner |
| repo | string | Yes | Repository name |
| branch | string | Yes | Branch name |
| files | array | Yes | Array of file objects |
| message | string | Yes | Commit message (max 1000 chars) |
**File Object**:
```json
{
"path": "path/to/file.txt",
"content": "File contents"
}
```
**Response**:
```json
{
"sha": "ghi789...",
"message": "Test commit",
"tree": "jkl012...",
"parent": "abc123...",
"url": "https://github.com/user/repo/commit/ghi789..."
}
```
### batch_create_commits
Create commits with 100+ files in batches.
**Method**: `batch_create_commits`
**Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| owner | string | Yes | | Repository owner |
| repo | string | Yes | | Repository name |
| branch | string | Yes | | Branch name |
| files | array | Yes | | Array of file objects |
| message | string | Yes | | Commit message |
| batchSize | integer | No | 50 | Files per batch (1-100) |
**Response**:
```json
{
"totalBatches": 3,
"successfulBatches": 3,
"failedBatches": 0,
"totalFiles": 150,
"processedFiles": 150,
"commits": [
{
"sha": "abc123...",
"message": "Test commit (batch 1/3)",
"tree": "def456...",
"parent": "ghi789...",
"batchNumber": 1,
"filesProcessed": 50,
"url": "https://github.com/user/repo/commit/abc123..."
}
],
"errors": [],
"finalSha": "xyz999...",
"initialSha": "ghi789..."
}
```
## Workflow Tools
### trigger_workflow
Trigger a GitHub Actions workflow.
**Method**: `trigger_workflow`
**Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| owner | string | Yes | | Repository owner |
| repo | string | Yes | | Repository name |
| workflowId | string | Yes | | Workflow ID or filename |
| ref | string | No | main | Branch to run on |
| inputs | object | No | | Workflow inputs |
**Response**:
```json
{
"success": true,
"workflowId": "test.yml",
"ref": "main",
"runId": 123456789,
"runNumber": 42,
"status": "queued",
"conclusion": null,
"url": "https://github.com/user/repo/actions/runs/123456789"
}
```
### get_workflow_status
Get status of a workflow run.
**Method**: `get_workflow_status`
**Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| owner | string | Yes | Repository owner |
| repo | string | Yes | Repository name |
| runId | integer | Yes | Workflow run ID |
**Response**:
```json
{
"id": 123456789,
"runNumber": 42,
"name": "Test Workflow",
"status": "completed",
"conclusion": "success",
"workflowId": 123456,
"url": "https://github.com/user/repo/actions/runs/123456789",
"createdAt": "2024-01-01T00:00:00Z",
"updatedAt": "2024-01-01T00:05:00Z",
"startedAt": "2024-01-01T00:00:30Z",
"completedAt": "2024-01-01T00:05:00Z",
"event": "workflow_dispatch",
"actor": {
"login": "user",
"type": "User"
},
"headBranch": "main",
"headSha": "abc123...",
"repository": {
"name": "repo",
"fullName": "user/repo"
}
}
```
### get_workflow_logs
Get logs from a workflow run.
**Method**: `get_workflow_logs`
**Parameters**:
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| owner | string | Yes | Repository owner |
| repo | string | Yes | Repository name |
| runId | integer | Yes | Workflow run ID |
**Response**:
```json
{
"runId": 123456789,
"size": 10240,
"type": "application/zip",
"message": "Logs are available as a zip file",
"url": "https://api.github.com/repos/user/repo/actions/runs/123456789/logs"
}
```
## Error Codes
| Code | Name | Description |
|------|------|-------------|
| -32700 | Parse error | Invalid JSON |
| -32600 | Invalid Request | Invalid JSON-RPC request |
| -32601 | Method not found | Tool does not exist |
| -32602 | Invalid params | Invalid parameters |
| -32603 | Internal error | Internal server error |
## Rate Limiting
The API implements rate limiting to prevent abuse:
- Default: 100 requests per 60 seconds per IP
- Rate limit headers included in responses:
- `X-RateLimit-Limit`: Maximum requests
- `X-RateLimit-Remaining`: Remaining requests
- `X-RateLimit-Reset`: Unix timestamp of reset
Exceeding rate limits returns:
```json
{
"error": {
"code": -32603,
"message": "Rate limit exceeded",
"data": {
"retryAfter": 30
}
}
}
```
## Health Check
Check worker health:
```bash
GET /health
```
Response:
```json
{
"status": "healthy",
"timestamp": "2024-01-01T00:00:00Z",
"version": "1.0.0"
}
```
