@withpica/mcp-server 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 (347) hide show
  1. package/.claude/settings.local.json +5 -0
  2. package/CHANGELOG.md +1850 -0
  3. package/README.md +304 -0
  4. package/assets/fonts/GeistSans-Light.woff2 +0 -0
  5. package/assets/fonts/InstrumentSerif-Italic.woff2 +0 -0
  6. package/assets/fonts/InstrumentSerif-Regular.woff2 +0 -0
  7. package/dist/apps/download.d.ts +2 -0
  8. package/dist/apps/download.d.ts.map +1 -0
  9. package/dist/apps/download.js +125 -0
  10. package/dist/apps/download.js.map +1 -0
  11. package/dist/apps/generated/shared-bundle.d.ts +5 -0
  12. package/dist/apps/generated/shared-bundle.d.ts.map +1 -0
  13. package/dist/apps/generated/shared-bundle.js +7 -0
  14. package/dist/apps/generated/shared-bundle.js.map +1 -0
  15. package/dist/apps/release.d.ts +2 -0
  16. package/dist/apps/release.d.ts.map +1 -0
  17. package/dist/apps/release.js +69 -0
  18. package/dist/apps/release.js.map +1 -0
  19. package/dist/apps/shared.d.ts +15 -0
  20. package/dist/apps/shared.d.ts.map +1 -0
  21. package/dist/apps/shared.js +480 -0
  22. package/dist/apps/shared.js.map +1 -0
  23. package/dist/apps/upload.d.ts +2 -0
  24. package/dist/apps/upload.d.ts.map +1 -0
  25. package/dist/apps/upload.js +280 -0
  26. package/dist/apps/upload.js.map +1 -0
  27. package/dist/config.d.ts +14 -0
  28. package/dist/config.d.ts.map +1 -0
  29. package/dist/config.js +73 -0
  30. package/dist/config.js.map +1 -0
  31. package/dist/index.d.ts +3 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +35 -0
  34. package/dist/index.js.map +1 -0
  35. package/dist/prompts/index.d.ts +86 -0
  36. package/dist/prompts/index.d.ts.map +1 -0
  37. package/dist/prompts/index.js +645 -0
  38. package/dist/prompts/index.js.map +1 -0
  39. package/dist/resources/agent-guide.d.ts +15 -0
  40. package/dist/resources/agent-guide.d.ts.map +1 -0
  41. package/dist/resources/agent-guide.js +284 -0
  42. package/dist/resources/agent-guide.js.map +1 -0
  43. package/dist/resources/index.d.ts +66 -0
  44. package/dist/resources/index.d.ts.map +1 -0
  45. package/dist/resources/index.js +510 -0
  46. package/dist/resources/index.js.map +1 -0
  47. package/dist/resources/llms-primer.d.ts +2 -0
  48. package/dist/resources/llms-primer.d.ts.map +1 -0
  49. package/dist/resources/llms-primer.js +68 -0
  50. package/dist/resources/llms-primer.js.map +1 -0
  51. package/dist/resources/required-schemas.generated.d.ts +455 -0
  52. package/dist/resources/required-schemas.generated.d.ts.map +1 -0
  53. package/dist/resources/required-schemas.generated.js +1041 -0
  54. package/dist/resources/required-schemas.generated.js.map +1 -0
  55. package/dist/resources/required-schemas.source.d.ts +53 -0
  56. package/dist/resources/required-schemas.source.d.ts.map +1 -0
  57. package/dist/resources/required-schemas.source.js +493 -0
  58. package/dist/resources/required-schemas.source.js.map +1 -0
  59. package/dist/resources/welcome.d.ts +14 -0
  60. package/dist/resources/welcome.d.ts.map +1 -0
  61. package/dist/resources/welcome.js +26 -0
  62. package/dist/resources/welcome.js.map +1 -0
  63. package/dist/server-instructions.d.ts +60 -0
  64. package/dist/server-instructions.d.ts.map +1 -0
  65. package/dist/server-instructions.js +93 -0
  66. package/dist/server-instructions.js.map +1 -0
  67. package/dist/server.d.ts +52 -0
  68. package/dist/server.d.ts.map +1 -0
  69. package/dist/server.js +334 -0
  70. package/dist/server.js.map +1 -0
  71. package/dist/tools/access-simulate.d.ts +23 -0
  72. package/dist/tools/access-simulate.d.ts.map +1 -0
  73. package/dist/tools/access-simulate.js +162 -0
  74. package/dist/tools/access-simulate.js.map +1 -0
  75. package/dist/tools/agent-identity.d.ts +36 -0
  76. package/dist/tools/agent-identity.d.ts.map +1 -0
  77. package/dist/tools/agent-identity.js +274 -0
  78. package/dist/tools/agent-identity.js.map +1 -0
  79. package/dist/tools/agreement-types.d.ts +27 -0
  80. package/dist/tools/agreement-types.d.ts.map +1 -0
  81. package/dist/tools/agreement-types.js +281 -0
  82. package/dist/tools/agreement-types.js.map +1 -0
  83. package/dist/tools/agreements.d.ts +20 -0
  84. package/dist/tools/agreements.d.ts.map +1 -0
  85. package/dist/tools/agreements.js +282 -0
  86. package/dist/tools/agreements.js.map +1 -0
  87. package/dist/tools/analytics.d.ts +20 -0
  88. package/dist/tools/analytics.d.ts.map +1 -0
  89. package/dist/tools/analytics.js +130 -0
  90. package/dist/tools/analytics.js.map +1 -0
  91. package/dist/tools/app-tools.d.ts +15 -0
  92. package/dist/tools/app-tools.d.ts.map +1 -0
  93. package/dist/tools/app-tools.js +388 -0
  94. package/dist/tools/app-tools.js.map +1 -0
  95. package/dist/tools/assets.d.ts +25 -0
  96. package/dist/tools/assets.d.ts.map +1 -0
  97. package/dist/tools/assets.js +454 -0
  98. package/dist/tools/assets.js.map +1 -0
  99. package/dist/tools/audio-files.d.ts +20 -0
  100. package/dist/tools/audio-files.d.ts.map +1 -0
  101. package/dist/tools/audio-files.js +409 -0
  102. package/dist/tools/audio-files.js.map +1 -0
  103. package/dist/tools/audit.d.ts +19 -0
  104. package/dist/tools/audit.d.ts.map +1 -0
  105. package/dist/tools/audit.js +58 -0
  106. package/dist/tools/audit.js.map +1 -0
  107. package/dist/tools/auth.d.ts +22 -0
  108. package/dist/tools/auth.d.ts.map +1 -0
  109. package/dist/tools/auth.js +212 -0
  110. package/dist/tools/auth.js.map +1 -0
  111. package/dist/tools/bulk.d.ts +22 -0
  112. package/dist/tools/bulk.d.ts.map +1 -0
  113. package/dist/tools/bulk.js +164 -0
  114. package/dist/tools/bulk.js.map +1 -0
  115. package/dist/tools/calendar.d.ts +15 -0
  116. package/dist/tools/calendar.d.ts.map +1 -0
  117. package/dist/tools/calendar.js +68 -0
  118. package/dist/tools/calendar.js.map +1 -0
  119. package/dist/tools/collaborators.d.ts +21 -0
  120. package/dist/tools/collaborators.d.ts.map +1 -0
  121. package/dist/tools/collaborators.js +381 -0
  122. package/dist/tools/collaborators.js.map +1 -0
  123. package/dist/tools/comparisons.d.ts +22 -0
  124. package/dist/tools/comparisons.d.ts.map +1 -0
  125. package/dist/tools/comparisons.js +80 -0
  126. package/dist/tools/comparisons.js.map +1 -0
  127. package/dist/tools/credits.d.ts +39 -0
  128. package/dist/tools/credits.d.ts.map +1 -0
  129. package/dist/tools/credits.js +541 -0
  130. package/dist/tools/credits.js.map +1 -0
  131. package/dist/tools/custody-hints.d.ts +16 -0
  132. package/dist/tools/custody-hints.d.ts.map +1 -0
  133. package/dist/tools/custody-hints.js +27 -0
  134. package/dist/tools/custody-hints.js.map +1 -0
  135. package/dist/tools/custody.d.ts +38 -0
  136. package/dist/tools/custody.d.ts.map +1 -0
  137. package/dist/tools/custody.js +281 -0
  138. package/dist/tools/custody.js.map +1 -0
  139. package/dist/tools/dashboard.d.ts +22 -0
  140. package/dist/tools/dashboard.d.ts.map +1 -0
  141. package/dist/tools/dashboard.js +258 -0
  142. package/dist/tools/dashboard.js.map +1 -0
  143. package/dist/tools/directory.d.ts +15 -0
  144. package/dist/tools/directory.d.ts.map +1 -0
  145. package/dist/tools/directory.js +107 -0
  146. package/dist/tools/directory.js.map +1 -0
  147. package/dist/tools/discovery.d.ts +49 -0
  148. package/dist/tools/discovery.d.ts.map +1 -0
  149. package/dist/tools/discovery.js +851 -0
  150. package/dist/tools/discovery.js.map +1 -0
  151. package/dist/tools/disputes.d.ts +18 -0
  152. package/dist/tools/disputes.d.ts.map +1 -0
  153. package/dist/tools/disputes.js +62 -0
  154. package/dist/tools/disputes.js.map +1 -0
  155. package/dist/tools/documents.d.ts +15 -0
  156. package/dist/tools/documents.d.ts.map +1 -0
  157. package/dist/tools/documents.js +37 -0
  158. package/dist/tools/documents.js.map +1 -0
  159. package/dist/tools/duplicates.d.ts +25 -0
  160. package/dist/tools/duplicates.d.ts.map +1 -0
  161. package/dist/tools/duplicates.js +108 -0
  162. package/dist/tools/duplicates.js.map +1 -0
  163. package/dist/tools/enrichment.d.ts +56 -0
  164. package/dist/tools/enrichment.d.ts.map +1 -0
  165. package/dist/tools/enrichment.js +616 -0
  166. package/dist/tools/enrichment.js.map +1 -0
  167. package/dist/tools/exports.d.ts +19 -0
  168. package/dist/tools/exports.d.ts.map +1 -0
  169. package/dist/tools/exports.js +184 -0
  170. package/dist/tools/exports.js.map +1 -0
  171. package/dist/tools/feedback.d.ts +22 -0
  172. package/dist/tools/feedback.d.ts.map +1 -0
  173. package/dist/tools/feedback.js +100 -0
  174. package/dist/tools/feedback.js.map +1 -0
  175. package/dist/tools/forbidden-keywords.d.ts +62 -0
  176. package/dist/tools/forbidden-keywords.d.ts.map +1 -0
  177. package/dist/tools/forbidden-keywords.js +99 -0
  178. package/dist/tools/forbidden-keywords.js.map +1 -0
  179. package/dist/tools/gap-hints.d.ts +53 -0
  180. package/dist/tools/gap-hints.d.ts.map +1 -0
  181. package/dist/tools/gap-hints.js +245 -0
  182. package/dist/tools/gap-hints.js.map +1 -0
  183. package/dist/tools/groups.d.ts +29 -0
  184. package/dist/tools/groups.d.ts.map +1 -0
  185. package/dist/tools/groups.js +186 -0
  186. package/dist/tools/groups.js.map +1 -0
  187. package/dist/tools/import-documents.d.ts +21 -0
  188. package/dist/tools/import-documents.d.ts.map +1 -0
  189. package/dist/tools/import-documents.js +206 -0
  190. package/dist/tools/import-documents.js.map +1 -0
  191. package/dist/tools/import.d.ts +31 -0
  192. package/dist/tools/import.d.ts.map +1 -0
  193. package/dist/tools/import.js +610 -0
  194. package/dist/tools/import.js.map +1 -0
  195. package/dist/tools/index.d.ts +293 -0
  196. package/dist/tools/index.d.ts.map +1 -0
  197. package/dist/tools/index.js +1182 -0
  198. package/dist/tools/index.js.map +1 -0
  199. package/dist/tools/integrations.d.ts +19 -0
  200. package/dist/tools/integrations.d.ts.map +1 -0
  201. package/dist/tools/integrations.js +120 -0
  202. package/dist/tools/integrations.js.map +1 -0
  203. package/dist/tools/labels.d.ts +20 -0
  204. package/dist/tools/labels.d.ts.map +1 -0
  205. package/dist/tools/labels.js +48 -0
  206. package/dist/tools/labels.js.map +1 -0
  207. package/dist/tools/licensing.d.ts +40 -0
  208. package/dist/tools/licensing.d.ts.map +1 -0
  209. package/dist/tools/licensing.js +436 -0
  210. package/dist/tools/licensing.js.map +1 -0
  211. package/dist/tools/memory.d.ts +21 -0
  212. package/dist/tools/memory.d.ts.map +1 -0
  213. package/dist/tools/memory.js +120 -0
  214. package/dist/tools/memory.js.map +1 -0
  215. package/dist/tools/metadata.d.ts +15 -0
  216. package/dist/tools/metadata.d.ts.map +1 -0
  217. package/dist/tools/metadata.js +1532 -0
  218. package/dist/tools/metadata.js.map +1 -0
  219. package/dist/tools/multimedia.d.ts +19 -0
  220. package/dist/tools/multimedia.d.ts.map +1 -0
  221. package/dist/tools/multimedia.js +371 -0
  222. package/dist/tools/multimedia.js.map +1 -0
  223. package/dist/tools/my-reported-issues.d.ts +32 -0
  224. package/dist/tools/my-reported-issues.d.ts.map +1 -0
  225. package/dist/tools/my-reported-issues.js +123 -0
  226. package/dist/tools/my-reported-issues.js.map +1 -0
  227. package/dist/tools/notes.d.ts +21 -0
  228. package/dist/tools/notes.d.ts.map +1 -0
  229. package/dist/tools/notes.js +115 -0
  230. package/dist/tools/notes.js.map +1 -0
  231. package/dist/tools/notifications.d.ts +28 -0
  232. package/dist/tools/notifications.d.ts.map +1 -0
  233. package/dist/tools/notifications.js +417 -0
  234. package/dist/tools/notifications.js.map +1 -0
  235. package/dist/tools/onboarding.d.ts +24 -0
  236. package/dist/tools/onboarding.d.ts.map +1 -0
  237. package/dist/tools/onboarding.js +81 -0
  238. package/dist/tools/onboarding.js.map +1 -0
  239. package/dist/tools/people.d.ts +254 -0
  240. package/dist/tools/people.d.ts.map +1 -0
  241. package/dist/tools/people.js +481 -0
  242. package/dist/tools/people.js.map +1 -0
  243. package/dist/tools/projects.d.ts +20 -0
  244. package/dist/tools/projects.d.ts.map +1 -0
  245. package/dist/tools/projects.js +316 -0
  246. package/dist/tools/projects.js.map +1 -0
  247. package/dist/tools/public-filter.d.ts +43 -0
  248. package/dist/tools/public-filter.d.ts.map +1 -0
  249. package/dist/tools/public-filter.js +356 -0
  250. package/dist/tools/public-filter.js.map +1 -0
  251. package/dist/tools/publishers.d.ts +30 -0
  252. package/dist/tools/publishers.d.ts.map +1 -0
  253. package/dist/tools/publishers.js +105 -0
  254. package/dist/tools/publishers.js.map +1 -0
  255. package/dist/tools/purchases.d.ts +27 -0
  256. package/dist/tools/purchases.d.ts.map +1 -0
  257. package/dist/tools/purchases.js +9 -0
  258. package/dist/tools/purchases.js.map +1 -0
  259. package/dist/tools/recording-attribution-hints.d.ts +24 -0
  260. package/dist/tools/recording-attribution-hints.d.ts.map +1 -0
  261. package/dist/tools/recording-attribution-hints.js +27 -0
  262. package/dist/tools/recording-attribution-hints.js.map +1 -0
  263. package/dist/tools/recordings.d.ts +96 -0
  264. package/dist/tools/recordings.d.ts.map +1 -0
  265. package/dist/tools/recordings.js +564 -0
  266. package/dist/tools/recordings.js.map +1 -0
  267. package/dist/tools/recovery-hints.d.ts +40 -0
  268. package/dist/tools/recovery-hints.d.ts.map +1 -0
  269. package/dist/tools/recovery-hints.js +827 -0
  270. package/dist/tools/recovery-hints.js.map +1 -0
  271. package/dist/tools/release-rich.d.ts +31 -0
  272. package/dist/tools/release-rich.d.ts.map +1 -0
  273. package/dist/tools/release-rich.js +245 -0
  274. package/dist/tools/release-rich.js.map +1 -0
  275. package/dist/tools/releases.d.ts +36 -0
  276. package/dist/tools/releases.d.ts.map +1 -0
  277. package/dist/tools/releases.js +649 -0
  278. package/dist/tools/releases.js.map +1 -0
  279. package/dist/tools/report-issue.d.ts +21 -0
  280. package/dist/tools/report-issue.d.ts.map +1 -0
  281. package/dist/tools/report-issue.js +101 -0
  282. package/dist/tools/report-issue.js.map +1 -0
  283. package/dist/tools/royalties.d.ts +23 -0
  284. package/dist/tools/royalties.d.ts.map +1 -0
  285. package/dist/tools/royalties.js +262 -0
  286. package/dist/tools/royalties.js.map +1 -0
  287. package/dist/tools/search.d.ts +30 -0
  288. package/dist/tools/search.d.ts.map +1 -0
  289. package/dist/tools/search.js +115 -0
  290. package/dist/tools/search.js.map +1 -0
  291. package/dist/tools/send.d.ts +17 -0
  292. package/dist/tools/send.d.ts.map +1 -0
  293. package/dist/tools/send.js +188 -0
  294. package/dist/tools/send.js.map +1 -0
  295. package/dist/tools/sessions.d.ts +18 -0
  296. package/dist/tools/sessions.d.ts.map +1 -0
  297. package/dist/tools/sessions.js +153 -0
  298. package/dist/tools/sessions.js.map +1 -0
  299. package/dist/tools/settings.d.ts +23 -0
  300. package/dist/tools/settings.d.ts.map +1 -0
  301. package/dist/tools/settings.js +365 -0
  302. package/dist/tools/settings.js.map +1 -0
  303. package/dist/tools/share-links.d.ts +22 -0
  304. package/dist/tools/share-links.d.ts.map +1 -0
  305. package/dist/tools/share-links.js +188 -0
  306. package/dist/tools/share-links.js.map +1 -0
  307. package/dist/tools/signup.d.ts +26 -0
  308. package/dist/tools/signup.d.ts.map +1 -0
  309. package/dist/tools/signup.js +266 -0
  310. package/dist/tools/signup.js.map +1 -0
  311. package/dist/tools/split-sheets.d.ts +25 -0
  312. package/dist/tools/split-sheets.d.ts.map +1 -0
  313. package/dist/tools/split-sheets.js +309 -0
  314. package/dist/tools/split-sheets.js.map +1 -0
  315. package/dist/tools/storage-config.d.ts +13 -0
  316. package/dist/tools/storage-config.d.ts.map +1 -0
  317. package/dist/tools/storage-config.js +245 -0
  318. package/dist/tools/storage-config.js.map +1 -0
  319. package/dist/tools/subscription.d.ts +60 -0
  320. package/dist/tools/subscription.d.ts.map +1 -0
  321. package/dist/tools/subscription.js +440 -0
  322. package/dist/tools/subscription.js.map +1 -0
  323. package/dist/tools/sync-placements.d.ts +31 -0
  324. package/dist/tools/sync-placements.d.ts.map +1 -0
  325. package/dist/tools/sync-placements.js +431 -0
  326. package/dist/tools/sync-placements.js.map +1 -0
  327. package/dist/tools/team.d.ts +22 -0
  328. package/dist/tools/team.d.ts.map +1 -0
  329. package/dist/tools/team.js +144 -0
  330. package/dist/tools/team.js.map +1 -0
  331. package/dist/tools/telegram.d.ts +21 -0
  332. package/dist/tools/telegram.d.ts.map +1 -0
  333. package/dist/tools/telegram.js +144 -0
  334. package/dist/tools/telegram.js.map +1 -0
  335. package/dist/tools/uploads.d.ts +17 -0
  336. package/dist/tools/uploads.d.ts.map +1 -0
  337. package/dist/tools/uploads.js +165 -0
  338. package/dist/tools/uploads.js.map +1 -0
  339. package/dist/tools/works.d.ts +71 -0
  340. package/dist/tools/works.d.ts.map +1 -0
  341. package/dist/tools/works.js +694 -0
  342. package/dist/tools/works.js.map +1 -0
  343. package/package.json +54 -0
  344. package/scripts/build-required-schemas.ts +233 -0
  345. package/scripts/bundle-apps.ts +61 -0
  346. package/scripts/refresh-schema-mirror.ts +182 -0
  347. package/server.json +20 -0
