pydantic-rpc

PydanticRPC is a Python library that lets you expose Pydantic models and simple Python services as both gRPC and Connect-RPC endpoints without writing protobuf files. It automatically generates protobuf definitions on the fly from your Python type annotations and Pydantic models, and it can expose these services as traditional gRPC servers or Connect-RPC endpoints (including ASGI/WSGI applications). You can create synchronous or asynchronous services, and you can mount them as gRPC services or Connect-RPC services depending on your app needs. The library also supports MCP (Model Context Protocol) by exposing these services as tools for AI assistants via the official MCP SDK, enabling both stdio and HTTP/SSE transports for tool consumption.

To use it, define your request/response message classes by subclassing the provided Message type (which is an alias for Pydantic's BaseModel), implement your service methods, and then run the server (either the AsyncIOServer for async services or the standard Server for sync services). For Connect-RPC you can expose the same service via ASGIApp or WSGI apps. The project also includes a CLI (pip install pydantic-rpc-cli) to run built-in server runners if you prefer a quick start without writing boilerplate code.

Key workflows include:

• Exposing a Python class with methods that take request messages and return response messages, automatically handling marshaling/validation via Pydantic.
• Serving via gRPC with optional health checks and server reflection.
• Serving via Connect-RPC with full streaming patterns (unary, server/client/bidirectional) and ASGI/WSGI compatibility.
• Generating and exporting protobuf definitions for cross-language use, and optionally skipping generation with environment control.

Prerequisites:

• Python 3.8+ (recommended)
• Access to pip

Installation steps:

1. Create and activate a Python virtual environment (optional but recommended):

python -m venv venv
source venv/bin/activate  # on Unix/macOS
# Windows: venv\Scripts\activate

2. Install PydanticRPC (core library):

pip install pydantic-rpc

3. (Optional) Install CLI support for built-in server runners (Hypercorn/Gunicorn, etc.):

pip install pydantic-rpc-cli  # Includes CLI tools for server runners

4. Verify installation:

python -c "import pydantic_rpc; print('pydantic_rpc version:', pydantic_rpc.__version__)"

Tips and caveats:

• If you plan to expose as a CLI service using the built-in runners, ensure you have the CLI package installed (pydantic-rpc-cli).
• For Connect-RPC with ASGI/WSGI, you can run the app via standard ASGI servers (e.g., Hypercorn, Uvicorn) or WSGI servers, depending on whether you need HTTP/2 or streaming features.
• You can export generated protobuf files for cross-language use and set PYDANTIC_RPC_SKIP_GENERATION to skip runtime generation if you want to rely on pre-generated protos.
• MCP support lets your services appear as tools to AI assistants; ensure you configure package_name and proper initialization if you’re packaging for MCP usage.
• If you encounter transport or streaming issues, verify your HTTP/2 support (some servers require specific backends for bidirectional streaming) and consult the Connect-RPC guidance in the docs for endpoint path formats and content types.