Skip to content

Commit 1856e56

Browse files
hesreallyhimhesreallyhim
committed
feat(read-tools): add invites settings and vault member read surface
1 parent 945ec32 commit 1856e56

9 files changed

Lines changed: 723 additions & 43 deletions

File tree

‎README.md‎

Lines changed: 13 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -15,16 +15,19 @@ It is designed as a thin integration layer:
1515

1616
As this project is in its initial stages, it exposes the following read-only tools:
1717

18-
| Tool | Purpose |
19-
| ------------------- | ------------------------------------------------ |
20-
| `view_session_info` | Session/account status from `pass-cli info` |
21-
| `view_user_info` | User account details from `pass-cli user info` |
22-
| `check_status` | Check user authentication status and CLI version |
23-
| `list_vaults` | List vaults |
24-
| `list_shares` | List shares |
25-
| `list_items` | List vault or share items, omitting contents |
26-
| `search_items` | Search items by title |
27-
| `view_item` | View item by URI or selectors |
18+
| Tool | Purpose |
19+
| -------------------- | ------------------------------------------------ |
20+
| `view_session_info` | Session/account status from `pass-cli info` |
21+
| `view_user_info` | User account details from `pass-cli user info` |
22+
| `check_status` | Check user authentication status and CLI version |
23+
| `list_vaults` | List vaults |
24+
| `list_shares` | List shares |
25+
| `list_invites` | List pending invitations |
26+
| `view_settings` | View current Proton Pass CLI settings |
27+
| `list_vault_members` | List members of a specific vault |
28+
| `list_items` | List vault or share items, omitting contents |
29+
| `search_items` | Search items by title |
30+
| `view_item` | View item by URI or selectors |
2831

2932
The `search_items` operation is additional functionality that is not provided by the base CLI.
3033

‎docs/TOOL_SCHEMA_PLAN.md‎

Lines changed: 100 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -97,6 +97,38 @@ Notes:
9797

9898
Cursor is an offset string (`"0"`, `"100"`, ...).
9999

100+
### `InviteRef` (canonical invitation list object)
101+
102+
```json
103+
{
104+
"id": "string",
105+
"type": "string | null",
106+
"target_name": "string | null",
107+
"inviter": "string | null",
108+
"role": "string | null",
109+
"state": "string | null",
110+
"create_time": "string | null"
111+
}
112+
```
113+
114+
Notes:
115+
116+
1. Treat invitation tokens as sensitive capabilities and do not expose them in list payloads.
117+
2. Include only stable metadata needed for triage and follow-up selection.
118+
119+
### `VaultMemberRef` (canonical vault-member list object)
120+
121+
```json
122+
{
123+
"id": "string",
124+
"username": "string | null",
125+
"email": "string | null",
126+
"role": "string | null",
127+
"state": "string | null",
128+
"create_time": "string | null"
129+
}
130+
```
131+
100132
## Item Discovery Contract
101133

102134
### `list_items` (planned v2 behavior)
@@ -136,6 +168,44 @@ Notes:
136168
1. Search is explicitly title-based for v1.
137169
2. If title is missing, item is still returned as a ref but cannot match title query except by empty/exact edge cases.
138170

171+
## Incremental Read Contracts (Pre-Write Track)
172+
173+
### `list_invites`
174+
175+
Input:
176+
177+
1. `pageSize`, `cursor`.
178+
179+
Output:
180+
181+
1. `structuredContent: CursorPage<InviteRef>`.
182+
2. Reference-only invite metadata (no raw invite token material in list payloads).
183+
3. When structured parsing is unavailable, return best-effort normalized text in `content`.
184+
185+
### `list_vault_members`
186+
187+
Input:
188+
189+
1. Scope selector: exactly one of `shareId` or `vaultName`.
190+
2. `pageSize`, `cursor`.
191+
192+
Output:
193+
194+
1. `structuredContent: CursorPage<VaultMemberRef>`.
195+
2. `scope` object echoing the selector used (`shareId` or `vaultName`).
196+
3. When structured parsing is unavailable, return best-effort normalized text in `content`.
197+
198+
### `view_settings`
199+
200+
Input:
201+
202+
1. none.
203+
204+
Output:
205+
206+
1. `structuredContent` with parsed settings when machine-readable shape is derivable.
207+
2. `content` remains present for debugging/interoperability.
208+
139209
## Planned Tool Inventory
140210

141211
Status key:
@@ -160,17 +230,17 @@ Status key:
160230

161231
### Vault Tools
162232

