semantic_scholar_author_batch

Instructions

Implementation Reference

• src/semantic_scholar_mcp/server.py:1309-1353 (handler)

  Handler function for the semantic_scholar_author_batch tool. Sends a POST request to the Semantic Scholar 'author/batch' endpoint with up to 1000 author IDs. Supports JSON and Markdown response formats, tracking successful retrievals and reporting not-found IDs.

  @mcp.tool(
      name="semantic_scholar_author_batch",
      annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True, openWorldHint=True),
  )
  async def get_author_batch(params: AuthorBatchInput) -> str:
      """Retrieve multiple authors in a single request (max 1000)."""
      logger.info("Batch author retrieval: %d authors", len(params.author_ids))
  
      try:
          response = await _make_request(
              "POST",
              "author/batch",
              params={"fields": ",".join(AUTHOR_FIELDS)},
              json_body={"ids": params.author_ids},
              api_key=params.api_key,
          )
          authors = response if isinstance(response, list) else response.get("data", [])
      except SemanticScholarError as e:
          raise ToolError(str(e)) from e
  
      succeeded = [a for a in authors if a]
      failed_indices = [i for i, a in enumerate(authors) if not a]
      failed_ids = [params.author_ids[i] for i in failed_indices if i < len(params.author_ids)]
  
      if params.response_format == ResponseFormat.JSON:
          result: dict[str, Any] = {
              "requested": len(params.author_ids),
              "retrieved": len(succeeded),
              "authors": succeeded,
          }
          if failed_ids:
              result["not_found"] = failed_ids
          return json.dumps(result, indent=2)
  
      lines = [
          "## Batch Author Retrieval",
          f"**Requested:** {len(params.author_ids)} | **Retrieved:** {len(succeeded)}",
          "",
      ]
      if failed_ids:
          lines.append(f"**Not found ({len(failed_ids)}):** {', '.join(failed_ids[:20])}")
          lines.append("")
      for author in succeeded:
          lines.append(_format_author_markdown(author))
      return "\n".join(lines)

• src/semantic_scholar_mcp/server.py:426-437 (schema)

  Pydantic input schema for AuthorBatchInput. Validates author_ids list (1-1000 items), response_format (default JSON), and optional api_key override.

  class AuthorBatchInput(BaseModel):
      model_config = ConfigDict(str_strip_whitespace=True, extra="forbid")
      author_ids: list[str] = Field(
          ..., description="List of author IDs (max 1000)", min_length=1, max_length=1000
      )
      response_format: ResponseFormat = Field(
          default=ResponseFormat.JSON, description="Output format"
      )
      api_key: str | None = Field(
          default=None,
          description="API key (overrides SEMANTIC_SCHOLAR_API_KEY env var)",
      )

• src/semantic_scholar_mcp/server.py:1309-1312 (registration)

  Registration of the 'semantic_scholar_author_batch' tool using the @mcp.tool decorator with readOnlyHint, idempotentHint, and openWorldHint annotations.

  @mcp.tool(
      name="semantic_scholar_author_batch",
      annotations=ToolAnnotations(readOnlyHint=True, idempotentHint=True, openWorldHint=True),
  )