Marvel MCP

Instructions

Implementation Reference

• src/tools/get_character_by_id/index.ts:9-13 (handler)

  The tool handler that parses the input arguments using GetCharacterByIdSchema, fetches the character data from the Marvel API using httpRequest, and parses the response using CharacterDataWrapperSchema.

  handler: async (args: any) => {
      const argsParsed = GetCharacterByIdSchema.parse(args);
      const res = await httpRequest(`/characters/${argsParsed.characterId}`);
      return CharacterDataWrapperSchema.parse(res);
  }

• src/tools/get_character_by_id/index.ts:6-14 (registration)

  Registers the 'get_character_by_id' tool with its description, input schema, and handler function.

  export const get_character_by_id = {
      description: `Fetch a Marvel character by ID.`,
      schema: GetCharacterByIdSchema,
      handler: async (args: any) => {
          const argsParsed = GetCharacterByIdSchema.parse(args);
          const res = await httpRequest(`/characters/${argsParsed.characterId}`);
          return CharacterDataWrapperSchema.parse(res);
      }
  };

• src/tools/schemas.ts:66-74 (schema)

  Zod schema used to parse and validate the response from the Marvel Characters API endpoint.

  export const CharacterDataWrapperSchema = z.object({
    code: z.number(),
    status: z.string(),
    copyright: z.string(),
    attributionText: z.string(),
    attributionHTML: z.string(),
    data: CharacterDataContainerSchema,
    etag: z.string(),
  });

• src/utils.ts:33-54 (helper)

  Helper utility function that makes authenticated HTTP requests to the Marvel API, handling timestamp, API key, and hash authentication.

  export async function httpRequest(endpoint: string, params: Record<string, string | number | undefined> = {}) {
    const url = new URL(`${MARVEL_API_BASE}${endpoint}`);
  
    const authParams = createAuthParams();
    url.searchParams.set('ts', authParams.ts);
    url.searchParams.set('apikey', authParams.apikey);
    url.searchParams.set('hash', authParams.hash);
  
    for (const [key, value] of Object.entries(params)) {
      if (value !== undefined) {
        url.searchParams.set(key, String(value));
      }
    }
  
    const res = await fetch(url.toString());
    if (!res.ok) {
      const text = await res.text();
      throw new Error(`Marvel API error: ${res.status} - ${text}`);
    }
  
    return res.json();
  }