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.
- npreq_mcp-0.1.0/LICENSE +21 -0
- npreq_mcp-0.1.0/PKG-INFO +168 -0
- npreq_mcp-0.1.0/README.md +148 -0
- npreq_mcp-0.1.0/npreq_mcp.egg-info/PKG-INFO +168 -0
- npreq_mcp-0.1.0/npreq_mcp.egg-info/SOURCES.txt +10 -0
- npreq_mcp-0.1.0/npreq_mcp.egg-info/dependency_links.txt +1 -0
- npreq_mcp-0.1.0/npreq_mcp.egg-info/entry_points.txt +2 -0
- npreq_mcp-0.1.0/npreq_mcp.egg-info/top_level.txt +1 -0
- npreq_mcp-0.1.0/npreq_mcp.py +467 -0
- npreq_mcp-0.1.0/pyproject.toml +33 -0
- npreq_mcp-0.1.0/setup.cfg +4 -0
- npreq_mcp-0.1.0/tests/test_npreq_mcp.py +764 -0
npreq_mcp-0.1.0/LICENSE
ADDED
|
@@ -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.
|
npreq_mcp-0.1.0/PKG-INFO
ADDED
|
@@ -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 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
npreq_mcp
|