# Git.Top [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/haocn-ops/git-top  
**GitHub Stars:** 0  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/git-top

## Description
Evidence-backed open-source project search, recommendations, alternatives, and comparisons.

## Claude Desktop Quick Installation
Remote MCP endpoint (confidence: high). Install path detected from listing signals. Add as a URL/SSE server in your client:

```json
"mcpServers": {
  "git-top": {
    "url": "https://git.top"
  }
}
```

## Documentation & README

# Git.Top

The Knowledge Graph of Open Source.

GitHub provides code. Git.Top provides knowledge.

Git.Top turns unstructured GitHub repository data into structured project knowledge that humans and AI agents can search, compare, recommend, score, and call through REST APIs or MCP tools.

The Cloudflare Worker is the only product surface. It serves the human HTML pages, REST APIs, MCP endpoint, GitHub sync, and D1-backed knowledge data.

Production: [git.top](https://git.top)

Repository: [github.com/haocn-ops/git-top](https://github.com/haocn-ops/git-top)

## Connect An Agent

Use the focused MCP profile for the shortest first connection:

```sh
codex mcp add git-top --url https://git.top/mcp/core
claude mcp add --transport http --scope user git-top https://git.top/mcp/core
```

Then ask your agent:

```text
Use Git.Top to recommend three open-source browser-agent projects for Docker, then cite the data source and one caveat for each.
```

Full setup, client status, and REST alternatives: [git.top/connect](https://git.top/connect).

Dated compatibility evidence and the distinction between configuration verification and real-client support: [git.top/compatibility](https://git.top/compatibility).

Registry-ready copy, profiles, privacy boundaries, campaign links, and submission status: [git.top/distribution.json](https://git.top/distribution.json). An installable REST-first Agent Skill is available at [`skills/git-top-project-selection`](https://github.com/haocn-ops/git-top/blob/HEAD/skills/git-top-project-selection/).

## What Git.Top Does

- Discover open-source AI projects by category, deployment target, and use case.
- Compare projects with decision summaries, ranking signals, and tradeoffs.
- Find alternatives with similarity signals and comparison-ready shortlists.
- Explore project relationships across alternatives, related projects, dependencies, deployments, and use cases.
- Explain Git.Top Score, Agent Score, quality signals, risk flags, and evidence.
- Serve agent-native REST, OpenAPI, `llms.txt`, `llms-full.txt`, and MCP surfaces.

## Product Surfaces

- `/discover` - browse AI agents, MCP servers, RAG, browser automation, and AI IDE projects.
- `/recommend` - turn use cases and constraints into explainable project shortlists.
- `/compare` - compare project shortlists.
- `/alternatives` and `/alternatives/:project` - find replacement candidates.
- `/graph/:project` - inspect project knowledge graphs.
- `/score/:project` - explain project score dimensions.
- `/atlas` - explore ecosystem maps.
- `/api/*` - consume structured knowledge.
- `/mcp` - connect agents through MCP.
- `/mcp/core` - connect a focused five-tool MCP profile for first-time use.

## Architecture

```text
GitHub API
  -> Git.Top ETL
  -> Cloudflare D1
  -> Worker pages, REST APIs, MCP tools, sync jobs, and quality gates
```

The project intentionally does not ship a separate Next.js app. Keeping Worker-rendered pages, APIs, sync, D1 access, OpenAPI, and MCP in one runtime avoids split product behavior.

## Documentation

- [Coding agent guide](https://github.com/haocn-ops/git-top/blob/HEAD/AGENTS.md)
- [AI agent adoption and distribution plan 2026-07-31](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AI_AGENT_ADOPTION_AND_DISTRIBUTION_PLAN_2026-07-31.md)
- [Agent client compatibility](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AGENT_CLIENT_COMPATIBILITY.md)
- [Agent distribution package](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AGENT_DISTRIBUTION_PACKAGE.md)
- [Agent-native assessment and optimization plan](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AGENT_NATIVE_ASSESSMENT_AND_OPTIMIZATION_PLAN.md)
- [Competitive analysis and 90-day optimization plan 2026-09-02](https://github.com/haocn-ops/git-top/blob/HEAD/docs/COMPETITIVE_ANALYSIS_AND_90_DAY_OPTIMIZATION_PLAN_2026-09-02.md)
- [Agent function test and improvement plan 2026-07-30](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AGENT_FUNCTION_TEST_AND_IMPROVEMENT_PLAN_2026-07-30.md)
- [Production freshness optimization plan 2026-07-14](https://github.com/haocn-ops/git-top/blob/HEAD/docs/PRODUCTION_FRESHNESS_OPTIMIZATION_PLAN_2026-07-14.md)
- [Site assessment and improvement plan 2026-07-12](https://github.com/haocn-ops/git-top/blob/HEAD/docs/SITE_ASSESSMENT_AND_IMPROVEMENT_PLAN_2026-07-12.md)
- [Automated operations and agent friendliness plan 2026-07-12](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AUTOMATED_OPERATIONS_AND_AGENT_FRIENDLINESS_PLAN_2026-07-12.md)
- [Agent task evaluation](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AGENT_TASK_EVAL.md)
- [Agent-native optimization implementation report](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AGENT_NATIVE_OPTIMIZATION_IMPLEMENTATION_REPORT.md)
- [Agent-native optimization PR summary](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AGENT_NATIVE_OPTIMIZATION_PR_SUMMARY.md)
- [Git.Top 2.0 product upgrade plan](https://github.com/haocn-ops/git-top/blob/HEAD/docs/GIT_TOP_2_PRODUCT_UPGRADE_PLAN.md)
- [Next stage plan](https://github.com/haocn-ops/git-top/blob/HEAD/docs/NEXT_STAGE_PLAN.md)
- [Agent friendliness optimization plan](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AGENT_FRIENDLINESS_OPTIMIZATION_PLAN_2026-06-29.md)
- [Deployment decision](https://github.com/haocn-ops/git-top/blob/HEAD/docs/DEPLOYMENT_DECISION.md)
- [REST API guide](https://github.com/haocn-ops/git-top/blob/HEAD/docs/API.md)
- [MCP guide](https://github.com/haocn-ops/git-top/blob/HEAD/docs/MCP.md)
- [MCP tool behavior examples](https://github.com/haocn-ops/git-top/blob/HEAD/docs/MCP_TOOL_BEHAVIOR_EXAMPLES.md)
- [MCP conformance matrix](https://github.com/haocn-ops/git-top/blob/HEAD/docs/MCP_CONFORMANCE_MATRIX.md)
- [SDK-oriented examples](https://github.com/haocn-ops/git-top/blob/HEAD/docs/SDK_EXAMPLES.md)
- [Adoption analytics runbook](https://github.com/haocn-ops/git-top/blob/HEAD/docs/ADOPTION_ANALYTICS_RUNBOOK.md)
- [GRP examples](https://github.com/haocn-ops/git-top/blob/HEAD/docs/GRP_EXAMPLES.md)
- [Agent quickstart](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AGENT_QUICKSTART.md)
- [MailAgents agent workflow article](https://github.com/haocn-ops/git-top/blob/HEAD/docs/MAILAGENTS_AGENT_WORKFLOW.md)
- [Site assessment 2026-06-21](https://github.com/haocn-ops/git-top/blob/HEAD/docs/SITE_ASSESSMENT_2026-06-21.md)
- [Production runbook](https://github.com/haocn-ops/git-top/blob/HEAD/docs/PRODUCTION_RUNBOOK.md)
- [Operations and data governance plan](https://github.com/haocn-ops/git-top/blob/HEAD/docs/OPERATIONS_DATA_GOVERNANCE_PLAN.md)
- Public trust benchmark: `/benchmark` and `/api/benchmark`
- [Data coverage report](https://github.com/haocn-ops/git-top/blob/HEAD/docs/DATA_COVERAGE.md)
- [Seed live check report](https://github.com/haocn-ops/git-top/blob/HEAD/docs/SEED_LIVE_CHECK.md)
- [Eval quality report](https://github.com/haocn-ops/git-top/blob/HEAD/docs/EVAL_QUALITY.md)
- [Local eval report](https://github.com/haocn-ops/git-top/blob/HEAD/docs/EVAL_LOCAL.md)
- [Ranking experiments](https://github.com/haocn-ops/git-top/blob/HEAD/docs/RANKING_EXPERIMENTS.md)
- [Quality hardening plan](https://github.com/haocn-ops/git-top/blob/HEAD/docs/QUALITY_HARDENING_PLAN.md)
- [Post-V1 improvement plan](https://github.com/haocn-ops/git-top/blob/HEAD/docs/POST_V1_IMPROVEMENT_PLAN.md)
- [Contributing](https://github.com/haocn-ops/git-top/blob/HEAD/CONTRIBUTING.md)
- [Security](https://github.com/haocn-ops/git-top/blob/HEAD/SECURITY.md)
- [License](https://github.com/haocn-ops/git-top/blob/HEAD/LICENSE)

## Development

For maintenance agents, start with [AGENTS.md](https://github.com/haocn-ops/git-top/blob/HEAD/AGENTS.md). It summarizes the runtime, high-risk areas, generated data, and validation tiers.

Fast checks:

```sh
pnpm docs:validate
pnpm check
```

Agent surface checks:

```sh
pnpm api:validate
pnpm mcp:validate
pnpm eval:explanations
pnpm check
```

Data and local D1 checks:

```sh
pnpm db:execute
pnpm db:seed
pnpm db:integration
```

Release checks:

```sh
pnpm validate
pnpm release:check
```

Common development commands:

```sh
pnpm install
pnpm db:execute
pnpm db:seed
pnpm seed:validate
pnpm seed:coverage
pnpm seed:candidates
pnpm seed:live-check -- --limit 20
pnpm seed:live-check -- --offset 20 --limit 20
node scripts/run-governance-task.mjs daily-production-health
pnpm knowledge:validate
pnpm db:seed-sql
pnpm db:validate
pnpm db:integration
pnpm core:validate
pnpm api:validate
pnpm mcp:validate
pnpm eval:quality
pnpm eval:explanations
pnpm eval:local
pnpm eval:ranking
pnpm eval:agent-tasks
pnpm smoke:prod
pnpm release:check
pnpm check
pnpm validate
pnpm quality:check
pnpm dev
```

`/api/health` reports D1 availability and the current project count. Run `pnpm db:execute` and `pnpm db:seed` before local API checks when the D1 state is empty. `pnpm db:execute` prepares the local D1 schema and backfills optional columns that may be missing from older local databases. `seed.sql` is generated from hand-authored seed knowledge and generated eval fixtures; run `pnpm db:seed-sql` after changing those fixtures. `pnpm db:integration` seeds local D1, starts a temporary local Worker, and validates the D1-backed HTTP API path.

`pnpm eval:quality` is the CI-safe recommendation and classification regression gate. `pnpm eval:explanations` checks that agent-facing responses include source metadata, classification evidence, quality signal confidence, recommendation reasons/tradeoffs, health count semantics, and GRP reasoning. `pnpm eval:agent-tasks` gates complete trust, fallback, pagination, evidence, comparison, change-feed, feedback, multilingual, typo, and alias workflows and writes [docs/AGENT_TASK_EVAL.md](https://github.com/haocn-ops/git-top/blob/HEAD/docs/AGENT_TASK_EVAL.md). `pnpm eval:local` runs broader generated category and deployment probes across the fixture-backed project set and writes [docs/EVAL_LOCAL.md](https://github.com/haocn-ops/git-top/blob/HEAD/docs/EVAL_LOCAL.md); use it before tuning ranking heuristics, but keep it out of the default validation path. `pnpm eval:ranking` compares offline ranking strategies in [docs/RANKING_EXPERIMENTS.md](https://github.com/haocn-ops/git-top/blob/HEAD/docs/RANKING_EXPERIMENTS.md). Runtime search keeps exact-intent ranking by default; broad scoped discovery can opt into `ranking=browse`.

`pnpm seed:candidates` discovers seed expansion candidates from live GitHub organization metadata and writes [docs/SEED_CANDIDATES.md](https://github.com/haocn-ops/git-top/blob/HEAD/docs/SEED_CANDIDATES.md). Treat it as a review queue, not an automatic append step; candidates still need live-check and category review before entering `data/seed-repositories.json`.

`pnpm smoke:prod` validates the deployed Worker at `https://git.top` and requires D1-backed responses. Use `pnpm smoke:prod -- --base-url http://localhost:8787` for a local or preview Worker, or add `--allow-seed` only when intentionally checking seed fallback behavior.

`pnpm quality:check` validates the production `/api/quality` endpoint at `https://git.top` by default, requires D1-backed metadata, and uses a default minimum score of `90`. Use `--base-url`, `--target`, `--min-score`, or `--allow-seed` for preview and fallback checks.

Operations and data governance are exposed through `/operations`, `/api/governance/summary`, and `/api/governance/runs`. The Cloudflare Worker cron runs hourly maintenance plus daily, weekly, biweekly, and monthly governance checks, then records results in `governance_runs`.

`pnpm release:check` runs the public V1 release gate: local validation, local D1 integration, production quality, and production smoke. Use `pnpm release:check -- --skip-prod-smoke` only when validating a build before the production deployment exists; it skips production-only checks. Use `pnpm release:check -- --base-url <origin>` to run the same gate against a Worker preview or local origin.

When updating an existing D1 database, apply SQL files in [migrations](https://github.com/haocn-ops/git-top/blob/HEAD/migrations) before deploying code that reads the new columns.

## Sync

Git.Top can sync real repository data from the GitHub API into D1.

Required production secrets:

```sh
wrangler secret put GITHUB_TOKEN
wrangler secret put SYNC_SECRET
```

For local development, copy [.dev.vars.example](https://github.com/haocn-ops/git-top/blob/HEAD/.dev.vars.example) to `.dev.vars` and fill in real values.

Trigger a protected local or production sync:

```sh
curl -X POST http://localhost:8787/api/admin/sync \
  -H "authorization: Bearer $SYNC_SECRET" \
  -H "content-type: application/json" \
  -d '{"limit": 40, "offset": 0, "signal_depth": "lite"}'
```

Use `{"limit":40,"signal_depth":"lite"}` for manual catch-up syncs after checking recent `/api/sync/status` runs. Cron uses a smaller lightweight batch size to stay under Worker subrequest limits, while manual catch-up remains capped at 50.

Run repeated production catch-up rounds:

```sh
SYNC_SECRET=... pnpm sync:prod:catchup --rounds 13 --limit 40
```

Omit `offset` to use the stored seed cursor. Cron syncs use this cursor and advance through the seed list in bounded batches.
Add `--refresh-cycle` when all seed repositories have been indexed but freshness recovery requires revisiting the full seed cursor despite `remaining_count=0`.

## API

- `GET /api/project/:owner/:name`
- `GET /api/health`
- `GET /api/quality`
- `GET /api/benchmark`
- `GET /api/governance/summary`
- `GET /api/governance/runs`
- `GET /api/sync/status`
- `GET /api/schema/agent-card.v1`
- `GET /api/schema/project-knowledge.v1`
- `GET /api/search`
- `GET /api/trending`
- `GET /api/category/:name`
- `GET /api/recommend`
- `GET /api/compare`
- `GET /api/alternatives/:owner/:name`
- `POST /api/grp/query`
- `POST /api/admin/sync`
- `POST /api/admin/alternatives`
- `POST /api/admin/governance/runs`

See [git_top_v1.md](https://github.com/haocn-ops/git-top/blob/HEAD/git_top_v1.md) for the V1 development spec and [git_top_grp_v1.md](https://github.com/haocn-ops/git-top/blob/HEAD/git_top_grp_v1.md) for the GRP v1 reasoning protocol implementation spec.

## License

MIT