radare2-mcp: Instructions file for Codex

Agentic Coding Guidelines for r2mcp

MCP server for radare2. Source lives in src/. Files named *.inc.c are #included into other .c files — they are not separate compilation units.

Build & Test

• make -j — fast incremental build (from repo root)
• make asan — AddressSanitizer build
• make fmt — auto-format with clang-format-radare2
• src/r2mcp -h — CLI help
• src/r2mcp -t — list available tools
• src/r2mcp -T 'open_file file_path="/bin/ls"; list_functions; close_file' — run DSL tests
• make test — run test suite (test.sh, test2.sh)

Code Style

• Tabs for indentation
• Space before parens: foo (), if (, for (
• Always use braces {} even for single-statement blocks
• Declare loop variables before for (C89 style)
• Declare local variables and assign in the same line if possible
• Prefer !strcmp () over strcmp () == 0
• Prefer r_str_startswith () over !strncmp ()
• Use R_STR_ISEMPTY() / R_STR_ISNOTEMPTY() instead of manual null+empty checks
• Use R_RETURN_VAL_IF_FAIL() / R_RETURN_IF_FAIL() for preconditions in R_API functions
• Use R_LOG_ERROR(), R_LOG_WARN(), R_LOG_INFO() for diagnostics

Memory

• R_NEW() / R_NEW0() — assumed never to return NULL
• R_FREE(ptr) — frees and sets to NULL
• No NULL-check before free() or *_free() helpers
• r_str_newf() for formatted string allocation (not manual malloc+snprintf)
• RStrBuf for building strings in loops:

  RStrBuf *sb = r_strbuf_new ("");
  r_strbuf_appendf (sb, "...", ...);
  return r_strbuf_drain (sb); // caller frees
  

• r_json_parse() does NOT own the input buffer — caller must free it separately after r_json_free()

JSON (PJ API)

Build JSON responses with the pj_* helpers:

PJ *pj = pj_new ();
pj_o (pj);           // open object
pj_ks (pj, "type", "text"); // key-string
pj_ki (pj, "count", 5);     // key-int
pj_kb (pj, "ok", true);     // key-bool
pj_k (pj, "items"); pj_a (pj); /* ... */ pj_end (pj); // key + array
pj_end (pj);         // close object
return pj_drain (pj); // extract string, free builder