Git.Top MCP API

openapi: 3.2.0
info:
  title: Git.Top Agent MCP API
  version: 0.1.0
  description: Agent-native GitHub project knowledge API for search, project lookup, alternatives, comparison, graph reasoning, quality, and schema discovery. High-confidence clients should inspect metadata.source, metadata.reason, trust fields, classification evidence, quality_signal_confidence, verification signals, and migration validation steps, and use require_d1=true when seed fallback should fail closed.
servers:
- url: https://git.top
  description: Production
- url: http://localhost:8787
  description: Local Worker
tags:
- name: MCP
paths:
  /mcp:
    get:
      summary: Discover Git.Top MCP tools, docs, quickstart, and JSON-RPC examples
      responses:
        '200':
          description: MCP discovery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpDiscoveryResponse'
              example:
                endpoint: https://git.top/mcp
                attribution:
                  campaign_source: null
                  preserve_endpoint_path: false
                  note: Use /connect?source=<channel> to generate an explicitly attributed MCP endpoint.
                docs_url: https://git.top/docs
                schema_url: https://git.top/api/schema/project.v2
                health_url: https://git.top/api/health
                quality_url: https://git.top/api/quality
                agent_map_url: https://git.top/api/agent-map
                quickstart:
                  first_step: Call tools/list, then use require_d1 for high-confidence reads.
                agent_map:
                  short_path: []
                  reference_path: []
                  surfaces: []
                  trust_policy:
                    high_confidence_source: metadata.source=d1
                tools:
                - name: search_projects
                  description: Search Git.Top projects.
                  inputSchema:
                    type: object
                    properties:
                      query:
                        type: string
                      require_d1:
                        type: boolean
      tags:
      - MCP
      operationId: getMcp
      x-operation-id-source: derived
    post:
      summary: Call MCP tools/list or tools/call via JSON-RPC
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpJsonRpcRequest'
            examples:
              toolsList:
                summary: List Git.Top MCP tools
                value:
                  jsonrpc: '2.0'
                  id: 1
                  method: tools/list
                  params: {}
              toolCall:
                summary: Call a Git.Top MCP tool
                value:
                  jsonrpc: '2.0'
                  id: 2
                  method: tools/call
                  params:
                    name: search_projects
                    arguments:
                      query: cloudflare agent framework
                      require_d1: true
                      limit: 5
      responses:
        '200':
          description: JSON-RPC success result. For tools/call, parse result.content[0].text as JSON before reading metadata or result fields; git_top_grp_query defaults to profile=compact and accepts profile=full for the complete graph.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpJsonRpcSuccessResponse'
              example:
                jsonrpc: '2.0'
                id: 2
                result:
                  content:
                  - type: text
                    text: '{"projects":[{"project_id":"cloudflare/agents","repo":"cloudflare/agents","name":"agents","github_url":"https://github.com/cloudflare/agents","language":"TypeScript","license":"MIT","project_kind":"project","category":["agent_framework"],"description":"Build and deploy AI agents on Cloudflare Workers.","deployments":["cloudflare","serverless"],"difficulty":"intermediate","cloudflare_ready":true,"git_top_score":86,"quality_score":82,"agent_score":90,"verification":{"schema_version":"git-top.verification.v1","overall_status":"partial","observed_at":"2026-07-04T00:00:00.000Z","signals":{"activity":{"status":"observed","source":"github_metadata","evidence":["project.pushed_at","metrics.recent_push_days"]},"license":{"status":"observed","source":"github_metadata","evidence":["project.license"]},"documentation":{"status":"observed","source":"github_metadata","evidence":["project.description"]},"runtime":{"status":"inferred","source":"git_top_heuristic","evidence":["agent_card.deployment","agent_card.cloudflare_ready"]},"install":{"status":"not_run","source":"git_top_runtime","evidence":["installation/build probe is not enabled"]},"security":{"status":"not_run","source":"git_top_runtime","evidence":["dependency/security scan is not enabled"]},"mcp":{"status":"not_applicable","source":"git_top_runtime","evidence":["project is not classified as mcp_server"]}},"coverage":{"observed":3,"inferred":1,"not_run":2,"unknown":0},"next_steps":["Run an installation/build probe before production adoption.","Run a dependency and security scan before treating the score as a trust claim."]},"quality_signal_confidence":{"stars_30d_delta":"snapshot","commits_30d":"complete","releases_180d":"partial","contributors_90d":"complete"},"evidence":{"source_fields":["agent_card.classification","metrics","verification.signals"],"caveats":[],"confidence_reason":"Evidence is usable for comparison.","verification":{"schema_version":"git-top.verification.v1","overall_status":"partial","observed_at":"2026-07-04T00:00:00.000Z","signals":{"activity":{"status":"observed","source":"github_metadata","evidence":["project.pushed_at","metrics.recent_push_days"]},"license":{"status":"observed","source":"github_metadata","evidence":["project.license"]},"documentation":{"status":"observed","source":"github_metadata","evidence":["project.description"]},"runtime":{"status":"inferred","source":"git_top_heuristic","evidence":["agent_card.deployment","agent_card.cloudflare_ready"]},"install":{"status":"not_run","source":"git_top_runtime","evidence":["installation/build probe is not enabled"]},"security":{"status":"not_run","source":"git_top_runtime","evidence":["dependency/security scan is not enabled"]},"mcp":{"status":"not_applicable","source":"git_top_runtime","evidence":["project is not classified as mcp_server"]}},"coverage":{"observed":3,"inferred":1,"not_run":2,"unknown":0},"next_steps":["Run an installation/build probe before production adoption.","Run a dependency and security scan before treating the score as a trust claim."]},"last_verified_at":"2026-07-04T00:00:00.000Z"},"caveats":[],"confidence_reason":"Evidence is usable for comparison.","source_fields":["agent_card.classification","metrics","verification.signals"],"last_verified_at":"2026-07-04T00:00:00.000Z"}],"metadata":{"source":"d1","reason":"d1_query","project_count":500,"generated_at":"2026-07-04T00:00:00.000Z","snapshot_id":"d1:500:2026-07-04T00:00:00.000Z","latest_synced_at":"2026-07-04T00:00:00.000Z","schema_version":"git-top.knowledge.v1"}}'
        '202':
          description: Accepted JSON-RPC notification with no response body, used for notifications/initialized.
        '400':
          description: JSON-RPC error result for invalid JSON, unsupported methods, unknown tools, invalid arguments, strict D1 failures (-32003), stale cursors (-32004), or unresolved singular projects (-32005).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpJsonRpcErrorResponse'
              example:
                jsonrpc: '2.0'
                id: 2
                error:
                  code: -32005
                  message: Project missing/project was not found.
      tags:
      - MCP
      operationId: postMcp
      x-operation-id-source: derived
  /mcp/core:
    get:
      summary: Discover the focused Git.Top MCP core profile for first-time agent connections
      responses:
        '200':
          description: MCP core profile discovery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpDiscoveryResponse'
              example:
                endpoint: https://git.top/mcp/core
                attribution:
                  campaign_source: null
                  preserve_endpoint_path: false
                  note: Use /connect?source=<channel> to generate an explicitly attributed MCP endpoint.
                docs_url: https://git.top/docs
                schema_url: https://git.top/api/schema/project.v2
                health_url: https://git.top/api/health
                quality_url: https://git.top/api/quality
                agent_map_url: https://git.top/api/agent-map
                quickstart:
                  first_step: Call tools/list, then use require_d1 for high-confidence reads.
                agent_map:
                  short_path: []
                  reference_path: []
                  surfaces: []
                  trust_policy:
                    high_confidence_source: metadata.source=d1
                tools:
                - name: search_projects
                  description: Search Git.Top projects.
                - name: get_project
                  description: Return one structured project record.
                - name: recommend_project
                  description: Recommend projects for a use case and constraints.
                - name: compare_projects
                  description: Compare a project shortlist.
                - name: get_agent_workflow
                  description: Return a guided project-selection workflow.
                profile: core
                profiles:
                  core:
                    endpoint: https://git.top/mcp/core
                    tool_count: 5
                  full:
                    endpoint: https://git.top/mcp
                    tool_count: 21
      tags:
      - MCP
      operationId: getMcpCore
      x-operation-id-source: derived
    post:
      summary: Call the focused MCP core profile via JSON-RPC
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpJsonRpcRequest'
      responses:
        '200':
          description: MCP core JSON-RPC success result; the full profile endpoint supports bounded compact and opt-in full GRP responses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpJsonRpcSuccessResponse'
              example:
                jsonrpc: '2.0'
                id: 2
                result:
                  content:
                  - type: text
                    text: '{"projects":[{"project_id":"cloudflare/agents","repo":"cloudflare/agents","name":"agents","github_url":"https://github.com/cloudflare/agents","language":"TypeScript","license":"MIT","project_kind":"project","category":["agent_framework"],"description":"Build and deploy AI agents on Cloudflare Workers.","deployments":["cloudflare","serverless"],"difficulty":"intermediate","cloudflare_ready":true,"git_top_score":86,"quality_score":82,"agent_score":90,"verification":{"schema_version":"git-top.verification.v1","overall_status":"partial","observed_at":"2026-07-04T00:00:00.000Z","signals":{"activity":{"status":"observed","source":"github_metadata","evidence":["project.pushed_at","metrics.recent_push_days"]},"license":{"status":"observed","source":"github_metadata","evidence":["project.license"]},"documentation":{"status":"observed","source":"github_metadata","evidence":["project.description"]},"runtime":{"status":"inferred","source":"git_top_heuristic","evidence":["agent_card.deployment","agent_card.cloudflare_ready"]},"install":{"status":"not_run","source":"git_top_runtime","evidence":["installation/build probe is not enabled"]},"security":{"status":"not_run","source":"git_top_runtime","evidence":["dependency/security scan is not enabled"]},"mcp":{"status":"not_applicable","source":"git_top_runtime","evidence":["project is not classified as mcp_server"]}},"coverage":{"observed":3,"inferred":1,"not_run":2,"unknown":0},"next_steps":["Run an installation/build probe before production adoption.","Run a dependency and security scan before treating the score as a trust claim."]},"quality_signal_confidence":{"stars_30d_delta":"snapshot","commits_30d":"complete","releases_180d":"partial","contributors_90d":"complete"},"evidence":{"source_fields":["agent_card.classification","metrics","verification.signals"],"caveats":[],"confidence_reason":"Evidence is usable for comparison.","verification":{"schema_version":"git-top.verification.v1","overall_status":"partial","observed_at":"2026-07-04T00:00:00.000Z","signals":{"activity":{"status":"observed","source":"github_metadata","evidence":["project.pushed_at","metrics.recent_push_days"]},"license":{"status":"observed","source":"github_metadata","evidence":["project.license"]},"documentation":{"status":"observed","source":"github_metadata","evidence":["project.description"]},"runtime":{"status":"inferred","source":"git_top_heuristic","evidence":["agent_card.deployment","agent_card.cloudflare_ready"]},"install":{"status":"not_run","source":"git_top_runtime","evidence":["installation/build probe is not enabled"]},"security":{"status":"not_run","source":"git_top_runtime","evidence":["dependency/security scan is not enabled"]},"mcp":{"status":"not_applicable","source":"git_top_runtime","evidence":["project is not classified as mcp_server"]}},"coverage":{"observed":3,"inferred":1,"not_run":2,"unknown":0},"next_steps":["Run an installation/build probe before production adoption.","Run a dependency and security scan before treating the score as a trust claim."]},"last_verified_at":"2026-07-04T00:00:00.000Z"},"caveats":[],"confidence_reason":"Evidence is usable for comparison.","source_fields":["agent_card.classification","metrics","verification.signals"],"last_verified_at":"2026-07-04T00:00:00.000Z"}],"metadata":{"source":"d1","reason":"d1_query","project_count":500,"generated_at":"2026-07-04T00:00:00.000Z","snapshot_id":"d1:500:2026-07-04T00:00:00.000Z","latest_synced_at":"2026-07-04T00:00:00.000Z","schema_version":"git-top.knowledge.v1"}}'
        '202':
          description: Accepted JSON-RPC notification with no response body.
        '400':
          description: MCP core JSON-RPC error result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpJsonRpcErrorResponse'
              example:
                jsonrpc: '2.0'
                id: 2
                error:
                  code: -32005
                  message: Project missing/project was not found.
      tags:
      - MCP
      operationId: postMcpCore
      x-operation-id-source: derived
  /mcp/core/source/{source}:
    parameters:
    - name: source
      in: path
      required: true
      description: Normalized campaign source preserved when an MCP client removes query parameters
      schema:
        type: string
        pattern: ^[a-z0-9][a-z0-9._-]{0,47}$
    get:
      summary: Discover the focused Git.Top MCP core profile while preserving campaign…
      responses:
        '200':
          description: Attributed MCP core profile discovery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpDiscoveryResponse'
              example:
                endpoint: https://git.top/mcp/core/source/smithery
                attribution:
                  campaign_source: smithery
                  endpoint_path: /mcp/core/source/smithery
                  preserve_endpoint_path: true
                  note: Keep the source-bearing endpoint path in subsequent MCP requests so campaign attribution remains explicit.
                docs_url: https://git.top/docs
                schema_url: https://git.top/api/schema/project.v2
                health_url: https://git.top/api/health
                quality_url: https://git.top/api/quality
                agent_map_url: https://git.top/api/agent-map
                quickstart:
                  first_step: Call tools/list, then use require_d1 for high-confidence reads.
                agent_map:
                  short_path: []
                  reference_path: []
                  surfaces: []
                  trust_policy:
                    high_confidence_source: metadata.source=d1
                tools:
                - name: search_projects
                  description: Search Git.Top projects.
                - name: get_project
                  description: Return one structured project record.
                - name: recommend_project
                  description: Recommend projects for a use case and constraints.
                - name: compare_projects
                  description: Compare a project shortlist.
                - name: get_agent_workflow
                  description: Return a guided project-selection workflow.
                profile: core
                profiles:
                  core:
                    endpoint: https://git.top/mcp/core
                    tool_count: 5
                  full:
                    endpoint: https://git.top/mcp
                    tool_count: 21
      tags:
      - MCP
      operationId: getMcpCoreSourceBySource
      x-operation-id-source: derived
    post:
      summary: Call the focused MCP core profile via an attributed JSON-RPC endpoint
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/McpJsonRpcRequest'
      responses:
        '200':
          description: Attributed MCP core JSON-RPC success result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpJsonRpcSuccessResponse'
              example:
                jsonrpc: '2.0'
                id: 2
                result:
                  content:
                  - type: text
                    text: '{"projects":[{"project_id":"cloudflare/agents","repo":"cloudflare/agents","name":"agents","github_url":"https://github.com/cloudflare/agents","language":"TypeScript","license":"MIT","project_kind":"project","category":["agent_framework"],"description":"Build and deploy AI agents on Cloudflare Workers.","deployments":["cloudflare","serverless"],"difficulty":"intermediate","cloudflare_ready":true,"git_top_score":86,"quality_score":82,"agent_score":90,"verification":{"schema_version":"git-top.verification.v1","overall_status":"partial","observed_at":"2026-07-04T00:00:00.000Z","signals":{"activity":{"status":"observed","source":"github_metadata","evidence":["project.pushed_at","metrics.recent_push_days"]},"license":{"status":"observed","source":"github_metadata","evidence":["project.license"]},"documentation":{"status":"observed","source":"github_metadata","evidence":["project.description"]},"runtime":{"status":"inferred","source":"git_top_heuristic","evidence":["agent_card.deployment","agent_card.cloudflare_ready"]},"install":{"status":"not_run","source":"git_top_runtime","evidence":["installation/build probe is not enabled"]},"security":{"status":"not_run","source":"git_top_runtime","evidence":["dependency/security scan is not enabled"]},"mcp":{"status":"not_applicable","source":"git_top_runtime","evidence":["project is not classified as mcp_server"]}},"coverage":{"observed":3,"inferred":1,"not_run":2,"unknown":0},"next_steps":["Run an installation/build probe before production adoption.","Run a dependency and security scan before treating the score as a trust claim."]},"quality_signal_confidence":{"stars_30d_delta":"snapshot","commits_30d":"complete","releases_180d":"partial","contributors_90d":"complete"},"evidence":{"source_fields":["agent_card.classification","metrics","verification.signals"],"caveats":[],"confidence_reason":"Evidence is usable for comparison.","verification":{"schema_version":"git-top.verification.v1","overall_status":"partial","observed_at":"2026-07-04T00:00:00.000Z","signals":{"activity":{"status":"observed","source":"github_metadata","evidence":["project.pushed_at","metrics.recent_push_days"]},"license":{"status":"observed","source":"github_metadata","evidence":["project.license"]},"documentation":{"status":"observed","source":"github_metadata","evidence":["project.description"]},"runtime":{"status":"inferred","source":"git_top_heuristic","evidence":["agent_card.deployment","agent_card.cloudflare_ready"]},"install":{"status":"not_run","source":"git_top_runtime","evidence":["installation/build probe is not enabled"]},"security":{"status":"not_run","source":"git_top_runtime","evidence":["dependency/security scan is not enabled"]},"mcp":{"status":"not_applicable","source":"git_top_runtime","evidence":["project is not classified as mcp_server"]}},"coverage":{"observed":3,"inferred":1,"not_run":2,"unknown":0},"next_steps":["Run an installation/build probe before production adoption.","Run a dependency and security scan before treating the score as a trust claim."]},"last_verified_at":"2026-07-04T00:00:00.000Z"},"caveats":[],"confidence_reason":"Evidence is usable for comparison.","source_fields":["agent_card.classification","metrics","verification.signals"],"last_verified_at":"2026-07-04T00:00:00.000Z"}],"metadata":{"source":"d1","reason":"d1_query","project_count":500,"generated_at":"2026-07-04T00:00:00.000Z","snapshot_id":"d1:500:2026-07-04T00:00:00.000Z","latest_synced_at":"2026-07-04T00:00:00.000Z","schema_version":"git-top.knowledge.v1"}}'
        '202':
          description: Accepted JSON-RPC notification with no response body.
        '400':
          description: Attributed MCP core JSON-RPC error result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/McpJsonRpcErrorResponse'
              example:
                jsonrpc: '2.0'
                id: 2
                error:
                  code: -32005
                  message: Project missing/project was not found.
      tags:
      - MCP
      operationId: postMcpCoreSourceBySource
      x-operation-id-source: derived
