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.
@@ -0,0 +1,12 @@
1
+ # secrets: never commit
2
+ .env
3
+ .env.*
4
+ !.env.example
5
+
6
+ .venv/
7
+ __pycache__/
8
+ *.py[cod]
9
+ *.egg-info/
10
+ dist/
11
+ build/
12
+ .pytest_cache/
@@ -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,2 @@
1
+ """Obscate MCP server — reversible PII redaction tools for AI agents."""
2
+ __version__ = "0.1.0"
@@ -0,0 +1,3 @@
1
+ from .server import main
2
+
3
+ main()
@@ -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))