163-
| Tool | Source | Status | Input Summary | Output Summary |
164-
| --------------------- | ------------------------------ | ----------- | ---------------------------------------------------------- | -------------------- |
165-
| `list_vaults` | `pass-cli vault list` | Implemented | `output?` | Vault list |
166-
| `create_vault` | `pass-cli vault create` | Implemented | `name`, `confirm` | Created vault status |
167-
| `update_vault` | `pass-cli vault update` | Implemented | `shareId \| vaultName`, `newName`, `confirm` | Update status |
168-
| `delete_vault` | `pass-cli vault delete` | Implemented | `shareId \| vaultName`, `confirm` | Delete status |
169-
| `vault_share` | `pass-cli vault share` | Planned | `shareId \| vaultName`, `email`, `role?`, `confirm` | Share result |
170-
| `vault_transfer` | `pass-cli vault transfer` | Planned | `shareId \| vaultName`, `memberShareId`, `confirm` | Transfer result |
171-
| `vault_member_list` | `pass-cli vault member list` | Planned | `shareId \| vaultName`, `output?` | Member list |
172-
| `vault_member_update` | `pass-cli vault member update` | Planned | `shareId \| vaultName`, `memberShareId`, `role`, `confirm` | Update status |
173-
| `vault_member_remove` | `pass-cli vault member remove` | Planned | `shareId \| vaultName`, `memberShareId`, `confirm` | Remove status |
233+
| Tool | Source | Status | Input Summary | Output Summary |
234+
| --------------------- | ------------------------------ | ----------- | ---------------------------------------------------------- | ---------------------------- |
235+
| `list_vaults` | `pass-cli vault list` | Implemented | `output?` | Vault list |
236+
| `create_vault` | `pass-cli vault create` | Implemented | `name`, `confirm` | Created vault status |
237+
| `update_vault` | `pass-cli vault update` | Implemented | `shareId \| vaultName`, `newName`, `confirm` | Update status |
238+
| `delete_vault` | `pass-cli vault delete` | Implemented | `shareId \| vaultName`, `confirm` | Delete status |
239+
| `vault_share` | `pass-cli vault share` | Planned | `shareId \| vaultName`, `email`, `role?`, `confirm` | Share result |
240+
| `vault_transfer` | `pass-cli vault transfer` | Planned | `shareId \| vaultName`, `memberShareId`, `confirm` | Transfer result |
241+
| `list_vault_members` | `pass-cli vault member list` | Implemented | `shareId \| vaultName`, `pageSize?`, `cursor?` | `CursorPage<VaultMemberRef>` |
242+
| `vault_member_update` | `pass-cli vault member update` | Planned | `shareId \| vaultName`, `memberShareId`, `role`, `confirm` | Update status |
243+
| `vault_member_remove` | `pass-cli vault member remove` | Planned | `shareId \| vaultName`, `memberShareId`, `confirm` | Remove status |
174244

175245
### Item Discovery and Read
176246

@@ -218,24 +288,24 @@ Status key:
218288

219289
### Share, Invite, Password, TOTP, User, Settings, SSH Agent
220290

221-
| Tool | Source | Status | Input Summary | Output Summary |
222-
| ------------------------------- | ---------------------------------------- | ------- | -------------------------------------- | ------------------------- |
223-
| `list_shares` | `pass-cli share list` | Planned | `onlyItems?`, `onlyVaults?`, `output?` | Shares list |
224-
| `invite_list` | `pass-cli invite list` | Planned | `output?` | Invite list |
225-
| `invite_accept` | `pass-cli invite accept` | Planned | `inviteId`, `confirm` | Accept status |
226-
| `invite_reject` | `pass-cli invite reject` | Planned | `inviteId`, `confirm` | Reject status |
227-
| `password_generate_random` | `pass-cli password generate random` | Planned | generation flags, `output?` | Password value/metadata |
228-
| `password_generate_passphrase` | `pass-cli password generate passphrase` | Planned | generation flags, `output?` | Passphrase value/metadata |
229-
| `password_score` | `pass-cli password score` | Planned | `password`, `output?` | Strength report |
230-
| `totp_generate` | `pass-cli totp generate` | Planned | `secretOrUri`, `output?` | TOTP value |
231-
| `settings_view` | `pass-cli settings view` | Planned | none | Settings object |
232-
| `settings_set_default_vault` | `pass-cli settings set default-vault` | Planned | `vaultName \| shareId`, `confirm` | Set status |
233-
| `settings_set_default_format` | `pass-cli settings set default-format` | Planned | `format`, `confirm` | Set status |
234-
| `settings_unset_default_vault` | `pass-cli settings unset default-vault` | Planned | `confirm` | Unset status |
235-
| `settings_unset_default_format` | `pass-cli settings unset default-format` | Planned | `confirm` | Unset status |
236-
| `ssh_agent_start` | `pass-cli ssh-agent start` | Planned | CLI flags passthrough, `confirm` | Agent status |
237-
| `ssh_agent_load` | `pass-cli ssh-agent load` | Planned | CLI flags passthrough, `confirm` | Load status |
238-
| `ssh_agent_debug` | `pass-cli ssh-agent debug` | Planned | selectors, `output?` | Debug report |
291+
| Tool | Source | Status | Input Summary | Output Summary |
292+
| ------------------------------- | ---------------------------------------- | ----------- | -------------------------------------- | ------------------------- |
293+
| `list_shares` | `pass-cli share list` | Implemented | `onlyItems?`, `onlyVaults?`, `output?` | Shares list |
294+
| `list_invites` | `pass-cli invite list` | Implemented | `pageSize?`, `cursor?` | `CursorPage<InviteRef>` |
295+
| `invite_accept` | `pass-cli invite accept` | Planned | `inviteId`, `confirm` | Accept status |
296+
| `invite_reject` | `pass-cli invite reject` | Planned | `inviteId`, `confirm` | Reject status |
297+
| `generate_random_password` | `pass-cli password generate random` | Planned | generation flags | Password value/metadata |
298+
| `generate_passphrase` | `pass-cli password generate passphrase` | Planned | generation flags | Passphrase value/metadata |
299+
| `score_password` | `pass-cli password score` | Planned | `password` | Strength report |
300+
| `totp_generate` | `pass-cli totp generate` | Planned | `secretOrUri`, `output?` | TOTP value |
301+
| `view_settings` | `pass-cli settings view` | Implemented | none | Settings object |
302+
| `settings_set_default_vault` | `pass-cli settings set default-vault` | Planned | `vaultName \| shareId`, `confirm` | Set status |
303+
| `settings_set_default_format` | `pass-cli settings set default-format` | Planned | `format`, `confirm` | Set status |
304+
| `settings_unset_default_vault` | `pass-cli settings unset default-vault` | Planned | `confirm` | Unset status |
305+
| `settings_unset_default_format` | `pass-cli settings unset default-format` | Planned | `confirm` | Unset status |
306+
| `ssh_agent_start` | `pass-cli ssh-agent start` | Planned | CLI flags passthrough, `confirm` | Agent status |
307+
| `ssh_agent_load` | `pass-cli ssh-agent load` | Planned | CLI flags passthrough, `confirm` | Load status |
308+
| `ssh_agent_debug` | `pass-cli ssh-agent debug` | Planned | selectors, `output?` | Debug report |
239309

