Thrift — 18 Operations for AI Agents
Thrift IDL defines the RPC contracts that hold service architectures together. act101 maps services, structs, and exceptions as structure, so agents trace an interface across definitions instead of grepping for type names.
This page is the canonical reference an AI coding agent uses to refactor, query, and analyze Thrift code through the act MCP server. 18 operations available: 0 refactor, 18 query, 0 analysis. 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 Thrift examples
act101 reads a Thrift file's namespace declaration, struct/exception definitions, and service definition as declarations: the namespace's dotted segments are concatenated into one name, structs and exceptions are tagged struct, and the service is tagged interface. symbols covers the struct, exception, and service, adds each service method as function, and adds every struct/exception field — but reports every field's kind as class, the same kind as its enclosing struct, rather than field, since the field rule captures the struct itself rather than the field. The unit of structure skeleton exposes is the top-level definition; symbols reaches one level deeper, into methods and fields, but not into a method's own parameters. Each example below is the verbatim output of the command shown, run against the file shown. Query outputs are pretty-printed with the timing block omitted.
Read the namespace, struct, exception, and service as a skeleton
hotel.thrift defines a hotel reservation RPC: a Reservation struct, a RoomUnavailable exception thrown when a room is already booked, and a ReservationService with bookRoom/cancelReservation methods.
$ act query skeleton hotel.thriftBefore
namespace java com.example.hotel
struct Reservation {
1: required string guestName;
2: required string roomNumber;
3: optional i32 nights = 1;
}
exception RoomUnavailable {
1: required string roomNumber;
2: optional string reason;
}
service ReservationService {
Reservation bookRoom(1: string guestName, 2: string roomNumber) throws (1: RoomUnavailable unavailable);
void cancelReservation(1: string reservationId);
}Output
{
"type": "Skeleton",
"declarations": [
{
"kind": "namespace",
"name": "com.example.hotel",
"range": {
"start": {
"file": "hotel.thrift",
"line": 1,
"column": 1,
"byte_offset": 0
},
"end": {
"file": "hotel.thrift",
"line": 1,
"column": 33,
"byte_offset": 32
}
},
"name_range": {
"start": {
"file": "hotel.thrift",
"line": 1,
"column": 16,
"byte_offset": 15
},
"end": {
"file": "hotel.thrift",
"line": 1,
"column": 19,
"byte_offset": 18
}
}
},
{
"kind": "struct",
"name": "Reservation",
"range": {
"start": {
"file": "hotel.thrift",
"line": 3,
"column": 1,
"byte_offset": 34
},
"end": {
"file": "hotel.thrift",
"line": 7,
"column": 2,
"byte_offset": 151
}
},
"name_range": {
"start": {
"file": "hotel.thrift",
"line": 3,
"column": 8,
"byte_offset": 41
},
"end": {
"file": "hotel.thrift",
"line": 3,
"column": 19,
"byte_offset": 52
}
}
},
{
"kind": "struct",
"name": "RoomUnavailable",
"range": {
"start": {
"file": "hotel.thrift",
"line": 9,
"column": 1,
"byte_offset": 153
},
"end": {
"file": "hotel.thrift",
"line": 12,
"column": 2,
"byte_offset": 244
}
},
"name_range": {
"start": {
"file": "hotel.thrift",
"line": 9,
"column": 11,
"byte_offset": 163
},
"end": {
"file": "hotel.thrift",
"line": 9,
"column": 26,
"byte_offset": 178
}
}
},
{
"kind": "interface",
"name": "ReservationService",
"range": {
"start": {
"file": "hotel.thrift",
"line": 14,
"column": 1,
"byte_offset": 246
},
"end": {
"file": "hotel.thrift",
"line": 17,
"column": 2,
"byte_offset": 434
}
},
"name_range": {
"start": {
"file": "hotel.thrift",
"line": 14,
"column": 9,
"byte_offset": 254
},
"end": {
"file": "hotel.thrift",
"line": 14,
"column": 27,
"byte_offset": 272
}
}
}
]
}The skeleton reports com.example.hotel as namespace, Reservation and RoomUnavailable as struct, and ReservationService as interface — the fields inside Reservation/RoomUnavailable and the methods inside ReservationService are not read.
List the service methods and struct fields as symbols
Reservation carries three fields, guestName, roomNumber, and nights; RoomUnavailable carries roomNumber and reason.
$ act query symbols hotel.thriftBefore
namespace java com.example.hotel
struct Reservation {
1: required string guestName;
2: required string roomNumber;
3: optional i32 nights = 1;
}
exception RoomUnavailable {
1: required string roomNumber;
2: optional string reason;
}
service ReservationService {
Reservation bookRoom(1: string guestName, 2: string roomNumber) throws (1: RoomUnavailable unavailable);
void cancelReservation(1: string reservationId);
}Output
{
"type": "Symbols",
"symbols": [
{
"name": "Reservation",
"kind": "class",
"range": {
"start": {
"file": "hotel.thrift",
"line": 3,
"column": 8,
"byte_offset": 41
},
"end": {
"file": "hotel.thrift",
"line": 3,
"column": 19,
"byte_offset": 52
}
},
"visibility": "unknown"
},
{
"name": "guestName",
"kind": "class",
"range": {
"start": {
"file": "hotel.thrift",
"line": 4,
"column": 22,
"byte_offset": 76
},
"end": {
"file": "hotel.thrift",
"line": 4,
"column": 31,
"byte_offset": 85
}
},
"visibility": "unknown"
},
{
"name": "roomNumber",
"kind": "class",
"range": {
"start": {
"file": "hotel.thrift",
"line": 5,
"column": 22,
"byte_offset": 108
},
"end": {
"file": "hotel.thrift",
"line": 5,
"column": 32,
"byte_offset": 118
}
},
"visibility": "unknown"
},
{
"name": "nights",
"kind": "class",
"range": {
"start": {
"file": "hotel.thrift",
"line": 6,
"column": 19,
"byte_offset": 138
},
"end": {
"file": "hotel.thrift",
"line": 6,
"column": 25,
"byte_offset": 144
}
},
"visibility": "unknown"
},
{
"name": "RoomUnavailable",
"kind": "class",
"range": {
"start": {
"file": "hotel.thrift",
"line": 9,
"column": 11,
"byte_offset": 163
},
"end": {
"file": "hotel.thrift",
"line": 9,
"column": 26,
"byte_offset": 178
}
},
"visibility": "unknown"
},
{
"name": "roomNumber",
"kind": "class",
"range": {
"start": {
"file": "hotel.thrift",
"line": 10,
"column": 22,
"byte_offset": 202
},
"end": {
"file": "hotel.thrift",
"line": 10,
"column": 32,
"byte_offset": 212
}
},
"visibility": "unknown"
},
{
"name": "reason",
"kind": "class",
"range": {
"start": {
"file": "hotel.thrift",
"line": 11,
"column": 22,
"byte_offset": 235
},
"end": {
"file": "hotel.thrift",
"line": 11,
"column": 28,
"byte_offset": 241
}
},
"visibility": "unknown"
},
{
"name": "ReservationService",
"kind": "interface",
"range": {
"start": {
"file": "hotel.thrift",
"line": 14,
"column": 9,
"byte_offset": 254
},
"end": {
"file": "hotel.thrift",
"line": 14,
"column": 27,
"byte_offset": 272
}
},
"visibility": "unknown"
},
{
"name": "bookRoom",
"kind": "function",
"range": {
"start": {
"file": "hotel.thrift",
"line": 15,
"column": 15,
"byte_offset": 289
},
"end": {
"file": "hotel.thrift",
"line": 15,
"column": 23,
"byte_offset": 297
}
},
"visibility": "unknown"
},
{
"name": "cancelReservation",
"kind": "function",
"range": {
"start": {
"file": "hotel.thrift",
"line": 16,
"column": 8,
"byte_offset": 389
},
"end": {
"file": "hotel.thrift",
"line": 16,
"column": 25,
"byte_offset": 406
}
},
"visibility": "unknown"
}
]
}symbols drops the namespace and adds bookRoom/cancelReservation as function and all five struct/exception fields — but every field comes back kind: class, the same kind reported for Reservation and RoomUnavailable themselves, rather than field.
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