ProtoBuf — 101 Operations for AI Agents

This page is the canonical reference an AI coding agent uses to refactor, query, and analyze ProtoBuf code through the act MCP server. 101 operations available: 27 refactor, 18 query, 42 analysis, 14 verification. Each operation is callable from Claude Code, Cursor, Codex, OpenCode, or any MCP-compatible agent host. Click any operation for a stable anchor link suitable for citation.

Worked ProtoBuf examples

act101 parses ProtoBuf schema files with the tree-sitter grammar and edits service, message, enum, and import blocks as syntax nodes, so a generated RPC or extracted message lands with a correctly renumbered field list rather than a raw text splice. It can append a new RPC method to a named service block, given its request and response types. It can extract a set of fields from a message into a new, separate message type, replacing them with a single field of the new type and renumbering what remains. It can sort a file's import statements alphabetically and drop duplicates. And it can append a new constant to an enum block with an explicit numeric value. Each example below is the verbatim output of the command shown, run against the file shown.

Add an RPC method to a service

user_service.proto's UserService declares GetUserRequest/GetUserResponse messages but the service block itself is empty.

$ act refactor-lang add_rpc_method --file user_service.proto --params '{"service_name":"UserService","method_name":"GetUser","request_type":"GetUserRequest","response_type":"GetUserResponse","line":5,"column":9}'

Before

syntax = "proto3";

package example;

service UserService {
}

message GetUserRequest {
  string user_id = 1;
}

message GetUserResponse {
  string name = 1;
  string email = 2;
}

After

syntax = "proto3";

package example;

service UserService {
  rpc GetUser (GetUserRequest) returns (GetUserResponse);
}

message GetUserRequest {
  string user_id = 1;
}

message GetUserResponse {
  string name = 1;
  string email = 2;
}

rpc GetUser (GetUserRequest) returns (GetUserResponse); is appended inside the service block.

Extract fields into a new message

order.proto's Order message carries street, city, and zip as individual top-level fields.

$ act refactor-lang extract_message --file order.proto --params '{"source_message":"Order","fields_to_extract":["street","city","zip"],"new_message_name":"ShippingAddress","line":7,"column":10}'

Before

syntax = "proto3";

package example;

message Order {
  string id = 1;
  string street = 2;
  string city = 3;
  string zip = 4;
}

After

syntax = "proto3";

package example;

message Order {
  string id = 1;
  ShippingAddress shipping_address = 5;
}

message ShippingAddress {
  string street = 1;
  string city = 2;
  string zip = 3;
}

The three fields are replaced by a single ShippingAddress shipping_address = 5; field, and a new ShippingAddress message declares them with fresh field numbers 1-3.

Sort and deduplicate imports

event.proto imports three google/protobuf well-known types in reverse alphabetical order.

$ act refactor-lang organize_imports --file event.proto --params '{"line":1,"column":1}'

Before

syntax = "proto3";

package example;

import "google/protobuf/wrappers.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/any.proto";

message Event {
  string id = 1;
}

After

syntax = "proto3";

package example;

import "google/protobuf/any.proto";
import "google/protobuf/timestamp.proto";
import "google/protobuf/wrappers.proto";

message Event {
  string id = 1;
}

The three import statements are reordered alphabetically; nothing else in the file changes.

Add an enum value with an explicit number

error_code.proto's ErrorCode enum defines ERROR_NONE, ERROR_NOT_FOUND, and ERROR_PERMISSION_DENIED at numbers 0 through 2.

$ act refactor-lang add_enum_value --file error_code.proto --params '{"enum_name":"ErrorCode","value_name":"ERROR_DELETED","value_number":99,"line":5,"column":6}'

Before

syntax = "proto3";

package example;

enum ErrorCode {
  ERROR_NONE = 0;
  ERROR_NOT_FOUND = 1;
  ERROR_PERMISSION_DENIED = 2;
}

After

syntax = "proto3";

package example;

enum ErrorCode {
  ERROR_NONE = 0;
  ERROR_NOT_FOUND = 1;
  ERROR_PERMISSION_DENIED = 2;
  ERROR_DELETED = 99;
}

ERROR_DELETED = 99; is appended inside the enum block, using the explicit number 99 instead of the next sequential value.

Query

18 query tools, the same on every supported language. Descriptions live in the shared reference: /docs/query-tools.

callers control_flow data_flow definition diagnostics effect_closure effect_summary fix_auto get_type graph import_organize interface mutations references repo_outline skeleton symbols symbols_batch

Refactor

Analysis

42 analysis tools, the same on every supported language. Descriptions live in the shared reference: /docs/analysis-tools.

analyze_api_diff analyze_chokepoints analyze_clones analyze_clusters analyze_cohesion analyze_conformance analyze_coupling analyze_cycle_risk analyze_cycles analyze_dead_code analyze_depth analyze_entry_points analyze_export analyze_extraction analyze_fan_balance analyze_features analyze_hotspots analyze_impact analyze_inconsistencies analyze_inheritance analyze_interface_bloat analyze_interfaces analyze_layers analyze_orphan_types analyze_patterns analyze_platform_deps analyze_readiness analyze_roles analyze_seams analyze_stability analyze_surface analyze_test_gaps analyze_thickness analyze_type_completeness churn_hotspots co_change_clusters coverage_overlay ownership_map profile_overlay simulate split_module trace_overlay

Verify

14 verify tools, the same on every supported language. Descriptions live in the shared reference: /docs/verification.

bisect_regression gate generate_test_harness scan secret_surface summarize_pr taint_flow unsafe_surface verify_behavioral_equivalence verify_contract_preserved verify_diff_semantics verify_port_parity verify_side_effects verify_test_impact