Florence-2 MCP Server

Instructions

Implementation Reference

• src/mcp_florence2/__init__.py:116-124 (handler)

  The primary MCP tool handler for 'ocr'. Accepts src (path/URL), loads images using get_images, and invokes the processor's ocr method via app lifespan context.
  @mcp.tool() def ocr( ctx: Context, src: PathLike | str = Field(description="A file path or URL to the image file that needs to be processed."), ) -> list[str]: """Process an image file or URL using OCR to extract text.""" with get_images(src) as images: app_ctx: AppContext = ctx.request_context.lifespan_context return app_ctx.processor.ocr(images)
• src/mcp_florence2/__init__.py:31-63 (helper)

  Helper context manager to load a list of PIL Images from src: supports local image/PDF files, HTTP(S) URLs to images/PDFs (renders PDF pages).
  @contextmanager def get_images(src: PathLike | str) -> Iterator[list[Image]]: """Opens and returns a list of images from a file path or URL.""" if isinstance(src, str) and (src.startswith("http://") or src.startswith("https://")): res = requests.get(src) res.raise_for_status() if res.headers["Content-Type"] == "application/pdf": pass with ExitStack() as stack: images = [] with closing(PdfDocument(res.content)) as doc: for page in doc: images.append(stack.enter_context(page.render().to_pil())) yield images else: with open_image(BytesIO(res.content)) as image: yield [image] else: ext = os.path.splitext(src)[1].lower() if ext == ".pdf": with ExitStack() as stack: images = [] with closing(PdfDocument(src)) as doc: for page in doc: images.append(stack.enter_context(page.render().to_pil())) yield images else: with open_image(src) as image: yield [image]
• src/mcp_florence2/florence2.py:50-79 (helper)

  Core Florence2 processor implementation: ocr() calls generate("<OCR>", images), which processes each image using the transformers Florence2 model to generate and parse OCR text.
  def ocr(self, images: list[Image]) -> list[str]: return self.generate("<OCR>", images) def caption(self, images: list[Image], level: CaptionLevel = CaptionLevel.NORMAL) -> list[str]: return self.generate(str(level.value), images) def generate(self, prompt: str, images: list[Image]) -> list[str]: res = [] for img in images: with img.convert("RGB") as rgb_img: inputs = self.processor(text=prompt, images=rgb_img, return_tensors="pt").to( self.device, self.torch_dtype ) generated_ids = self.model.generate( input_ids=inputs["input_ids"], pixel_values=inputs["pixel_values"], max_new_tokens=1024, num_beams=3, do_sample=False, ) generated_text = self.processor.batch_decode(generated_ids, skip_special_tokens=False)[0] parsed_answer = self.processor.post_process_generation( generated_text, task=prompt, image_size=(rgb_img.width, rgb_img.height) ) res.append(parsed_answer[prompt].strip()) return res
• src/mcp_florence2/__init__.py:112-137 (registration)

  Factory function to create and configure the FastMCP server instance, including lifespan for processor initialization and registration of 'ocr' and 'caption' tools via @mcp.tool() decorators.
  def server(name: str, model_id: str, subprocess: bool = True) -> FastMCP: """Creates a new FastMCP server instance with the specified name and model ID.""" mcp = FastMCP(name, lifespan=partial(app_lifespan, model_id=model_id, subprocess=subprocess)) @mcp.tool() def ocr( ctx: Context, src: PathLike | str = Field(description="A file path or URL to the image file that needs to be processed."), ) -> list[str]: """Process an image file or URL using OCR to extract text.""" with get_images(src) as images: app_ctx: AppContext = ctx.request_context.lifespan_context return app_ctx.processor.ocr(images) @mcp.tool() def caption( ctx: Context, src: PathLike | str = Field(description="A file path or URL to the image file that needs to be processed."), ) -> list[str]: """Processes an image file and generates captions for the image.""" with get_images(src) as images: app_ctx: AppContext = ctx.request_context.lifespan_context return app_ctx.processor.caption(images, CaptionLevel.MORE_DETAILED) return mcp
• src/mcp_florence2/__init__.py:117-119 (schema)

  Input schema for 'ocr' tool: parameter 'src' (PathLike | str) with description, using pydantic Field for validation in MCP.
  def ocr( ctx: Context, src: PathLike | str = Field(description="A file path or URL to the image file that needs to be processed."),