GitHub Repository Health MCP

A real-time GitHub repository health assistant built with the Model Context Protocol, LangChain 1.x, and Groq.

The agent can summarize repository activity, open issues, recent commits, and GitHub Actions workflow health using live GitHub API data.

Project Structure

MCP-Project1/
├── src/
│   └── github_repo_health/
│       ├── __init__.py       # Package metadata
│       ├── config.py         # Environment-backed settings
│       ├── github_api.py      # GitHub REST client and data shaping
│       ├── mcp_server.py     # MCP tools, resources, and prompts
│       └── agent.py           # LangChain + Groq application client
├── tests/
│   └── test_github_api.py    # Fast unit tests for API helpers
├── .env.example              # Configuration template
├── pyproject.toml            # Dependencies and console entry points
├── uv.lock                   # Reproducible dependency lockfile
└── README.md

The separation keeps responsibilities small:

• github_api.py knows how to call GitHub.

• mcp_server.py exposes GitHub capabilities through MCP.

• agent.py decides whether to use MCP or call Groq directly.

• tests/ verifies pure helper behavior without network calls.

Related MCP server: GitHub Health Monitor MCP

MCP Capabilities

Tools

Resources

Prompts

The first version is read-only. It does not create, modify, close, or label GitHub issues.

Setup

Install dependencies:

uv sync

Create local configuration:

Copy-Item .env.example .env

Set these values in .env:

GROQ_API_KEY=your-groq-api-key
GROQ_MODEL=openai/gpt-oss-120b
GITHUB_OWNER=chetangpande-ai
GITHUB_REPO=GitHubReposHealth-MCP
GITHUB_TOKEN=your-github-token

GITHUB_TOKEN is optional for public repositories but recommended for a higher GitHub API rate limit. Never commit .env.

Run The Agent

The installed console command starts the LangChain agent:

uv run github-health-agent "Is this repository healthy?"
uv run github-health-agent "What are the most important open issues?"
uv run github-health-agent "Did the latest workflow pass?"
uv run github-health-agent "Prepare a release-readiness report."

You can also run it as a module:

uv run python -m github_repo_health.agent "Summarize recent activity."

To run only the MCP server for an MCP host such as Claude Desktop:

uv run github-health-mcp

The MCP server is normally started automatically by the LangChain client over stdio.

The current repository target is configured through GITHUB_OWNER and GITHUB_REPO; change those values to analyze a different repository without changing the code.

Agent Flow

For a repository question:

1. agent.py identifies the request as GitHub-related.

2. It starts github_repo_health.mcp_server over stdio.

3. The MCP adapter discovers tools and reads the health resource.

4. The client loads daily_health_report or triage_open_issues.

5. Groq decides which live GitHub tools to call.

6. github_api.py calls GitHub and returns shaped data.

7. Groq summarizes the results into the final answer.

For unrelated questions, the agent calls Groq directly without starting the MCP server.

Logs

Logs go to stderr and the final answer goes to stdout. GitHub requests show entries such as:

Starting MCP server: github_repo_health.mcp_server
Invoking MCP server: list tools
Invoking MCP server: read resource github://repository/owner/repo/health
Invoking MCP server: get prompt daily_health_report
Invoking LLM: Groq model=openai/gpt-oss-120b
Invoking MCP tool: get_workflow_runs input=...
MCP tool returned: get_workflow_runs
LLM response received

Direct questions show Invoking LLM directly instead.

Tests

Run the fast local tests:

uv run python -m unittest discover -s tests -v

The tests do not call GitHub or Groq, so they are safe to run without API keys.