ResearchTwin

Instructions

Implementation Reference

• mcp-server/src/mcp_server_researchtwin/server.py:77-89 (handler)

  MCP tool handler for 'get_context'. Decorated with @mcp.tool(), this async function takes a researcher slug, calls the backend API endpoint /api/context/{slug}, and returns comprehensive research context as JSON including S-Index, paper impact, source connection statuses, and QIC scores.

  @mcp.tool(annotations=ToolAnnotations(title="Get Researcher Context", read_only_hint=True))
  async def get_context(slug: str) -> str:
      """Get comprehensive research context for a researcher including all data source metrics.
  
      Args:
          slug: Researcher identifier (e.g. 'martin-frasch').
  
      Returns S-Index, paper impact, source connection status (Semantic Scholar,
      Google Scholar, GitHub, Figshare), dataset QIC scores, and repo QIC scores.
      More detailed than get_profile — use this when you need the full picture.
      """
      data = await _get(f"/api/context/{slug}")
      return json.dumps(data, indent=2)

• backend/main.py:476-516 (handler)

  Backend API endpoint implementation for /api/context/{slug}. This FastAPI route fetches researcher data from all sources (Semantic Scholar, Google Scholar, GitHub, Figshare), computes QIC scores, and returns a comprehensive context object with S-Index, paper impact, source statuses, dataset scores, and repository scores.

  @app.get("/api/context/{slug}")
  async def get_context(slug: str):
      researcher = _get_researcher_or_404(slug)
  
      merged_data, gh_data, fs_data = await _fetch_all(researcher)
      qic = compute_researcher_qic(fs_data, gh_data, merged_data)
  
      def _source_status(data, name):
          if "_error" in data:
              return {"status": "error", "error": data["_error"][:100]}
          return {"status": "connected"}
  
      # Academic sources — merged data has _sources field
      academic_sources = merged_data.get("_sources", [])
      s2_info = {"status": "connected"} if "semantic_scholar" in academic_sources else {"status": "error", "error": "Semantic Scholar unavailable"}
      s2_info.update({"paper_count": merged_data.get("paper_count", 0), "citation_count": merged_data.get("citation_count", 0), "h_index": merged_data.get("h_index", 0)})
  
      gs_info = {"status": "connected"} if "google_scholar" in academic_sources else {"status": "error", "error": "Google Scholar unavailable"}
      gs_info.update({"i10_index": merged_data.get("i10_index", 0)})
  
      gh_info = _source_status(gh_data, "github")
      gh_info.update({"total_repos": gh_data.get("total_repos", 0), "total_stars": gh_data.get("total_stars", 0)})
  
      fs_info = _source_status(fs_data, "figshare")
      fs_info.update({"total_datasets": fs_data.get("total_datasets", 0), "total_downloads": fs_data.get("total_downloads", 0)})
  
      return {
          "researcher_slug": slug,
          "display_name": researcher["display_name"],
          "s_index": qic["s_index"],
          "paper_impact": qic["paper_impact"],
          "summary": qic["summary"],
          "sources": {
              "semantic_scholar": s2_info,
              "google_scholar": gs_info,
              "github": gh_info,
              "figshare": fs_info,
          },
          "dataset_scores": qic.get("dataset_scores", []),
          "repo_scores": qic.get("repo_scores", [])[:5],
      }

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

  Tool registration via @mcp.tool() decorator with ToolAnnotations specifying title='Get Researcher Context' and read_only_hint=True. This decorator registers the get_context function as an MCP tool.

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

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

  Documentation listing 'get_context' as one of the available tools in the about() resource function, which provides information about the ResearchTwin platform.

  "- get_context: Get full research context with all metrics\n"

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

  Helper function _get() that makes HTTP GET requests to the ResearchTwin API. Used by the get_context tool (and other tools) to communicate with the backend API endpoints.

  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()