🌐 Integrating with a REST API

The repository listing tool uses the library httpx to make asynchronous requests to the GitHub API. The essential code:

@server.tool()
async def list_repos(visibility: str = "all") -> str:
    """Lista repositórios do usuário autenticado."""
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            "https://api.github.com/user/repos",
            headers={"Authorization": f"Bearer {GITHUB_TOKEN}"},
            params={"visibility": visibility, "sort": "updated"}
        )
        repos = resp.json()
    lines = []
    for r in repos:
        stars = r["stargazers_count"]
        lang = r.get("language", "N/A")
        lines.append(f"⭐ {stars} | {r['name']} ({lang}) — {r.get('description', 'Sem descrição')}")
    return "\n".join(lines)

The issue search tool receives owner (repository owner), repo (repository name) and optional parameters such as state (open/closed/all) and labels (filter by labels). The endpoint returns a JSON array where each issue contains: number, title, user.login, state, labels[] e created_at. Format the output with the number, title, author, and labels to make it easier to read.

The issue creation tool sends a POST with a JSON body containing title (required) and body (description, optional but recommended). Validate that the title is not empty and has a reasonable length. After creating it, return the URL of the created issue so the user can access it directly:

@server.tool()
async def create_issue(owner: str, repo: str, title: str, body: str = "") -> str:
    """Cria uma nova issue em um repositório GitHub."""
    if not title.strip():
        return "Erro: o título da issue não pode ser vazio."
    async with httpx.AsyncClient() as client:
        resp = await client.post(
            f"https://api.github.com/repos/{owner}/{repo}/issues",
            headers={"Authorization": f"Bearer {GITHUB_TOKEN}"},
            json={"title": title, "body": body}
        )
    if resp.status_code == 201:
        issue = resp.json()
        return f"Issue criada com sucesso! #{issue['number']}: {issue['html_url']}"
    return f"Erro ao criar issue: {resp.status_code}"

Test with these prompts in Claude Desktop:

• →"List my repositories" — should call list_repos and display name, language, stars
• →"Which issues are open in repo X?" — should call search_issues with state=open
• →"Create an issue in repo Y with title Z" — should call create_issue and return the URL
• →"Which private repos do I have?" — should call list_repos with visibility=private