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:maingithub_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:starsPriority 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/ |