# Git.Top Full Agent Guide

Git.Top turns GitHub repository metadata, generated Agent Cards, quality metrics, deployment signals, alternatives, and graph relationships into structured knowledge for AI agents.

## Positioning

Git.Top is not a GitHub leaderboard. It is a project intelligence layer for agents choosing open-source projects based on fit, deployability, alternatives, maintenance, evidence, and data confidence.

## Base URLs

- Production: https://git.top
- Local Worker: http://localhost:8787

## Recommended Agent Flow

1. Trust first: GET /api/health and GET /api/trust before high-confidence production recommendations.
2. GET /api/health and verify db=available and metadata.source=d1 for high-confidence production recommendations.
3. GET /api/trust or call MCP get_trust_gate before high-confidence production recommendations.
4. Use /api/workflow or MCP get_agent_workflow when an agent needs a guided path across trends, recommendations, graph, alternatives, score, compare, and trust policy.
5. Search with /api/search or MCP search_projects.
6. Fetch candidate details with /api/project/:owner/:repo or MCP get_project.
7. Fetch alternatives with /api/alternatives/:owner/:repo or MCP get_alternatives.
8. Compare final candidates with /api/compare or MCP compare_projects.
9. Use /api/agent-map when an agent needs the human page, REST endpoint, MCP tool, output fields, and trust fields for a Git.Top concept.
10. Use /api/projects or MCP get_projects_batch for snapshot-consistent cache hydration, then /api/changes or MCP get_project_changes for incremental updates and deletion tombstones.
11. Cite metadata, classification evidence, quality_signal_confidence, verification signals, and freshness fields.
12. Operators can use the protected classification override API for reviewed one-off corrections from /quality/review.

## REST Endpoints

- GET /api/health
- GET /api/search?q=cloudflare%20agent&limit=5
- GET /api/search?q=langchian&limit=5 (discloses typo normalization and returns snapshot-bound pagination)
- GET /api/search?category=agent_framework&ranking=browse&limit=12
- GET /api/search?deployment=cloudflare&cloudflare_ready=true&ranking=browse&limit=12
- GET /api/project/cloudflare/agents
- POST /api/project
- GET/POST /api/projects (1-20 canonical project IDs; compact, decision, or evidence profile)
- GET /api/changes (opaque cursor, 30-day retention, deletion tombstones)
- POST /api/feedback/proposals (public validation; FEEDBACK_SECRET required for persistence)
- GET /api/trending?limit=10
- GET /api/workflow?intent=choose%20a%20Cloudflare-ready%20agent%20framework&deployment=cloudflare&category=agent_framework&cloudflare_ready=true&limit=5
- POST /api/workflow
- GET /api/recommend?use_case=build%20a%20browser%20automation%20agent&deployment=docker&limit=5
- POST /api/recommend
- GET /api/compare?repos=cloudflare/agents,langchain-ai/langchain&deployment=cloudflare
- POST /api/compare
- GET /api/alternatives/langchain-ai/langchain
- POST /api/alternatives
- GET /api/related/cloudflare/agents
- POST /api/related
- GET /api/score/cloudflare/agents
- POST /api/score
- GET /api/graph?repo=cloudflare/agents&limit=24
- POST /api/graph
- GET /api/atlas?limit=6
- GET /api/atlas/cloudflare?limit=8
- GET /api/journeys?limit=8
- GET /api/agent-map
- GET /api/quickstart
- GET /api/recipes
- GET /api/examples
- GET /api/roadmap
- GET /api/trust
- GET /api/benchmark
- GET /api/quality
- GET /api/quality/review
- GET /api/sync/status
- GET /api/schema/project.v2
- GET /api/openapi.json
- POST /api/grp/query
- GET/POST /api/admin/classification-overrides (requires SYNC_SECRET)

## MCP

Endpoint: https://git.top/mcp
Core endpoint: https://git.top/mcp/core

GET /mcp returns docs, schema, health, quality, quickstart hints, example JSON-RPC payloads, and tool schemas.

Tools include:

- search_projects
- get_project
- get_projects_batch
- get_project_changes
- propose_project_feedback
- get_alternatives
- get_related_projects
- get_deployment
- get_quality_score
- recommend_project
- get_trends
- get_agent_workflow
- get_atlas
- get_quality_report
- get_trust_gate
- find_alternatives
- get_project_card
- get_project_graph
- compare_projects
- git_top_grp_query

Example tools/list:

curl -X POST https://git.top/mcp -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Example search:

curl -X POST https://git.top/mcp -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_projects","arguments":{"query":"cloudflare agent framework","limit":5}}}'

Example project lookup:

