SureChEMBL MCP Server

Instructions

Implementation Reference

• src/index.ts:941-1015 (handler)

  Executes the tool logic: validates input, fetches patent document contents via SureChEMBL API, extracts and aggregates chemical annotations from abstracts and descriptions, computes analysis statistics (total annotations, unique chemicals, categories), and returns formatted JSON response.

  private async handleAnalyzePatentChemistry(args: any) {
    if (!isValidDocumentArgs(args)) {
      throw new McpError(ErrorCode.InvalidParams, 'Invalid document arguments');
    }
  
    try {
      const response = await this.apiClient.get(`/document/${args.document_id}/contents`);
      const document = response.data.data;
  
      if (!document) {
        throw new Error('Document not found');
      }
  
      // Extract chemical annotations from abstracts and descriptions
      const chemicalAnnotations: any[] = [];
  
      // Process abstracts
      if (document.contents?.patentDocument?.abstracts) {
        document.contents.patentDocument.abstracts.forEach((abstract: any) => {
          if (abstract.section?.annotations) {
            abstract.section.annotations.forEach((annotation: any) => {
              chemicalAnnotations.push({
                source: 'abstract',
                language: abstract.lang,
                annotation: annotation
              });
            });
          }
        });
      }
  
      // Process descriptions
      if (document.contents?.patentDocument?.descriptions) {
        document.contents.patentDocument.descriptions.forEach((description: any) => {
          if (description.section?.annotations) {
            description.section.annotations.forEach((annotation: any) => {
              chemicalAnnotations.push({
                source: 'description',
                language: description.lang,
                annotation: annotation
              });
            });
          }
        });
      }
  
      // Analyze chemical content
      const analysis = {
        document_id: args.document_id,
        total_chemical_annotations: chemicalAnnotations.length,
        unique_chemicals: [...new Set(chemicalAnnotations.map(a => a.annotation.name))],
        annotation_categories: [...new Set(chemicalAnnotations.map(a => a.annotation.category))],
        chemical_annotations: chemicalAnnotations,
        summary: {
          has_chemical_content: chemicalAnnotations.length > 0,
          languages: [...new Set(chemicalAnnotations.map(a => a.language))],
          sources: [...new Set(chemicalAnnotations.map(a => a.source))]
        }
      };
  
      return {
        content: [
          {
            type: 'text',
            text: JSON.stringify(analysis, null, 2),
          },
        ],
      };
    } catch (error) {
      throw new McpError(
        ErrorCode.InternalError,
        `Failed to analyze patent chemistry: ${error instanceof Error ? error.message : 'Unknown error'}`
      );
    }
  }

• src/index.ts:487-497 (registration)

  Registers the tool in the ListTools response, providing name, description, and input schema definition.

  {
    name: 'analyze_patent_chemistry',
    description: 'Analyze chemical content and annotations in a patent document',
    inputSchema: {
      type: 'object',
      properties: {
        document_id: { type: 'string', description: 'Patent document ID to analyze' },
      },
      required: ['document_id'],
    },
  },

• src/index.ts:569-570 (registration)

  Dispatches tool calls to the specific handler function in the CallToolRequestHandler switch statement.

  case 'analyze_patent_chemistry':
    return await this.handleAnalyzePatentChemistry(args);

• src/index.ts:490-496 (schema)

  Defines the input schema requiring a 'document_id' string parameter.

  inputSchema: {
    type: 'object',
    properties: {
      document_id: { type: 'string', description: 'Patent document ID to analyze' },
    },
    required: ['document_id'],
  },

• src/index.ts:104-114 (helper)

  Type guard function used in the handler to validate input arguments.

  const isValidDocumentArgs = (
    args: any
  ): args is { document_id: string; include_annotations?: boolean } => {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.document_id === 'string' &&
      args.document_id.length > 0 &&
      (args.include_annotations === undefined || typeof args.include_annotations === 'boolean')
    );
  };