ResearchTwin

Instructions

Implementation Reference

• mcp-server/src/mcp_server_researchtwin/server.py:215-238 (handler)

  The main handler function that implements get_network_map tool logic. It calls the /api/network/map endpoint, processes researcher affiliation data, and returns a formatted string with geographic information for all researchers in the network.

  async def get_network_map() -> str:
      """Get geographic affiliations for all researchers in the network.
  
      Returns researchers with their institutional affiliations and coordinates,
      sourced from ORCID and Semantic Scholar. Useful for understanding the
      geographic distribution of the research network.
      """
      data = await _get("/api/network/map")
      researchers = data.get("researchers", [])
      if not researchers:
          return "No affiliation data available yet."
  
      lines = []
      for r in researchers:
          affs = r.get("affiliations", [])
          aff_strs = []
          for a in affs:
              loc = [a.get("city"), a.get("country")]
              loc_str = ", ".join(x for x in loc if x)
              status = "current" if a.get("current") else "past"
              aff_strs.append(f"  - {a['institution']}" + (f" ({loc_str})" if loc_str else "") + f" [{status}]")
          lines.append(f"**{r['name']}** (`{r['slug']}`):\n" + "\n".join(aff_strs))
  
      return f"**Network map — {data.get('total_researchers', len(researchers))} researchers:**\n\n" + "\n\n".join(lines)

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

  The @mcp.tool decorator that registers get_network_map as an MCP tool with metadata including title 'Get Network Map' and read_only_hint=True.

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

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

  The _get() helper utility function that makes async HTTP GET requests to the ResearchTwin API, used by get_network_map to fetch data from /api/network/map endpoint.

  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:19-19 (schema)

  Import of ToolAnnotations from mcp.types, which provides the schema/metadata structure for tool definitions (used in the decorator at line 214).

  from mcp.types import ToolAnnotations