git-repo-brief

An MCP (Model Context Protocol) server that generates structured briefs for public GitHub repositories. Get comprehensive repository information including overview, key files, release notes, and activity snapshots.

Features

• repo_overview: Get repository metadata (name, description, stars, forks, language, topics, license, timestamps)
• extract_key_files: Fetch contents of key files (README.md, LICENSE, package.json, pyproject.toml)
• release_notes: Get recent release notes with tag names, descriptions, and dates
• activity_snapshot: Get activity metrics (last commit, open issues/PRs, contributors count)

Installation

npm install
npm run build

Usage

As MCP Server (stdio mode)

# Run directly
npm start

# Or after building
node dist/cli.js

As HTTP Server

npm start -- --http
# or
HTTP_PORT=3001 node dist/cli.js --http

MCP Client Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "git-repo-brief": {
      "command": "node",
      "args": ["/path/to/git-repo-brief/dist/cli.js"]
    }
  }
}

Tools

repo_overview

Get a comprehensive overview of a GitHub repository.

Input:

{
  "repo_url": "https://github.com/owner/repo"
}

Output:

{
  "ok": true,
  "data": {
    "name": "repo",
    "full_name": "owner/repo",
    "description": "Repository description",
    "stars": 1234,
    "forks": 567,
    "language": "TypeScript",
    "topics": ["mcp", "github"],
    "license": "MIT",
    "created_at": "2023-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z",
    "default_branch": "main",
    "homepage": "https://example.com",
    "owner": {
      "login": "owner",
      "avatar_url": "https://github.com/owner.png",
      "type": "User"
    }
  },
  "meta": {
    "source": "https://api.github.com/repos/owner/repo",
    "retrieved_at": "2024-01-15T10:00:00Z",
    "pagination": { "next_cursor": null },
    "warnings": []
  }
}

extract_key_files

Fetch contents of key files from a repository.

Input:

{
  "repo_url": "https://github.com/owner/repo",
  "paths": ["README.md", "package.json"]
}

Output:

{
  "ok": true,
  "data": {
    "files": [
      {
        "path": "README.md",
        "content": "# Project\n\nDescription...",
        "size": 1234,
        "encoding": "utf-8"
      },
      {
        "path": "package.json",
        "content": "{\"name\": \"project\"}",
        "size": 456,
        "encoding": "utf-8"
      }
    ],
    "default_branch": "main"
  },
  "meta": {
    "retrieved_at": "2024-01-15T10:00:00Z",
    "warnings": []
  }
}

release_notes

Get recent release notes from a repository.

Input:

{
  "repo_url": "https://github.com/owner/repo",
  "limit": 5
}

Output:

{
  "ok": true,
  "data": {
    "releases": [
      {
        "tag_name": "v1.0.0",
        "name": "Version 1.0.0",
        "body": "## Changes\n- Feature A\n- Bug fix B",
        "published_at": "2024-01-01T00:00:00Z",
        "prerelease": false,
        "draft": false,
        "html_url": "https://github.com/owner/repo/releases/tag/v1.0.0"
      }
    ],
    "total_count": 1
  },
  "meta": {
    "retrieved_at": "2024-01-15T10:00:00Z",
    "pagination": { "next_cursor": null },
    "warnings": []
  }
}

activity_snapshot

Get a snapshot of recent repository activity.

Input:

{
  "repo_url": "https://github.com/owner/repo"
}

Output:

{
  "ok": true,
  "data": {
    "last_commit_date": "2024-01-14T15:30:00Z",
    "last_commit_message": "fix: resolve parsing issue",
    "open_issues_count": 25,
    "open_prs_count": 8,
    "contributors_count": 42,
    "watchers_count": 100,
    "has_wiki": true,
    "has_discussions": true
  },
  "meta": {
    "retrieved_at": "2024-01-15T10:00:00Z",
    "warnings": []
  }
}

HTTP API Endpoints

When running in HTTP mode:

• GET /health - Health check
• GET /tools - List available tools
• POST /tools/repo_overview - Get repository overview
• POST /tools/extract_key_files - Extract key files
• POST /tools/release_notes - Get release notes
• POST /tools/activity_snapshot - Get activity snapshot

Example HTTP Request

curl -X POST http://localhost:3000/tools/repo_overview \
  -H "Content-Type: application/json" \
  -d '{"repo_url": "https://github.com/microsoft/vscode"}'

Configuration

Environment Variables

Variable	Default	Description
GITHUB_TOKEN	-	GitHub personal access token (optional, increases rate limit from 60 to 5000 req/hour)
REQUEST_DELAY_MS	100	Delay between requests for rate limiting
REQUEST_TIMEOUT_MS	30000	Request timeout in milliseconds
TRANSPORT_MODE	stdio	Transport mode: stdio or http
HTTP_PORT	3000	HTTP server port (when using HTTP transport)

Rate Limiting

The server implements polite rate limiting:

• Default delay of 100ms between requests
• Handles GitHub API rate limit responses gracefully
• Optional GitHub token support for higher rate limits

Response Format

All responses follow the standard envelope format:

Success Response

{
  "ok": true,
  "data": { ... },
  "meta": {
    "source": "optional API URL",
    "retrieved_at": "ISO-8601 timestamp",
    "pagination": { "next_cursor": null },
    "warnings": []
  }
}

Error Response

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT | UPSTREAM_ERROR | RATE_LIMITED | TIMEOUT | PARSE_ERROR | INTERNAL_ERROR",
    "message": "Human readable message",
    "details": { ... }
  },
  "meta": {
    "retrieved_at": "ISO-8601 timestamp"
  }
}

Development

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Type check
npm run typecheck

# Build
npm run build

Testing

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

License

MIT