npreq-mcp 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Miles Medical Service
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,168 @@
1
+ Metadata-Version: 2.4
2
+ Name: npreq-mcp
3
+ Version: 0.1.0
4
+ Summary: A local MCP server for the NPReq API: read-only NP/APRN state requirement data with official sources, through your own API key.
5
+ Author: Miles Medical Service
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://npreq.com/
8
+ Project-URL: Documentation, https://account.npreq.com/account/docs
9
+ Project-URL: Source, https://github.com/Miles-Medical-Service/npreq-mcp
10
+ Project-URL: Issues, https://github.com/Miles-Medical-Service/npreq-mcp/issues
11
+ Keywords: mcp,nurse-practitioner,aprn,licensure,continuing-education
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Operating System :: OS Independent
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Dynamic: license-file
20
+
21
+ # npreq-mcp: the NPReq API as MCP tools
22
+
23
+ <!-- mcp-name: io.github.Miles-Medical-Service/npreq -->
24
+
25
+ NPReq gives nurse practitioners and the tools they use curated NP/APRN state requirement data for 56 US
26
+ jurisdictions: practice authority, licensure, continuing education (CE) rules, renewal, prescribing and board
27
+ contacts, each value with the official source it came from. This repository holds two things:
28
+
29
+ - **npreq-mcp**, a local MCP server (one Python file, standard library only) that gives AI agents read-only access to
30
+ that data with **your own NPReq API key**;
31
+ - **the `npreq` plugin for Claude Code**, which runs that server, asks for your key once and keeps it in your
32
+ system's credential store, and adds a skill that tells Claude when to use each tool.
33
+
34
+ NPReq data is for information. It is **not for clinical or licensing decisions**: always confirm a requirement with
35
+ the state board of nursing before you act on it.
36
+
37
+ You need an NPReq API key (https://npreq.com/) and Python 3.10 or newer as `python3` on your PATH.
38
+
39
+ ## Install the plugin (Claude Code)
40
+
41
+ The plugin needs **Claude Code v2.1.271 or later** and works in **Claude Code only**. (Cowork skips a plugin server
42
+ whose required, sensitive setting has no default, and an API key cannot have one.)
43
+
44
+ ```
45
+ /plugin marketplace add Miles-Medical-Service/npreq-mcp
46
+ /plugin install npreq@npreq
47
+ ```
48
+
49
+ On Claude Code 2.1.275 or later, one line does both: `/plugin install npreq --marketplace Miles-Medical-Service/npreq-mcp`.
50
+
51
+ **On Windows**, the plugin starts the server with `python3`. On many Windows machines `python3` is only the Microsoft
52
+ Store alias, which opens the Store instead of running Python. Before you enable the plugin, run `python3 --version`
53
+ in a terminal: it must print Python 3.10 or newer. If it does not, install Python from python.org or the Microsoft
54
+ Store, or turn off the `python3.exe` App Execution Alias (Settings > Apps > Advanced app settings) once a real
55
+ `python3` is on your PATH.
56
+
57
+ When the plugin is enabled, Claude Code asks for two settings:
58
+
59
+ | Setting | What it is |
60
+ |---|---|
61
+ | NPReq API key | Your key (`npq_live_...`, or `npq_test_...` for staging). Masked when typed and stored in your system's credential store, not in a settings file. |
62
+ | NPReq API | A choice of `https://api.npreq.com` (the default) or `https://api-staging.npreq.com`. There is no free-text address, because the key is sent there. |
63
+
64
+ The plugin passes these two values to the server. It does not read an API key that is already set in your shell.
65
+ The API choice also appears in `/config`; the key does not, because it is a sensitive setting.
66
+
67
+ The tools then appear as `mcp__plugin_npreq_npreq__<tool>`.
68
+
69
+ ## The tools
70
+
71
+ Every tool is exactly one read-only request to the NPReq REST API. No tool writes anything.
72
+
73
+ | Tool | Request it makes | Scope your key needs | Arguments |
74
+ |---|---|---|---|
75
+ | `get_data_version` | `GET /v1/meta` | none (public) | none |
76
+ | `list_states` | `GET /v1/states` | `states:read` | none |
77
+ | `get_state` | `GET /v1/states/{code}` | `states:read` | `code`: two capital letters (`TX`, `PR`) |
78
+ | `get_state_ce` | `GET /v1/states/{code}/ce` | `ce:read` | `code`: two capital letters |
79
+ | `search_requirements` | `GET /v1/search?q=` | `search` | `q`: 2 to 64 letters, digits, spaces, hyphens, apostrophes or periods |
80
+
81
+ A result is the API's JSON reply. An API error comes back as a tool error with the HTTP status, the API's error code
82
+ and a fixed message; for `429` and `503` it says how many seconds to wait.
83
+
84
+ ## Everything the plugin runs, sends and fetches
85
+
86
+ - **Runs:** `python3 <plugin folder>/npreq_mcp.py`, a local process that talks to Claude Code over stdin and stdout.
87
+ It runs nothing else, installs nothing, and writes no files.
88
+ - **Sends, only to the API you chose (`https://api.npreq.com` or `https://api-staging.npreq.com`), over HTTPS:**
89
+ 1. `POST /v1/token` with your API key in the `Authorization` header. This is the only request that carries the
90
+ key. The reply is an access token that lasts 6 hours; the server keeps it in memory only and asks for a new one
91
+ when fewer than 5 minutes are left, or once after a data request is refused with `401`.
92
+ 2. The five `GET` requests in the table above, each with the access token (never the key) in the `Authorization`
93
+ header, plus the state code or search text you or Claude passed as the tool's argument.
94
+
95
+ Every request also carries `Accept: application/json` and `User-Agent: npreq-mcp/<version>`.
96
+ - **Fetches:** only the API's JSON replies to those requests (at most 16 MB each). It never follows a redirect,
97
+ since a redirect would carry the `Authorization` header to another address, and it checks the TLS certificate.
98
+ - **Nothing else:** no telemetry, no analytics, no update checks, no other host.
99
+
100
+ ## Privacy
101
+
102
+ - The NPReq API receives your key (at `/v1/token` only), the tool arguments (a state code or a search text), your
103
+ IP address and the `User-Agent` above. It counts your requests against your plan's minute limit and monthly
104
+ quota. What NPReq keeps and for how long is in the privacy policy: https://npreq.com/privacy.html. Use of the API
105
+ is under the terms: https://npreq.com/terms.html.
106
+ - Do not put personal or patient information in a search: the search text is sent to the API.
107
+ - The server never writes your key or a token to its output, its log (one line per tool call, with the tool name and
108
+ the status, on stderr), a tool result or an error. It takes the key out of its own environment once it has read it.
109
+ - Results are curated requirement data with sources. The tools and the skill tell Claude to treat them as data, not
110
+ instructions.
111
+
112
+ ## What happens when something is refused
113
+
114
+ - **A refused key is held.** Once `/v1/token` answers `401` or `403`, the server sends nothing more with the key.
115
+ Every tool that needs a token answers at once with that status, and only `get_data_version` keeps working until
116
+ you fix the key (or its IP allowlist) and restart. This is because every refusal counts toward the API's lockout
117
+ of your IP address (10 in 10 minutes locks it for 15 minutes), so a retrying client can never lock you out.
118
+ - A `429` or `5xx` at `/v1/token` is temporary and is not held.
119
+ - A revoked key, a lapsed subscription, or a scope your plan lacks stops the tools on the next call: the API checks
120
+ the key behind every token on every request.
121
+
122
+ ## Without the plugin
123
+
124
+ Any MCP client that starts a local stdio server can run `npreq_mcp.py` directly. Set `NPREQ_API_KEY` in that
125
+ client's server configuration (never on a command line or in a prompt), and optionally `NPREQ_API_BASE`, which
126
+ accepts only an `https://` origin and defaults to `https://api.npreq.com`. For example, in Claude Desktop's
127
+ `claude_desktop_config.json`:
128
+
129
+ ```json
130
+ {
131
+ "mcpServers": {
132
+ "npreq": {
133
+ "command": "python3",
134
+ "args": ["/path/to/npreq-mcp/npreq_mcp.py"],
135
+ "env": { "NPREQ_API_KEY": "<your key>" }
136
+ }
137
+ }
138
+ }
139
+ ```
140
+
141
+ On Windows, use `python` (or `py -3`) instead of `python3`, and a full path with forward slashes. Installed with
142
+ `pip install .` from this folder, the server is also the `npreq-mcp` command.
143
+
144
+ The NPReq API documentation, with more client setups, is at https://account.npreq.com/account/docs.
145
+
146
+ ## Protocol
147
+
148
+ Newline-delimited JSON-RPC 2.0 on stdio. A request whose `_meta` carries `io.modelcontextprotocol/protocolVersion`
149
+ `2026-07-28` is served statelessly by that revision. An `initialize` request selects the handshake of `2025-11-25`,
150
+ `2025-06-18` or `2025-03-26` for the life of the process. Any other version gets error `-32022` with the supported
151
+ list. The server offers tools only: no resources, prompts, sampling or elicitation.
152
+
153
+ ## Tests
154
+
155
+ `python3 tests/test_npreq_mcp.py` runs on Python 3.10 and 3.13 with no network: the API is a fake, and the
156
+ child-process tests point the server at an address that refuses at once. They cover:
157
+
158
+ - the five routes and their argument checks;
159
+ - the error map;
160
+ - token renewal and the single retry, and the refused key held for the session;
161
+ - that redirects are never followed;
162
+ - that the key never appears in output, logs, results or arguments;
163
+ - the plugin's settings, and that the key the plugin passes wins over one set in the shell.
164
+
165
+ ## Security and licence
166
+
167
+ Report a vulnerability as described in [SECURITY.md](SECURITY.md); please do not open a public issue for it.
168
+ MIT licence: see [LICENSE](LICENSE).
@@ -0,0 +1,148 @@
1
+ # npreq-mcp: the NPReq API as MCP tools
2
+
3
+ <!-- mcp-name: io.github.Miles-Medical-Service/npreq -->
4
+
5
+ NPReq gives nurse practitioners and the tools they use curated NP/APRN state requirement data for 56 US
6
+ jurisdictions: practice authority, licensure, continuing education (CE) rules, renewal, prescribing and board
7
+ contacts, each value with the official source it came from. This repository holds two things:
8
+
9
+ - **npreq-mcp**, a local MCP server (one Python file, standard library only) that gives AI agents read-only access to
10
+ that data with **your own NPReq API key**;
11
+ - **the `npreq` plugin for Claude Code**, which runs that server, asks for your key once and keeps it in your
12
+ system's credential store, and adds a skill that tells Claude when to use each tool.
13
+
14
+ NPReq data is for information. It is **not for clinical or licensing decisions**: always confirm a requirement with
15
+ the state board of nursing before you act on it.
16
+
17
+ You need an NPReq API key (https://npreq.com/) and Python 3.10 or newer as `python3` on your PATH.
18
+
19
+ ## Install the plugin (Claude Code)
20
+
21
+ The plugin needs **Claude Code v2.1.271 or later** and works in **Claude Code only**. (Cowork skips a plugin server
22
+ whose required, sensitive setting has no default, and an API key cannot have one.)
23
+
24
+ ```
25
+ /plugin marketplace add Miles-Medical-Service/npreq-mcp
26
+ /plugin install npreq@npreq
27
+ ```
28
+
29
+ On Claude Code 2.1.275 or later, one line does both: `/plugin install npreq --marketplace Miles-Medical-Service/npreq-mcp`.
30
+
31
+ **On Windows**, the plugin starts the server with `python3`. On many Windows machines `python3` is only the Microsoft
32
+ Store alias, which opens the Store instead of running Python. Before you enable the plugin, run `python3 --version`
33
+ in a terminal: it must print Python 3.10 or newer. If it does not, install Python from python.org or the Microsoft
34
+ Store, or turn off the `python3.exe` App Execution Alias (Settings > Apps > Advanced app settings) once a real
35
+ `python3` is on your PATH.
36
+
37
+ When the plugin is enabled, Claude Code asks for two settings:
38
+
39
+ | Setting | What it is |
40
+ |---|---|
41
+ | NPReq API key | Your key (`npq_live_...`, or `npq_test_...` for staging). Masked when typed and stored in your system's credential store, not in a settings file. |
42
+ | NPReq API | A choice of `https://api.npreq.com` (the default) or `https://api-staging.npreq.com`. There is no free-text address, because the key is sent there. |
43
+
44
+ The plugin passes these two values to the server. It does not read an API key that is already set in your shell.
45
+ The API choice also appears in `/config`; the key does not, because it is a sensitive setting.
46
+
47
+ The tools then appear as `mcp__plugin_npreq_npreq__<tool>`.
48
+
49
+ ## The tools
50
+
51
+ Every tool is exactly one read-only request to the NPReq REST API. No tool writes anything.
52
+
53
+ | Tool | Request it makes | Scope your key needs | Arguments |
54
+ |---|---|---|---|
55
+ | `get_data_version` | `GET /v1/meta` | none (public) | none |
56
+ | `list_states` | `GET /v1/states` | `states:read` | none |
57
+ | `get_state` | `GET /v1/states/{code}` | `states:read` | `code`: two capital letters (`TX`, `PR`) |
58
+ | `get_state_ce` | `GET /v1/states/{code}/ce` | `ce:read` | `code`: two capital letters |
59
+ | `search_requirements` | `GET /v1/search?q=` | `search` | `q`: 2 to 64 letters, digits, spaces, hyphens, apostrophes or periods |
60
+
61
+ A result is the API's JSON reply. An API error comes back as a tool error with the HTTP status, the API's error code
62
+ and a fixed message; for `429` and `503` it says how many seconds to wait.
63
+
64
+ ## Everything the plugin runs, sends and fetches
65
+
66
+ - **Runs:** `python3 <plugin folder>/npreq_mcp.py`, a local process that talks to Claude Code over stdin and stdout.
67
+ It runs nothing else, installs nothing, and writes no files.
68
+ - **Sends, only to the API you chose (`https://api.npreq.com` or `https://api-staging.npreq.com`), over HTTPS:**
69
+ 1. `POST /v1/token` with your API key in the `Authorization` header. This is the only request that carries the
70
+ key. The reply is an access token that lasts 6 hours; the server keeps it in memory only and asks for a new one
71
+ when fewer than 5 minutes are left, or once after a data request is refused with `401`.
72
+ 2. The five `GET` requests in the table above, each with the access token (never the key) in the `Authorization`
73
+ header, plus the state code or search text you or Claude passed as the tool's argument.
74
+
75
+ Every request also carries `Accept: application/json` and `User-Agent: npreq-mcp/<version>`.
76
+ - **Fetches:** only the API's JSON replies to those requests (at most 16 MB each). It never follows a redirect,
77
+ since a redirect would carry the `Authorization` header to another address, and it checks the TLS certificate.
78
+ - **Nothing else:** no telemetry, no analytics, no update checks, no other host.
79
+
80
+ ## Privacy
81
+
82
+ - The NPReq API receives your key (at `/v1/token` only), the tool arguments (a state code or a search text), your
83
+ IP address and the `User-Agent` above. It counts your requests against your plan's minute limit and monthly
84
+ quota. What NPReq keeps and for how long is in the privacy policy: https://npreq.com/privacy.html. Use of the API
85
+ is under the terms: https://npreq.com/terms.html.
86
+ - Do not put personal or patient information in a search: the search text is sent to the API.
87
+ - The server never writes your key or a token to its output, its log (one line per tool call, with the tool name and
88
+ the status, on stderr), a tool result or an error. It takes the key out of its own environment once it has read it.
89
+ - Results are curated requirement data with sources. The tools and the skill tell Claude to treat them as data, not
90
+ instructions.
91
+
92
+ ## What happens when something is refused
93
+
94
+ - **A refused key is held.** Once `/v1/token` answers `401` or `403`, the server sends nothing more with the key.
95
+ Every tool that needs a token answers at once with that status, and only `get_data_version` keeps working until
96
+ you fix the key (or its IP allowlist) and restart. This is because every refusal counts toward the API's lockout
97
+ of your IP address (10 in 10 minutes locks it for 15 minutes), so a retrying client can never lock you out.
98
+ - A `429` or `5xx` at `/v1/token` is temporary and is not held.
99
+ - A revoked key, a lapsed subscription, or a scope your plan lacks stops the tools on the next call: the API checks
100
+ the key behind every token on every request.
101
+
102
+ ## Without the plugin
103
+
104
+ Any MCP client that starts a local stdio server can run `npreq_mcp.py` directly. Set `NPREQ_API_KEY` in that
105
+ client's server configuration (never on a command line or in a prompt), and optionally `NPREQ_API_BASE`, which
106
+ accepts only an `https://` origin and defaults to `https://api.npreq.com`. For example, in Claude Desktop's
107
+ `claude_desktop_config.json`:
108
+
109
+ ```json
110
+ {
111
+ "mcpServers": {
112
+ "npreq": {
113
+ "command": "python3",
114
+ "args": ["/path/to/npreq-mcp/npreq_mcp.py"],
115
+ "env": { "NPREQ_API_KEY": "<your key>" }
116
+ }
117
+ }
118
+ }
119
+ ```
120
+
121
+ On Windows, use `python` (or `py -3`) instead of `python3`, and a full path with forward slashes. Installed with
122
+ `pip install .` from this folder, the server is also the `npreq-mcp` command.
123
+
124
+ The NPReq API documentation, with more client setups, is at https://account.npreq.com/account/docs.
125
+
126
+ ## Protocol
127
+
128
+ Newline-delimited JSON-RPC 2.0 on stdio. A request whose `_meta` carries `io.modelcontextprotocol/protocolVersion`
129
+ `2026-07-28` is served statelessly by that revision. An `initialize` request selects the handshake of `2025-11-25`,
130
+ `2025-06-18` or `2025-03-26` for the life of the process. Any other version gets error `-32022` with the supported
131
+ list. The server offers tools only: no resources, prompts, sampling or elicitation.
132
+
133
+ ## Tests
134
+
135
+ `python3 tests/test_npreq_mcp.py` runs on Python 3.10 and 3.13 with no network: the API is a fake, and the
136
+ child-process tests point the server at an address that refuses at once. They cover:
137
+
138
+ - the five routes and their argument checks;
139
+ - the error map;
140
+ - token renewal and the single retry, and the refused key held for the session;
141
+ - that redirects are never followed;
142
+ - that the key never appears in output, logs, results or arguments;
143
+ - the plugin's settings, and that the key the plugin passes wins over one set in the shell.
144
+
145
+ ## Security and licence
146
+
147
+ Report a vulnerability as described in [SECURITY.md](SECURITY.md); please do not open a public issue for it.
148
+ MIT licence: see [LICENSE](LICENSE).
@@ -0,0 +1,168 @@
1
+ Metadata-Version: 2.4
2
+ Name: npreq-mcp
3
+ Version: 0.1.0
4
+ Summary: A local MCP server for the NPReq API: read-only NP/APRN state requirement data with official sources, through your own API key.
5
+ Author: Miles Medical Service
6
+ License-Expression: MIT
7
+ Project-URL: Homepage, https://npreq.com/
8
+ Project-URL: Documentation, https://account.npreq.com/account/docs
9
+ Project-URL: Source, https://github.com/Miles-Medical-Service/npreq-mcp
10
+ Project-URL: Issues, https://github.com/Miles-Medical-Service/npreq-mcp/issues
11
+ Keywords: mcp,nurse-practitioner,aprn,licensure,continuing-education
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.13
15
+ Classifier: Operating System :: OS Independent
16
+ Requires-Python: >=3.10
17
+ Description-Content-Type: text/markdown
18
+ License-File: LICENSE
19
+ Dynamic: license-file
20
+
21
+ # npreq-mcp: the NPReq API as MCP tools
22
+
23
+ <!-- mcp-name: io.github.Miles-Medical-Service/npreq -->
24
+
25
+ NPReq gives nurse practitioners and the tools they use curated NP/APRN state requirement data for 56 US
26
+ jurisdictions: practice authority, licensure, continuing education (CE) rules, renewal, prescribing and board
27
+ contacts, each value with the official source it came from. This repository holds two things:
28
+
29
+ - **npreq-mcp**, a local MCP server (one Python file, standard library only) that gives AI agents read-only access to
30
+ that data with **your own NPReq API key**;
31
+ - **the `npreq` plugin for Claude Code**, which runs that server, asks for your key once and keeps it in your
32
+ system's credential store, and adds a skill that tells Claude when to use each tool.
33
+
34
+ NPReq data is for information. It is **not for clinical or licensing decisions**: always confirm a requirement with
35
+ the state board of nursing before you act on it.
36
+
37
+ You need an NPReq API key (https://npreq.com/) and Python 3.10 or newer as `python3` on your PATH.
38
+
39
+ ## Install the plugin (Claude Code)
40
+
41
+ The plugin needs **Claude Code v2.1.271 or later** and works in **Claude Code only**. (Cowork skips a plugin server
42
+ whose required, sensitive setting has no default, and an API key cannot have one.)
43
+
44
+ ```
45
+ /plugin marketplace add Miles-Medical-Service/npreq-mcp
46
+ /plugin install npreq@npreq
47
+ ```
48
+
49
+ On Claude Code 2.1.275 or later, one line does both: `/plugin install npreq --marketplace Miles-Medical-Service/npreq-mcp`.
50
+
51
+ **On Windows**, the plugin starts the server with `python3`. On many Windows machines `python3` is only the Microsoft
52
+ Store alias, which opens the Store instead of running Python. Before you enable the plugin, run `python3 --version`
53
+ in a terminal: it must print Python 3.10 or newer. If it does not, install Python from python.org or the Microsoft
54
+ Store, or turn off the `python3.exe` App Execution Alias (Settings > Apps > Advanced app settings) once a real
55
+ `python3` is on your PATH.
56
+
57
+ When the plugin is enabled, Claude Code asks for two settings:
58
+
59
+ | Setting | What it is |
60
+ |---|---|
61
+ | NPReq API key | Your key (`npq_live_...`, or `npq_test_...` for staging). Masked when typed and stored in your system's credential store, not in a settings file. |
62
+ | NPReq API | A choice of `https://api.npreq.com` (the default) or `https://api-staging.npreq.com`. There is no free-text address, because the key is sent there. |
63
+
64
+ The plugin passes these two values to the server. It does not read an API key that is already set in your shell.
65
+ The API choice also appears in `/config`; the key does not, because it is a sensitive setting.
66
+
67
+ The tools then appear as `mcp__plugin_npreq_npreq__<tool>`.
68
+
69
+ ## The tools
70
+
71
+ Every tool is exactly one read-only request to the NPReq REST API. No tool writes anything.
72
+
73
+ | Tool | Request it makes | Scope your key needs | Arguments |
74
+ |---|---|---|---|
75
+ | `get_data_version` | `GET /v1/meta` | none (public) | none |
76
+ | `list_states` | `GET /v1/states` | `states:read` | none |
77
+ | `get_state` | `GET /v1/states/{code}` | `states:read` | `code`: two capital letters (`TX`, `PR`) |
78
+ | `get_state_ce` | `GET /v1/states/{code}/ce` | `ce:read` | `code`: two capital letters |
79
+ | `search_requirements` | `GET /v1/search?q=` | `search` | `q`: 2 to 64 letters, digits, spaces, hyphens, apostrophes or periods |
80
+
81
+ A result is the API's JSON reply. An API error comes back as a tool error with the HTTP status, the API's error code
82
+ and a fixed message; for `429` and `503` it says how many seconds to wait.
83
+
84
+ ## Everything the plugin runs, sends and fetches
85
+
86
+ - **Runs:** `python3 <plugin folder>/npreq_mcp.py`, a local process that talks to Claude Code over stdin and stdout.
87
+ It runs nothing else, installs nothing, and writes no files.
88
+ - **Sends, only to the API you chose (`https://api.npreq.com` or `https://api-staging.npreq.com`), over HTTPS:**
89
+ 1. `POST /v1/token` with your API key in the `Authorization` header. This is the only request that carries the
90
+ key. The reply is an access token that lasts 6 hours; the server keeps it in memory only and asks for a new one
91
+ when fewer than 5 minutes are left, or once after a data request is refused with `401`.
92
+ 2. The five `GET` requests in the table above, each with the access token (never the key) in the `Authorization`
93
+ header, plus the state code or search text you or Claude passed as the tool's argument.
94
+
95
+ Every request also carries `Accept: application/json` and `User-Agent: npreq-mcp/<version>`.
96
+ - **Fetches:** only the API's JSON replies to those requests (at most 16 MB each). It never follows a redirect,
97
+ since a redirect would carry the `Authorization` header to another address, and it checks the TLS certificate.
98
+ - **Nothing else:** no telemetry, no analytics, no update checks, no other host.
99
+
100
+ ## Privacy
101
+
102
+ - The NPReq API receives your key (at `/v1/token` only), the tool arguments (a state code or a search text), your
103
+ IP address and the `User-Agent` above. It counts your requests against your plan's minute limit and monthly
104
+ quota. What NPReq keeps and for how long is in the privacy policy: https://npreq.com/privacy.html. Use of the API
105
+ is under the terms: https://npreq.com/terms.html.
106
+ - Do not put personal or patient information in a search: the search text is sent to the API.
107
+ - The server never writes your key or a token to its output, its log (one line per tool call, with the tool name and
108
+ the status, on stderr), a tool result or an error. It takes the key out of its own environment once it has read it.
109
+ - Results are curated requirement data with sources. The tools and the skill tell Claude to treat them as data, not
110
+ instructions.
111
+
112
+ ## What happens when something is refused
113
+
114
+ - **A refused key is held.** Once `/v1/token` answers `401` or `403`, the server sends nothing more with the key.
115
+ Every tool that needs a token answers at once with that status, and only `get_data_version` keeps working until
116
+ you fix the key (or its IP allowlist) and restart. This is because every refusal counts toward the API's lockout
117
+ of your IP address (10 in 10 minutes locks it for 15 minutes), so a retrying client can never lock you out.
118
+ - A `429` or `5xx` at `/v1/token` is temporary and is not held.
119
+ - A revoked key, a lapsed subscription, or a scope your plan lacks stops the tools on the next call: the API checks
120
+ the key behind every token on every request.
121
+
122
+ ## Without the plugin
123
+
124
+ Any MCP client that starts a local stdio server can run `npreq_mcp.py` directly. Set `NPREQ_API_KEY` in that
125
+ client's server configuration (never on a command line or in a prompt), and optionally `NPREQ_API_BASE`, which
126
+ accepts only an `https://` origin and defaults to `https://api.npreq.com`. For example, in Claude Desktop's
127
+ `claude_desktop_config.json`:
128
+
129
+ ```json
130
+ {
131
+ "mcpServers": {
132
+ "npreq": {
133
+ "command": "python3",
134
+ "args": ["/path/to/npreq-mcp/npreq_mcp.py"],
135
+ "env": { "NPREQ_API_KEY": "<your key>" }
136
+ }
137
+ }
138
+ }
139
+ ```
140
+
141
+ On Windows, use `python` (or `py -3`) instead of `python3`, and a full path with forward slashes. Installed with
142
+ `pip install .` from this folder, the server is also the `npreq-mcp` command.
143
+
144
+ The NPReq API documentation, with more client setups, is at https://account.npreq.com/account/docs.
145
+
146
+ ## Protocol
147
+
148
+ Newline-delimited JSON-RPC 2.0 on stdio. A request whose `_meta` carries `io.modelcontextprotocol/protocolVersion`
149
+ `2026-07-28` is served statelessly by that revision. An `initialize` request selects the handshake of `2025-11-25`,
150
+ `2025-06-18` or `2025-03-26` for the life of the process. Any other version gets error `-32022` with the supported
151
+ list. The server offers tools only: no resources, prompts, sampling or elicitation.
152
+
153
+ ## Tests
154
+
155
+ `python3 tests/test_npreq_mcp.py` runs on Python 3.10 and 3.13 with no network: the API is a fake, and the
156
+ child-process tests point the server at an address that refuses at once. They cover:
157
+
158
+ - the five routes and their argument checks;
159
+ - the error map;
160
+ - token renewal and the single retry, and the refused key held for the session;
161
+ - that redirects are never followed;
162
+ - that the key never appears in output, logs, results or arguments;
163
+ - the plugin's settings, and that the key the plugin passes wins over one set in the shell.
164
+
165
+ ## Security and licence
166
+
167
+ Report a vulnerability as described in [SECURITY.md](SECURITY.md); please do not open a public issue for it.
168
+ MIT licence: see [LICENSE](LICENSE).
@@ -0,0 +1,10 @@
1
+ LICENSE
2
+ README.md
3
+ npreq_mcp.py
4
+ pyproject.toml
5
+ npreq_mcp.egg-info/PKG-INFO
6
+ npreq_mcp.egg-info/SOURCES.txt
7
+ npreq_mcp.egg-info/dependency_links.txt
8
+ npreq_mcp.egg-info/entry_points.txt
9
+ npreq_mcp.egg-info/top_level.txt
10
+ tests/test_npreq_mcp.py
@@ -0,0 +1,2 @@
1
+ [console_scripts]
2
+ npreq-mcp = npreq_mcp:cli
@@ -0,0 +1 @@
1
+ npreq_mcp