ResearchTwin

Instructions

Implementation Reference

• mcp-server/src/mcp_server_researchtwin/server.py:139-163 (handler)

  The get_repos tool handler - an async function that fetches a researcher's code repositories with QIC scores. It makes an HTTP GET request to /api/researcher/{slug}/repos, processes the response items, and formats them into a human-readable string showing repository names, programming languages, star counts, QIC scores, and descriptions.

  @mcp.tool(annotations=ToolAnnotations(title="Get Repositories", read_only_hint=True))
  async def get_repos(slug: str) -> str:
      """Get a researcher's code repositories with QIC scores.
  
      Args:
          slug: Researcher identifier.
  
      Returns GitHub repositories with stars, forks, language, and QIC scores
      computed using FAIR-based quality assessment.
      """
      data = await _get(f"/api/researcher/{slug}/repos")
      items = data.get("items", [])
      if not items:
          return f"No repositories found for {slug}."
  
      lines = []
      for repo in items:
          qic = repo.get("qic_score", 0)
          lang = repo.get("language") or "?"
          lines.append(
              f"- **{repo['name']}** ({lang}, {repo.get('stars', 0)} stars, QIC: {qic})"
              + (f" — {repo['description']}" if repo.get("description") else "")
          )
  
      return f"**{data.get('total', len(items))} repos for {slug}:**\n" + "\n".join(lines)

• mcp-server/src/mcp_server_researchtwin/server.py:139-139 (registration)

  The @mcp.tool decorator registers the get_repos function as an MCP tool with title 'Get Repositories' and read_only_hint=True annotation.

  @mcp.tool(annotations=ToolAnnotations(title="Get Repositories", read_only_hint=True))

• mcp-server/src/mcp_server_researchtwin/server.py:35-40 (helper)

  The _get helper function used by get_repos and other tools to make HTTP GET requests to the ResearchTwin API. It handles async HTTP client creation, request execution, and JSON response parsing.

  async def _get(path: str, params: dict | None = None) -> dict:
      """Make a GET request to the ResearchTwin API."""
      async with httpx.AsyncClient(timeout=TIMEOUT) as client:
          resp = await client.get(f"{BASE_URL}{path}", params=params)
          resp.raise_for_status()
          return resp.json()

• mcp-server/src/mcp_server_researchtwin/server.py:141-148 (schema)

  Schema definition embedded in docstring - defines the tool's input parameter (slug: Researcher identifier) and describes the output format (GitHub repositories with stars, forks, language, and QIC scores computed using FAIR-based quality assessment).

  """Get a researcher's code repositories with QIC scores.
  
  Args:
      slug: Researcher identifier.
  
  Returns GitHub repositories with stars, forks, language, and QIC scores
  computed using FAIR-based quality assessment.
  """