fulcrum: "1.0"
name: github_search_repos
description: |
  Search GitHub repositories with GitHub's search syntax. Returns matching
  repos sorted by relevance (default) or stars/forks/updated.

  Search syntax supports filters like `stars:>1000`, `language:python`,
  `created:>2024-01-01`, `user:torvalds`. See GitHub search docs for the
  full grammar.

schema:
  input:
    type: object
    properties:
      q:
        type: string
        description: GitHub search query
        examples:
          - "machine learning stars:>10000 language:python"
          - "mcp language:rust"
          - "topic:claude-code"
      sort:
        type: string
        enum: [stars, forks, help-wanted-issues, updated]
      order:
        type: string
        enum: [asc, desc]
        default: desc
      per_page:
        type: integer
        default: 10
        minimum: 1
        maximum: 100
      page:
        type: integer
        default: 1
    required:
      - q
  output:
    type: object
    properties:
      total_count: { type: integer }
      incomplete_results: { type: boolean }
      items: { type: array }

providers:
  primary:
    service: rest
    cost_per_call: 0
    timeout: 15
    config:
      base_url: https://api.github.com
      path: /search/repositories
      method: GET
      headers:
        Accept: "application/vnd.github+json"
        X-GitHub-Api-Version: "2022-11-28"
        User-Agent: "mcp-gateway-knowledge/1.0"
      static_params:
        per_page: "10"
      params:
        q: "{q}"
        sort: "{sort}"
        order: "{order}"
        per_page: "{per_page}"
        page: "{page}"

cache:
  strategy: exact
  ttl: 600

auth:
  required: false
  type: none

metadata:
  category: knowledge
  tags: [github, search, repositories, code, free]
  cost_category: free
  execution_time: fast
  read_only: true
  produces: [github_repo_list]
  chains_with: [github_get_repo]
  docs: "https://docs.github.com/en/rest/search/search#search-repositories"
  license: "MIT"
  rate_limit: "10 req/min unauthenticated, 30 req/min authenticated"