components:
  schemas:
    AgentPathStep:
      type: object
      properties:
        step:
          type: integer
        concept:
          type: string
        rest:
          type: array
          items:
            type: string
        mcp_tools:
          type: array
          items:
            type: string
        inspect:
          type: array
          items:
            type: string
        trust_fields:
          type: array
          items:
            type: string
        use_when:
          type: string
      additionalProperties: true
    McpJsonRpcSuccessResponse:
      type: object
      description: JSON-RPC 2.0 success response. initialize returns server capabilities, tools/list returns tool metadata, and tools/call returns MCP content blocks; Git.Top serializes structured tool payloads as JSON text in result.content[0].text.
      required:
      - jsonrpc
      - id
      - result
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - type: string
          - type: number
          - type: 'null'
        result:
          anyOf:
          - type: object
            description: initialize result.
            properties:
              protocolVersion:
                type: string
              capabilities:
                type: object
                additionalProperties: true
              serverInfo:
                type: object
                additionalProperties: true
            additionalProperties: true
          - type: object
            description: tools/list result.
            properties:
              tools:
                type: array
                items:
                  type: object
                  additionalProperties: true
            additionalProperties: true
          - type: object
            description: tools/call result. Parse text content as JSON.
            required:
            - content
            properties:
              content:
                type: array
                items:
                  type: object
                  required:
                  - type
                  - text
                  properties:
                    type:
                      type: string
                      enum:
                      - text
                    text:
                      type: string
                      description: JSON string containing the structured tool result, usually with metadata.source and metadata.reason. git_top_grp_query includes profile and defaults to a bounded compact graph response; use profile=full for the complete graph.
                  additionalProperties: true
            additionalProperties: true
      additionalProperties: true
    AgentMapResponse:
      type: object
      required:
      - surfaces
      - short_path
      - reference_path
      - trust_policy
      properties:
        name:
          type: string
        positioning:
          type: string
        purpose:
          type: string
        production_base_url:
          type: string
        rest_base_url:
          type: string
        mcp_endpoint:
          type: string
        openapi_url:
          type: string
        schema_url:
          type: string
        llms_url:
          type: string
        llms_full_url:
          type: string
        short_path:
          type: array
          items:
            $ref: '#/components/schemas/AgentPathStep'
        reference_path:
          type: array
          items:
            $ref: '#/components/schemas/AgentPathStep'
        core_surfaces:
          type: array
          items:
            type: object
            additionalProperties: true
        recommended_agent_flow:
          type: array
          items:
            type: string
        surfaces:
          type: array
          items:
            type: object
            additionalProperties: true
        trust_policy:
          type: object
          additionalProperties: true
      additionalProperties: true
    McpDiscoveryResponse:
      type: object
      description: GET /mcp discovery response for agents before JSON-RPC tool calls.
      required:
      - endpoint
      - tools
      properties:
        endpoint:
          type: string
        attribution:
          type: object
          description: Explicit campaign attribution for source-bearing MCP endpoints.
          additionalProperties: true
        docs_url:
          type: string
        schema_url:
          type: string
        health_url:
          type: string
        quality_url:
          type: string
        agent_map_url:
          type: string
        quickstart:
          type: object
          additionalProperties: true
        examples:
          type: array
          items:
            type: object
            additionalProperties: true
        agent_map:
          $ref: '#/components/schemas/AgentMapResponse'
        tools:
          type: array
          items:
            type: object
            additionalProperties: true
      additionalProperties: true
    McpJsonRpcRequest:
      type: object
      description: JSON-RPC 2.0 request accepted by POST /mcp.
      required:
      - jsonrpc
      - method
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - type: string
          - type: number
          - type: 'null'
          description: Client-chosen request id returned unchanged in success or error responses. Omit for JSON-RPC notifications.
        method:
          type: string
          enum:
          - initialize
          - notifications/initialized
          - tools/list
          - tools/call
          description: Supported JSON-RPC method.
        params:
          type: object
          properties:
            name:
              type: string
              description: Tool name for tools/call.
            arguments:
              type: object
              description: Tool arguments. Pass require_d1=true for high-confidence D1-backed reads.
              additionalProperties: true
          additionalProperties: true
      additionalProperties: true
    McpJsonRpcErrorResponse:
      type: object
      description: JSON-RPC 2.0 error response. Strict D1 failures use code -32003; unresolved singular project lookups use code -32005, while stale pagination cursors use -32004.
      required:
      - jsonrpc
      - id
      - error
      properties:
        jsonrpc:
          type: string
          const: '2.0'
        id:
          oneOf:
          - type: string
          - type: number
          - type: 'null'
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: integer
              description: JSON-RPC error code. Common values include -32700 parse error, -32601 method/tool not found, -32602 invalid params, -32003 D1 required, -32004 stale pagination cursor, and -32005 project not found.
            message:
              type: string
          additionalProperties: true
      additionalProperties: true
  securitySchemes:
    syncSecret:
      type: http
      scheme: bearer
      description: Admin endpoints require the SYNC_SECRET bearer token.
    feedbackSecret:
      type: http
      scheme: bearer
      description: Optional FEEDBACK_SECRET. Without it, proposals are validated and fingerprinted but not persisted.