pubmed-mcp-server

Instructions

Implementation Reference

• src/mcp-server/tools/definitions/convert-ids.tool.ts:46-70 (handler)

  The main handler function that executes the pubmed_convert_ids tool. It calls getNcbiService().idConvert() to convert article IDs and transforms the response into a consistent format with requestedId, pmid, pmcid, doi, and errmsg fields.

  async handler(input, ctx) {
    ctx.log.info('Executing pubmed_convert_ids', {
      count: input.ids.length,
      idtype: input.idtype,
    });
  
    const raw = await getNcbiService().idConvert(input.ids, input.idtype);
  
    // NCBI returns pmid as a number in JSON — coerce all ID fields to strings
    const records = raw.map((r) => ({
      requestedId: String(r['requested-id']),
      ...(r.pmid !== undefined && { pmid: String(r.pmid) }),
      ...(r.pmcid !== undefined && { pmcid: String(r.pmcid) }),
      ...(r.doi !== undefined && { doi: String(r.doi) }),
      ...(r.errmsg !== undefined && { errmsg: String(r.errmsg) }),
    }));
  
    const totalConverted = records.filter((r) => !r.errmsg).length;
    ctx.log.info('pubmed_convert_ids completed', {
      totalConverted,
      totalSubmitted: input.ids.length,
    });
  
    return { records, totalConverted, totalSubmitted: input.ids.length };
  },

• src/mcp-server/tools/definitions/convert-ids.tool.ts:14-44 (schema)

  Input and output Zod schemas for the pubmed_convert_ids tool. The input schema validates the 'ids' array (1-50 items) and 'idtype' enum ('pmcid', 'pmid', 'doi'). The output schema defines the structure of conversion results including records array and conversion counts.

  input: z.object({
    ids: z
      .array(z.string().min(1))
      .min(1)
      .max(50)
      .describe(
        'Article identifiers to convert. All IDs must be the same type. ' +
          'DOIs: "10.1093/nar/gks1195", PMIDs: "23193287", PMCIDs: "PMC3531190".',
      ),
    idtype: z
      .enum(['pmcid', 'pmid', 'doi'])
      .describe(
        'The type of IDs being submitted. Required so the API can unambiguously resolve them.',
      ),
  }),
  
  output: z.object({
    records: z
      .array(
        z.object({
          requestedId: z.string().describe('The ID that was submitted'),
          pmid: z.string().optional().describe('PubMed ID'),
          pmcid: z.string().optional().describe('PubMed Central ID'),
          doi: z.string().optional().describe('Digital Object Identifier'),
          errmsg: z.string().optional().describe('Error message if conversion failed'),
        }),
      )
      .describe('Conversion results, one per input ID'),
    totalConverted: z.number().describe('Number of IDs successfully converted'),
    totalSubmitted: z.number().describe('Number of IDs submitted'),
  }),

• src/index.ts:10-31 (registration)

  The pubmed_convert_ids tool is registered in the MCP server. The convertIdsTool is imported from convert-ids.tool.ts and added to the tools array in createApp().

  import { convertIdsTool } from './mcp-server/tools/definitions/convert-ids.tool.js';
  import { fetchArticlesTool } from './mcp-server/tools/definitions/fetch-articles.tool.js';
  import { fetchFulltextTool } from './mcp-server/tools/definitions/fetch-fulltext.tool.js';
  import { findRelatedTool } from './mcp-server/tools/definitions/find-related.tool.js';
  import { formatCitationsTool } from './mcp-server/tools/definitions/format-citations.tool.js';
  import { lookupCitationTool } from './mcp-server/tools/definitions/lookup-citation.tool.js';
  import { lookupMeshTool } from './mcp-server/tools/definitions/lookup-mesh.tool.js';
  import { searchArticlesTool } from './mcp-server/tools/definitions/search-articles.tool.js';
  import { spellCheckTool } from './mcp-server/tools/definitions/spell-check.tool.js';
  import { initNcbiService } from './services/ncbi/ncbi-service.js';
  
  await createApp({
    tools: [
      searchArticlesTool,
      fetchArticlesTool,
      fetchFulltextTool,
      formatCitationsTool,
      findRelatedTool,
      spellCheckTool,
      lookupMeshTool,
      lookupCitationTool,
      convertIdsTool,

• src/services/ncbi/ncbi-service.ts:147-176 (helper)

  The idConvert helper method in NcbiService that makes the actual API call to the NCBI PMC ID Converter API. It joins the IDs, makes an external request through the API client, parses the JSON response, and returns the conversion records.

  async idConvert(ids: string[], idtype?: string): Promise<IdConvertRecord[]> {
    const params: NcbiRequestParams = {
      ids: ids.join(','),
      format: 'json',
      ...(idtype && { idtype }),
    };
  
    const text = await this.queue.enqueue(
      () =>
        this.withRetry(
          () => this.apiClient.makeExternalRequest(NCBI_PMC_IDCONV_URL, params),
          'idconv',
        ),
      'idconv',
      params,
    );
  
    let parsed: unknown;
    try {
      parsed = JSON.parse(text);
    } catch {
      throw new McpError(
        JsonRpcErrorCode.SerializationError,
        'Failed to parse ID Converter JSON response.',
        { responseSnippet: text.substring(0, 200) },
      );
    }
  
    return (parsed as IdConvertResponse).records ?? [];
  }