240310
## Phased Delivery
241311

@@ -260,4 +330,4 @@ Status key:
260330
1. Compatibility strategy for `list_items` response change:
261331
Option A: break to ref-only now.
262332
Option B: transition with `includeRawItem`.
263-
2. Whether to split non-JSON outputs into dedicated `*_human` tools or keep `output` enum on all parity wrappers.
333+
2. If a CLI command has no documented JSON mode, what minimum parsed structure should MCP provide by default.

‎src/server.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,8 +21,10 @@ export * from "./pass-cli/output.js";
2121
export * from "./pass-cli/runner.js";
2222
export * from "./pass-cli/version.js";
2323
export * from "./tools/check-status.js";
24+
export * from "./tools/invite.js";
2425
export * from "./tools/item.js";
2526
export * from "./tools/session.js";
27+
export * from "./tools/settings.js";
2628
export * from "./tools/share.js";
2729
export * from "./tools/vault.js";
2830
export * from "./tools/write-gate.js";

‎src/server/register-tools.ts‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,13 +12,20 @@ import {
1212
viewItemHandler,
1313
viewItemInputSchema,
1414
} from "../tools/item.js";
15+
import { listInvitesHandler, listInvitesInputSchema } from "../tools/invite.js";
1516
import {
1617
viewSessionInfoHandler,
1718
viewUserInfoHandler,
1819
viewUserInfoInputSchema,
1920
} from "../tools/session.js";
21+
import { viewSettingsHandler } from "../tools/settings.js";
2022
import { listSharesHandler, listSharesInputSchema } from "../tools/share.js";
21-
import { listVaultsHandler, listVaultsInputSchema } from "../tools/vault.js";
23+
import {
24+
listVaultMembersHandler,
25+
listVaultMembersInputSchema,
26+
listVaultsHandler,
27+
listVaultsInputSchema,
28+
} from "../tools/vault.js";
2229

2330
export function registerTools(
2431
server: McpServer,
@@ -69,6 +76,32 @@ export function registerTools(
6976
withAuthErrorHandling(async (input) => listSharesHandler(passCli, input)),
7077
);
7178

79+
server.registerTool(
80+
"list_invites",
81+
{
82+
description: "List pending invitations accessible to the current authenticated user.",
83+
inputSchema: listInvitesInputSchema,
84+
},
85+
withAuthErrorHandling(async (input) => listInvitesHandler(passCli, input)),
86+
);
87+
88+
server.registerTool(
89+
"view_settings",
90+
{
91+
description: "View current Proton Pass CLI settings.",
92+
},
93+
withAuthErrorHandling(async () => viewSettingsHandler(passCli)),
94+
);
95+
96+
server.registerTool(
97+
"list_vault_members",
98+
{
99+
description: "List members for a vault by share ID or vault name.",
100+
inputSchema: listVaultMembersInputSchema,
101+
},
102+
withAuthErrorHandling(async (input) => listVaultMembersHandler(passCli, input)),
103+
);
104+
72105
server.registerTool(
73106
"list_items",
74107
{

0 commit comments

Comments
 (0)