curl -X POST https://git.top/mcp -H "content-type: application/json" -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_project","arguments":{"owner":"cloudflare","repo":"agents","require_d1":true}}}'

## Scoring

git_top_score weights community, maintenance, documentation, stability, adoption, and agent readability.

Score explanations expose dimensions, strongest_dimension, weakest_dimension, adoption_guidance, risk_flags, score_confidence, next_actions, related_scores, evidence, and links.

quality_score weights repository activity: 40% 30-day star movement, 20% commits, 15% releases, 15% contributors, 10% issue response.

agent_score weights agent usefulness: 22% documentation, 24% maintenance, 20% deployment, 18% popularity, 16% community.

## Recommendation Engine

Recommendation results include reason, reasons, decision_summary, fit_profile, adoption_plan, risk_flags, tradeoffs, matched_constraints, unmatched_constraints, ranking_signals, confidence, and next_actions links into project, graph, alternatives, score, and compare flows.

## Compare

Compare responses expose summary, stats, decision_matrix, next_actions, ordered projects, winner, reasoning, and context so agents can justify project shortlist decisions.

## Graph

Focused graph responses expose summary, graph_stats, next_actions, relationship_groups, migration_paths, nodes, and edges across alternatives, related projects, dependencies, deployment targets, and use cases. migration_paths are heuristic decision aids with gaps and validation_steps, not drop-in compatibility guarantees.

## Alternatives Engine

Alternatives responses expose summary, stats, next_actions, comparison_links, alternatives, and alternative_matches with fit_summary, adoption_notes, and replacement_risk so agents can move from replacement discovery into comparison, graph, score, and recommendation flows.

## Atlas

Atlas responses expose ecosystem stats, exploration_paths, comparison_paths, map.nodes, and map.edges so agents can move from ecosystem discovery into search, graph, alternatives, score, and compare flows.

Atlas journeys expose reusable routes across ecosystems. GET /api/journeys returns journeys, journeys[].steps, comparison_paths, stats, ecosystem_id, and metadata so agents can turn a map into an ordered exploration plan.

## Trends

Trends responses expose summary, stats, trend_signals, category/deployment/language buckets, rising_projects, and agent_briefing so agents can understand current corpus-level direction before recommending projects.

## Agent Surface Map

GET /api/agent-map maps Git.Top concepts to human pages, REST endpoints, MCP tools, output fields, trust fields, and recommended use. Agents should read short_path first for the smallest viable trust-first route, then expand into reference_path when they need the fuller discovery surface. Use it when choosing between project lookup, recommendations, alternatives, graph, compare, score, Atlas, GRP, and quality surfaces.

## Trust Fields

- metadata.source: d1 or seed
- metadata.generated_at
- project.synced_at
- metrics.calculated_at
- classification.category/deployment/difficulty/cloudflare_ready confidence and evidence
- quality_signal_confidence for stars, commits, releases, contributors
- verification.overall_status and verification.signals.* (observed, inferred, verified, not_run, not_applicable, unknown)
- verification.next_steps before production adoption; not_run install, security, and MCP signals must remain disclosed

## Public Discovery

- /robots.txt
- /sitemap.xml
- /privacy
- /terms
- /.well-known/security.txt
- /connect
- /compatibility
- /distribution.json
- /integrations
- /quickstart
- /recipes
- /examples
- /journeys
- /status
- /trust
- /benchmark
- /quality
- /coverage
- /quality/review
- /atlas
- /api/journeys
- /api/agent-map
- /roadmap
- /api/quickstart
- /api/recipes
- /api/examples
- /api/trust
- /api/benchmark
- /api/roadmap
- /llms.txt
- /llms-full.txt
- /openapi.json
- /og.svg
- /badge/:owner/:repo.svg

## Topic Pages

- /topics/best-mcp-servers
- /topics/best-ai-agent-frameworks
- /topics/cloudflare-ready-ai-projects
- /topics/atlas-guide
- /topics/atlas-journey-guide
- /topics/graph-guide
- /topics/project-graph-guide
- /topics/open-source-knowledge-graph-api
- /topics/mcp-integration-guide
- /topics/recommendation-guide
- /topics/git-top-score-guide
- /topics/agent-workflow-guide
- /topics/alternatives-engine-guide
- /topics/trust-gate-guide
- /topics/data-trust-guide
- /topics/langchain-alternatives
- /topics/open-source-rag-frameworks
- /topics/browser-ai-automation
- /topics/ai-ide-coding-agents
- /topics/open-source-llm-gateways
- /topics/ai-observability-tools
- /topics/ai-workflow-automation
- /topics/project-comparison-guide
- /topics/github-project-alternatives-api
- /topics/open-source-quality-score-api
- /atlas