| name | generating-grpc-services |
| description | Generate gRPC service definitions, stubs, and implementations from Protocol Buffers.
Use when creating high-performance gRPC services.
Trigger with phrases like "generate gRPC service", "create gRPC API", or "build gRPC server".
|
| allowed-tools | Read, Write, Edit, Grep, Glob, Bash(api:grpc-*) |
| version | 1.23.0 |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
| license | MIT |
| tags | ["api","performance","grpc-services"] |
| compatibility | Designed for Claude Code, also compatible with Codex and OpenClaw |
Generating gRPC Services
Overview
Generate gRPC service definitions, client/server stubs, and implementations from Protocol Buffer (protobuf) .proto files. Scaffold unary, server-streaming, client-streaming, and bidirectional-streaming RPC methods with proper error status codes, interceptors for auth/logging, and health check service registration.
Prerequisites
- Protocol Buffers compiler (
protoc) v3.21+ installed
- Language-specific gRPC plugin:
grpc_tools_node_protoc_plugin (Node.js), grpcio-tools (Python), or Go gRPC plugin
buf CLI for proto linting and breaking change detection (recommended)
- gRPC testing tool:
grpcurl, evans, or BloomRPC
- TLS certificates for production transport security (mTLS recommended for service-to-service)
Instructions
- Read existing
.proto files using Glob and Read, or design new service definitions with message types, RPC methods, and streaming patterns per service requirements.
- Define proto3 message types with appropriate field types, using
google.protobuf.Timestamp for dates, google.protobuf.Struct for dynamic fields, and oneof for polymorphic messages.
- Compile
.proto files with protoc to generate language-specific stubs, server interfaces, and client libraries using the appropriate gRPC plugin.
- Implement server-side RPC handlers for each method, returning proper gRPC status codes (
OK, NOT_FOUND, INVALID_ARGUMENT, PERMISSION_DENIED) instead of generic errors.
- Add server interceptors for authentication (extracting JWT from metadata), request logging with correlation IDs, and deadline propagation across service calls.
- Implement health check service (
grpc.health.v1.Health) and reflection service for runtime introspection by tools like grpcurl.
- Configure TLS transport security, preferring mutual TLS (mTLS) for service-to-service communication with certificate rotation support.
- Write integration tests using an in-process test server, validating all RPC methods including streaming scenarios with multiple messages and error conditions.
- Generate a REST-to-gRPC gateway using
grpc-gateway annotations for HTTP/JSON clients that need to access gRPC services.