GitHub Tools Reference

# GitHub Tools Reference

Quick reference for the GitHub MCP tools for searching Algorand code examples.

## Tools

| Tool | Purpose |
|------|---------|
| `github_get_file_contents` | Read files or list directories |
| `github_search_code` | Search for code patterns |
| `github_search_repositories` | Find repositories |

## github_get_file_contents

Retrieve file contents or list directory entries from a GitHub repository.

**Parameters:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `owner` | Yes | Repository owner (e.g., `algorandfoundation`) |
| `repo` | Yes | Repository name (e.g., `puya-ts`) |
| `path` | No | Path to file or directory (default: root) |
| `ref` | No | Git ref (branch, tag, or commit SHA) |

**Examples:**

```
# Get a specific file
github_get_file_contents owner:algorandfoundation repo:puya-ts path:examples/voting/contract.algo.ts

# List directory contents
github_get_file_contents owner:algorandfoundation repo:puya-ts path:examples

# List repo root
github_get_file_contents owner:algorandfoundation repo:devportal-code-examples

# Get file from specific branch
github_get_file_contents owner:algorandfoundation repo:puya-ts path:README.md ref:main
```

## github_search_code

Search for code patterns across GitHub repositories.

**Parameters:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search query (GitHub code search syntax) |
| `sort` | No | Sort field (`indexed` only) |
| `order` | No | Sort order (`asc` or `desc`) |
| `page` | No | Page number (default: 1) |
| `perPage` | No | Results per page (max 100, default: 30) |

**Query Syntax:**

| Qualifier | Example | Description |
|-----------|---------|-------------|
| `org:` | `org:algorandfoundation` | Search within organization |
| `repo:` | `repo:algorandfoundation/puya-ts` | Search specific repo |
| `language:` | `language:typescript` | Filter by language |
| `path:` | `path:examples/` | Filter by file path |
| `extension:` | `extension:ts` | Filter by file extension |

**Examples:**

```
# Search for BoxMap usage in TypeScript
github_search_code query:"BoxMap org:algorandfoundation language:typescript"

# Search for inner transactions
github_search_code query:"itxn org:algorandfoundation language:typescript"

# Search in specific repo
github_search_code query:"GlobalState repo:algorandfoundation/puya-ts"

# Search for ARC-4 implementations
github_search_code query:"arc4 abimethod org:algorandfoundation"
```

## github_search_repositories

Find repositories by name, description, topics, or other criteria.

**Parameters:**

| Parameter | Required | Description |
|-----------|----------|-------------|
| `query` | Yes | Search query (GitHub repo search syntax) |
| `sort` | No | Sort by: `stars`, `forks`, `help-wanted-issues`, `updated` |
| `order` | No | Sort order (`asc` or `desc`) |
| `page` | No | Page number (default: 1) |
| `perPage` | No | Results per page (max 100, default: 30) |

**Query Syntax:**

| Qualifier | Example | Description |
|-----------|---------|-------------|
| `topic:` | `topic:algorand` | Filter by topic |
| `language:` | `language:typescript` | Filter by primary language |
| `org:` | `org:algorandfoundation` | Filter by organization |
| `stars:` | `stars:>100` | Filter by star count |

**Examples:**

```
# Find Algorand repos by topic
github_search_repositories query:"topic:algorand language:typescript"

# Find NFT-related Algorand projects
github_search_repositories query:"algorand nft" sort:stars order:desc

# Find repos in algorandfoundation
github_search_repositories query:"org:algorandfoundation smart-contract"

# Find popular Algorand repos
github_search_repositories query:"topic:algorand stars:>50" sort:stars
```

## Priority Repositories

| Repository | Path | Content |
|------------|------|---------|
| `devportal-code-examples` | `projects/typescript-examples/contracts/` | Beginner TypeScript |
| `devportal-code-examples` | `projects/python-examples/smart_contracts/` | Beginner Python |
| `puya-ts` | `examples/` | Advanced TypeScript (voting, amm, auction) |
| `puya` | `examples/` | Advanced Python |
| `algokit-typescript-template` | `/` | Project template |
| `algokit-utils-ts` | `src/` | Utility library |

## Common Patterns Location

| Pattern | Repository | Path |
|---------|------------|------|
| Box storage | devportal-code-examples | `contracts/BoxStorage/` |
| BoxMap | puya-ts | `examples/voting/`, `examples/amm/` |
| Inner transactions | devportal-code-examples | `contracts/` |
| ARC-4 methods | puya-ts | `examples/hello_world_arc4/` |
| State management | devportal-code-examples | `contracts/` |