octocounts-mcp
by huanglizhuo
README.md
<p align="center">
<img src="images/favicon.png" alt="OctoCounts logo" width="64">
</p>
# OctoCounts – GitHub SLOC Counter
> GitHub shows language bars. OctoCounts shows the actual line counts.
[](https://chromewebstore.google.com/detail/octocounts-%E2%80%94-github-sloc/gkgjpjdnaklagijmekoolhcpebmoldbj)
[](https://microsoftedge.microsoft.com/addons/detail/octocounts-%E2%80%93-github-sloc-/ehifednhpbpekkadndaipnngopbhpoim)
[](https://addons.mozilla.org/en-US/firefox/addon/octocounts-github-sloc/)
[](https://octocounts.com/github/huanglizhuo/OctoCounts)
GitHub's sidebar shows language percentages, but misses actual file and line counts. OctoCounts adds this missing SLOC (Source Lines of Code) view to public repos without cloning.
Install the extension for stats directly on GitHub, or use the web app for public GitHub repositories. It downloads the repo archive, runs [tokei](https://github.com/XAMPPRocky/tokei), and caches the results without downloading Git history.
## Use OctoCounts
| Surface | Use it for |
|---|---|
| [Web app](https://octocounts.com/) | Analyze public GitHub repositories and share a live report or a fixed saved result. |
| [Browser extension](extension/README.md) | Show SLOC directly inside GitHub's repository sidebar in Chrome, Edge, or Firefox. |
| [Public stats](https://octocounts.com/stats) | See aggregate report totals, largest repos, language coverage, and source breakdown. |
| [GitHub Action](action/README.md) | Comment SLOC changes on pull requests. |
| [CLI](cli/README.md) | Run `npx octocounts https://github.com/owner/repo --json`. |
| [MCP server](mcp/README.md) | Give agents and developer assistants access to SLOC reports. |
| [README badges](#badges) | Add a live SLOC badge that links to the repository report page. |
| [Research](https://octocounts.com/research) | Original research: a 10-repository study of how test/doc/generated-file filtering affects SLOC counts. |
## Preview
<p align="center">
<img src="images/preview.png" alt="OctoCounts extension preview">
</p>
## Why?
Sometimes you just want to know whether a repo is 2k lines, 200k lines, or a weekend-devouring monolith. GitHub already has the repo, the language stats, and the sidebar. OctoCounts fills in the missing numbers.
## What it does
- Adds a browser extension card to GitHub repo pages with files, total lines, code, comments, blanks, and language count
- Provides a web app where you can paste any public GitHub repo URL
- Resolves any branch, tag, or commit SHA — pins results to an exact commit so the cache is actually meaningful
- Downloads the GitHub archive tarball instead of cloning, without Git history
- Counts files, lines, code, comments, and blanks per language via tokei
- Caches reports by repository, commit, tokei version, and analysis options — matching runs can reuse saved results
- Queues analysis jobs so concurrent requests don't bring the server to its knees
- Exports reports as plain text, JSON, or a shareable PNG card
Live repository links follow the latest cached public report. Fixed result links bind a saved report and commit, but saved records are subject to cache retention and may expire or be replaced; export JSON or text for long-term archival.
## Counting scope
Every OctoCounts surface — the web app, badges, the browser extension, the CLI, the MCP server, and the indexed public report pages — counts under one **default scope**: documentation, test, and generated files are **excluded** from the code count.
The exclusion is directory-based. Alongside the always-ignored build/VCS directories (`node_modules`, `target`, `dist`, `build`, `vendor`, …), the default scope drops these directories wherever they appear in the tree:
| Excluded | Directories |
|---|---|
| Docs | `doc`, `docs`, `documentation` |
| Tests | `test`, `tests`, `__tests__`, `fixtures` |
| Generated | `gen`, `generated`, `.generated` |
Know the boundaries of the rule:
- **It is a scope, not a purity claim.** Files that happen to live outside those directories still count — a root `README.md`, JSON lockfiles, and Rust `#[cfg(test)]` modules inline in source files are all included.
- **Opt back in explicitly.** The web app's analysis options (and the API's `includeDocs` / `includeTests` / `includeGenerated` toggles) count the whole repository when enabled; such runs produce a different measurement of the same repo and are pinned as their own saved results.
- **Reports state their scope.** Every report page names its counting scope next to the headline numbers, and the counting-policy section spells out the full effective rules for that specific run.
A 10-repository study of how this filtering moves SLOC counts is on the [research page](https://octocounts.com/research).
## Stack
| Layer | Tech |
|---|---|
| Backend | Rust · Axum · Tokio · SQLx · Postgres · tokei |
| Frontend | React · TypeScript · Vite · TanStack Query |
| Infra | Cloudflare Pages (Pages Functions SSR) · GHCR image + sloc-infra dual VPS (VPS-A/VPS-B) + Cloudflare Tunnel · Postgres on VPS-B (nightly backups to VPS-A) · Docker Compose (local dev only) |
## Badges
Drop a live SLOC badge into any README:
```markdown
<!-- Default branch — full SLOC summary -->
[](https://octocounts.com/github/:owner/:repo)
<!-- Specific branch -->
[](https://octocounts.com/github/:owner/:repo/tree/:branch)
<!-- Specific tag (pinned to that tag) -->
[](https://octocounts.com/github/:owner/:repo/tree/:tag)
<!-- Specific commit SHA (pinned to that commit) -->
[](https://octocounts.com/github/:owner/:repo/commit/:sha)
```
Add `?lang=<language>` to any of the above to get a per-language badge instead:
```markdown
<!-- Lines of code for a single language -->
[](https://octocounts.com/github/:owner/:repo)
[](https://octocounts.com/github/:owner/:repo/tree/:branch)
```
Language names are case-insensitive (`rust`, `Rust`, and `RUST` all work). If a language is not found in the report the badge shows `—`. While a fresh analysis is running the badge shows `···` — most badge CDNs will retry automatically.
| Cache behaviour | Header |
|---|---|
| Default branch / branch | `max-age=300, s-maxage=86400, stale-while-revalidate=3600` |
| Tag / commit | `max-age=300, s-maxage=604800` |
## API
```
POST /api/analyze { "repoUrl": "...", "refName": "main" }
GET /api/jobs/:id
GET /api/reports/:id
GET /api/stats
GET /badge/:owner/:repo
GET /badge/:owner/:repo/branch/:branch
GET /badge/:owner/:repo/tag/:tag
GET /badge/:owner/:repo/commit/:sha
```
All badge routes accept an optional `?lang=<language>` query parameter that switches the response from the full SLOC summary badge to a per-language shields.io-style badge.
## Running it
See **[how-to-run-and-deploy.md](docs/how-to-run-and-deploy.md)** for local development setup, host-native instructions, GitHub token configuration, and production deployment.
## Growth report inventory
Popular public repositories are listed in [`data/popular-repos.txt`](data/popular-repos.txt). The scheduled workflow [`seed-popular-repos.yml`](.github/workflows/seed-popular-repos.yml) refreshes that curated inventory weekly.
[`refresh-github-trending.yml`](.github/workflows/refresh-github-trending.yml) discovers GitHub's daily Trending repositories, validates and publishes the current snapshot to `/trending`, and pre-generates their stable `/github/:owner/:repo` SLOC reports. Trending provenance stays separate from real `/popular` access counts; no date-stamped archive pages are generated.
## License
[MIT](LICENSE)
TDQS
A3.5/5.0
Scored across 2 tools
Disambiguation5/5
analyze_repo targets a single repository, while compare_repos targets two repositories or refs. Their boundaries are clear and non-overlapping, so an agent can easily choose the right tool.
Naming Consistency5/5
Both tools follow a consistent verb_noun pattern: analyze_repo and compare_repos. Naming is predictable and uses snake_case throughout.
Tool Count3/5
Two tools is thin for most MCP servers, though this server has a narrow SLOC-counting purpose. The pair covers single-repo analysis and comparison, but feels minimal.
Completeness4/5
The core domain of SLOC totals and comparisons is covered by the two tools. Minor gaps exist around deeper breakdowns or output options, but agents can accomplish the primary workflows.
Maintenance
ActivityActive
ResponsivenessLimited data