@@ -0,0 +1,245 @@
1
+ // Copyright (c) 2024-2026 Withpica Ltd. All rights reserved.
2
+ /**
3
+ * Storage Configuration Tools — ADR-217 Primitives B + C.
4
+ *
5
+ * `pica_storage_status` (Primitive A) lives in `settings.ts` (ADR-184/189
6
+ * settings cluster — kept there to avoid churn). This file owns the two
7
+ * mutating verbs:
8
+ *
9
+ * B — `pica_storage_configure_start` — mints a JWT-bound URL pointing at
10
+ * `/storage/configure/<token>` where the user pastes credentials. Same
11
+ * JWT-URL pattern as ADR-208 P2 upload + ADR-211 P1 signup.
12
+ *
13
+ * C — `pica_storage_disconnect` — reverts org back to PICA-managed default.
14
+ * Destructive (future uploads route differently); two-step confirmation
15
+ * handled by the destructive-tool gate in index.ts via
16
+ * `risk: "destructive"` in metadata.ts. Does NOT delete files in the
17
+ * BYOC bucket; only removes the org's pointer (idempotent).
18
+ *
19
+ * Both tools call public backend endpoints to mint / mutate; the
20
+ * `STORAGE_CONFIG_TOKEN_SECRET` never leaves the backend so customer-
21
+ * distributed binaries (`npx @withpica/mcp-server`) cannot mint tokens
22
+ * locally.
23
+ */
24
+ import { randomUUID } from "node:crypto";
25
+ import { clientSupportsUrlElicitation } from "@withpica/mcp-utils";
26
+ const VALID_PROVIDERS = ["s3", "gcs", "azure", "r2", "backblaze"];
27
+ export class StorageConfigTools {
28
+ pica;
29
+ constructor(pica) {
30
+ this.pica = pica;
31
+ }
32
+ getTools() {
33
+ return [
34
+ {
35
+ definition: {
36
+ name: "pica_storage_configure_start",
37
+ description: "Set up your own cloud storage bucket (BYOC) instead of PICA's default — " +
38
+ "supports AWS S3, Google Cloud Storage, Azure Blob, Cloudflare R2, " +
39
+ "and Backblaze B2. Mints a single-use configure link valid for 15 minutes; " +
40
+ "surface the URL to the user as a clickable resource_link. The link opens " +
41
+ "a page that collects bucket names + credentials, runs a real PUT/HEAD/DELETE " +
42
+ "test against your bucket, and only saves on success. Future uploads route " +
43
+ "to the configured bucket; existing files stay where they are. Use " +
44
+ "pica_storage_disconnect to revert to PICA default.",
45
+ workflows: "infrastructure",
46
+ inputSchema: {
47
+ type: "object",
48
+ properties: {
49
+ provider: {
50
+ type: "string",
51
+ enum: [...VALID_PROVIDERS],
52
+ description: "The storage provider you want to connect. Use pica_storage_disconnect " +
53
+ "to revert to PICA-managed (pica_s3) — that's not a valid value here.",
54
+ },
55
+ purpose: {
56
+ type: "string",
57
+ description: "Optional free-text — why the user is configuring BYOC " +
58
+ "(e.g. 'compliance requires data in eu-west-1', 'consolidate billing'). " +
59
+ "Captured for product analytics. Not surfaced to the user.",
60
+ },
61
+ },
62
+ required: ["provider"],
63
+ },
64
+ annotations: {
65
+ readOnlyHint: false,
66
+ destructiveHint: false,
67
+ },
68
+ },
69
+ executor: this.configureStart.bind(this),
70
+ },
71
+ {
72
+ definition: {
73
+ name: "pica_storage_disconnect",
74
+ description: "Revert your storage to PICA-managed default. Future uploads will route " +
75
+ "to PICA's buckets; existing files in your BYOC bucket are NOT deleted — " +
76
+ "they remain in your bucket and continue to be accessible by your URLs. " +
77
+ "Two-step destructive: the first call returns a confirmation token; the " +
78
+ "second call with the token executes. Idempotent — calling on an already-" +
79
+ "PICA-managed org is a no-op.",
80
+ workflows: "infrastructure",
81
+ inputSchema: {
82
+ type: "object",
83
+ properties: {
84
+ confirmation_token: {
85
+ type: "string",
86
+ description: "Token returned by the first call. Pass it back to confirm. " +
87
+ "If omitted, the tool returns confirmation_required + a fresh " +
88
+ "token. The destructive-tool dispatcher in tools/index.ts " +
89
+ "validates the token automatically.",
90
+ },
91
+ },
92
+ },
93
+ annotations: {
94
+ readOnlyHint: false,
95
+ destructiveHint: true,
96
+ idempotentHint: true,
97
+ },
98
+ },
99
+ executor: this.disconnect.bind(this),
100
+ },
101
+ ];
102
+ }
103
+ async configureStart(args, ctx) {
104
+ const provider = typeof args.provider === "string" ? args.provider : "";
105
+ if (!VALID_PROVIDERS.includes(provider)) {
106
+ return {
107
+ content: [
108
+ {
109
+ type: "text",
110
+ text: `provider must be one of: ${VALID_PROVIDERS.join(", ")}.`,
111
+ },
112
+ ],
113
+ isError: true,
114
+ };
115
+ }
116
+ const purpose = typeof args.purpose === "string" && args.purpose.trim().length > 0
117
+ ? args.purpose.trim()
118
+ : undefined;
119
+ // Calls the public mint endpoint. Same shape as
120
+ // pica_signup_start → /api/public/onboarding/signup-start.
121
+ let response;
122
+ try {
123
+ response = (await this.pica.request("POST", "/admin/settings/storage/configure-start", purpose ? { provider, purpose } : { provider }));
124
+ }
125
+ catch (err) {
126
+ const message = err instanceof Error ? err.message : "network error";
127
+ return {
128
+ content: [
129
+ {
130
+ type: "text",
131
+ text: `couldn't mint your configure link (${message}). check your connection and try again.`,
132
+ },
133
+ ],
134
+ isError: true,
135
+ };
136
+ }
137
+ if (!response?.url || !response?.expires_at) {
138
+ return {
139
+ content: [
140
+ {
141
+ type: "text",
142
+ text: "the configure endpoint returned an incomplete response. please try again.",
143
+ },
144
+ ],
145
+ isError: true,
146
+ };
147
+ }
148
+ const url = response.url;
149
+ const expiresAt = response.expires_at;
150
+ const textSummary = `configure link minted for ${provider}. surface this URL to the user — ` +
151
+ `they should click it to paste their bucket names and credentials. ` +
152
+ `the link expires at ${expiresAt} (15 minutes from now). after they ` +
153
+ `submit, we run a real test (PUT + HEAD + DELETE on each bucket) and ` +
154
+ `only save on success.`;
155
+ const resourceLink = {
156
+ type: "resource_link",
157
+ uri: url,
158
+ name: `Configure ${provider} storage`,
159
+ description: "Open this link to enter your bucket names and credentials. " +
160
+ "We test the connection before saving.",
161
+ mimeType: "text/html",
162
+ };
163
+ const baseContent = [
164
+ {
165
+ type: "text",
166
+ text: JSON.stringify({
167
+ text_summary: textSummary,
168
+ configure_url: url,
169
+ expires_at: expiresAt,
170
+ provider,
171
+ surface: response.surface ?? "storage-config",
172
+ }),
173
+ },
174
+ resourceLink,
175
+ ];
176
+ // Capability-gated url elicitation per
177
+ // `feedback_mcp_sdk_capability_gates_elicitation.md` — the SDK throws
178
+ // synchronously if the client doesn't advertise `elicitation.url`.
179
+ if (clientSupportsUrlElicitation(ctx?.server)) {
180
+ try {
181
+ await ctx.server.elicitInput({
182
+ mode: "url",
183
+ url,
184
+ elicitationId: `pica-storage-config-${randomUUID()}`,
185
+ message: `Open this URL to configure ${provider} storage. Expires at ${expiresAt}.`,
186
+ }, { timeout: 60_000 });
187
+ }
188
+ catch {
189
+ // user declined / cancelled / timed out — `resource_link` remains
190
+ // usable so we degrade silently rather than fail the tool.
191
+ }
192
+ }
193
+ return {
194
+ content: baseContent,
195
+ structuredContent: {
196
+ kind: "pica.card.storage_configure_start",
197
+ version: 1,
198
+ data: {
199
+ configure_url: url,
200
+ expires_at: expiresAt,
201
+ provider,
202
+ },
203
+ },
204
+ };
205
+ }
206
+ async disconnect(args, _ctx) {
207
+ // Note: the destructive-tool gate in index.ts validates
208
+ // `confirmation_token` before this executor runs. By the time we're
209
+ // here, the token has been consumed and we can perform the disconnect.
210
+ void args;
211
+ let response;
212
+ try {
213
+ response = (await this.pica.request("POST", "/admin/settings/storage/disconnect", {}));
214
+ }
215
+ catch (err) {
216
+ const message = err instanceof Error ? err.message : "network error";
217
+ return {
218
+ content: [
219
+ {
220
+ type: "text",
221
+ text: `couldn't disconnect (${message}). please try again.`,
222
+ },
223
+ ],
224
+ isError: true,
225
+ };
226
+ }
227
+ const previousProvider = response?.previous_provider ?? "unknown";
228
+ const summary = previousProvider === "pica_s3" || previousProvider === "unknown"
229
+ ? "you were already on PICA-managed storage — no change."
230
+ : `disconnected ${previousProvider}. future uploads route to PICA-managed storage. ` +
231
+ `your existing files in the ${previousProvider} bucket are not deleted.`;
232
+ return {
233
+ content: [{ type: "text", text: summary }],
234
+ structuredContent: {
235
+ kind: "pica.card.storage_disconnected",
236
+ version: 1,
237
+ data: {
238
+ previous_provider: previousProvider,
239
+ current_provider: "pica_s3",
240
+ },
241
+ },
242
+ };
243
+ }
244
+ }
245
+ //# sourceMappingURL=storage-config.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"storage-config.js","sourceRoot":"","sources":["../../src/tools/storage-config.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,60 @@
1
+ import { PicaClient, type BillingTier, type SubscriptionStatusResponse } from "@withpica/mcp-sdk";
2
+ import { ToolDefinition, ToolExecutor } from "./index.js";
3
+ interface SubscriptionStatusFlat {
4
+ billing_state: "trial" | "active" | "hibernated";
5
+ trial_days_remaining: number | null;
6
+ trial_ends_at: string | null;
7
+ current_tier: BillingTier | null;
8
+ capacity_used: number;
9
+ capacity_limit: number | null;
10
+ capacity_pct: number;
11
+ recommended_tier: BillingTier | null;
12
+ summary: string;
13
+ }
14
+ /**
15
+ * Compose the flat 9-field response from the existing GET admin route's
16
+ * shape. Mirrors `getOrgBillingSlice`'s "no meaningful cap" rule for
17
+ * `capacity_pct` (0 whenever current_tier is null OR enterprise) and
18
+ * carries through `overflow.recommendedTier` (already
19
+ * `inferTierFromCount`-derived) per Stage 1 Q2.
20
+ *
21
+ * Exported for unit tests.
22
+ */
23
+ export declare function flattenStatus(status: SubscriptionStatusResponse): SubscriptionStatusFlat;
24
+ /**
25
+ * Server-side template per Stage 1 Q1 option A. Predictable wording,
26
+ * less variance across connectors. Phase 2.5 may add agent
27
+ * paraphrasing if telemetry shows demand.
28
+ *
29
+ * Exported for unit tests.
30
+ */
31
+ export declare function composeSummary(fields: {
32
+ billing_state: "trial" | "active" | "hibernated";
33
+ trial_days_remaining: number | null;
34
+ current_tier: BillingTier | null;
35
+ capacity_used: number;
36
+ capacity_limit: number | null;
37
+ recommended_tier: BillingTier | null;
38
+ }): string;
39
+ export declare class SubscriptionTools {
40
+ private pica;
41
+ constructor(pica: PicaClient);
42
+ getTools(): Array<{
43
+ definition: ToolDefinition;
44
+ executor: ToolExecutor;
45
+ }>;
46
+ private status;
47
+ private manage;
48
+ /**
49
+ * Universal-floor return per ADR-200 Phase 1: every successful manage
50
+ * response carries a `resource_link` so any compliant MCP client can
51
+ * render or open the URL. Clients that advertise
52
+ * `capabilities.elicitation.url` additionally receive a server-issued
53
+ * elicitation/create request — the gate is mandatory because
54
+ * `elicitInput` with `mode: "url"` throws synchronously against
55
+ * non-supporters (`feedback_mcp_sdk_capability_gates_elicitation.md`).
56
+ */
57
+ private buildLinkResult;
58
+ }
59
+ export {};
60
+ //# sourceMappingURL=subscription.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"subscription.d.ts","sourceRoot":"","sources":["../../src/tools/subscription.ts"],"names":[],"mappings":"AA8BA,OAAO,EACL,UAAU,EACV,KAAK,WAAW,EAChB,KAAK,0BAA0B,EAChC,MAAM,mBAAmB,CAAC;AAE3B,OAAO,EACL,cAAc,EACd,YAAY,EAGb,MAAM,YAAY,CAAC;AAoBpB,UAAU,sBAAsB;IAC9B,aAAa,EAAE,OAAO,GAAG,QAAQ,GAAG,YAAY,CAAC;IACjD,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,YAAY,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,WAAW,GAAG,IAAI,CAAC;IACrC,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,MAAM,EAAE,0BAA0B,GACjC,sBAAsB,CA+CxB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE;IACrC,aAAa,EAAE,OAAO,GAAG,QAAQ,GAAG,YAAY,CAAC;IACjD,oBAAoB,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,YAAY,EAAE,WAAW,GAAG,IAAI,CAAC;IACjC,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,gBAAgB,EAAE,WAAW,GAAG,IAAI,CAAC;CACtC,GAAG,MAAM,CA6CT;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,IAAI,CAAa;gBAEb,IAAI,EAAE,UAAU;IAI5B,QAAQ,IAAI,KAAK,CAAC;QAAE,UAAU,EAAE,cAAc,CAAC;QAAC,QAAQ,EAAE,YAAY,CAAA;KAAE,CAAC;YAmF3D,MAAM;YAkCN,MAAM;IA4JpB;;;;;;;;OAQG;YACW,eAAe;CA2D9B"}