@nodatachat/mcp 1.0.0 → 1.3.0

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.
Files changed (4) hide show
  1. package/LICENSE.md +105 -105
  2. package/README.md +187 -161
  3. package/dist/index.js +108 -54
  4. package/package.json +57 -49
package/LICENSE.md CHANGED
@@ -1,105 +1,105 @@
1
- # Functional Source License, Version 1.1, ALv2 Future License
2
-
3
- ## Abbreviation
4
-
5
- FSL-1.1-ALv2
6
-
7
- ## Notice
8
-
9
- Copyright 2026 Capsule Ltd.
10
-
11
- ## Terms and Conditions
12
-
13
- ### Licensor ("We")
14
-
15
- The party offering the Software under these Terms and Conditions.
16
-
17
- ### The Software
18
-
19
- The "Software" is each version of the software that we make available under
20
- these Terms and Conditions, as indicated by our inclusion of these Terms and
21
- Conditions with the Software.
22
-
23
- ### License Grant
24
-
25
- Subject to your compliance with this License Grant and the Patents,
26
- Redistribution and Trademark clauses below, we hereby grant you the right to
27
- use, copy, modify, create derivative works, publicly perform, publicly display
28
- and redistribute the Software for any Permitted Purpose identified below.
29
-
30
- ### Permitted Purpose
31
-
32
- A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
33
- means making the Software available to others in a commercial product or
34
- service that:
35
-
36
- 1. substitutes for the Software;
37
-
38
- 2. substitutes for any other product or service we offer using the Software
39
- that exists as of the date we make the Software available; or
40
-
41
- 3. offers the same or substantially similar functionality as the Software.
42
-
43
- Permitted Purposes specifically include using the Software:
44
-
45
- 1. for your internal use and access;
46
-
47
- 2. for non-commercial education;
48
-
49
- 3. for non-commercial research; and
50
-
51
- 4. in connection with professional services that you provide to a licensee
52
- using the Software in accordance with these Terms and Conditions.
53
-
54
- ### Patents
55
-
56
- To the extent your use for a Permitted Purpose would necessarily infringe our
57
- patents, the license grant above includes a license under our patents. If you
58
- make a claim against any party that the Software infringes or contributes to
59
- the infringement of any patent, then your patent license to the Software ends
60
- immediately.
61
-
62
- ### Redistribution
63
-
64
- The Terms and Conditions apply to all copies, modifications and derivatives of
65
- the Software.
66
-
67
- If you redistribute any copies, modifications or derivatives of the Software,
68
- you must include a copy of or a link to these Terms and Conditions and not
69
- remove any copyright notices provided in or with the Software.
70
-
71
- ### Disclaimer
72
-
73
- THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
74
- IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
75
- PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
76
-
77
- IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
78
- SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
79
- EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
80
-
81
- ### Trademarks
82
-
83
- Except for displaying the License Details and identifying us as the origin of
84
- the Software, you have no right under these Terms and Conditions to use our
85
- trademarks, trade names, service marks or product names.
86
-
87
- ## Grant of Future License
88
-
89
- We hereby irrevocably grant you an additional license to use the Software under
90
- the Apache License, Version 2.0 that is effective on the second anniversary of
91
- the date we make the Software available. On or after that date, you may use the
92
- Software under the Apache License, Version 2.0, in which case the following
93
- will apply:
94
-
95
- Licensed under the Apache License, Version 2.0 (the "License"); you may not use
96
- this file except in compliance with the License.
97
-
98
- You may obtain a copy of the License at
99
-
100
- http://www.apache.org/licenses/LICENSE-2.0
101
-
102
- Unless required by applicable law or agreed to in writing, software distributed
103
- under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
104
- CONDITIONS OF ANY KIND, either express or implied. See the License for the
105
- specific language governing permissions and limitations under the License.
1
+ # Functional Source License, Version 1.1, ALv2 Future License
2
+
3
+ ## Abbreviation
4
+
5
+ FSL-1.1-ALv2
6
+
7
+ ## Notice
8
+
9
+ Copyright 2026 Capsule Ltd.
10
+
11
+ ## Terms and Conditions
12
+
13
+ ### Licensor ("We")
14
+
15
+ The party offering the Software under these Terms and Conditions.
16
+
17
+ ### The Software
18
+
19
+ The "Software" is each version of the software that we make available under
20
+ these Terms and Conditions, as indicated by our inclusion of these Terms and
21
+ Conditions with the Software.
22
+
23
+ ### License Grant
24
+
25
+ Subject to your compliance with this License Grant and the Patents,
26
+ Redistribution and Trademark clauses below, we hereby grant you the right to
27
+ use, copy, modify, create derivative works, publicly perform, publicly display
28
+ and redistribute the Software for any Permitted Purpose identified below.
29
+
30
+ ### Permitted Purpose
31
+
32
+ A Permitted Purpose is any purpose other than a Competing Use. A Competing Use
33
+ means making the Software available to others in a commercial product or
34
+ service that:
35
+
36
+ 1. substitutes for the Software;
37
+
38
+ 2. substitutes for any other product or service we offer using the Software
39
+ that exists as of the date we make the Software available; or
40
+
41
+ 3. offers the same or substantially similar functionality as the Software.
42
+
43
+ Permitted Purposes specifically include using the Software:
44
+
45
+ 1. for your internal use and access;
46
+
47
+ 2. for non-commercial education;
48
+
49
+ 3. for non-commercial research; and
50
+
51
+ 4. in connection with professional services that you provide to a licensee
52
+ using the Software in accordance with these Terms and Conditions.
53
+
54
+ ### Patents
55
+
56
+ To the extent your use for a Permitted Purpose would necessarily infringe our
57
+ patents, the license grant above includes a license under our patents. If you
58
+ make a claim against any party that the Software infringes or contributes to
59
+ the infringement of any patent, then your patent license to the Software ends
60
+ immediately.
61
+
62
+ ### Redistribution
63
+
64
+ The Terms and Conditions apply to all copies, modifications and derivatives of
65
+ the Software.
66
+
67
+ If you redistribute any copies, modifications or derivatives of the Software,
68
+ you must include a copy of or a link to these Terms and Conditions and not
69
+ remove any copyright notices provided in or with the Software.
70
+
71
+ ### Disclaimer
72
+
73
+ THE SOFTWARE IS PROVIDED "AS IS" AND WITHOUT WARRANTIES OF ANY KIND, EXPRESS OR
74
+ IMPLIED, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR
75
+ PURPOSE, MERCHANTABILITY, TITLE OR NON-INFRINGEMENT.
76
+
77
+ IN NO EVENT WILL WE HAVE ANY LIABILITY TO YOU ARISING OUT OF OR RELATED TO THE
78
+ SOFTWARE, INCLUDING INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES,
79
+ EVEN IF WE HAVE BEEN INFORMED OF THEIR POSSIBILITY IN ADVANCE.
80
+
81
+ ### Trademarks
82
+
83
+ Except for displaying the License Details and identifying us as the origin of
84
+ the Software, you have no right under these Terms and Conditions to use our
85
+ trademarks, trade names, service marks or product names.
86
+
87
+ ## Grant of Future License
88
+
89
+ We hereby irrevocably grant you an additional license to use the Software under
90
+ the Apache License, Version 2.0 that is effective on the second anniversary of
91
+ the date we make the Software available. On or after that date, you may use the
92
+ Software under the Apache License, Version 2.0, in which case the following
93
+ will apply:
94
+
95
+ Licensed under the Apache License, Version 2.0 (the "License"); you may not use
96
+ this file except in compliance with the License.
97
+
98
+ You may obtain a copy of the License at
99
+
100
+ http://www.apache.org/licenses/LICENSE-2.0
101
+
102
+ Unless required by applicable law or agreed to in writing, software distributed
103
+ under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
104
+ CONDITIONS OF ANY KIND, either express or implied. See the License for the
105
+ specific language governing permissions and limitations under the License.
package/README.md CHANGED
@@ -1,161 +1,187 @@
1
- # @nodatachat/mcp
2
-
3
- The MCP door to **NoData, the Information Access Processor**.
4
-
5
- **Give an AI agent real power over your data — without the power to leak it.**
6
-
7
- One line connects any MCP client (Claude Code, an agent runtime) to NoData's governed‑access layer. Your agent asks *"may I reach this?"* and only ever sees the columns you granted. Denied columns are **never decrypted on the server** — there is nothing to leak — and every access leaves a signed, verifiable receipt.
8
-
9
- ```bash
10
- claude mcp add nodata -- npx @nodatachat/mcp
11
- ```
12
-
13
- Any other MCP client (Codex, Cursor, VS Code, Windsurf, Cline) runs the same server from its config:
14
-
15
- ```json
16
- { "mcpServers": { "nodata": { "command": "npx", "args": ["-y", "@nodatachat/mcp"] } } }
17
- ```
18
-
19
- That's it — **no flags**. Self‑serve: registering opens an instant free **sandbox key** (no approval wall) and a **12‑word recovery phrase only you hold**. No card. **10,000 governed decisions per month free**, then $0.25 per 1,000.
20
-
21
- > **The one idea:** *API access ≠ data access.* A successful call is a request for a **decision**, not a handoff of data. **`no key = no plaintext`**, and every decision carries a proof.
22
-
23
- ---
24
-
25
- ## Get started in one command
26
-
27
- Run the line above with no credential. The server still connects (it never fails the MCP handshake) and exposes two setup tools:
28
-
29
- - **`nodata_get_started`** — call it first. It explains what you get and the single next step.
30
- - **`nodata_connect`** — register once, autoload forever:
31
- 1. `nodata_connect` (no args) → opens the free signup in your browser (work email + company, ~30s). Your **12‑word recovery phrase** is generated **in your browser — NoData never sees it**. The page shows your org key **once**.
32
- 2. `nodata_connect` with `api_key: "<that key>"` → saved to `~/.nodata/credentials.json` (chmod 600).
33
- 3. Restart, or run `/mcp` → every later start loads your identity with nothing to retype. *Registration ≠ login.*
34
-
35
- Keep the 12‑word phrase somewhere safe — it is the only way back into your org, and NoData cannot reissue it.
36
-
37
- ---
38
-
39
- ## One journey, five verbs, two ways in
40
-
41
- The whole product is one primitive shown five ways — **Classify · Protect · Route · Retrieve · Prove** — entered from **a table** (govern the DB columns an agent reads) **or a folder/document** (seal into a Capsule). Same journey, same proof.
42
-
43
- | Verb | What you do | Tool |
44
- |------|-------------|------|
45
- | **Classify** | connect a table (or seal a document) | `nodata_register_table` |
46
- | **Protect** | grant an agent only the columns you name | `nodata_grant` → `ndca-` token |
47
- | **Route** | *"may this agent reach X?"* — plan, no data moves | `nodata_decide` |
48
- | **Retrieve** | pull only the authorized columns into the prompt | `nodata_retrieve` / `nodata_read` |
49
- | **Prove** | a signed receipt on every read **and** every deny | `nodata_evidence` · `/decisions` |
50
-
51
- ---
52
-
53
- ## Try it — the "wow" in four calls
54
-
55
- After `nodata_connect`, ask your agent in plain language (*"grant a support bot first_name and last_name on agent_demo_records, then read it"*), or run the raw API with your key (`export NDP=ndp_test_…`):
56
-
57
- ```bash
58
- # 1 · grant an agent two columns of the built-in demo table (auto-seeds sample rows)
59
- curl -s -X POST https://www.nodatacapsule.com/api/v1/governance/grant \
60
- -H "Authorization: Bearer $NDP" -H 'content-type: application/json' \
61
- -d '{"agent":"support-copilot","table":"agent_demo_records","columns":["first_name","last_name"]}'
62
- # → { "grant_token": "ndca-…", "handle": "…" }
63
-
64
- # 2 · the agent reads what it's allowed — RELEASED
65
- curl -s -X POST https://www.nodatacapsule.com/api/agents/<handle>/read \
66
- -H "Authorization: Bearer ndca-…" -H 'content-type: application/json' \
67
- -d '{"table":"agent_demo_records","columns":["first_name","last_name"],"limit":5}'
68
- # → 200 { "rows": [ { "first_name": "…", "last_name": "…" }, … ] }
69
-
70
- # 3 · the agent asks for a column it was NOT granted — WITHHELD
71
- curl -s -X POST https://www.nodatacapsule.com/api/agents/<handle>/read \
72
- -H "Authorization: Bearer ndca-…" -H 'content-type: application/json' \
73
- -d '{"table":"agent_demo_records","columns":["email"]}'
74
- # → 403 { "error": "scope_violation", "denied_columns": ["email"] } ← the key for email is never derived
75
-
76
- # 4 · prove it — signed receipts for the allow AND the deny, verifiable without the data:
77
- # https://www.nodatacapsule.com/decisions
78
- ```
79
-
80
- `email` came back **absent, not blanked** — there is no decrypt‑all‑then‑filter path. That is *"you decide what the AI sees,"* as math, not a promise.
81
-
82
- No terminal? Same idea in the browser, zero install: **https://www.nodatacapsule.com/ai-folder** — drop a folder, see exactly what an AI would be allowed to read (nothing uploads).
83
-
84
- ---
85
-
86
- ## Two modes — the credential decides what the server can do
87
-
88
- **Agent mode (`--grant-token ndca-…`)** — *permission management for language models.* Hand an AI agent a grant token; the server exposes only tools hard‑scoped to that grant. The agent may request **only** the columns its grant allows — denied columns never decrypt server‑side, and every action emits a receipt. Point any MCP client at it and it **physically cannot exceed its claims**.
89
-
90
- ```bash
91
- claude mcp add nodata -- npx @nodatachat/mcp --grant-token ndca-YOUR_GRANT
92
- ```
93
-
94
- **Admin mode (`--api-key ndp_… / sk_live_…`)** — the owner seat: register tables, issue and revoke grants, and use blind relay (encrypt / decrypt / deliver / evidence) from inside any MCP client.
95
-
96
- ```bash
97
- claude mcp add nodata -- npx @nodatachat/mcp --api-key YOUR_API_KEY
98
- ```
99
-
100
- Credential precedence: `--api-key` / `--grant-token` › `NODATA_API_KEY` / `NODATA_GRANT_TOKEN` › the saved `~/.nodata` file. An explicit flag or env always wins.
101
-
102
- On **Windows**, native (non‑WSL) `npx` needs the `cmd /c` wrapper: `claude mcp add nodata -- cmd /c npx @nodatachat/mcp …`. After changing the credential, **restart** — the running server keeps its old arguments.
103
-
104
- ---
105
-
106
- ## Available tools
107
-
108
- **Agent mode** (`--grant-token`):
109
-
110
- | Tool | What it does |
111
- |------|--------------|
112
- | `nodata_decide` | May the agent reach a resource? allow / degrade (reachable subset) / deny + an access‑distance cost + a signed proof. No data. Plan before you read. |
113
- | `nodata_retrieve` | Prompt‑ready authorized context, filtered to allowed columns, with an accounting of what was withheld + a proof. |
114
- | `nodata_read` | Read governed rows within the grant; denied columns never decrypt; every read is receipted. |
115
- | `nodata_use` | Invoke a pre‑registered secret‑blind capability — the Capsule injects the sealed credential server‑side and returns only the result. The secret never reaches the agent. |
116
-
117
- **Admin mode** (`--api-key`):
118
-
119
- | Tool | What it does |
120
- |------|--------------|
121
- | `nodata_register_table` | Register one of your tables as AI‑agent‑readable ("connect your data"). |
122
- | `nodata_grant` | Issue an agent a claim‑scoped grant; returns a `grant_token` (shown once). |
123
- | `nodata_revoke` | Revoke a grant by handle or jti — access stops at once. |
124
- | `nodata_encrypt` / `nodata_decrypt` | Field‑level AES‑256‑GCM; NoData stores nothing of the plaintext. |
125
- | `nodata_deliver` | Create a burn‑after‑read secure link with OTP. |
126
- | `nodata_evidence` | Retrieve the audit trail — metadata only, never values. |
127
-
128
- ---
129
-
130
- ## Security & privacy model
131
-
132
- - **Content‑blind.** For governed reads, denied columns are **never decrypted on the server** — the key release is scoped to the grant, not "we promise not to look."
133
- - **Every action is a receipt.** Reads, grants, revokes and denials mint a signed, hash‑chained decision receipt (Ed25519, publicly verifiable), written **before** the release it authorizes — if the receipt can't be written, nothing is served.
134
- - **Structural isolation.** A key is bound to its org; every governance query is scoped to that tenant, so a key cannot aim at another org's data.
135
- - **The honest boundary.** This governs data the agent reaches **through the Capsule**. It does not sandbox a process already executing as you on your own machine.
136
-
137
- ---
138
-
139
- ## Configuration
140
-
141
- | Option | Flag | Env var | Default |
142
- |--------|------|---------|---------|
143
- | API key (admin) | `--api-key` | `NODATA_API_KEY` | — |
144
- | Grant token (agent) | `--grant-token` | `NODATA_GRANT_TOKEN` | — |
145
- | Base URL | `--base-url` | `NODATA_BASE_URL` | `https://www.nodatacapsule.com` |
146
-
147
- Get a key free at **https://www.nodatacapsule.com/capsule-api/register** (issues `ndp_test_…` instantly). `--help` and `--version` are also available.
148
-
149
- ## NoData on npm
150
-
151
- - **`@nodatachat/nodata`**: the main package, with all protection, scanning and governance capabilities, from the terminal.
152
- - **`@nodatachat/sdk`**: integration for developers.
153
- - **`@nodatachat/mcp`** (this one): integration for AI agents and MCP clients.
154
-
155
- ## License
156
-
157
- [FSL-1.1-ALv2](LICENSE.md) (Functional Source License 1.1, Apache 2.0 future license).
158
- Use it for any purpose except a competing product or service. Each release becomes
159
- available under the Apache License 2.0 two years after it is published. Versions up
160
- to 0.9.0 were published under MIT and remain available under that license.
161
- Copyright 2026 Capsule Ltd.
1
+ # @nodatachat/mcp
2
+
3
+ The MCP door to **NoData, the Information Access Processor**.
4
+
5
+ **Give an AI agent real power over your data — without the power to leak it.**
6
+
7
+ One line connects any MCP client (Claude Code, an agent runtime) to NoData's governed‑access layer. Your agent asks *"may I reach this?"* and only ever sees the columns you granted. Denied columns are **never decrypted on the server** — there is nothing to leak — and every access leaves a signed, verifiable receipt.
8
+
9
+ ```bash
10
+ claude mcp add nodata -- npx @nodatachat/mcp
11
+ ```
12
+
13
+ Any other MCP client (Codex, Cursor, VS Code, Windsurf, Cline) runs the same server from its config:
14
+
15
+ ```json
16
+ { "mcpServers": { "nodata": { "command": "npx", "args": ["-y", "@nodatachat/mcp"] } } }
17
+ ```
18
+
19
+ That's it — **no flags**. Self‑serve: registering opens an instant free **sandbox key** (no approval wall) and a **12‑word recovery phrase only you hold**. No card. **10,000 governed decisions per month free**, then $0.25 per 1,000.
20
+
21
+ > **The one idea:** *API access ≠ data access.* A successful call is a request for a **decision**, not a handoff of data. **`no key = no plaintext`**, and every decision carries a proof.
22
+
23
+ ---
24
+
25
+ ## Get started in one command
26
+
27
+ Run the line above with no credential. The server still connects (it never fails the MCP handshake) and exposes two setup tools:
28
+
29
+ - **`nodata_get_started`** — call it first. It explains what you get and the single next step.
30
+ - **`nodata_connect`** — register once, autoload forever:
31
+ 1. `nodata_connect` (no args) → opens the free signup in your browser (work email + company, ~30s). Your **12‑word recovery phrase** is generated **in your browser — NoData never sees it**. The page shows your org key **once**.
32
+ 2. `nodata_connect` with `api_key: "<that key>"` → saved to `~/.nodata/credentials.json` (chmod 600).
33
+ 3. Restart, or run `/mcp` → every later start loads your identity with nothing to retype. *Registration ≠ login.*
34
+
35
+ Keep the 12‑word phrase somewhere safe — it is the only way back into your org, and NoData cannot reissue it.
36
+
37
+ ---
38
+
39
+ ## One journey, five verbs, two ways in
40
+
41
+ The whole product is one primitive shown five ways — **Classify · Protect · Route · Retrieve · Prove** — entered from **a table** (govern the DB columns an agent reads) **or a folder/document** (seal into a Capsule). Same journey, same proof.
42
+
43
+ | Verb | What you do | Tool |
44
+ |------|-------------|------|
45
+ | **Classify** | register a table's policy, then connect your own Supabase as its source | `nodata_register_table` → `nodata_connect_source` |
46
+ | **Protect** | grant an agent only the columns you name | `nodata_grant` → `ndca-` token |
47
+ | **Route** | *"may this agent reach X?"* — plan, no data moves | `nodata_decide` |
48
+ | **Retrieve** | pull only the authorized columns into the prompt | `nodata_retrieve` / `nodata_read` |
49
+ | **Prove** | a signed receipt on every grant, read **and** deny | `nodata_proofs` · `/decisions` |
50
+
51
+ ---
52
+
53
+ ## Try it — the "wow" in four calls
54
+
55
+ After `nodata_connect`, ask your agent in plain language (*"grant a support bot first_name and last_name on agent_demo_records, then read it"*), or run the raw API with your key (`export NDP=ndp_test_…`):
56
+
57
+ ```bash
58
+ # 1 · grant an agent two columns of the built-in demo table (auto-seeds sample rows)
59
+ curl -s -X POST https://www.nodatacapsule.com/api/v1/governance/grant \
60
+ -H "Authorization: Bearer $NDP" -H 'content-type: application/json' \
61
+ -d '{"agent":"support-copilot","table":"agent_demo_records","columns":["first_name","last_name"]}'
62
+ # → { "grant_token": "ndca-…", "handle": "…" }
63
+
64
+ # 2 · the agent reads what it's allowed — RELEASED
65
+ curl -s -X POST https://www.nodatacapsule.com/api/agents/<handle>/read \
66
+ -H "Authorization: Bearer ndca-…" -H 'content-type: application/json' \
67
+ -d '{"table":"agent_demo_records","columns":["first_name","last_name"],"limit":5}'
68
+ # → 200 { "rows": [ { "first_name": "…", "last_name": "…" }, … ] }
69
+
70
+ # 3 · the agent asks for a column it was NOT granted — WITHHELD
71
+ curl -s -X POST https://www.nodatacapsule.com/api/agents/<handle>/read \
72
+ -H "Authorization: Bearer ndca-…" -H 'content-type: application/json' \
73
+ -d '{"table":"agent_demo_records","columns":["email"]}'
74
+ # → 403 { "error": "scope_violation", "denied_columns": ["email"] } ← the key for email is never derived
75
+
76
+ # 4 · prove it — signed receipts for the allow AND the deny, verifiable without the data:
77
+ # https://www.nodatacapsule.com/decisions
78
+ ```
79
+
80
+ `email` came back **absent, not blanked** — there is no decrypt‑all‑then‑filter path. That is *"you decide what the AI sees,"* as math, not a promise.
81
+
82
+ No terminal? Same idea in the browser, zero install: **https://www.nodatacapsule.com/ai-folder** — drop a folder, see exactly what an AI would be allowed to read (nothing uploads).
83
+
84
+ ---
85
+
86
+ ## Two modes — the credential decides what the server can do
87
+
88
+ **Agent mode (`--grant-token ndca-…`)** — *permission management for language models.* Hand an AI agent a grant token; the server exposes only tools hard‑scoped to that grant. The agent may request **only** the columns its grant allows — denied columns never decrypt server‑side, and every action emits a receipt. Point any MCP client at it and it **physically cannot exceed its claims**.
89
+
90
+ ```bash
91
+ claude mcp add nodata -- npx @nodatachat/mcp --grant-token ndca-YOUR_GRANT
92
+ ```
93
+
94
+ **Admin mode (`--api-key ndp_… / sk_live_…`)** — the owner seat: register tables, issue and revoke grants, and use blind relay (encrypt / decrypt / deliver / evidence) from inside any MCP client.
95
+
96
+ ```bash
97
+ claude mcp add nodata -- npx @nodatachat/mcp --api-key YOUR_API_KEY
98
+ ```
99
+
100
+ Credential precedence: `--api-key` / `--grant-token` › `NODATA_API_KEY` / `NODATA_GRANT_TOKEN` › the saved `~/.nodata` file. An explicit flag or env always wins.
101
+
102
+ On **Windows**, native (non‑WSL) `npx` needs the `cmd /c` wrapper: `claude mcp add nodata -- cmd /c npx @nodatachat/mcp …`. After changing the credential, **restart** — the running server keeps its old arguments.
103
+
104
+ ## The local workspace — scan, lock, work, release
105
+
106
+ Any mode except agent mode, **no account needed**, entirely on your machine. Anything that changes files or policy **asks first**: the call without `confirm: true` shows exactly what would happen and changes nothing.
107
+
108
+ | Say | Tool | What happens |
109
+ |-----|------|--------------|
110
+ | "scan this folder" | `nodata_scan_folder` | The **whole** result — counts by type, folder and file — plus a full content‑free HTML report in `~/.nodata/reports` (every finding, never a value). |
111
+ | "lock what it found" | `nodata_protect` | Seals the files with findings to this device's key as `<file>.ndc` — the same v3 seal and format as `nodata protect`, so `nodata open` opens it too. Local receipt with hashes. |
112
+ | "clean copy of this file" | `nodata_redact` | A copy with every detected value replaced by `[CARD]`, `[ID]`, `[IBAN]`, `[PHONE]`, `[EMAIL]` (a personal‑data CSV column hidden whole) — the rest can be analysed. Same detectors as the scan. |
113
+ | "open this .ndc" | `nodata_open` | Opens it back next to itself, hash‑checked. |
114
+ | "who can read what?" | `nodata_policy` | The policy board (admin): every agent and its exact reach. Change it with `nodata_grant` (preview → approve, a copy of the approval kept in `~/.nodata/approvals`) or `nodata_revoke` (immediate). |
115
+
116
+ ## Govern sharing — send, prove, revoke (admin)
117
+
118
+ The one-sentence version: **encrypt locally, send, revoke later, prove what happened.** NoData never holds a key that opens your file.
119
+
120
+ | Say | Tool | What happens |
121
+ |-----|------|--------------|
122
+ | "send this file to …" | `nodata_send` | Encrypts on this machine (post‑quantum hybrid) and returns a `/lock/open/<id>#<key>` link. The key rides in the `#fragment`, which never reaches a server; NoData stores ciphertext only. Expiry (≤ 7 days) and max opens. Filed under your org with a signed receipt + `proof_url`. Preview first. |
123
+ | "was it opened?" | `nodata_link_status` | Opens so far, expiry, burned — one link or every link sent from this machine. |
124
+ | "revoke it" | `nodata_burn` | Zeroes the stored ciphertext: nobody can open it again, including a forwarded copy. Signed receipt. Preview first. |
125
+ | "archive these" | `nodata_wrap` | Seals files to the public half of your **org master key (the 12 words)** into your zero‑knowledge capsule. NoData can never open them; your 12 words always can — even if this computer is lost. Signed receipt + `proof_url` per document. Preview first. |
126
+
127
+ ---
128
+
129
+ ## Available tools
130
+
131
+ **Agent mode** (`--grant-token`):
132
+
133
+ | Tool | What it does |
134
+ |------|--------------|
135
+ | `nodata_decide` | May the agent reach a resource? allow / degrade (reachable subset) / deny + an access‑distance cost + a signed proof. No data. Plan before you read. |
136
+ | `nodata_retrieve` | Prompt‑ready authorized context, filtered to allowed columns, with an accounting of what was withheld + a proof. |
137
+ | `nodata_read` | Read governed rows within the grant; denied columns never decrypt; every read is receipted. |
138
+ | `nodata_use` | Invoke a pre‑registered secret‑blind capability — the Capsule injects the sealed credential server‑side and returns only the result. The secret never reaches the agent. |
139
+
140
+ **Admin mode** (`--api-key`):
141
+
142
+ | Tool | What it does |
143
+ |------|--------------|
144
+ | `nodata_register_table` | Register one of your tables' **policy** (which columns are sensitive, which are metadata). Encrypts nothing — the response says what your table still needs. |
145
+ | `nodata_connect_source` | Connect your own Supabase project as the data source. Reads the URL, anon key and JWT secret from your **local** `.env.local` / `.env` and sends them straight to NoData — the model never sees them. |
146
+ | `nodata_grant` | Issue **one** agent a claim‑scoped grant — over one table, or several with `tables: [...]`. Previews the policy change first; with `confirm: true` it grants, returns a `grant_token` (shown once) and a `proof_url`, and keeps a copy of the approval. |
147
+ | `nodata_policy` | The policy board — every agent and exactly what it can reach. |
148
+ | `nodata_revoke` | Revoke a grant by handle or jti — access stops at once. |
149
+ | `nodata_encrypt` / `nodata_decrypt` | Field‑level AES‑256‑GCM; NoData stores nothing of the plaintext. |
150
+ | `nodata_deliver` | Create a burn‑after‑read secure link with OTP. |
151
+ | `nodata_proofs` | Your organization's signed proofs — every grant, read and deny — each verifiable by anyone at `/api/access/verify`. Every org key. Also returns `plan`: which proof types your plan includes, and which need an upgrade (named, never hidden) — the same list the site's proofs hub shows. |
152
+ | `nodata_evidence` | Field‑level encrypt/decrypt/deliver events. Requires the Engine scope. |
153
+
154
+ ---
155
+
156
+ ## Security & privacy model
157
+
158
+ - **Content‑blind.** For governed reads, denied columns are **never decrypted on the server** — the key release is scoped to the grant, not "we promise not to look."
159
+ - **Every action is a receipt.** Reads, grants, revokes and denials mint a signed, hash‑chained decision receipt (Ed25519, publicly verifiable), written **before** the release it authorizes — if the receipt can't be written, nothing is served.
160
+ - **Structural isolation.** A key is bound to its org; every governance query is scoped to that tenant, so a key cannot aim at another org's data.
161
+ - **The honest boundary.** This governs data the agent reaches **through the Capsule**. It does not sandbox a process already executing as you on your own machine.
162
+
163
+ ---
164
+
165
+ ## Configuration
166
+
167
+ | Option | Flag | Env var | Default |
168
+ |--------|------|---------|---------|
169
+ | API key (admin) | `--api-key` | `NODATA_API_KEY` | — |
170
+ | Grant token (agent) | `--grant-token` | `NODATA_GRANT_TOKEN` | — |
171
+ | Base URL | `--base-url` | `NODATA_BASE_URL` | `https://www.nodatacapsule.com` |
172
+
173
+ Get a key free at **https://www.nodatacapsule.com/capsule-api/register** (issues `ndp_test_…` instantly). `--help` and `--version` are also available.
174
+
175
+ ## NoData on npm
176
+
177
+ - **`@nodatachat/nodata`**: the main package, with all protection, scanning and governance capabilities, from the terminal.
178
+ - **`@nodatachat/sdk`**: integration for developers.
179
+ - **`@nodatachat/mcp`** (this one): integration for AI agents and MCP clients.
180
+
181
+ ## License
182
+
183
+ [FSL-1.1-ALv2](LICENSE.md) (Functional Source License 1.1, Apache 2.0 future license).
184
+ Use it for any purpose except a competing product or service. Each release becomes
185
+ available under the Apache License 2.0 two years after it is published. Versions up
186
+ to 0.9.0 were published under MIT and remain available under that license.
187
+ Copyright 2026 Capsule Ltd.