nvda-mcp 1.0.0__tar.gz

nvda_mcp-1.0.0/.gitignore

@@ -0,0 +1,41 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+
+# Node.js
+node_modules/
+.astro/
+.next/
+.cache/
+npm-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+# Secrets and local settings: never commit these
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+
+# Editors and operating systems
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# This project
+# Compiled translations; build_addon.py makes them from the .po files.
+*.mo
+# NVDA documents downloaded for reference. They belong to their authors; see README.md for where they come from.
+docs/reference/

nvda_mcp-1.0.0/CHANGELOG.md

@@ -0,0 +1,58 @@
+# Changelog
+
+All notable changes to NVDA MCP are listed here.
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and versions follow [Semantic Versioning](https://semver.org/).
+The add-on (`addon/manifest.ini`) and the server (`pyproject.toml`) share one version number;
+install them together.
+
+## [1.0.0] - 2026-11-02
+
+First release, on the NV Access Add-on Store and PyPI.
+
+### Added
+
+- An NVDA add-on with a loopback bridge protected by a per-start token, and an MCP server published on PyPI
+  as `nvda-mcp`. It runs with `uvx nvda-mcp`, `pipx install nvda-mcp` or `python -m nvda_mcp`.
+- NVDA MCP settings: *Set up this MCP client* and **Copy setup command** copy the command (Claude Code, Codex CLI)
+  or the JSON settings (Claude Desktop, Cursor and others) that start the server version matching the add-on.
+- Reading: `nvda_get_status`, `nvda_get_focus` (with `documentMode`, browse or focus), `nvda_get_navigator_object`,
+  `nvda_get_object_tree` (at most `max_children` children of each object), `nvda_get_text` (with `contains`
+  to search without moving the cursor) and `nvda_get_speech_history`.
+- Speech: `nvda_speak`, and `nvda_wait_for_speech` to wait until NVDA says something, such as a chat reply.
+- Keys and typing: `nvda_press_keys` presses keys as the user would, so NVDA runs its command for a key first,
+  and takes `hold` to keep alt, control, shift or windows down across several keys. `nvda_type_text` types
+  a line of text in any language, emoji included, without using the clipboard.
+- Windows: `nvda_list_windows`, optionally including other virtual desktops, and `nvda_activate_window`.
+- Controls: `nvda_find_objects`, `nvda_focus_object` and `nvda_activate_object`; `nvda_audit_focus_order`.
+- Web pages and documents: `nvda_set_document_mode`, `nvda_find_in_page`, and `nvda_list_elements` and
+  `nvda_move_to_element`, like the Elements List.
+- Expected results: every action tool takes `until_speech`, keeps listening until NVDA says that text,
+  and reports whether it was heard.
+- Tools for developers of NVDA add-ons and accessible applications:
+  - `nvda_preview_speech` says what NVDA would announce when a control gets focus, without moving focus.
+    With `target: "window"` it checks the focused control and the controls of the foreground window,
+    and flags unlabeled and silent ones.
+  - `nvda_trace_events` records the events NVDA handles and what NVDA said for each, including speech that comes
+    just before or after an event, such as a browser's live region. It stops by itself after 10 minutes.
+  - `nvda_get_log` reads NVDA's log; IO entries, which record keys typed, are left out unless asked for.
+  - `nvda_get_output_history` shows beeps, sounds, braille output and speech being cut off.
+  - `nvda_get_dev_info` shows NVDA's developer info for a control, like NVDA+F1.
+  - `nvda_list_scripts` lists the NVDA commands available where focus is, or says which command a key runs.
+  - `nvda_run_script` runs an NVDA command by name; `nvda_reload_plugins` reloads add-ons and app modules.
+  - `nvda_get_settings` reads NVDA's settings as they apply now. Values whose names suggest secrets are hidden.
+  - `nvda_run_scenario` runs key presses and typing, records what NVDA said after each step, and saves it
+    as a baseline file or compares it with one.
+- Safety:
+  - Pressing keys is off by default. NVDA asks before the first key press after it starts, in a dialog whose
+    title names the MCP client asking.
+  - A setting to let MCP clients control only some applications.
+  - A log of every action clients take (`%APPDATA%\nvda\nvdaMcp\actions.log`), with a setting to turn it off,
+    an NVDA command to open it and the `nvda_get_action_log` tool.
+  - When the add-on and the server don't match, the error says which one is older and how to update it.
+- A **Donate** button in the NVDA MCP settings, and donation links on GitHub, PyPI and in the README.
+- Help pages and translation in English and Indonesian.
+- [docs/using.md](docs/using.md), [CONTRIBUTING.md](CONTRIBUTING.md) and
+  [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+[1.0.0]: https://github.com/InfiArtt/nvda-mcp/releases/tag/v1.0.0

nvda_mcp-1.0.0/COPYING.txt

@@ -0,0 +1,338 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 2, June 1991
+
+ Copyright (C) 1989, 1991 Free Software Foundation, Inc.,
+ <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The licenses for most software are designed to take away your
+freedom to share and change it.  By contrast, the GNU General Public
+License is intended to guarantee your freedom to share and change free
+software--to make sure the software is free for all its users.  This
+General Public License applies to most of the Free Software
+Foundation's software and to any other program whose authors commit to
+using it.  (Some other Free Software Foundation software is covered by
+the GNU Lesser General Public License instead.)  You can apply it to
+your programs, too.
+
+  When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+this service if you wish), that you receive source code or can get it
+if you want it, that you can change the software or use pieces of it
+in new free programs; and that you know you can do these things.
+
+  To protect your rights, we need to make restrictions that forbid
+anyone to deny you these rights or to ask you to surrender the rights.
+These restrictions translate to certain responsibilities for you if you
+distribute copies of the software, or if you modify it.
+
+  For example, if you distribute copies of such a program, whether
+gratis or for a fee, you must give the recipients all the rights that
+you have.  You must make sure that they, too, receive or can get the
+source code.  And you must show them these terms so they know their
+rights.
+
+  We protect your rights with two steps: (1) copyright the software, and
+(2) offer you this license which gives you legal permission to copy,
+distribute and/or modify the software.
+
+  Also, for each author's protection and ours, we want to make certain
+that everyone understands that there is no warranty for this free
+software.  If the software is modified by someone else and passed on, we
+want its recipients to know that what they have is not the original, so
+that any problems introduced by others will not reflect on the original
+authors' reputations.
+
+  Finally, any free program is threatened constantly by software
+patents.  We wish to avoid the danger that redistributors of a free
+program will individually obtain patent licenses, in effect making the
+program proprietary.  To prevent this, we have made it clear that any
+patent must be licensed for everyone's free use or not licensed at all.
+
+  The precise terms and conditions for copying, distribution and
+modification follow.
+
+                    GNU GENERAL PUBLIC LICENSE
+   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
+
+  0. This License applies to any program or other work which contains
+a notice placed by the copyright holder saying it may be distributed
+under the terms of this General Public License.  The "Program", below,
+refers to any such program or work, and a "work based on the Program"
+means either the Program or any derivative work under copyright law:
+that is to say, a work containing the Program or a portion of it,
+either verbatim or with modifications and/or translated into another
+language.  (Hereinafter, translation is included without limitation in
+the term "modification".)  Each licensee is addressed as "you".
+
+Activities other than copying, distribution and modification are not
+covered by this License; they are outside its scope.  The act of
+running the Program is not restricted, and the output from the Program
+is covered only if its contents constitute a work based on the
+Program (independent of having been made by running the Program).
+Whether that is true depends on what the Program does.
+
+  1. You may copy and distribute verbatim copies of the Program's
+source code as you receive it, in any medium, provided that you
+conspicuously and appropriately publish on each copy an appropriate
+copyright notice and disclaimer of warranty; keep intact all the
+notices that refer to this License and to the absence of any warranty;
+and give any other recipients of the Program a copy of this License
+along with the Program.
+
+You may charge a fee for the physical act of transferring a copy, and
+you may at your option offer warranty protection in exchange for a fee.
+
+  2. You may modify your copy or copies of the Program or any portion
+of it, thus forming a work based on the Program, and copy and
+distribute such modifications or work under the terms of Section 1
+above, provided that you also meet all of these conditions:
+
+    a) You must cause the modified files to carry prominent notices
+    stating that you changed the files and the date of any change.
+
+    b) You must cause any work that you distribute or publish, that in
+    whole or in part contains or is derived from the Program or any
+    part thereof, to be licensed as a whole at no charge to all third
+    parties under the terms of this License.
+
+    c) If the modified program normally reads commands interactively
+    when run, you must cause it, when started running for such
+    interactive use in the most ordinary way, to print or display an
+    announcement including an appropriate copyright notice and a
+    notice that there is no warranty (or else, saying that you provide
+    a warranty) and that users may redistribute the program under
+    these conditions, and telling the user how to view a copy of this
+    License.  (Exception: if the Program itself is interactive but
+    does not normally print such an announcement, your work based on
+    the Program is not required to print an announcement.)
+
+These requirements apply to the modified work as a whole.  If
+identifiable sections of that work are not derived from the Program,
+and can be reasonably considered independent and separate works in
+themselves, then this License, and its terms, do not apply to those
+sections when you distribute them as separate works.  But when you
+distribute the same sections as part of a whole which is a work based
+on the Program, the distribution of the whole must be on the terms of
+this License, whose permissions for other licensees extend to the
+entire whole, and thus to each and every part regardless of who wrote it.
+
+Thus, it is not the intent of this section to claim rights or contest
+your rights to work written entirely by you; rather, the intent is to
+exercise the right to control the distribution of derivative or
+collective works based on the Program.
+
+In addition, mere aggregation of another work not based on the Program
+with the Program (or with a work based on the Program) on a volume of
+a storage or distribution medium does not bring the other work under
+the scope of this License.
+
+  3. You may copy and distribute the Program (or a work based on it,
+under Section 2) in object code or executable form under the terms of
+Sections 1 and 2 above provided that you also do one of the following:
+
+    a) Accompany it with the complete corresponding machine-readable
+    source code, which must be distributed under the terms of Sections
+    1 and 2 above on a medium customarily used for software interchange; or,
+
+    b) Accompany it with a written offer, valid for at least three
+    years, to give any third party, for a charge no more than your
+    cost of physically performing source distribution, a complete
+    machine-readable copy of the corresponding source code, to be
+    distributed under the terms of Sections 1 and 2 above on a medium
+    customarily used for software interchange; or,
+
+    c) Accompany it with the information you received as to the offer
+    to distribute corresponding source code.  (This alternative is
+    allowed only for noncommercial distribution and only if you
+    received the program in object code or executable form with such
+    an offer, in accord with Subsection b above.)
+
+The source code for a work means the preferred form of the work for
+making modifications to it.  For an executable work, complete source
+code means all the source code for all modules it contains, plus any
+associated interface definition files, plus the scripts used to
+control compilation and installation of the executable.  However, as a
+special exception, the source code distributed need not include
+anything that is normally distributed (in either source or binary
+form) with the major components (compiler, kernel, and so on) of the
+operating system on which the executable runs, unless that component
+itself accompanies the executable.
+
+If distribution of executable or object code is made by offering
+access to copy from a designated place, then offering equivalent
+access to copy the source code from the same place counts as
+distribution of the source code, even though third parties are not
+compelled to copy the source along with the object code.
+
+  4. You may not copy, modify, sublicense, or distribute the Program
+except as expressly provided under this License.  Any attempt
+otherwise to copy, modify, sublicense or distribute the Program is
+void, and will automatically terminate your rights under this License.
+However, parties who have received copies, or rights, from you under
+this License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+  5. You are not required to accept this License, since you have not
+signed it.  However, nothing else grants you permission to modify or
+distribute the Program or its derivative works.  These actions are
+prohibited by law if you do not accept this License.  Therefore, by
+modifying or distributing the Program (or any work based on the
+Program), you indicate your acceptance of this License to do so, and
+all its terms and conditions for copying, distributing or modifying
+the Program or works based on it.
+
+  6. Each time you redistribute the Program (or any work based on the
+Program), the recipient automatically receives a license from the
+original licensor to copy, distribute or modify the Program subject to
+these terms and conditions.  You may not impose any further
+restrictions on the recipients' exercise of the rights granted herein.
+You are not responsible for enforcing compliance by third parties to
+this License.
+
+  7. If, as a consequence of a court judgment or allegation of patent
+infringement or for any other reason (not limited to patent issues),
+conditions are imposed on you (whether by court order, agreement or
+otherwise) that contradict the conditions of this License, they do not
+excuse you from the conditions of this License.  If you cannot
+distribute so as to satisfy simultaneously your obligations under this
+License and any other pertinent obligations, then as a consequence you
+may not distribute the Program at all.  For example, if a patent
+license would not permit royalty-free redistribution of the Program by
+all those who receive copies directly or indirectly through you, then
+the only way you could satisfy both it and this License would be to
+refrain entirely from distribution of the Program.
+
+If any portion of this section is held invalid or unenforceable under
+any particular circumstance, the balance of the section is intended to
+apply and the section as a whole is intended to apply in other
+circumstances.
+
+It is not the purpose of this section to induce you to infringe any
+patents or other property right claims or to contest validity of any
+such claims; this section has the sole purpose of protecting the
+integrity of the free software distribution system, which is
+implemented by public license practices.  Many people have made
+generous contributions to the wide range of software distributed
+through that system in reliance on consistent application of that
+system; it is up to the author/donor to decide if he or she is willing
+to distribute software through any other system and a licensee cannot
+impose that choice.
+
+This section is intended to make thoroughly clear what is believed to
+be a consequence of the rest of this License.
+
+  8. If the distribution and/or use of the Program is restricted in
+certain countries either by patents or by copyrighted interfaces, the
+original copyright holder who places the Program under this License
+may add an explicit geographical distribution limitation excluding
+those countries, so that distribution is permitted only in or among
+countries not thus excluded.  In such case, this License incorporates
+the limitation as if written in the body of this License.
+
+  9. The Free Software Foundation may publish revised and/or new versions
+of the General Public License from time to time.  Such new versions will
+be similar in spirit to the present version, but may differ in detail to
+address new problems or concerns.
+
+Each version is given a distinguishing version number.  If the Program
+specifies a version number of this License which applies to it and "any
+later version", you have the option of following the terms and conditions
+either of that version or of any later version published by the Free
+Software Foundation.  If the Program does not specify a version number of
+this License, you may choose any version ever published by the Free Software
+Foundation.
+
+  10. If you wish to incorporate parts of the Program into other free
+programs whose distribution conditions are different, write to the author
+to ask for permission.  For software which is copyrighted by the Free
+Software Foundation, write to the Free Software Foundation; we sometimes
+make exceptions for this.  Our decision will be guided by the two goals
+of preserving the free status of all derivatives of our free software and
+of promoting the sharing and reuse of software generally.
+
+                            NO WARRANTY
+
+  11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
+FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW.  EXCEPT WHEN
+OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
+PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED
+OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.  THE ENTIRE RISK AS
+TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU.  SHOULD THE
+PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
+REPAIR OR CORRECTION.
+
+  12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
+WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
+REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
+INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING
+OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED
+TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY
+YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
+PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
+POSSIBILITY OF SUCH DAMAGES.
+
+                     END OF TERMS AND CONDITIONS
+
+            How to Apply These Terms to Your New Programs
+
+  If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+  To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+convey the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software; you can redistribute it and/or modify
+    it under the terms of the GNU General Public License as published by
+    the Free Software Foundation; either version 2 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU General Public License for more details.
+
+    You should have received a copy of the GNU General Public License along
+    with this program; if not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If the program is interactive, make it output a short notice like this
+when it starts in an interactive mode:
+
+    Gnomovision version 69, Copyright (C) year name of author
+    Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+    This is free software, and you are welcome to redistribute it
+    under certain conditions; type `show c' for details.
+
+The hypothetical commands `show w' and `show c' should show the appropriate
+parts of the General Public License.  Of course, the commands you use may
+be called something other than `show w' and `show c'; they could even be
+mouse-clicks or menu items--whatever suits your program.
+
+You should also get your employer (if you work as a programmer) or your
+school, if any, to sign a "copyright disclaimer" for the program, if
+necessary.  Here is a sample; alter the names:
+
+  Yoyodyne, Inc., hereby disclaims all copyright interest in the program
+  `Gnomovision' (which makes passes at compilers) written by James Hacker.
+
+  <signature of Moe Ghoul>, 1 April 1989
+  Moe Ghoul, President of Vice
+
+This General Public License does not permit incorporating your program into
+proprietary programs.  If your program is a subroutine library, you may
+consider it more useful to permit linking proprietary applications with the
+library.  If this is what you want to do, use the GNU Lesser General
+Public License instead of this License.

nvda_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,234 @@
+Metadata-Version: 2.5
+Name: nvda-mcp
+Version: 1.0.0
+Summary: MCP server that lets AI assistants work with the NVDA screen reader through the NVDA MCP add-on.
+Project-URL: Homepage, https://github.com/InfiArtt/nvda-mcp
+Project-URL: Documentation, https://github.com/InfiArtt/nvda-mcp/blob/main/docs/using.md
+Project-URL: Changelog, https://github.com/InfiArtt/nvda-mcp/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/InfiArtt/nvda-mcp/issues
+Project-URL: Donate, https://paypal.me/rafli23115
+Author-email: InfiArtt <info@infiartt.com>
+License-Expression: GPL-2.0-or-later
+License-File: COPYING.txt
+License-File: THIRD_PARTY_NOTICES.md
+Keywords: accessibility,ai assistant,mcp,model context protocol,nvda,screen reader
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Win32 (MS Windows)
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Adaptive Technologies
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: mcp<3,>=2.3
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: markdown>=3.5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.16; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# NVDA MCP
+
+NVDA MCP connects AI assistants to the [NVDA](https://www.nvaccess.org) screen reader through the
+[Model Context Protocol](https://modelcontextprotocol.io) (MCP).
+The assistant can read what NVDA reads and hear what NVDA says. If you allow it, it can also press keys,
+and you hear every step through NVDA, as if you had pressed them yourself.
+
+## Why it exists
+
+AI assistants can now do things on a computer, not just answer questions. Most of them work by looking at
+screenshots and clicking on what they see. For someone who uses a screen reader, that has two problems:
+
+- **You can't follow what the assistant does.** It clicks things you never hear about, in places your
+  screen reader may not even show you.
+- **A screenshot is not what you experience.** What matters to a screen reader user is which control has
+  focus, its name, role and state, and what NVDA says about it. A picture of the screen leaves most of that out.
+
+NVDA already knows all of this, because it is how you use your computer. NVDA MCP gives the assistant the same
+view: the focused control, the accessibility tree, the text of a document or web page, and exactly what NVDA
+said. When the assistant acts, it uses the keyboard through NVDA, the way you would, and NVDA announces the result.
+You and the assistant work from the same information, and you stay in control.
+
+## What it is useful for
+
+For people who use NVDA:
+
+- **"What did NVDA just say?"** The assistant reads NVDA's speech history, so you can ask about something
+  you missed, or ask for a summary of a long dialog.
+- **Getting through confusing or inaccessible applications.** Ask what is in a window, where a control is,
+  or why a button has no name, and get an answer based on what NVDA actually sees.
+- **Doing repetitive tasks.** The assistant can move through an application with the keyboard,
+  type text, switch windows, and wait for something to happen, such as a chat reply.
+- **Learning.** Ask which NVDA commands work where you are, or what a key does here.
+
+For developers and testers:
+
+- **See what NVDA announces** for each control without moving focus, and find unlabeled or silent controls.
+- **Audit the tab order** of a dialog or page: duplicate names, keyboard traps, controls NVDA says nothing about.
+- **Find out why NVDA is silent**: trace the events NVDA handles and what it said for each one.
+- **Regression tests**: record what NVDA says through a series of key presses, and compare later runs with it.
+- **Develop NVDA add-ons faster**: read NVDA's log, see developer info like NVDA+F1, and reload add-on code.
+
+## Who it is for
+
+- **Blind and low-vision people** who use NVDA and want an AI assistant that works with their screen reader
+  instead of around it.
+- **NVDA add-on developers**, who can test what their add-on makes NVDA say without doing every step by hand.
+- **Developers of Windows applications and websites**, who want to check their work with a real screen reader.
+- **Accessibility testers, auditors and QA teams**, who need repeatable checks of what a screen reader announces.
+- **Trainers and support staff** who help screen reader users and want to understand what they hear.
+
+## What you need
+
+- Windows with NVDA 2026.3 or later.
+- An AI assistant that supports MCP, such as Claude Code, Claude Desktop, Codex CLI, Cursor or VS Code.
+- [uv](https://docs.astral.sh/uv/), which downloads and runs the NVDA MCP server for you.
+  If you already have Python 3.11 or later, you can use pip or pipx instead.
+
+NVDA MCP has two parts: this add-on, and a small program called the **nvda-mcp server**, which your assistant
+starts. The add-on comes from NVDA's Add-on Store; the server comes from the Python Package Index (PyPI).
+Both are free and open source.
+
+## Setting it up
+
+1. **Install the add-on.** In NVDA, open Tools, then Add-on Store. Find NVDA MCP, install it and restart NVDA.
+2. **Install uv**, if you don't have it. Open a command prompt and run:
+
+   ```
+   winget install --id=astral-sh.uv -e
+   ```
+
+   Close the command prompt and open a new one, so it finds uv.
+3. **Connect your assistant.** In NVDA, open Settings (NVDA+N, Preferences, Settings), then the
+   **NVDA MCP** category. Choose your assistant under *Set up this MCP client* and press
+   **Copy setup command**.
+   - For Claude Code or Codex CLI, paste the command into a command prompt and press Enter.
+   - For Claude Desktop, Cursor and other assistants that use a settings file, paste the settings into
+     that file. For Claude Desktop, it is `claude_desktop_config.json` (Settings, Developer, Edit Config).
+
+   The command is like `claude mcp add --scope user nvda -- uvx nvda-mcp==1.0.0`: it tells your assistant to
+   run the server version that matches your add-on.
+
+Start your assistant and ask it something like "what has focus in NVDA?". It answers without pressing anything.
+
+### With pip or pipx instead of uv
+
+```
+pipx install nvda-mcp
+claude mcp add --scope user nvda -- nvda-mcp
+```
+
+Use the same version as the add-on, and upgrade both together. With plain pip, run `python -m nvda_mcp` if the
+`nvda-mcp` command is not found.
+
+## Safety
+
+Reading is always allowed. Everything that acts on your computer is **off until you turn it on**:
+pressing keys, typing, switching windows, activating controls, moving through web pages,
+running NVDA commands and reloading add-ons.
+
+In NVDA's Settings, **NVDA MCP** category:
+
+- **Let MCP clients, such as AI assistants, connect to NVDA** (on by default).
+- **Allow MCP clients to press keys** (off by default).
+- **Ask before the first key press after NVDA starts** (on by default). NVDA asks you, with **No** focused,
+  and names the program asking, as it calls itself.
+- **Only let MCP clients control these applications** (empty by default, meaning all).
+  For example `notepad, winword`. Anything else is refused.
+- **Keep a log of every action MCP clients take** (on by default), in `%APPDATA%\nvda\nvdaMcp\actions.log`.
+- **Number of spoken messages to remember** (500 by default).
+
+Commands in Input Gestures, NVDA MCP category (no keys assigned by default):
+
+- Report whether NVDA MCP is running and whether it may press keys.
+- Stop MCP clients from pressing keys until you approve again.
+- Open the log of actions MCP clients have taken.
+
+How the connection is protected:
+
+- The add-on listens only on your own computer (127.0.0.1), on a random port.
+- Every request needs a secret token, made new each time NVDA starts, stored where only your Windows account
+  can read it.
+- Requests from web pages are refused.
+- Nothing works on secure screens (sign-in, UAC), and requests are refused while Windows is locked.
+- The settings live in NVDA's base configuration, so a configuration profile cannot turn key presses on.
+
+## Privacy
+
+The add-on itself sends nothing over the internet. But **what your assistant reads goes to the assistant**,
+and most assistants send it to their provider's servers. That can include the text on your screen,
+what NVDA says, the contents of documents and chat windows, and anything NVDA reads aloud while you type.
+
+- Before you work with something private, such as banking, passwords or personal messages,
+  close your assistant or turn off *Let MCP clients connect* in NVDA's settings.
+- NVDA's speech history is kept in memory only, and cleared when NVDA restarts.
+- The action log stays on your computer.
+
+## Tools
+
+The assistant sees these tools:
+
+| Tool | What it does |
+|---|---|
+| `nvda_get_status` | NVDA version, synthesizer, speech mode, foreground app, permissions |
+| `nvda_get_focus` | The focused control: name, role, states, value, position, containers |
+| `nvda_get_navigator_object` | The same, for NVDA's navigator object |
+| `nvda_get_object_tree` | The accessibility tree of the foreground window, focus or navigator; long lists are shortened |
+| `nvda_find_objects` | Find controls in the foreground window by name and/or role |
+| `nvda_get_text` | Full text of a document, web page or edit field, plus the caret line; or only the lines containing some text |
+| `nvda_get_speech_history` | What NVDA said, with ids for polling and a text filter |
+| `nvda_wait_for_speech` | Wait until NVDA says something, such as a chat reply |
+| `nvda_list_windows` | Open application windows, including ones on other virtual desktops if asked |
+| `nvda_speak` | Say something through NVDA's speech and braille |
+| `nvda_press_keys` | Press keys, optionally holding modifiers, then report what NVDA said and where focus went |
+| `nvda_type_text` | Type a line of text in any language, emoji included, without using the clipboard |
+| `nvda_activate_window` | Bring a window to the front by title or handle |
+| `nvda_focus_object` | Move focus to a control found with `nvda_find_objects` |
+| `nvda_activate_object` | Press, follow or toggle a control found with `nvda_find_objects` |
+| `nvda_set_document_mode` | Switch between browse mode and focus mode in a web page, like NVDA+space |
+| `nvda_find_in_page` | Move the browse mode cursor to a match on the page, like NVDA's find command |
+| `nvda_list_elements` | Headings, links, landmarks, form fields and more, like the Elements List |
+| `nvda_move_to_element` | Move to, or activate, an element from `nvda_list_elements` |
+| `nvda_get_action_log` | The newest entries of the log of actions clients took |
+| `nvda_audit_focus_order` | Tab through a window and report unlabeled controls, silent controls, duplicate names, keyboard traps |
+
+For developers of add-ons and accessible applications:
+
+| Tool | What it does |
+|---|---|
+| `nvda_preview_speech` | What NVDA would announce when a control gets focus, without moving focus; scan a whole window and flag unlabeled or silent controls |
+| `nvda_trace_events` | Record the events NVDA handles (focus, name and value changes, live regions, UIA notifications) and what it said for each one |
+| `nvda_get_log` | NVDA's log, filtered by level and text; IO entries (keys typed) only when asked |
+| `nvda_get_output_history` | Beeps, sounds, braille output and speech being cut off, optionally merged with speech |
+| `nvda_get_dev_info` | Developer info for a control, like NVDA+F1 |
+| `nvda_list_scripts` | NVDA commands available where focus is, with their keys; or which command a key runs |
+| `nvda_run_script` | Run an NVDA command by name, whatever key it is assigned to |
+| `nvda_reload_plugins` | Reload add-ons and app modules from disk, like NVDA+control+F3 |
+| `nvda_get_settings` | Read NVDA's settings as they apply now; values that look like secrets are hidden |
+| `nvda_run_scenario` | Run keys and typing, record what NVDA said after each step, and compare with a baseline file |
+
+Every action reports what NVDA said afterwards and where focus went, and can wait for an expected announcement,
+such as "sent" or a dialog's title.
+
+## Support NVDA MCP
+
+NVDA MCP is free, and made in spare time. If it helps you, you can support its development with a donation
+through [PayPal](https://paypal.me/rafli23115). There is also a **Donate** button in NVDA's Settings,
+NVDA MCP category.
+
+## More
+
+- [Using NVDA MCP](docs/using.md): updating, restarting the server, and what to do when something does not work.
+- [What's new](CHANGELOG.md) in each version.
+- [Contributing](CONTRIBUTING.md): building, testing and releasing.
+- Questions and bug reports: [GitHub issues](https://github.com/InfiArtt/nvda-mcp/issues).
+
+## License
+
+Copyright (C) 2026 InfiArtt.
+NVDA MCP is free software under the [GNU General Public License, version 2](COPYING.txt) or later.
+The software it uses and their licenses are listed in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).