obscate-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.
- obscate_mcp-0.1.0/.gitignore +12 -0
- obscate_mcp-0.1.0/LICENSE +21 -0
- obscate_mcp-0.1.0/PKG-INFO +192 -0
- obscate_mcp-0.1.0/README.md +171 -0
- obscate_mcp-0.1.0/pyproject.toml +39 -0
- obscate_mcp-0.1.0/src/obscate_mcp/__init__.py +2 -0
- obscate_mcp-0.1.0/src/obscate_mcp/__main__.py +3 -0
- obscate_mcp-0.1.0/src/obscate_mcp/_client.py +306 -0
- obscate_mcp-0.1.0/src/obscate_mcp/server.py +200 -0
- obscate_mcp-0.1.0/tests/fake_api.py +157 -0
- obscate_mcp-0.1.0/tests/test_server.py +178 -0
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Skycast
|
|
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,192 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: obscate-mcp
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: MCP server for Obscate: reversible PII redaction (redact, restore, detect, JSON) for AI agents
|
|
5
|
+
Project-URL: Homepage, https://obscate.com
|
|
6
|
+
Project-URL: Documentation, https://obscate.com/docs/mcp
|
|
7
|
+
Author: Skycast
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: agents,dpdp,gdpr,llm,mcp,pii,privacy,redaction
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Programming Language :: Python :: 3
|
|
13
|
+
Classifier: Topic :: Security
|
|
14
|
+
Requires-Python: >=3.10
|
|
15
|
+
Requires-Dist: httpx>=0.27
|
|
16
|
+
Requires-Dist: mcp<3,>=2.0
|
|
17
|
+
Provides-Extra: test
|
|
18
|
+
Requires-Dist: anyio>=4; extra == 'test'
|
|
19
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
20
|
+
Description-Content-Type: text/markdown
|
|
21
|
+
|
|
22
|
+
# obscate-mcp
|
|
23
|
+
|
|
24
|
+
An MCP server that gives any AI agent reversible PII redaction. Your agent
|
|
25
|
+
redacts personal data before a payload leaves (for another model, a tool or a
|
|
26
|
+
third-party API), then restores the real values in the reply.
|
|
27
|
+
|
|
28
|
+
It is a thin wrapper over the [Obscate](https://obscate.com) HTTP API.
|
|
29
|
+
Full docs: [obscate.com/docs/mcp](https://obscate.com/docs/mcp).
|
|
30
|
+
Detection runs in the API (hosted, or your own self-hosted instance). This
|
|
31
|
+
package only forwards calls.
|
|
32
|
+
|
|
33
|
+
<!-- mcp-name: com.obscate/mcp -->
|
|
34
|
+
|
|
35
|
+
| tool | what it does | API units |
|
|
36
|
+
|---|---|---|
|
|
37
|
+
| `redact` | redact a text; default `fpe` keeps formats and needs no map to restore | 1 per 100 KB |
|
|
38
|
+
| `restore` | put the original values back | free |
|
|
39
|
+
| `detect` | classify what PII a text contains (labels, offsets, counts) without changing it | 1 per 100 KB |
|
|
40
|
+
| `redact_json` | redact values inside a JSON object/array; keys and shape are unchanged | 1 per 100 KB |
|
|
41
|
+
| `restore_json` | restore any JSON reply | free |
|
|
42
|
+
| `list_entities` | supported labels and strategies | free, no key |
|
|
43
|
+
|
|
44
|
+
What to expect from detection: structured IDs (email, phone, cards, Aadhaar,
|
|
45
|
+
PAN, GSTIN, IBAN, SSN, IPs, AWS keys) are near-perfect because they are
|
|
46
|
+
regex- and checksum-based. Names and places come from an NER model and are
|
|
47
|
+
best-effort. Check the output if recall on those matters to you.
|
|
48
|
+
([Detectors and accuracy](https://obscate.com/docs/detectors),
|
|
49
|
+
[benchmark methodology](https://obscate.com/docs/benchmark).)
|
|
50
|
+
|
|
51
|
+
## Known limitation: partial values come back wrong
|
|
52
|
+
|
|
53
|
+
If the model quotes only **part** of a redacted value ("your card ending in
|
|
54
|
+
7588", "the email starting with…"), restore can't fix it: it matches whole
|
|
55
|
+
tokens, and a fragment isn't one. With `fpe` this fails **silently and
|
|
56
|
+
plausibly**. The fake card looks like a real card, so its last four digits
|
|
57
|
+
look like real digits, and your user sees a confident, wrong statement about
|
|
58
|
+
their own data. Assistants paraphrase values like this all the time, so expect
|
|
59
|
+
it in normal use.
|
|
60
|
+
|
|
61
|
+
What we measured with real Claude (`claude-haiku-5-5`, a support-reply prompt,
|
|
62
|
+
3 runs each; a small test, not a guarantee):
|
|
63
|
+
|
|
64
|
+
| setup | replies stating wrong card digits |
|
|
65
|
+
|---|---|
|
|
66
|
+
| `fpe`, plain prompt | 2 of 3 |
|
|
67
|
+
| `fpe` + the instruction below in the system prompt | 0 of 3 |
|
|
68
|
+
| `tokenize`, plain prompt | 0 of 3 |
|
|
69
|
+
|
|
70
|
+
For user-facing output where the model may paraphrase values:
|
|
71
|
+
|
|
72
|
+
- Add to your system prompt: *"When you mention a card number, email or phone
|
|
73
|
+
number, repeat it exactly and in full as given. Never abbreviate, mask or
|
|
74
|
+
quote part of it."*
|
|
75
|
+
- Or use `strategy="tokenize"`: models treat `[CREDIT_CARD_1]` as a unit and
|
|
76
|
+
don't split it, and restore only touches tokens in its map.
|
|
77
|
+
|
|
78
|
+
Partial references are a boundary of any reversible-redaction approach, not
|
|
79
|
+
only ours: once the model only sees a stand-in, a fragment of the stand-in can
|
|
80
|
+
never map back to a fragment of the original.
|
|
81
|
+
|
|
82
|
+
## Quickstart (about 3 minutes)
|
|
83
|
+
|
|
84
|
+
1. **Get a free API key** at [obscate.com](https://obscate.com) ([quickstart](https://obscate.com/docs/quickstart)). It is free
|
|
85
|
+
for 1,000 requests a month at 60 a minute, with no card. The key is shown
|
|
86
|
+
once.
|
|
87
|
+
2. **Install** with one of these:
|
|
88
|
+
```bash
|
|
89
|
+
uvx obscate-mcp --version # no install, runs from PyPI
|
|
90
|
+
pip install obscate-mcp # or install into an environment
|
|
91
|
+
```
|
|
92
|
+
3. **Add it to your MCP client** (below), with the key in the `env` block.
|
|
93
|
+
4. Ask your agent: *"Redact this before you send it to the CRM: Ravi Kumar,
|
|
94
|
+
ravi@example.com, +91 98765 43210"*.
|
|
95
|
+
|
|
96
|
+
### Claude Desktop
|
|
97
|
+
|
|
98
|
+
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
|
|
99
|
+
`%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
100
|
+
|
|
101
|
+
```json
|
|
102
|
+
{
|
|
103
|
+
"mcpServers": {
|
|
104
|
+
"obscate": {
|
|
105
|
+
"command": "uvx",
|
|
106
|
+
"args": ["obscate-mcp"],
|
|
107
|
+
"env": { "OBSCATE_API_KEY": "ob_..." }
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
}
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
### Claude Code
|
|
114
|
+
|
|
115
|
+
```bash
|
|
116
|
+
claude mcp add obscate --env OBSCATE_API_KEY=ob_... -- uvx obscate-mcp
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
### Cursor
|
|
120
|
+
|
|
121
|
+
`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project). Use the
|
|
122
|
+
same JSON block as Claude Desktop.
|
|
123
|
+
|
|
124
|
+
### Configuration
|
|
125
|
+
|
|
126
|
+
| env var | default | |
|
|
127
|
+
|---|---|---|
|
|
128
|
+
| `OBSCATE_API_KEY` | none | required for every tool except `list_entities` |
|
|
129
|
+
| `OBSCATE_BASE_URL` | `https://api.obscate.com` | point at a self-hosted Obscate (the self-hosted edition is in pilot; ask contact@obscate.com) |
|
|
130
|
+
|
|
131
|
+
Do not commit config files that contain the key. If your client supports env
|
|
132
|
+
files or secret references, use them.
|
|
133
|
+
|
|
134
|
+
`obscate-mcp --transport streamable-http` serves over HTTP instead of stdio.
|
|
135
|
+
|
|
136
|
+
## Example agent flow
|
|
137
|
+
|
|
138
|
+
The agent has a customer record and must create a ticket in a third-party
|
|
139
|
+
helpdesk tool, which should never see the raw PII.
|
|
140
|
+
|
|
141
|
+
```text
|
|
142
|
+
user: File a ticket: Ravi Kumar (ravi@example.com, +91 98765 43210) was double-charged on card 4242 4242 4242 4242.
|
|
143
|
+
|
|
144
|
+
agent → redact_json({"json": {"customer": "Ravi Kumar", "email": "ravi@example.com",
|
|
145
|
+
"phone": "+91 98765 43210", "issue": "double-charged on card 4242 4242 4242 4242"}})
|
|
146
|
+
← {"redacted": {"customer": "[PERSON:…]", "email": "<email-shaped value>", "phone": "<phone-shaped value>",
|
|
147
|
+
"issue": "double-charged on card <valid-looking card number>"},
|
|
148
|
+
"type_changes": [], "keys_redacted": false, …}
|
|
149
|
+
|
|
150
|
+
agent → helpdesk.create_ticket(<the redacted object>) # the tool only sees redacted values
|
|
151
|
+
← {"ticket": 812, "summary": "Refund for [PERSON:…], reply to <email-shaped value>"}
|
|
152
|
+
|
|
153
|
+
agent → restore_json({"json": <the tool's reply>, "type_changes": []})
|
|
154
|
+
← {"json": {"ticket": 812, "summary": "Refund for Ravi Kumar, reply to ravi@example.com"}}
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
With `strategy: "tokenize"` the redacted values look like `[EMAIL_1]`, and
|
|
158
|
+
you pass the returned `token_map` to `restore` / `restore_json`. With `fpe`
|
|
159
|
+
(the default) no map exists. Restore needs only your key, plus the
|
|
160
|
+
`key_version` that `redact` returned. Pass it back to `restore` or
|
|
161
|
+
`restore_json`. It names the version of your account's key that made the
|
|
162
|
+
tokens, so restore keeps working if Obscate rotates keys in between. If it is
|
|
163
|
+
left out, the current version is used.
|
|
164
|
+
|
|
165
|
+
**If you store redacted text to restore later**, store `key_version` with it.
|
|
166
|
+
|
|
167
|
+
**fpe caveat:** an email, phone number or ID that a model *invents*, which
|
|
168
|
+
was never redacted, is indistinguishable from an fpe token. `restore` will
|
|
169
|
+
decrypt it into a different value. Restore only text whose structured values
|
|
170
|
+
came from your own redaction. If that matters, use `tokenize`, which only
|
|
171
|
+
replaces tokens that appear in the map. See [strategies](https://obscate.com/docs/strategies).
|
|
172
|
+
|
|
173
|
+
## Privacy
|
|
174
|
+
|
|
175
|
+
- The server never logs, prints or stores the text, the detected values or
|
|
176
|
+
the token map. Errors carry the HTTP status and the API's fixed message
|
|
177
|
+
only. This is enforced by `tests/test_server.py::test_privacy_*`.
|
|
178
|
+
- `redact` and `detect` do not echo the original values back into the model's
|
|
179
|
+
context (`detect` can with `include_values: true`).
|
|
180
|
+
- The Obscate API has the same contract on its side: it does not log or store
|
|
181
|
+
payloads. The hosted API runs in DigitalOcean Bangalore. Traffic passes
|
|
182
|
+
through DigitalOcean's Cloudflare edge. See
|
|
183
|
+
[security & limits](https://obscate.com/docs/security).
|
|
184
|
+
|
|
185
|
+
## Develop
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
pip install -e '.[test]' && pytest -q # unit tests against an in-process fake API
|
|
189
|
+
OBSCATE_API_KEY=ob_... python ../scripts/live_e2e.py mcp # real end-to-end against the live API
|
|
190
|
+
```
|
|
191
|
+
|
|
192
|
+
License: MIT.
|
|
@@ -0,0 +1,171 @@
|
|
|
1
|
+
# obscate-mcp
|
|
2
|
+
|
|
3
|
+
An MCP server that gives any AI agent reversible PII redaction. Your agent
|
|
4
|
+
redacts personal data before a payload leaves (for another model, a tool or a
|
|
5
|
+
third-party API), then restores the real values in the reply.
|
|
6
|
+
|
|
7
|
+
It is a thin wrapper over the [Obscate](https://obscate.com) HTTP API.
|
|
8
|
+
Full docs: [obscate.com/docs/mcp](https://obscate.com/docs/mcp).
|
|
9
|
+
Detection runs in the API (hosted, or your own self-hosted instance). This
|
|
10
|
+
package only forwards calls.
|
|
11
|
+
|
|
12
|
+
<!-- mcp-name: com.obscate/mcp -->
|
|
13
|
+
|
|
14
|
+
| tool | what it does | API units |
|
|
15
|
+
|---|---|---|
|
|
16
|
+
| `redact` | redact a text; default `fpe` keeps formats and needs no map to restore | 1 per 100 KB |
|
|
17
|
+
| `restore` | put the original values back | free |
|
|
18
|
+
| `detect` | classify what PII a text contains (labels, offsets, counts) without changing it | 1 per 100 KB |
|
|
19
|
+
| `redact_json` | redact values inside a JSON object/array; keys and shape are unchanged | 1 per 100 KB |
|
|
20
|
+
| `restore_json` | restore any JSON reply | free |
|
|
21
|
+
| `list_entities` | supported labels and strategies | free, no key |
|
|
22
|
+
|
|
23
|
+
What to expect from detection: structured IDs (email, phone, cards, Aadhaar,
|
|
24
|
+
PAN, GSTIN, IBAN, SSN, IPs, AWS keys) are near-perfect because they are
|
|
25
|
+
regex- and checksum-based. Names and places come from an NER model and are
|
|
26
|
+
best-effort. Check the output if recall on those matters to you.
|
|
27
|
+
([Detectors and accuracy](https://obscate.com/docs/detectors),
|
|
28
|
+
[benchmark methodology](https://obscate.com/docs/benchmark).)
|
|
29
|
+
|
|
30
|
+
## Known limitation: partial values come back wrong
|
|
31
|
+
|
|
32
|
+
If the model quotes only **part** of a redacted value ("your card ending in
|
|
33
|
+
7588", "the email starting with…"), restore can't fix it: it matches whole
|
|
34
|
+
tokens, and a fragment isn't one. With `fpe` this fails **silently and
|
|
35
|
+
plausibly**. The fake card looks like a real card, so its last four digits
|
|
36
|
+
look like real digits, and your user sees a confident, wrong statement about
|
|
37
|
+
their own data. Assistants paraphrase values like this all the time, so expect
|
|
38
|
+
it in normal use.
|
|
39
|
+
|
|
40
|
+
What we measured with real Claude (`claude-haiku-5-5`, a support-reply prompt,
|
|
41
|
+
3 runs each; a small test, not a guarantee):
|
|
42
|
+
|
|
43
|
+
| setup | replies stating wrong card digits |
|
|
44
|
+
|---|---|
|
|
45
|
+
| `fpe`, plain prompt | 2 of 3 |
|
|
46
|
+
| `fpe` + the instruction below in the system prompt | 0 of 3 |
|
|
47
|
+
| `tokenize`, plain prompt | 0 of 3 |
|
|
48
|
+
|
|
49
|
+
For user-facing output where the model may paraphrase values:
|
|
50
|
+
|
|
51
|
+
- Add to your system prompt: *"When you mention a card number, email or phone
|
|
52
|
+
number, repeat it exactly and in full as given. Never abbreviate, mask or
|
|
53
|
+
quote part of it."*
|
|
54
|
+
- Or use `strategy="tokenize"`: models treat `[CREDIT_CARD_1]` as a unit and
|
|
55
|
+
don't split it, and restore only touches tokens in its map.
|
|
56
|
+
|
|
57
|
+
Partial references are a boundary of any reversible-redaction approach, not
|
|
58
|
+
only ours: once the model only sees a stand-in, a fragment of the stand-in can
|
|
59
|
+
never map back to a fragment of the original.
|
|
60
|
+
|
|
61
|
+
## Quickstart (about 3 minutes)
|
|
62
|
+
|
|
63
|
+
1. **Get a free API key** at [obscate.com](https://obscate.com) ([quickstart](https://obscate.com/docs/quickstart)). It is free
|
|
64
|
+
for 1,000 requests a month at 60 a minute, with no card. The key is shown
|
|
65
|
+
once.
|
|
66
|
+
2. **Install** with one of these:
|
|
67
|
+
```bash
|
|
68
|
+
uvx obscate-mcp --version # no install, runs from PyPI
|
|
69
|
+
pip install obscate-mcp # or install into an environment
|
|
70
|
+
```
|
|
71
|
+
3. **Add it to your MCP client** (below), with the key in the `env` block.
|
|
72
|
+
4. Ask your agent: *"Redact this before you send it to the CRM: Ravi Kumar,
|
|
73
|
+
ravi@example.com, +91 98765 43210"*.
|
|
74
|
+
|
|
75
|
+
### Claude Desktop
|
|
76
|
+
|
|
77
|
+
`~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or
|
|
78
|
+
`%APPDATA%\Claude\claude_desktop_config.json` (Windows):
|
|
79
|
+
|
|
80
|
+
```json
|
|
81
|
+
{
|
|
82
|
+
"mcpServers": {
|
|
83
|
+
"obscate": {
|
|
84
|
+
"command": "uvx",
|
|
85
|
+
"args": ["obscate-mcp"],
|
|
86
|
+
"env": { "OBSCATE_API_KEY": "ob_..." }
|
|
87
|
+
}
|
|
88
|
+
}
|
|
89
|
+
}
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
### Claude Code
|
|
93
|
+
|
|
94
|
+
```bash
|
|
95
|
+
claude mcp add obscate --env OBSCATE_API_KEY=ob_... -- uvx obscate-mcp
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Cursor
|
|
99
|
+
|
|
100
|
+
`~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per project). Use the
|
|
101
|
+
same JSON block as Claude Desktop.
|
|
102
|
+
|
|
103
|
+
### Configuration
|
|
104
|
+
|
|
105
|
+
| env var | default | |
|
|
106
|
+
|---|---|---|
|
|
107
|
+
| `OBSCATE_API_KEY` | none | required for every tool except `list_entities` |
|
|
108
|
+
| `OBSCATE_BASE_URL` | `https://api.obscate.com` | point at a self-hosted Obscate (the self-hosted edition is in pilot; ask contact@obscate.com) |
|
|
109
|
+
|
|
110
|
+
Do not commit config files that contain the key. If your client supports env
|
|
111
|
+
files or secret references, use them.
|
|
112
|
+
|
|
113
|
+
`obscate-mcp --transport streamable-http` serves over HTTP instead of stdio.
|
|
114
|
+
|
|
115
|
+
## Example agent flow
|
|
116
|
+
|
|
117
|
+
The agent has a customer record and must create a ticket in a third-party
|
|
118
|
+
helpdesk tool, which should never see the raw PII.
|
|
119
|
+
|
|
120
|
+
```text
|
|
121
|
+
user: File a ticket: Ravi Kumar (ravi@example.com, +91 98765 43210) was double-charged on card 4242 4242 4242 4242.
|
|
122
|
+
|
|
123
|
+
agent → redact_json({"json": {"customer": "Ravi Kumar", "email": "ravi@example.com",
|
|
124
|
+
"phone": "+91 98765 43210", "issue": "double-charged on card 4242 4242 4242 4242"}})
|
|
125
|
+
← {"redacted": {"customer": "[PERSON:…]", "email": "<email-shaped value>", "phone": "<phone-shaped value>",
|
|
126
|
+
"issue": "double-charged on card <valid-looking card number>"},
|
|
127
|
+
"type_changes": [], "keys_redacted": false, …}
|
|
128
|
+
|
|
129
|
+
agent → helpdesk.create_ticket(<the redacted object>) # the tool only sees redacted values
|
|
130
|
+
← {"ticket": 812, "summary": "Refund for [PERSON:…], reply to <email-shaped value>"}
|
|
131
|
+
|
|
132
|
+
agent → restore_json({"json": <the tool's reply>, "type_changes": []})
|
|
133
|
+
← {"json": {"ticket": 812, "summary": "Refund for Ravi Kumar, reply to ravi@example.com"}}
|
|
134
|
+
```
|
|
135
|
+
|
|
136
|
+
With `strategy: "tokenize"` the redacted values look like `[EMAIL_1]`, and
|
|
137
|
+
you pass the returned `token_map` to `restore` / `restore_json`. With `fpe`
|
|
138
|
+
(the default) no map exists. Restore needs only your key, plus the
|
|
139
|
+
`key_version` that `redact` returned. Pass it back to `restore` or
|
|
140
|
+
`restore_json`. It names the version of your account's key that made the
|
|
141
|
+
tokens, so restore keeps working if Obscate rotates keys in between. If it is
|
|
142
|
+
left out, the current version is used.
|
|
143
|
+
|
|
144
|
+
**If you store redacted text to restore later**, store `key_version` with it.
|
|
145
|
+
|
|
146
|
+
**fpe caveat:** an email, phone number or ID that a model *invents*, which
|
|
147
|
+
was never redacted, is indistinguishable from an fpe token. `restore` will
|
|
148
|
+
decrypt it into a different value. Restore only text whose structured values
|
|
149
|
+
came from your own redaction. If that matters, use `tokenize`, which only
|
|
150
|
+
replaces tokens that appear in the map. See [strategies](https://obscate.com/docs/strategies).
|
|
151
|
+
|
|
152
|
+
## Privacy
|
|
153
|
+
|
|
154
|
+
- The server never logs, prints or stores the text, the detected values or
|
|
155
|
+
the token map. Errors carry the HTTP status and the API's fixed message
|
|
156
|
+
only. This is enforced by `tests/test_server.py::test_privacy_*`.
|
|
157
|
+
- `redact` and `detect` do not echo the original values back into the model's
|
|
158
|
+
context (`detect` can with `include_values: true`).
|
|
159
|
+
- The Obscate API has the same contract on its side: it does not log or store
|
|
160
|
+
payloads. The hosted API runs in DigitalOcean Bangalore. Traffic passes
|
|
161
|
+
through DigitalOcean's Cloudflare edge. See
|
|
162
|
+
[security & limits](https://obscate.com/docs/security).
|
|
163
|
+
|
|
164
|
+
## Develop
|
|
165
|
+
|
|
166
|
+
```bash
|
|
167
|
+
pip install -e '.[test]' && pytest -q # unit tests against an in-process fake API
|
|
168
|
+
OBSCATE_API_KEY=ob_... python ../scripts/live_e2e.py mcp # real end-to-end against the live API
|
|
169
|
+
```
|
|
170
|
+
|
|
171
|
+
License: MIT.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
[build-system]
|
|
2
|
+
requires = ["hatchling>=1.25"]
|
|
3
|
+
build-backend = "hatchling.build"
|
|
4
|
+
|
|
5
|
+
[project]
|
|
6
|
+
name = "obscate-mcp"
|
|
7
|
+
version = "0.1.0"
|
|
8
|
+
description = "MCP server for Obscate: reversible PII redaction (redact, restore, detect, JSON) for AI agents"
|
|
9
|
+
readme = "README.md"
|
|
10
|
+
requires-python = ">=3.10"
|
|
11
|
+
license = "MIT"
|
|
12
|
+
authors = [{ name = "Skycast" }]
|
|
13
|
+
keywords = ["mcp", "pii", "redaction", "privacy", "llm", "agents", "dpdp", "gdpr"]
|
|
14
|
+
classifiers = [
|
|
15
|
+
"Programming Language :: Python :: 3",
|
|
16
|
+
"Topic :: Security",
|
|
17
|
+
"Development Status :: 4 - Beta",
|
|
18
|
+
]
|
|
19
|
+
dependencies = ["mcp>=2.0,<3", "httpx>=0.27"]
|
|
20
|
+
|
|
21
|
+
[project.urls]
|
|
22
|
+
Homepage = "https://obscate.com"
|
|
23
|
+
Documentation = "https://obscate.com/docs/mcp"
|
|
24
|
+
|
|
25
|
+
[project.scripts]
|
|
26
|
+
obscate-mcp = "obscate_mcp.server:main"
|
|
27
|
+
|
|
28
|
+
[project.optional-dependencies]
|
|
29
|
+
test = ["pytest>=8", "anyio>=4"]
|
|
30
|
+
|
|
31
|
+
[tool.hatch.build.targets.wheel]
|
|
32
|
+
packages = ["src/obscate_mcp"]
|
|
33
|
+
|
|
34
|
+
[tool.pytest.ini_options]
|
|
35
|
+
testpaths = ["tests"]
|
|
36
|
+
|
|
37
|
+
[tool.hatch.build.targets.sdist]
|
|
38
|
+
# server.json is MCP-registry metadata, published separately; not part of the package
|
|
39
|
+
exclude = ["server.json"]
|
|
@@ -0,0 +1,306 @@
|
|
|
1
|
+
"""Minimal client for the Obscate HTTP API, shared by the Obscate integrations.
|
|
2
|
+
|
|
3
|
+
This file is vendored byte-for-byte into each package (obscate-mcp,
|
|
4
|
+
langchain-obscate, llama-index-postprocessor-obscate) so every package installs
|
|
5
|
+
on its own. Edit ``shared/_client.py`` and run ``python scripts/sync_client.py``;
|
|
6
|
+
a test fails if the copies drift.
|
|
7
|
+
|
|
8
|
+
Privacy contract (tested in every package):
|
|
9
|
+
* Nothing here logs, prints or writes to disk the text you send, the values
|
|
10
|
+
detected, or the restore map.
|
|
11
|
+
* ``ObscateError`` carries the HTTP status and the server's ``detail`` only.
|
|
12
|
+
The API never echoes request bodies in errors, so neither do we.
|
|
13
|
+
* ``RestoreContext`` keeps the token map in memory only and hides it from
|
|
14
|
+
``repr()`` so it does not end up in tracebacks or debug logs by accident.
|
|
15
|
+
|
|
16
|
+
Key versions: every redact response carries ``key_version`` (the version of
|
|
17
|
+
your account's key that made the tokens). ``RestoreContext`` keeps it and
|
|
18
|
+
every restore sends it back, so a redact -> LLM -> restore round trip keeps
|
|
19
|
+
working across a server-side key rotation with no code on your side. If you
|
|
20
|
+
store fpe tokens to restore later without a context, store ``key_version``
|
|
21
|
+
with them too (see https://obscate.com/docs/strategies).
|
|
22
|
+
"""
|
|
23
|
+
from __future__ import annotations
|
|
24
|
+
|
|
25
|
+
import os
|
|
26
|
+
from dataclasses import dataclass, field
|
|
27
|
+
from typing import Any, Iterable
|
|
28
|
+
|
|
29
|
+
import httpx
|
|
30
|
+
|
|
31
|
+
DEFAULT_BASE_URL = "https://api.obscate.com"
|
|
32
|
+
STRATEGIES = ("fpe", "tokenize", "synthetic", "mask", "hash", "partial")
|
|
33
|
+
REVERSIBLE = ("fpe", "tokenize", "synthetic")
|
|
34
|
+
SIGNUP_URL = "https://obscate.com"
|
|
35
|
+
|
|
36
|
+
__all__ = ["ObscateClient", "ObscateError", "RestoreContext", "DEFAULT_BASE_URL",
|
|
37
|
+
"STRATEGIES", "REVERSIBLE"]
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
class ObscateError(RuntimeError):
|
|
41
|
+
"""An Obscate API call failed. Holds the status code and the server's
|
|
42
|
+
``detail`` message — never any of the text you sent."""
|
|
43
|
+
|
|
44
|
+
def __init__(self, message: str, status: int | None = None, request_id: str | None = None):
|
|
45
|
+
super().__init__(message)
|
|
46
|
+
self.status = status
|
|
47
|
+
self.request_id = request_id
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
@dataclass
|
|
51
|
+
class RestoreContext:
|
|
52
|
+
"""What is needed to undo one redaction. In-memory only; never logged.
|
|
53
|
+
|
|
54
|
+
For ``fpe`` the context holds no secrets at all (restore needs only your
|
|
55
|
+
API key). For ``tokenize``/``synthetic`` it holds the token map, which
|
|
56
|
+
contains the original values — keep it in memory and let it go when done.
|
|
57
|
+
"""
|
|
58
|
+
strategy: str
|
|
59
|
+
token_map: dict[str, str] = field(default_factory=dict, repr=False)
|
|
60
|
+
type_changes: list[dict] = field(default_factory=list, repr=False)
|
|
61
|
+
keys_redacted: bool = False
|
|
62
|
+
labels: list[str] | None = None
|
|
63
|
+
min_confidence: float = 0.0
|
|
64
|
+
hints: bool = True
|
|
65
|
+
field_map: dict[str, str | None] | None = field(default=None, repr=False)
|
|
66
|
+
key_version: int | None = None # from the redact response; None = server's current
|
|
67
|
+
|
|
68
|
+
@property
|
|
69
|
+
def reversible(self) -> bool:
|
|
70
|
+
return self.strategy in REVERSIBLE
|
|
71
|
+
|
|
72
|
+
def merge(self, other: "RestoreContext") -> "RestoreContext":
|
|
73
|
+
"""Combine two contexts from the same strategy (token maps are unioned)."""
|
|
74
|
+
if other.strategy != self.strategy:
|
|
75
|
+
raise ValueError("cannot merge restore contexts from different strategies")
|
|
76
|
+
if None not in (self.key_version, other.key_version) and self.key_version != other.key_version:
|
|
77
|
+
raise ValueError("cannot merge restore contexts made under different key versions")
|
|
78
|
+
merged = dict(self.token_map)
|
|
79
|
+
merged.update(other.token_map)
|
|
80
|
+
kv = self.key_version if self.key_version is not None else other.key_version
|
|
81
|
+
return RestoreContext(self.strategy, merged, [], False, self.labels,
|
|
82
|
+
self.min_confidence, self.hints, self.field_map, kv)
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _check_strategy(strategy: str) -> None:
|
|
86
|
+
if strategy not in STRATEGIES:
|
|
87
|
+
raise ValueError(f"strategy must be one of {list(STRATEGIES)}")
|
|
88
|
+
|
|
89
|
+
|
|
90
|
+
class ObscateClient:
|
|
91
|
+
"""Thin synchronous + asynchronous wrapper over the Obscate REST API.
|
|
92
|
+
|
|
93
|
+
``api_key`` defaults to ``$OBSCATE_API_KEY``; ``base_url`` defaults to
|
|
94
|
+
``$OBSCATE_BASE_URL`` or https://api.obscate.com (point it at a
|
|
95
|
+
self-hosted instance if you run one).
|
|
96
|
+
"""
|
|
97
|
+
|
|
98
|
+
def __init__(self, api_key: str | None = None, base_url: str | None = None,
|
|
99
|
+
timeout: float = 30.0, user_agent: str = "obscate-python-integration",
|
|
100
|
+
transport: httpx.BaseTransport | None = None,
|
|
101
|
+
async_transport: httpx.AsyncBaseTransport | None = None):
|
|
102
|
+
self._api_key = api_key if api_key is not None else os.environ.get("OBSCATE_API_KEY", "")
|
|
103
|
+
self.base_url = (base_url or os.environ.get("OBSCATE_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
|
|
104
|
+
self.timeout = timeout
|
|
105
|
+
self._headers = {"user-agent": user_agent, "accept": "application/json"}
|
|
106
|
+
self._transport = transport
|
|
107
|
+
self._async_transport = async_transport
|
|
108
|
+
self._http: httpx.Client | None = None
|
|
109
|
+
self._ahttp: httpx.AsyncClient | None = None
|
|
110
|
+
|
|
111
|
+
def __repr__(self) -> str: # never show the key
|
|
112
|
+
return f"ObscateClient(base_url={self.base_url!r}, api_key={'set' if self._api_key else 'missing'})"
|
|
113
|
+
|
|
114
|
+
# -- plumbing ---------------------------------------------------------------
|
|
115
|
+
def _auth_headers(self) -> dict[str, str]:
|
|
116
|
+
if not self._api_key:
|
|
117
|
+
raise ObscateError(
|
|
118
|
+
"OBSCATE_API_KEY is not set. Get a free key (1,000 requests/month) at "
|
|
119
|
+
f"{SIGNUP_URL} and export OBSCATE_API_KEY, or pass api_key=...")
|
|
120
|
+
return {**self._headers, "x-api-key": self._api_key}
|
|
121
|
+
|
|
122
|
+
@staticmethod
|
|
123
|
+
def _handle(resp: httpx.Response) -> Any:
|
|
124
|
+
if resp.status_code < 400:
|
|
125
|
+
return resp.json()
|
|
126
|
+
try:
|
|
127
|
+
detail = resp.json().get("detail")
|
|
128
|
+
except Exception:
|
|
129
|
+
detail = None
|
|
130
|
+
if not isinstance(detail, str):
|
|
131
|
+
# 422 validation errors are a list of {loc,msg,type}; keep field paths + messages only.
|
|
132
|
+
if isinstance(detail, list):
|
|
133
|
+
detail = "; ".join(f"{'.'.join(str(p) for p in d.get('loc', []))}: {d.get('msg')}"
|
|
134
|
+
for d in detail if isinstance(d, dict))
|
|
135
|
+
else:
|
|
136
|
+
detail = resp.reason_phrase
|
|
137
|
+
hint = {401: " (check OBSCATE_API_KEY)",
|
|
138
|
+
402: " (monthly quota reached; see https://obscate.com/pricing)",
|
|
139
|
+
429: f" (retry after {resp.headers.get('retry-after', '?')}s)",
|
|
140
|
+
503: " (detection failed closed: nothing was redacted)"}.get(resp.status_code, "")
|
|
141
|
+
raise ObscateError(f"Obscate API error {resp.status_code}: {detail}{hint}",
|
|
142
|
+
status=resp.status_code, request_id=resp.headers.get("x-request-id"))
|
|
143
|
+
|
|
144
|
+
def _client(self) -> httpx.Client:
|
|
145
|
+
if self._http is None:
|
|
146
|
+
self._http = httpx.Client(base_url=self.base_url, timeout=self.timeout,
|
|
147
|
+
transport=self._transport)
|
|
148
|
+
return self._http
|
|
149
|
+
|
|
150
|
+
def _aclient(self) -> httpx.AsyncClient:
|
|
151
|
+
if self._ahttp is None:
|
|
152
|
+
self._ahttp = httpx.AsyncClient(base_url=self.base_url, timeout=self.timeout,
|
|
153
|
+
transport=self._async_transport)
|
|
154
|
+
return self._ahttp
|
|
155
|
+
|
|
156
|
+
def _post(self, path: str, body: dict) -> Any:
|
|
157
|
+
try:
|
|
158
|
+
resp = self._client().post(path, json=body, headers=self._auth_headers())
|
|
159
|
+
except httpx.HTTPError as e: # network errors carry the URL, not the body
|
|
160
|
+
raise ObscateError(f"could not reach Obscate at {self.base_url}: {type(e).__name__}") from None
|
|
161
|
+
return self._handle(resp)
|
|
162
|
+
|
|
163
|
+
async def _apost(self, path: str, body: dict) -> Any:
|
|
164
|
+
try:
|
|
165
|
+
resp = await self._aclient().post(path, json=body, headers=self._auth_headers())
|
|
166
|
+
except httpx.HTTPError as e:
|
|
167
|
+
raise ObscateError(f"could not reach Obscate at {self.base_url}: {type(e).__name__}") from None
|
|
168
|
+
return self._handle(resp)
|
|
169
|
+
|
|
170
|
+
def close(self) -> None:
|
|
171
|
+
if self._http is not None:
|
|
172
|
+
self._http.close()
|
|
173
|
+
self._http = None
|
|
174
|
+
|
|
175
|
+
async def aclose(self) -> None:
|
|
176
|
+
if self._ahttp is not None:
|
|
177
|
+
await self._ahttp.aclose()
|
|
178
|
+
self._ahttp = None
|
|
179
|
+
|
|
180
|
+
# -- request bodies (shared by sync + async) ----------------------------------
|
|
181
|
+
@staticmethod
|
|
182
|
+
def _redact_body(text, strategy, labels, min_confidence):
|
|
183
|
+
_check_strategy(strategy)
|
|
184
|
+
return {"text": text, "strategy": strategy, "labels": labels, "min_confidence": min_confidence}
|
|
185
|
+
|
|
186
|
+
@staticmethod
|
|
187
|
+
def _redact_json_body(payload, strategy, labels, min_confidence, hints, field_map, keys):
|
|
188
|
+
_check_strategy(strategy)
|
|
189
|
+
if keys not in ("report", "strict", "redact"):
|
|
190
|
+
raise ValueError("keys must be 'report', 'strict' or 'redact'")
|
|
191
|
+
return {"json": payload, "strategy": strategy, "labels": labels,
|
|
192
|
+
"min_confidence": min_confidence, "hints": hints, "field_map": field_map, "keys": keys}
|
|
193
|
+
|
|
194
|
+
@staticmethod
|
|
195
|
+
def _restore_route(text: str, ctx: RestoreContext) -> tuple[str, dict]:
|
|
196
|
+
if ctx.strategy == "fpe":
|
|
197
|
+
body = {"text": text, "labels": ctx.labels, "min_confidence": ctx.min_confidence}
|
|
198
|
+
if ctx.key_version is not None:
|
|
199
|
+
body["key_version"] = ctx.key_version
|
|
200
|
+
return "/v1/restore-fpe", body
|
|
201
|
+
if ctx.strategy in ("tokenize", "synthetic"):
|
|
202
|
+
return "/v1/restore", {"text": text, "token_map": ctx.token_map}
|
|
203
|
+
raise ValueError(f"strategy {ctx.strategy!r} is one-way and cannot be restored; "
|
|
204
|
+
f"use one of {list(REVERSIBLE)}")
|
|
205
|
+
|
|
206
|
+
@staticmethod
|
|
207
|
+
def _restore_json_body(payload: Any, ctx: RestoreContext) -> dict:
|
|
208
|
+
if not ctx.reversible:
|
|
209
|
+
raise ValueError(f"strategy {ctx.strategy!r} is one-way and cannot be restored")
|
|
210
|
+
body = {"json": payload, "token_map": ctx.token_map, "fpe": ctx.strategy == "fpe",
|
|
211
|
+
"type_changes": ctx.type_changes or None, "keys_redacted": ctx.keys_redacted,
|
|
212
|
+
"labels": ctx.labels, "min_confidence": ctx.min_confidence,
|
|
213
|
+
"hints": ctx.hints, "field_map": ctx.field_map}
|
|
214
|
+
if ctx.key_version is not None:
|
|
215
|
+
body["key_version"] = ctx.key_version
|
|
216
|
+
return body
|
|
217
|
+
|
|
218
|
+
@staticmethod
|
|
219
|
+
def _ctx(r: dict, strategy, labels, min_confidence, hints=True, field_map=None) -> RestoreContext:
|
|
220
|
+
kv = r.get("key_version")
|
|
221
|
+
return RestoreContext(strategy, dict(r.get("token_map") or {}), list(r.get("type_changes") or []),
|
|
222
|
+
bool(r.get("keys_redacted")), labels, min_confidence, hints, field_map,
|
|
223
|
+
kv if isinstance(kv, int) else None)
|
|
224
|
+
|
|
225
|
+
# -- sync API ---------------------------------------------------------------
|
|
226
|
+
def redact(self, text: str, strategy: str = "fpe", labels: list[str] | None = None,
|
|
227
|
+
min_confidence: float = 0.0) -> tuple[dict, RestoreContext]:
|
|
228
|
+
"""POST /v1/redact. Returns the raw response and a context for restore()."""
|
|
229
|
+
r = self._post("/v1/redact", self._redact_body(text, strategy, labels, min_confidence))
|
|
230
|
+
return r, self._ctx(r, strategy, labels, min_confidence)
|
|
231
|
+
|
|
232
|
+
def restore(self, text: str, ctx: RestoreContext) -> str:
|
|
233
|
+
"""POST /v1/restore (token map) or /v1/restore-fpe (map-free). Free."""
|
|
234
|
+
path, body = self._restore_route(text, ctx)
|
|
235
|
+
return self._post(path, body)["text"]
|
|
236
|
+
|
|
237
|
+
def detect(self, text: str, labels: list[str] | None = None, min_confidence: float = 0.0) -> dict:
|
|
238
|
+
"""POST /v1/detect. Metered like redact."""
|
|
239
|
+
return self._post("/v1/detect", {"text": text, "labels": labels, "min_confidence": min_confidence})
|
|
240
|
+
|
|
241
|
+
def redact_json(self, payload: Any, strategy: str = "fpe", labels: list[str] | None = None,
|
|
242
|
+
min_confidence: float = 0.0, hints: bool = True,
|
|
243
|
+
field_map: dict[str, str | None] | None = None,
|
|
244
|
+
keys: str = "report") -> tuple[dict, RestoreContext]:
|
|
245
|
+
"""POST /v1/redact-json. One request (one unit up to 100 KB) for the whole payload."""
|
|
246
|
+
r = self._post("/v1/redact-json", self._redact_json_body(payload, strategy, labels, min_confidence,
|
|
247
|
+
hints, field_map, keys))
|
|
248
|
+
return r, self._ctx(r, strategy, labels, min_confidence, hints, field_map)
|
|
249
|
+
|
|
250
|
+
def restore_json(self, payload: Any, ctx: RestoreContext) -> Any:
|
|
251
|
+
"""POST /v1/restore-json. Free."""
|
|
252
|
+
return self._post("/v1/restore-json", self._restore_json_body(payload, ctx))["json"]
|
|
253
|
+
|
|
254
|
+
def redact_texts(self, texts: Iterable[str], strategy: str = "fpe", labels: list[str] | None = None,
|
|
255
|
+
min_confidence: float = 0.0) -> tuple[list[str], RestoreContext]:
|
|
256
|
+
"""Redact several strings in ONE request with consistent tokens across them.
|
|
257
|
+
|
|
258
|
+
Uses /v1/redact-json on a JSON array, so ``[PERSON_1]`` means the same
|
|
259
|
+
person in every string and the whole batch costs one unit (≤ 100 KB).
|
|
260
|
+
"""
|
|
261
|
+
texts = list(texts)
|
|
262
|
+
if not texts:
|
|
263
|
+
return [], RestoreContext(strategy, labels=labels, min_confidence=min_confidence)
|
|
264
|
+
r, ctx = self.redact_json(texts, strategy, labels, min_confidence, hints=False)
|
|
265
|
+
return list(r["redacted"]), ctx
|
|
266
|
+
|
|
267
|
+
def entities(self) -> dict:
|
|
268
|
+
"""GET /v1/entities (public, no key needed)."""
|
|
269
|
+
try:
|
|
270
|
+
resp = self._client().get("/v1/entities", headers=self._headers)
|
|
271
|
+
except httpx.HTTPError as e:
|
|
272
|
+
raise ObscateError(f"could not reach Obscate at {self.base_url}: {type(e).__name__}") from None
|
|
273
|
+
return self._handle(resp)
|
|
274
|
+
|
|
275
|
+
# -- async API --------------------------------------------------------------
|
|
276
|
+
async def aredact(self, text: str, strategy: str = "fpe", labels: list[str] | None = None,
|
|
277
|
+
min_confidence: float = 0.0) -> tuple[dict, RestoreContext]:
|
|
278
|
+
r = await self._apost("/v1/redact", self._redact_body(text, strategy, labels, min_confidence))
|
|
279
|
+
return r, self._ctx(r, strategy, labels, min_confidence)
|
|
280
|
+
|
|
281
|
+
async def arestore(self, text: str, ctx: RestoreContext) -> str:
|
|
282
|
+
path, body = self._restore_route(text, ctx)
|
|
283
|
+
return (await self._apost(path, body))["text"]
|
|
284
|
+
|
|
285
|
+
async def adetect(self, text: str, labels: list[str] | None = None, min_confidence: float = 0.0) -> dict:
|
|
286
|
+
return await self._apost("/v1/detect", {"text": text, "labels": labels, "min_confidence": min_confidence})
|
|
287
|
+
|
|
288
|
+
async def aredact_json(self, payload: Any, strategy: str = "fpe", labels: list[str] | None = None,
|
|
289
|
+
min_confidence: float = 0.0, hints: bool = True,
|
|
290
|
+
field_map: dict[str, str | None] | None = None,
|
|
291
|
+
keys: str = "report") -> tuple[dict, RestoreContext]:
|
|
292
|
+
r = await self._apost("/v1/redact-json", self._redact_json_body(payload, strategy, labels,
|
|
293
|
+
min_confidence, hints, field_map, keys))
|
|
294
|
+
return r, self._ctx(r, strategy, labels, min_confidence, hints, field_map)
|
|
295
|
+
|
|
296
|
+
async def arestore_json(self, payload: Any, ctx: RestoreContext) -> Any:
|
|
297
|
+
return (await self._apost("/v1/restore-json", self._restore_json_body(payload, ctx)))["json"]
|
|
298
|
+
|
|
299
|
+
async def aredact_texts(self, texts: Iterable[str], strategy: str = "fpe",
|
|
300
|
+
labels: list[str] | None = None,
|
|
301
|
+
min_confidence: float = 0.0) -> tuple[list[str], RestoreContext]:
|
|
302
|
+
texts = list(texts)
|
|
303
|
+
if not texts:
|
|
304
|
+
return [], RestoreContext(strategy, labels=labels, min_confidence=min_confidence)
|
|
305
|
+
r, ctx = await self.aredact_json(texts, strategy, labels, min_confidence, hints=False)
|
|
306
|
+
return list(r["redacted"]), ctx
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
"""Obscate MCP server: reversible PII redaction tools for AI agents.
|
|
2
|
+
|
|
3
|
+
Every tool is a thin call to the Obscate HTTP API (detection runs there, not
|
|
4
|
+
here). Configure with environment variables:
|
|
5
|
+
|
|
6
|
+
OBSCATE_API_KEY required for every tool except list_entities
|
|
7
|
+
OBSCATE_BASE_URL optional; default https://api.obscate.com (or your
|
|
8
|
+
self-hosted instance)
|
|
9
|
+
|
|
10
|
+
Privacy: this process never logs, prints or writes the text, the detected
|
|
11
|
+
values or the token map. Tool errors carry the HTTP status and the API's
|
|
12
|
+
fixed error message only.
|
|
13
|
+
"""
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
from typing import Any, Literal
|
|
17
|
+
|
|
18
|
+
from mcp.server.mcpserver import MCPServer
|
|
19
|
+
from mcp.server.mcpserver.exceptions import ToolError
|
|
20
|
+
from mcp.types import ToolAnnotations
|
|
21
|
+
|
|
22
|
+
from . import __version__
|
|
23
|
+
from ._client import ObscateClient, ObscateError, RestoreContext
|
|
24
|
+
|
|
25
|
+
Strategy = Literal["fpe", "tokenize", "synthetic", "mask", "hash", "partial"]
|
|
26
|
+
KeysMode = Literal["report", "strict", "redact"]
|
|
27
|
+
|
|
28
|
+
INSTRUCTIONS = """\
|
|
29
|
+
Obscate redacts personal data (emails, phone numbers, card numbers, Aadhaar,
|
|
30
|
+
PAN, names, places, ...) reversibly. Typical agent flow:
|
|
31
|
+
1. Before sending user data to another tool, model or third-party API, call
|
|
32
|
+
`redact` (text) or `redact_json` (objects). Send the redacted output.
|
|
33
|
+
2. When the reply comes back, call `restore` / `restore_json` with the same
|
|
34
|
+
`strategy` and `key_version` (and the `token_map` for tokenize/synthetic)
|
|
35
|
+
to put the real values back before showing it to the user.
|
|
36
|
+
Default strategy `fpe` keeps formats (an email stays email-shaped) and needs no
|
|
37
|
+
token_map to restore. Structured IDs are detected near-perfectly; names and
|
|
38
|
+
places are best-effort, so review if recall on those matters.
|
|
39
|
+
"""
|
|
40
|
+
|
|
41
|
+
_READ_ONLY = ToolAnnotations(readOnlyHint=True, destructiveHint=False, idempotentHint=True,
|
|
42
|
+
openWorldHint=True)
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def _fail(e: Exception) -> ToolError:
|
|
46
|
+
# Safe by construction: ObscateError/ValueError messages never contain payload text.
|
|
47
|
+
return ToolError(str(e))
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _public_entities(entities: list[dict]) -> list[dict]:
|
|
51
|
+
"""Labels, positions and replacements only. The caller already has the
|
|
52
|
+
originals; we don't echo them back into the model context."""
|
|
53
|
+
keep = ("label", "replacement", "path", "confidence")
|
|
54
|
+
return [{k: e[k] for k in keep if k in e} for e in entities]
|
|
55
|
+
|
|
56
|
+
|
|
57
|
+
def build_server(client: ObscateClient | None = None) -> MCPServer:
|
|
58
|
+
ob = client or ObscateClient(user_agent=f"obscate-mcp/{__version__}")
|
|
59
|
+
mcp = MCPServer(name="obscate", title="Obscate PII redaction", version=__version__,
|
|
60
|
+
instructions=INSTRUCTIONS, website_url="https://obscate.com/docs/mcp")
|
|
61
|
+
|
|
62
|
+
@mcp.tool(annotations=_READ_ONLY)
|
|
63
|
+
async def redact(text: str, strategy: Strategy = "fpe", labels: list[str] | None = None,
|
|
64
|
+
min_confidence: float = 0.0) -> dict[str, Any]:
|
|
65
|
+
"""Redact PII in a text before it is sent anywhere else.
|
|
66
|
+
|
|
67
|
+
strategy: `fpe` (default; format-preserving, restorable without a map;
|
|
68
|
+
names/places become bracketed `[PERSON:...]` tokens), `tokenize`
|
|
69
|
+
(`[EMAIL_1]`, needs the returned token_map to restore), `synthetic`
|
|
70
|
+
(realistic fakes, needs token_map), or one-way `mask`/`hash`/`partial`.
|
|
71
|
+
labels: optional filter such as ["EMAIL","PHONE"]; see list_entities.
|
|
72
|
+
Costs 1 API unit per 100 KB.
|
|
73
|
+
"""
|
|
74
|
+
try:
|
|
75
|
+
r, _ = await ob.aredact(text, strategy, labels, min_confidence)
|
|
76
|
+
except (ObscateError, ValueError) as e:
|
|
77
|
+
raise _fail(e) from None
|
|
78
|
+
out = {"redacted": r["redacted"], "strategy": strategy, "reversible": r.get("reversible"),
|
|
79
|
+
"entities": _public_entities(r.get("entities", [])), "counts": r.get("counts", {})}
|
|
80
|
+
if r.get("key_version") is not None:
|
|
81
|
+
out["key_version"] = r["key_version"]
|
|
82
|
+
if strategy in ("tokenize", "synthetic"):
|
|
83
|
+
out["token_map"] = r.get("token_map", {})
|
|
84
|
+
out["restore_with"] = "restore(text, strategy, token_map)"
|
|
85
|
+
elif strategy == "fpe":
|
|
86
|
+
out["restore_with"] = "restore(text, strategy='fpe', key_version) - no token_map needed"
|
|
87
|
+
return out
|
|
88
|
+
|
|
89
|
+
@mcp.tool(annotations=_READ_ONLY)
|
|
90
|
+
async def restore(text: str, strategy: Literal["fpe", "tokenize", "synthetic"] = "fpe",
|
|
91
|
+
token_map: dict[str, str] | None = None, labels: list[str] | None = None,
|
|
92
|
+
min_confidence: float = 0.0, key_version: int | None = None) -> dict[str, Any]:
|
|
93
|
+
"""Put the original values back into text redacted by `redact`.
|
|
94
|
+
|
|
95
|
+
Pass the same `strategy` (and `labels`/`min_confidence`) used to
|
|
96
|
+
redact, and the `key_version` that `redact` returned (fpe tokens only
|
|
97
|
+
restore under the key version that made them). tokenize/synthetic
|
|
98
|
+
also need the `token_map` returned by `redact`. Free (no API units). Caveat for fpe: a new email/phone/ID
|
|
99
|
+
that a model invented (never redacted) looks like an fpe token and will
|
|
100
|
+
be decrypted into a different value; restore only text whose
|
|
101
|
+
structured values came from your own redaction.
|
|
102
|
+
"""
|
|
103
|
+
if strategy in ("tokenize", "synthetic") and token_map is None:
|
|
104
|
+
raise ToolError(f"strategy {strategy!r} needs the token_map returned by redact")
|
|
105
|
+
ctx = RestoreContext(strategy, dict(token_map or {}), labels=labels, min_confidence=min_confidence,
|
|
106
|
+
key_version=key_version)
|
|
107
|
+
try:
|
|
108
|
+
return {"text": await ob.arestore(text, ctx)}
|
|
109
|
+
except (ObscateError, ValueError) as e:
|
|
110
|
+
raise _fail(e) from None
|
|
111
|
+
|
|
112
|
+
@mcp.tool(annotations=_READ_ONLY)
|
|
113
|
+
async def detect(text: str, labels: list[str] | None = None, min_confidence: float = 0.0,
|
|
114
|
+
include_values: bool = False) -> dict[str, Any]:
|
|
115
|
+
"""Classify what PII a text contains without changing it.
|
|
116
|
+
|
|
117
|
+
Returns entity labels, character offsets and confidence, plus counts
|
|
118
|
+
by label. The matched values are left out unless include_values=true
|
|
119
|
+
(offsets let you find them in your own copy). Costs 1 API unit per 100 KB.
|
|
120
|
+
"""
|
|
121
|
+
try:
|
|
122
|
+
r = await ob.adetect(text, labels, min_confidence)
|
|
123
|
+
except (ObscateError, ValueError) as e:
|
|
124
|
+
raise _fail(e) from None
|
|
125
|
+
ents = r.get("entities", [])
|
|
126
|
+
by_label: dict[str, int] = {}
|
|
127
|
+
for e in ents:
|
|
128
|
+
by_label[e["label"]] = by_label.get(e["label"], 0) + 1
|
|
129
|
+
keep = ("label", "start", "end", "confidence") + (("text",) if include_values else ())
|
|
130
|
+
return {"entities": [{k: e[k] for k in keep if k in e} for e in ents],
|
|
131
|
+
"counts": {"total": len(ents), "by_label": by_label}}
|
|
132
|
+
|
|
133
|
+
@mcp.tool(annotations=_READ_ONLY)
|
|
134
|
+
async def redact_json(json: Any, strategy: Strategy = "fpe", labels: list[str] | None = None,
|
|
135
|
+
min_confidence: float = 0.0, hints: bool = True,
|
|
136
|
+
field_map: dict[str, str | None] | None = None,
|
|
137
|
+
keys: KeysMode = "report") -> dict[str, Any]:
|
|
138
|
+
"""Redact PII inside a JSON object/array (e.g. a tool-call payload).
|
|
139
|
+
|
|
140
|
+
Keys, nesting and non-sensitive values are unchanged so the receiving
|
|
141
|
+
schema still works. hints: built-in field-name hints (name, email,
|
|
142
|
+
phone, address, aadhaar, pan) on by default. field_map: per-path
|
|
143
|
+
overrides, e.g. {"product.name": null, "sku": "IGNORE",
|
|
144
|
+
"$.rows[*].label": "PERSON"}. keys: "report" (default, count PII in
|
|
145
|
+
keys), "strict" (refuse if keys contain PII), "redact" (redact keys
|
|
146
|
+
too). Keep `type_changes`, `keys_redacted`, `key_version` and
|
|
147
|
+
(tokenize/synthetic) `token_map` for restore_json. Costs 1 API unit per 100 KB.
|
|
148
|
+
"""
|
|
149
|
+
try:
|
|
150
|
+
r, _ = await ob.aredact_json(json, strategy, labels, min_confidence, hints, field_map, keys)
|
|
151
|
+
except (ObscateError, ValueError) as e:
|
|
152
|
+
raise _fail(e) from None
|
|
153
|
+
out = {"redacted": r["redacted"], "strategy": strategy,
|
|
154
|
+
"type_changes": r.get("type_changes", []), "keys_redacted": r.get("keys_redacted", False),
|
|
155
|
+
"pii_in_keys": r.get("pii_in_keys", 0),
|
|
156
|
+
"entities": _public_entities(r.get("entities", [])), "counts": r.get("counts", {})}
|
|
157
|
+
if r.get("key_version") is not None:
|
|
158
|
+
out["key_version"] = r["key_version"]
|
|
159
|
+
if strategy in ("tokenize", "synthetic"):
|
|
160
|
+
out["token_map"] = r.get("token_map", {})
|
|
161
|
+
return out
|
|
162
|
+
|
|
163
|
+
@mcp.tool(annotations=_READ_ONLY)
|
|
164
|
+
async def restore_json(json: Any, strategy: Literal["fpe", "tokenize", "synthetic"] = "fpe",
|
|
165
|
+
token_map: dict[str, str] | None = None,
|
|
166
|
+
type_changes: list[dict] | None = None, keys_redacted: bool = False,
|
|
167
|
+
hints: bool = True, field_map: dict[str, str | None] | None = None,
|
|
168
|
+
labels: list[str] | None = None,
|
|
169
|
+
min_confidence: float = 0.0, key_version: int | None = None) -> dict[str, Any]:
|
|
170
|
+
"""Restore a JSON value (any shape, e.g. a model's reply) redacted by
|
|
171
|
+
`redact_json`. Pass back the same strategy, field_map and hints, plus
|
|
172
|
+
`type_changes`, `keys_redacted`, `key_version` and (tokenize/synthetic)
|
|
173
|
+
`token_map` from the redact_json result. Free (no API units)."""
|
|
174
|
+
if strategy in ("tokenize", "synthetic") and token_map is None:
|
|
175
|
+
raise ToolError(f"strategy {strategy!r} needs the token_map returned by redact_json")
|
|
176
|
+
ctx = RestoreContext(strategy, dict(token_map or {}), list(type_changes or []), keys_redacted,
|
|
177
|
+
labels, min_confidence, hints, field_map, key_version)
|
|
178
|
+
try:
|
|
179
|
+
return {"json": await ob.arestore_json(json, ctx)}
|
|
180
|
+
except (ObscateError, ValueError) as e:
|
|
181
|
+
raise _fail(e) from None
|
|
182
|
+
|
|
183
|
+
@mcp.tool(annotations=_READ_ONLY)
|
|
184
|
+
def list_entities() -> dict[str, Any]:
|
|
185
|
+
"""List the entity labels and strategies the Obscate API supports. Free, no key needed."""
|
|
186
|
+
try:
|
|
187
|
+
return ob.entities()
|
|
188
|
+
except ObscateError as e:
|
|
189
|
+
raise _fail(e) from None
|
|
190
|
+
|
|
191
|
+
return mcp
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
def main() -> None:
|
|
195
|
+
import argparse
|
|
196
|
+
p = argparse.ArgumentParser(prog="obscate-mcp", description="Obscate PII redaction MCP server")
|
|
197
|
+
p.add_argument("--transport", choices=["stdio", "streamable-http"], default="stdio")
|
|
198
|
+
p.add_argument("--version", action="version", version=f"obscate-mcp {__version__}")
|
|
199
|
+
args = p.parse_args()
|
|
200
|
+
build_server().run(transport=args.transport)
|
|
@@ -0,0 +1,157 @@
|
|
|
1
|
+
"""In-process stand-in for the Obscate API, for unit tests only.
|
|
2
|
+
|
|
3
|
+
Vendored into each package's tests/ by scripts/sync_client.py. It is NOT the
|
|
4
|
+
real detector: it only knows emails, Indian-style +91 phone numbers and a
|
|
5
|
+
fixed list of names, which is enough to exercise the integrations' plumbing
|
|
6
|
+
(request shapes, restore paths, error handling, privacy). Real detection
|
|
7
|
+
quality is tested in obscate-api and in the live end-to-end runs.
|
|
8
|
+
|
|
9
|
+
fpe here is a toy reversible encoding ("[EMAIL:hex]"), not FF1. It does model
|
|
10
|
+
key versions: tokens embed the version that made them, redact responses
|
|
11
|
+
return ``key_version``, and restoring under any other version yields a wrong
|
|
12
|
+
value (as real FF1 would), so tests can prove the version is carried through.
|
|
13
|
+
"""
|
|
14
|
+
from __future__ import annotations
|
|
15
|
+
|
|
16
|
+
import json
|
|
17
|
+
import re
|
|
18
|
+
from typing import Any
|
|
19
|
+
|
|
20
|
+
import httpx
|
|
21
|
+
|
|
22
|
+
NAMES = ("Ravi Kumar", "Priya Sharma")
|
|
23
|
+
_PATTERNS = [
|
|
24
|
+
("EMAIL", re.compile(r"[\w.+-]+@[\w-]+\.[\w.]+")),
|
|
25
|
+
("PHONE", re.compile(r"\+91[ -]?\d{5}[ -]?\d{5}")),
|
|
26
|
+
("PERSON", re.compile("|".join(re.escape(n) for n in NAMES))),
|
|
27
|
+
]
|
|
28
|
+
_FPE_TOKEN = re.compile(r"\[(EMAIL|PHONE|PERSON):([0-9a-f]+)\]")
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _spans(text: str):
|
|
32
|
+
out = []
|
|
33
|
+
for label, pat in _PATTERNS:
|
|
34
|
+
out += [(m.start(), m.end(), label, m.group(0)) for m in pat.finditer(text)]
|
|
35
|
+
return sorted(out)
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class FakeObscate:
|
|
39
|
+
def __init__(self, api_key: str = "ob_test_key", fail_with: int | None = None,
|
|
40
|
+
key_version: int = 1):
|
|
41
|
+
self.api_key = api_key
|
|
42
|
+
self.fail_with = fail_with
|
|
43
|
+
self.key_version = key_version # bump it to simulate a key rotation
|
|
44
|
+
self.calls: list[tuple[str, Any]] = [] # (path, parsed body) — test-side only
|
|
45
|
+
|
|
46
|
+
# -- engine -----------------------------------------------------------------
|
|
47
|
+
def _redact(self, text: str, strategy: str, st: dict) -> tuple[str, list[dict]]:
|
|
48
|
+
out, cur, ents = [], 0, []
|
|
49
|
+
for s, e, label, val in _spans(text):
|
|
50
|
+
if strategy == "fpe":
|
|
51
|
+
rep = f"[{label}:{f'{self.key_version}|{val}'.encode().hex()}]"
|
|
52
|
+
elif strategy in ("tokenize", "synthetic"):
|
|
53
|
+
if val not in st["seen"]:
|
|
54
|
+
st["n"][label] = st["n"].get(label, 0) + 1
|
|
55
|
+
st["seen"][val] = f"[{label}_{st['n'][label]}]"
|
|
56
|
+
rep = st["seen"][val]
|
|
57
|
+
st["map"][rep] = val
|
|
58
|
+
elif strategy == "mask":
|
|
59
|
+
rep = "*" * len(val)
|
|
60
|
+
else:
|
|
61
|
+
rep = f"<{label}>"
|
|
62
|
+
out += [text[cur:s], rep]
|
|
63
|
+
cur = e
|
|
64
|
+
ents.append({"label": label, "text": val, "replacement": rep, "start": s, "end": e,
|
|
65
|
+
"confidence": 0.99})
|
|
66
|
+
out.append(text[cur:])
|
|
67
|
+
return "".join(out), ents
|
|
68
|
+
|
|
69
|
+
def _restore_fpe(self, text: str, version: int | None = None) -> str:
|
|
70
|
+
v = str(self.key_version if version is None else version)
|
|
71
|
+
def dec(m):
|
|
72
|
+
made, _, val = bytes.fromhex(m.group(2)).decode().partition("|")
|
|
73
|
+
return val if made == v else "WRONG-KEY-VERSION"
|
|
74
|
+
return _FPE_TOKEN.sub(dec, text)
|
|
75
|
+
|
|
76
|
+
@staticmethod
|
|
77
|
+
def _restore_map(text: str, token_map: dict) -> str:
|
|
78
|
+
# Toy left-to-right scan; tokens in this fake never overlap.
|
|
79
|
+
out, i = [], 0
|
|
80
|
+
while i < len(text):
|
|
81
|
+
for tok, val in token_map.items():
|
|
82
|
+
if text.startswith(tok, i):
|
|
83
|
+
out.append(val)
|
|
84
|
+
i += len(tok)
|
|
85
|
+
break
|
|
86
|
+
else:
|
|
87
|
+
out.append(text[i])
|
|
88
|
+
i += 1
|
|
89
|
+
return "".join(out)
|
|
90
|
+
|
|
91
|
+
def _walk(self, obj, fn):
|
|
92
|
+
if isinstance(obj, str):
|
|
93
|
+
return fn(obj)
|
|
94
|
+
if isinstance(obj, list):
|
|
95
|
+
return [self._walk(v, fn) for v in obj]
|
|
96
|
+
if isinstance(obj, dict):
|
|
97
|
+
return {k: self._walk(v, fn) for k, v in obj.items()}
|
|
98
|
+
return obj
|
|
99
|
+
|
|
100
|
+
# -- http -------------------------------------------------------------------
|
|
101
|
+
def handler(self, request: httpx.Request) -> httpx.Response:
|
|
102
|
+
path = request.url.path
|
|
103
|
+
if request.method == "GET" and path == "/v1/entities":
|
|
104
|
+
return httpx.Response(200, json={"regex": ["EMAIL", "PHONE"], "ner": ["PERSON"],
|
|
105
|
+
"strategies": ["tokenize", "mask", "hash", "partial",
|
|
106
|
+
"synthetic", "fpe"]})
|
|
107
|
+
body = json.loads(request.content or b"{}")
|
|
108
|
+
self.calls.append((path, body))
|
|
109
|
+
if request.headers.get("x-api-key") != self.api_key:
|
|
110
|
+
return httpx.Response(401, json={"detail": "invalid or missing x-api-key"})
|
|
111
|
+
if self.fail_with:
|
|
112
|
+
return httpx.Response(self.fail_with, json={"detail": "simulated failure"},
|
|
113
|
+
headers={"retry-after": "7", "x-request-id": "rid123"})
|
|
114
|
+
st = {"n": {}, "seen": {}, "map": {}}
|
|
115
|
+
if path == "/v1/redact":
|
|
116
|
+
red, ents = self._redact(body["text"], body["strategy"], st)
|
|
117
|
+
return httpx.Response(200, json={"redacted": red, "strategy": body["strategy"],
|
|
118
|
+
"reversible": body["strategy"] in ("fpe", "tokenize", "synthetic"),
|
|
119
|
+
"token_map": st["map"], "entities": ents,
|
|
120
|
+
"counts": {"total": len(ents)},
|
|
121
|
+
"key_version": self.key_version})
|
|
122
|
+
if path == "/v1/detect":
|
|
123
|
+
ents = [{"label": l, "text": v, "start": s, "end": e, "confidence": 0.99}
|
|
124
|
+
for s, e, l, v in _spans(body["text"])]
|
|
125
|
+
return httpx.Response(200, json={"entities": ents, "counts": {"total": len(ents)}})
|
|
126
|
+
if path == "/v1/restore":
|
|
127
|
+
return httpx.Response(200, json={"text": self._restore_map(body["text"], body["token_map"])})
|
|
128
|
+
if path == "/v1/restore-fpe":
|
|
129
|
+
return httpx.Response(200, json={"text": self._restore_fpe(body["text"],
|
|
130
|
+
body.get("key_version"))})
|
|
131
|
+
if path == "/v1/redact-json":
|
|
132
|
+
ents: list = []
|
|
133
|
+
|
|
134
|
+
def fn(s):
|
|
135
|
+
r, e = self._redact(s, body["strategy"], st)
|
|
136
|
+
ents.extend(e)
|
|
137
|
+
return r
|
|
138
|
+
red = self._walk(body["json"], fn)
|
|
139
|
+
return httpx.Response(200, json={"redacted": red, "strategy": body["strategy"],
|
|
140
|
+
"token_map": st["map"], "entities": ents,
|
|
141
|
+
"type_changes": [], "pii_in_keys": 0, "keys_redacted": False,
|
|
142
|
+
"counts": {"total": len(ents)},
|
|
143
|
+
"key_version": self.key_version})
|
|
144
|
+
if path == "/v1/restore-json":
|
|
145
|
+
if body.get("fpe"):
|
|
146
|
+
out = self._walk(body["json"], lambda s: self._restore_fpe(s, body.get("key_version")))
|
|
147
|
+
else:
|
|
148
|
+
out = self._walk(body["json"], lambda s: self._restore_map(s, body["token_map"]))
|
|
149
|
+
return httpx.Response(200, json={"json": out})
|
|
150
|
+
return httpx.Response(404, json={"detail": "Not Found"})
|
|
151
|
+
|
|
152
|
+
def transport(self) -> httpx.MockTransport:
|
|
153
|
+
return httpx.MockTransport(self.handler)
|
|
154
|
+
|
|
155
|
+
def sent_text(self) -> str:
|
|
156
|
+
"""Everything the integration sent to the API, as one string (for assertions)."""
|
|
157
|
+
return json.dumps([b for _, b in self.calls])
|
|
@@ -0,0 +1,178 @@
|
|
|
1
|
+
import json
|
|
2
|
+
import logging
|
|
3
|
+
import os
|
|
4
|
+
import sys
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
|
|
7
|
+
import pytest
|
|
8
|
+
from mcp import Client
|
|
9
|
+
|
|
10
|
+
sys.path.insert(0, str(Path(__file__).parent))
|
|
11
|
+
from fake_api import FakeObscate # noqa: E402
|
|
12
|
+
|
|
13
|
+
from obscate_mcp._client import ObscateClient # noqa: E402
|
|
14
|
+
from obscate_mcp.server import build_server # noqa: E402
|
|
15
|
+
|
|
16
|
+
pytestmark = pytest.mark.anyio
|
|
17
|
+
|
|
18
|
+
SECRET_TEXT = "Ravi Kumar (ravi@example.com, +91 98765 43210) asked about his order."
|
|
19
|
+
RAW_VALUES = ["Ravi Kumar", "ravi@example.com", "98765 43210"]
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@pytest.fixture
|
|
23
|
+
def anyio_backend():
|
|
24
|
+
return "asyncio"
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def make(fake=None, key="ob_test_key"):
|
|
28
|
+
fake = fake or FakeObscate()
|
|
29
|
+
t = fake.transport()
|
|
30
|
+
client = ObscateClient(api_key=key, base_url="https://fake.obscate.test", transport=t, async_transport=t)
|
|
31
|
+
return fake, build_server(client)
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
def data(result):
|
|
35
|
+
assert not result.is_error, result.content
|
|
36
|
+
if result.structured_content is not None:
|
|
37
|
+
sc = result.structured_content
|
|
38
|
+
return sc.get("result", sc) if isinstance(sc, dict) and set(sc) == {"result"} else sc
|
|
39
|
+
return json.loads(result.content[0].text)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
async def test_lists_all_tools():
|
|
43
|
+
_, server = make()
|
|
44
|
+
async with Client(server) as c:
|
|
45
|
+
names = {t.name for t in (await c.list_tools()).tools}
|
|
46
|
+
assert {"redact", "restore", "detect", "redact_json", "restore_json", "list_entities"} <= names
|
|
47
|
+
|
|
48
|
+
|
|
49
|
+
async def test_redact_restore_fpe_roundtrip_without_map():
|
|
50
|
+
fake, server = make()
|
|
51
|
+
async with Client(server) as c:
|
|
52
|
+
r = data(await c.call_tool("redact", {"text": SECRET_TEXT}))
|
|
53
|
+
assert r["strategy"] == "fpe" and "token_map" not in r
|
|
54
|
+
for v in RAW_VALUES:
|
|
55
|
+
assert v not in r["redacted"]
|
|
56
|
+
# originals are not echoed back into the model context
|
|
57
|
+
assert all("text" not in e for e in r["entities"])
|
|
58
|
+
back = data(await c.call_tool("restore", {"text": r["redacted"]}))
|
|
59
|
+
assert back["text"] == SECRET_TEXT
|
|
60
|
+
assert fake.calls[-1][0] == "/v1/restore-fpe"
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
async def test_tokenize_roundtrip_needs_map():
|
|
64
|
+
_, server = make()
|
|
65
|
+
async with Client(server) as c:
|
|
66
|
+
r = data(await c.call_tool("redact", {"text": SECRET_TEXT, "strategy": "tokenize"}))
|
|
67
|
+
assert "[EMAIL_1]" in r["redacted"]
|
|
68
|
+
missing = await c.call_tool("restore", {"text": r["redacted"], "strategy": "tokenize"})
|
|
69
|
+
assert missing.is_error
|
|
70
|
+
back = data(await c.call_tool("restore", {"text": "Reply to [EMAIL_1]", "strategy": "tokenize",
|
|
71
|
+
"token_map": r["token_map"]}))
|
|
72
|
+
assert back["text"] == "Reply to ravi@example.com"
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
async def test_redact_json_and_restore_json():
|
|
76
|
+
_, server = make()
|
|
77
|
+
payload = {"customer": {"name": "Ravi Kumar", "email": "ravi@example.com"}, "qty": 3}
|
|
78
|
+
async with Client(server) as c:
|
|
79
|
+
r = data(await c.call_tool("redact_json", {"json": payload}))
|
|
80
|
+
assert r["redacted"]["qty"] == 3
|
|
81
|
+
assert "ravi@example.com" not in json.dumps(r["redacted"])
|
|
82
|
+
reply = {"draft": f"Hi {r['redacted']['customer']['name']}"}
|
|
83
|
+
back = data(await c.call_tool("restore_json", {"json": reply, "type_changes": r["type_changes"]}))
|
|
84
|
+
assert back["json"] == {"draft": "Hi Ravi Kumar"}
|
|
85
|
+
|
|
86
|
+
|
|
87
|
+
async def test_detect_hides_values_by_default():
|
|
88
|
+
_, server = make()
|
|
89
|
+
async with Client(server) as c:
|
|
90
|
+
r = data(await c.call_tool("detect", {"text": SECRET_TEXT}))
|
|
91
|
+
r2 = data(await c.call_tool("detect", {"text": SECRET_TEXT, "include_values": True}))
|
|
92
|
+
assert r["counts"]["by_label"] == {"PERSON": 1, "EMAIL": 1, "PHONE": 1}
|
|
93
|
+
assert "ravi@example.com" not in json.dumps(r)
|
|
94
|
+
assert "ravi@example.com" in json.dumps(r2)
|
|
95
|
+
|
|
96
|
+
|
|
97
|
+
async def test_one_way_strategy_cannot_be_restored():
|
|
98
|
+
_, server = make()
|
|
99
|
+
async with Client(server) as c:
|
|
100
|
+
res = await c.call_tool("restore", {"text": "x", "strategy": "mask"})
|
|
101
|
+
assert res.is_error
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
async def test_missing_key_gives_actionable_error():
|
|
105
|
+
_, server = make(key="")
|
|
106
|
+
async with Client(server) as c:
|
|
107
|
+
res = await c.call_tool("redact", {"text": SECRET_TEXT})
|
|
108
|
+
assert res.is_error and "OBSCATE_API_KEY" in res.content[0].text
|
|
109
|
+
|
|
110
|
+
|
|
111
|
+
@pytest.mark.parametrize("status,needle", [(401, "OBSCATE_API_KEY"), (402, "quota"), (429, "retry after 7"),
|
|
112
|
+
(503, "failed closed")])
|
|
113
|
+
async def test_api_errors_are_reported_without_payload(status, needle):
|
|
114
|
+
fake = FakeObscate(fail_with=status)
|
|
115
|
+
_, server = make(fake)
|
|
116
|
+
async with Client(server) as c:
|
|
117
|
+
res = await c.call_tool("redact", {"text": SECRET_TEXT})
|
|
118
|
+
assert res.is_error
|
|
119
|
+
msg = res.content[0].text
|
|
120
|
+
assert needle in msg and str(status) in msg
|
|
121
|
+
for v in RAW_VALUES:
|
|
122
|
+
assert v not in msg
|
|
123
|
+
|
|
124
|
+
|
|
125
|
+
async def test_base_url_env_is_honoured(monkeypatch):
|
|
126
|
+
monkeypatch.setenv("OBSCATE_BASE_URL", "https://obscate.internal.example/")
|
|
127
|
+
assert ObscateClient().base_url == "https://obscate.internal.example"
|
|
128
|
+
monkeypatch.delenv("OBSCATE_BASE_URL")
|
|
129
|
+
assert ObscateClient().base_url == "https://api.obscate.com"
|
|
130
|
+
|
|
131
|
+
|
|
132
|
+
async def test_privacy_nothing_sensitive_is_logged_or_written(caplog, tmp_path, monkeypatch, capsys):
|
|
133
|
+
"""The privacy promise: no raw text, detected values or token map in logs,
|
|
134
|
+
stdout/stderr, or files — on success AND on failure paths."""
|
|
135
|
+
monkeypatch.chdir(tmp_path)
|
|
136
|
+
caplog.set_level(logging.DEBUG) # every logger, every level
|
|
137
|
+
for fail in (None, 422, 503):
|
|
138
|
+
_, server = make(FakeObscate(fail_with=fail))
|
|
139
|
+
async with Client(server) as c:
|
|
140
|
+
r = await c.call_tool("redact", {"text": SECRET_TEXT, "strategy": "tokenize"})
|
|
141
|
+
await c.call_tool("detect", {"text": SECRET_TEXT})
|
|
142
|
+
await c.call_tool("redact_json", {"json": {"name": "Ravi Kumar", "email": "ravi@example.com"}})
|
|
143
|
+
if not r.is_error:
|
|
144
|
+
await c.call_tool("restore", {"text": data(r)["redacted"], "strategy": "tokenize",
|
|
145
|
+
"token_map": data(r)["token_map"]})
|
|
146
|
+
await c.call_tool("restore", {"text": "[EMAIL_1]", "strategy": "tokenize",
|
|
147
|
+
"token_map": {"[EMAIL_1]": "ravi@example.com"}})
|
|
148
|
+
logged = "\n".join(rec.getMessage() + repr(rec.args) for rec in caplog.records)
|
|
149
|
+
out = capsys.readouterr()
|
|
150
|
+
for v in RAW_VALUES + ["[EMAIL_1]"]:
|
|
151
|
+
assert v not in logged, f"{v!r} leaked into logs"
|
|
152
|
+
assert v not in out.out + out.err
|
|
153
|
+
assert list(tmp_path.iterdir()) == []
|
|
154
|
+
assert "ob_test_key" not in repr(ObscateClient(api_key="ob_test_key"))
|
|
155
|
+
|
|
156
|
+
|
|
157
|
+
async def test_key_version_is_returned_and_restores_after_rotation():
|
|
158
|
+
"""A server-side key rotation between redact and restore must not break the
|
|
159
|
+
round trip: redact returns key_version, restore sends it back."""
|
|
160
|
+
fake, server = make()
|
|
161
|
+
async with Client(server) as c:
|
|
162
|
+
r = data(await c.call_tool("redact", {"text": SECRET_TEXT}))
|
|
163
|
+
rj = data(await c.call_tool("redact_json", {"json": {"note": SECRET_TEXT}}))
|
|
164
|
+
assert r["key_version"] == rj["key_version"] == 1
|
|
165
|
+
fake.key_version = 2 # rotation happens mid-flight
|
|
166
|
+
back = data(await c.call_tool("restore", {"text": r["redacted"], "key_version": 1}))
|
|
167
|
+
jback = data(await c.call_tool("restore_json", {"json": rj["redacted"], "key_version": 1}))
|
|
168
|
+
stale = data(await c.call_tool("restore", {"text": r["redacted"]}))
|
|
169
|
+
assert back["text"] == SECRET_TEXT and jback["json"] == {"note": SECRET_TEXT}
|
|
170
|
+
assert stale["text"] != SECRET_TEXT # proves the version mattered
|
|
171
|
+
|
|
172
|
+
|
|
173
|
+
def test_restore_context_merge_respects_key_version():
|
|
174
|
+
from obscate_mcp._client import RestoreContext
|
|
175
|
+
a = RestoreContext("tokenize", {"[A_1]": "x"}, key_version=1)
|
|
176
|
+
assert a.merge(RestoreContext("tokenize", {"[B_1]": "y"})).key_version == 1
|
|
177
|
+
with pytest.raises(ValueError):
|
|
178
|
+
a.merge(RestoreContext("tokenize", key_version=2))
|