fix(docs): MCP guide omits built-in analysis editing tools

Aberta
#8,712 0 comentários 0 reações 0 responsáveis Ver no GitHub

Mantenedores costumam responder em até 2 dias

Ninguém assumiu esta issue ainda.

Avaliação

Dificuldade
1/5
Tempo estimado
1-3 horas
Facilidade para iniciantes
20/100
Tipo de issue
Documentação
Clareza
Claramente especificada
Status de atividade
Ativa
Stack de tecnologia
markdown
Domínio
documentation

Direção de pesquisa

Read docs/guide/mcp.md at the Introduction, Tool Overview, and Headless Server sections, then compare the descriptions with the supplied saved tools/list excerpt. The guide needs to acknowledge built-in analysis editing, with representative comment, name, or type operations, while keeping read-only wording scoped to inspection. The linked open PR #8701 already contains changes addressing this issue, so check its status before starting.

Escrita pelo modelo de indexação a partir do texto da issue.

Descrição

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

  1. Read the introduction, Tool Overview, and Headless Server sections in either pinned guide listed under Runtime or environment.
  2. Compare the overview with the supplied GUI server's tools/list response excerpt below. Its editing tools are not represented by any overview category.
  3. 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/list response 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 serverInfo name binaryninja_ui_mcp, server version 0.1.0, protocol version 2025-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.
Linguagem predominante
C++
Estrelas
1.3k
Forks
304
Merge médio
2d 20h
PRs com merge (30d)
10

Preparar o ambiente

Este projeto não oferece contêiner de desenvolvimento, Dockerfile nem guia de contribuição, então a configuração fica por sua conta: comece pelo README e veja nosso guia da primeira contribuição para os passos gerais.

Primeiros passos

  1. Leia a issue inteira e depois o guia de contribuição do projeto.
  2. Comente na issue dizendo que vai assumir — evita que duas pessoas façam o mesmo trabalho.
  3. Faça um fork do repositório e trabalhe em uma branch.
  4. Abra um pull request que referencie o número da issue.

Mais de Vector35/binaryninja-api

Todas as issues de Vector35/binaryninja-api

Issues semelhantes

Mais issues de C++

Receba novas issues na sua caixa de entrada

Um resumo curto de issues do GitHub para quem está começando.