jp_lit_search_illustrations

Instructions

Implementation Reference

• src/tools/jpLitSearchIllustrations.ts:25-98 (handler)

  Main handler function that creates the jp_lit_search_illustrations tool. Accepts keyword, size, from parameters; delegates to NextDigitalLibraryClient.searchIllustrations; maps results to include IIIF image URLs (page and region); outputs structured content with items, total, from.

  export function createJpLitSearchIllustrationsTool(
    nextDlClient: NextDigitalLibraryClient,
    cache: FileCache = createFileCache(),
    sessions: SessionStore = createSessionStore()
  ) {
    return async (input: unknown) => {
      const parsed = searchIllustrationsInputSchema.parse(input);
  
      const { structuredContent } = await runCachedTool<SearchIllustrationsOutput>({
        tool: "jp_lit_search_illustrations",
        input: parsed as Record<string, unknown>,
        cache,
        sessions,
        live: async () => {
          const result = await nextDlClient.searchIllustrations(parsed.keyword, {
            size: parsed.size,
            from: parsed.from
          });
  
          if (!result) {
            throw new NotFoundError("検索結果が取得できませんでした");
          }
  
          const rawList = Array.isArray(result.list) ? result.list : [];
          const items = rawList.map((item: unknown) => {
            const r = item as Record<string, unknown>;
            const pid = String(r["pid"] ?? "");
            const page = Number(r["page"] ?? 0);
            const x = Number(r["x"] ?? 0);
            const y = Number(r["y"] ?? 0);
            const w = Number(r["w"] ?? 0);
            const h = Number(r["h"] ?? 0);
            const rawTags = Array.isArray(r["graphictags"]) ? r["graphictags"] : [];
            const graphictags = rawTags.map((t: unknown) => {
              const tag = t as Record<string, unknown>;
              return {
                tagname: String(tag["tagname"] ?? ""),
                confidence: Number(tag["confidence"] ?? 0)
              };
            });
  
            return {
              id: String(r["id"] ?? ""),
              pid,
              viewer_url: `https://dl.ndl.go.jp/pid/${pid}`,
              page,
              x,
              y,
              w,
              h,
              graphictags,
              page_image_url: buildIiifPageUrl(pid, page),
              illustration_image_url: buildIiifRegionUrl(pid, page, x, y, w, h)
            };
          });
  
          const total = (result.hit ?? result.total ?? 0) as number;
  
          return searchIllustrationsOutputSchema.parse({
            keyword: parsed.keyword,
            total,
            from: parsed.from,
            items,
            raw: result
          });
        }
      });
  
      return {
        content: [{ type: "text" as const, text: JSON.stringify(structuredContent, null, 2) }],
        structuredContent
      };
    };
  }

• src/lib/schemas.ts:689-693 (schema)

  Input schema for the tool: keyword (required), size (default 20, max 100), from (default 0).

  export const searchIllustrationsInputSchema = z.object({
    keyword: z.string().trim().min(1),
    size: z.number().int().positive().max(100).default(20),
    from: z.number().int().nonnegative().default(0)
  });

• src/lib/schemas.ts:695-701 (schema)

  Output schema with keyword, total, from, items (array of illustrationItemSchema), raw results.

  export const searchIllustrationsOutputSchema = z.object({
    keyword: z.string(),
    total: z.number().int().nonnegative(),
    from: z.number().int().nonnegative(),
    items: z.array(illustrationItemSchema),
    raw: z.record(z.unknown())
  });

• src/lib/schemas.ts:672-687 (schema)

  Schema for each illustration item including pid, page coordinates, IIF image URLs, and graphic tags with confidence scores.

  const illustrationItemSchema = z.object({
    id: z.string(),
    pid: z.string(),
    viewer_url: z.string(),
    page: z.number().int().positive(),
    x: z.number(),
    y: z.number(),
    w: z.number(),
    h: z.number(),
    graphictags: z.array(z.object({
      tagname: z.string(),
      confidence: z.number()
    })),
    page_image_url: z.string(),
    illustration_image_url: z.string()
  });

• src/server.ts:547-555 (registration)

  Registration of the tool with the MCP server under the name 'jp_lit_search_illustrations'.

  server.registerTool(
    "jp_lit_search_illustrations",
    {
      description: "NDL デジタルコレクション全資料の図版・挿絵をテキストキーワードで検索する（公開範囲のみ）。結果には IIIF 画像 URL（ページ全体・図版トリミング）を含む",
      inputSchema: searchIllustrationsInputSchema,
      outputSchema: searchIllustrationsOutputSchema
    },
    searchIllustrationsTool
  );