MCP Polib Server

A Model Context Protocol (MCP) server for reading, writing, and manipulating GNU Gettext .po files.

Overview

This project provides a FastAPI-based MCP server that exposes a set of tools for working with PO (Portable Object) translation files using the polib library. It integrates with FastMCP to expose all operations as MCP-compatible tools, enabling seamless integration with language models and AI agents.

Key Features

• File Operations: Read complete PO files or look up specific entries by context.
• Entry Management: Create, update, and modify PO entries with full context support (msgid, msgstr, comments, flags, occurrences).
• Partial Updates: Merge new entries into existing PO files without overwriting unrelated data.
• Fuzzy Entry Detection: Identify and list all entries flagged as "fuzzy" for review.
• Automatic Formatting: Apply powrap formatting after writes to maintain PO file standards.
• Dockerized Deployment: Ready-to-use Docker image with Python 3.12 and all dependencies pre-installed.
• MCP Transport Flexibility: Support for both stdio and http transports.

Available Tools

All endpoints operate on absolute file paths to PO files:

• read_po – Load all entries from a PO file.
• write_po – Create or update entries in a PO file. Merges intelligently: updates existing entries by msgid + msgctxt, appends new ones, and preserves unmodified entries. Auto-formats with powrap.
• read_po_context – Fetch a specific entry by msgid plus surrounding context (configurable window size).
• find_fuzzy – Return all entries marked with the "fuzzy" flag.

Tool Details

read_po

• Input: file_path (absolute path to .po file)
• Output: List of all PO entries with msgid, msgstr, comments, flags, and occurrences
• Use Case: Extract all translations from a file for review or processing

write_po

• Input: file_path and list of entries with msgid, msgstr, optional metadata
• Behavior:
  • If entry exists (same msgid + msgctxt), updates it
  • Otherwise, appends as new entry
  • Unmodified entries remain unchanged
  • Runs powrap --modified for automatic formatting
• Output: Success status and message (includes powrap errors if any)
• Use Case: Batch update or create translations

read_po_context

• Input: file_path, msgid, context_size (default: 1)
• Output: Target entry with surrounding entries before/after
• Use Case: View a translation with its neighboring context for better understanding

find_fuzzy

• Input: file_path
• Output: All entries marked as "fuzzy"
• Use Case: Find incomplete or uncertain translations for review

Getting Started

Local Development

1. Install dependencies:

   uv sync
   

2. Run the MCP server:

   # stdio transport (default)
   uv run fastmcp run mcp_tools/main.py
   

   # http transport
   uv run fastmcp run mcp_tools/main.py --transport http
   

3. Run tests:

   uv run pytest
   

Docker

1. Build the image:

   docker build -t mcp-polib:latest .
   

2. Run the container with stdio transport:

   docker run -i --rm mcp-polib:latest
   

3. Run the container with http transport:

   docker run --rm -p 8000:8000 mcp-polib:latest uv run fastmcp run mcp_tools/main.py --transport http
   

Configure in Claude Desktop

To use this server with Claude Desktop, add the following to your claude_desktop_config.json:

macOS:

{
  "mcpServers": {
    "mcp-polib": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/Users:/Users",
        "mcp-polib:latest"
      ]
    }
  }
}

Linux:

{
  "mcpServers": {
    "mcp-polib": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/home:/home",
        "mcp-polib:latest"
      ]
    }
  }
}

Windows:

{
  "mcpServers": {
    "mcp-polib": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "C:\\Users:C:\\Users",
        "mcp-polib:latest"
      ]
    }
  }
}

Project Structure

mcp-polib/
├── mcp_tools/
│   ├── main.py          # FastAPI app and MCP tool implementations
│   ├── schemas.py       # Pydantic models for request/response validation
│   └── __init__.py
├── tests/
│   ├── test_po_tools.py # Comprehensive test suite
│   └── test.po          # Sample PO file for testing
├── scripts/
│   ├── build_docs.sh    # Documentation build script
│   ├── build_image.sh   # Docker image build helper
│   ├── export_openapi.py # Extract OpenAPI spec
│   └── openapi_to_markdown.py # Convert OpenAPI to Markdown
├── docs/                # MkDocs documentation
├── Dockerfile           # Production-ready Docker image
├── pyproject.toml       # Project metadata and dependencies
└── README.md            # This file

Documentation

Full API documentation is available in:

• OpenAPI Spec: docs/reference/endpoints_swagger.md
• MkDocs: Run uv run mkdocs serve to view locally

To rebuild documentation:

chmod +x scripts/build_docs.sh
scripts/build_docs.sh
uv run mkdocs build

Technical Stack

• Framework: FastAPI + FastMCP
• PO File Handling: polib
• Package Manager: uv
• Container: Docker (Python 3.12, Bookworm slim)
• Formatting: powrap
• Testing: pytest
• Documentation: MkDocs