Repository navigation
fix(docs): MCP guide omits built-in analysis editing tools #8712
Description
Summary
The MCP guide's introduction, tool-category overview, and headless-server description cover BinaryView inspection but omit the built-in analysis editing tools advertised by the shipped GUI server. This is a documentation completeness issue: the guide does not say that clients can edit comments, names, and types through the built-in MCP tools. The read-only wording can describe the inspection subset accurately; this report does not interpret it as an explicit guarantee that the entire server is read-only.
Steps to reproduce
- Read the introduction, Tool Overview, and Headless Server sections in either pinned guide listed under Runtime or environment.
- Compare the overview with the supplied GUI server's
tools/listresponse excerpt below. Its editing tools are not represented by any overview category. - Optionally verify the advertisement on an installation matching the supplied runtime: enable and start the GUI MCP server using the guide, connect an MCP client, and inspect its tool listing. This optional live rerun was not executed for this report; the supplied saved response was inspected directly. No mutation call is required to observe the documentation omission.
Expected behavior
The MCP capability overview should identify the built-in analysis editing category as well as inspection and file-management categories, so readers can understand that the server offers tools for changing analysis data. It need not enumerate every tool. Read-only terminology should remain scoped to inspection tools rather than serving as the only description of BinaryView capabilities.
Actual behavior
Both pinned guides describe querying read-only BinaryView information and list six tool categories covering management, analysis control, overview, structure, memory inspection, and function inspection. Neither overview mentions analysis editing. The headless description likewise mentions the file manager and read-only inspection subset. The guide does direct users to their client's tool listing for the complete inventory, which is a practical workaround.
The supplied saved GUI response contains 75 advertised tools, including the following excerpt. These names, descriptions, and required input fields were read from that response; no successful editing operation is claimed.
| Tool | Advertised operation | Required input fields |
|---|---|---|
bn_comment_set |
Set an address comment | comment, text |
bn_comment_delete |
Delete an address comment | comment |
bn_symbol_rename |
Define a renamed user symbol | symbol, newName |
bn_type_define |
Parse C source and define user types | source |
bn_function_prototype_set |
Set a user function prototype | function, prototype |
bn_variable_set_type |
Set a function variable's type | function, variable |
bn_section_create |
Create a persistent user-defined section | section, start, length |
Evidence
- Expected source:
docs/guide/mcp.md, Introduction and Tool Overview, presents the server's purpose and broad tool categories; the repository's documentation intake explicitly accepts confusing or missing concept/API documentation. - Failure source: Both pinned guides, lines 3 and 12–23, omit analysis editing; the supplied saved GUI
tools/listresponse advertises the editing operations summarized above. A maintainer also confirms built-in symbol/type editing tools in the closed issue listed under References. - Evidence provenance: supplied
- Local verification: not-run
- Reproduction completeness: complete
The primary runtime evidence is the supplied saved tool advertisement. Both public source documents and tracker context were inspected directly, and the source comparison and saved-response extraction were executed. A fresh live MCP session was not run, and mutation execution was not attempted. Reproduction is complete for the documentation omission versus the supplied advertisement; successful writes and headless runtime behavior are outside this report's claim.
Restoration check
Read the guide's introduction, Tool Overview, and server-variant descriptions and compare them with the built-in tool advertisement. Passing documentation should acknowledge analysis editing, including representative comment/name/type operations, while keeping read-only descriptions scoped to inspection tools. This does not require changing tool behavior or removing read-only descriptions that correctly describe an inspection subset.
Runtime or environment
- Latest published release inspected:
stable/6.0.10905; stable MCP guide. - Current default branch inspected:
dev; default-branch MCP guide. - Supplied live capture: Binary Ninja Free GUI on macOS, matching the stable product release above; MCP
serverInfonamebinaryninja_ui_mcp, server version0.1.0, protocol version2025-11-25. - No current development runtime or headless runtime was tested; the current development documentation was inspected directly.
Documentation intake details
- Is this a general concept or a specific API? The built-in MCP server capability overview, specifically analysis editing.
- What concept needs more documentation? The presence of built-in tools that edit comments, symbols, types, variables, function prototypes, and sections.
- Is this related to a specific API? The MCP interface, rather than the C++, Python, or Rust API reference.
- Are there known examples? The supplied tool advertisement above and the public maintainer confirmation linked under References establish the existing capability. No separate client example or successful write is asserted.
References
- Closed issue #8554: the maintainer confirms that symbol renaming and type editing are already available; its closure resolves a request for write functionality, not the guide's missing capability description. This report requests documentation of existing tools.
- Open PR #8701: its current diff already adds an Analysis editing category and updates the introduction and headless description. It is not merged into the inspected default branch; the relevant documentation changes appear to address this report.
Triage assessment
- Impact level: P3
- Assessment status: supported
- Impact basis: This is an omission in capability documentation. The evidence does not demonstrate failed edits, unexpected writes, data loss, a security boundary violation, or a blocked workflow.
- Workaround status: available
- Workaround basis: The guide already directs readers to the client's tool listing, and the supplied saved response exposes the editing tool names and input schemas without requiring a mutation call.
Activity