@classytic/arc 2.45.2 → 2.46.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 (321) hide show
  1. package/README.md +1 -1
  2. package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
  3. package/dist/{EventTransport-DHb1tpu-.mjs → EventTransport-DNgD9NP4.mjs} +3 -4
  4. package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-DRbPzEcP.mjs} +3 -4
  5. package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
  6. package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-Douk51fa.mjs} +15 -4
  7. package/dist/{acquire-DTkA8Lme.mjs → acquire-RbtvDg9s.mjs} +2 -3
  8. package/dist/{actionPermissions-DRVk6m7x.mjs → actionPermissions-De0AJ7hm.mjs} +37 -42
  9. package/dist/audit/index.d.mts +2 -10
  10. package/dist/audit/index.mjs +8 -12
  11. package/dist/auth/audit.d.mts +0 -2
  12. package/dist/auth/audit.mjs +2 -3
  13. package/dist/auth/index.d.mts +9 -17
  14. package/dist/auth/index.mjs +26 -29
  15. package/dist/auth/redis-session.d.mts +2 -4
  16. package/dist/auth/redis-session.mjs +2 -3
  17. package/dist/{authorizationDecision-D48fUJv1.mjs → authorizationDecision-DeZMrHcm.mjs} +5 -6
  18. package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
  19. package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-2WBh3gM9.mjs} +2 -3
  20. package/dist/{buildHandler-BiZ4VATS.mjs → buildHandler-DxVOOBpw.mjs} +5 -6
  21. package/dist/cache/index.d.mts +4 -10
  22. package/dist/cache/index.mjs +5 -6
  23. package/dist/{caching-Cj0as-P1.mjs → caching-BYRwYrUo.mjs} +3 -4
  24. package/dist/{claimed-ChI13rUR.mjs → claimed-DYlELdnm.mjs} +2 -3
  25. package/dist/cleanup/index.d.mts +4 -18
  26. package/dist/cleanup/index.mjs +12 -20
  27. package/dist/cli/commands/describe.d.mts +1 -3
  28. package/dist/cli/commands/describe.mjs +4 -5
  29. package/dist/cli/commands/docs.d.mts +1 -3
  30. package/dist/cli/commands/docs.mjs +4 -5
  31. package/dist/cli/commands/doctor.d.mts +1 -3
  32. package/dist/cli/commands/doctor.mjs +2 -3
  33. package/dist/cli/commands/generate.d.mts +1 -1
  34. package/dist/cli/commands/generate.mjs +2 -2
  35. package/dist/cli/commands/init.d.mts +1 -1
  36. package/dist/cli/commands/init.mjs +2 -2
  37. package/dist/cli/commands/introspect.d.mts +1 -3
  38. package/dist/cli/commands/introspect.mjs +3 -4
  39. package/dist/cli/index.d.mts +2 -2
  40. package/dist/cli/index.mjs +3 -3
  41. package/dist/{constants-D_aiew34.mjs → constants-CHZMUwBW.mjs} +2 -3
  42. package/dist/context/index.d.mts +0 -8
  43. package/dist/context/index.mjs +6 -7
  44. package/dist/core/index.d.mts +3 -3
  45. package/dist/core/index.mjs +8 -8
  46. package/dist/{core-QIZ2560Y.mjs → core-D9rS2BxO.mjs} +9 -12
  47. package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-0qkCRzTL.mjs} +7 -8
  48. package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-CUf5Esd9.mjs} +9 -10
  49. package/dist/{createApp-CKjZpmq9.mjs → createApp-DZIXfDKD.mjs} +49 -62
  50. package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DeVpqQF-.d.mts} +1 -3
  51. package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-bmKQ4NmC.mjs} +2 -3
  52. package/dist/{defineResource-CEo0gDCb.mjs → defineResource-CGmdmGwh.mjs} +78 -29
  53. package/dist/discovery/index.d.mts +1 -3
  54. package/dist/discovery/index.mjs +2 -3
  55. package/dist/docs/index.d.mts +8 -8
  56. package/dist/docs/index.mjs +4 -5
  57. package/dist/{elevation-BJTsSnke.mjs → elevation-CzhqAyVN.mjs} +9 -10
  58. package/dist/{elevation-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
  59. package/dist/encryption/index.d.mts +1 -7
  60. package/dist/encryption/index.mjs +8 -13
  61. package/dist/{errorHandler--4rSMMvq.d.mts → errorHandler-B9r88jZV.d.mts} +8 -3
  62. package/dist/{errorHandler-2p4SL5zm.mjs → errorHandler-dFyGOEoB.mjs} +16 -6
  63. package/dist/{errors-grZkIA8N.mjs → errors-BY8vzlP4.mjs} +2 -3
  64. package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
  65. package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
  66. package/dist/{eventPlugin-ItcYBGUs.mjs → eventPlugin-eMhAPtQA.mjs} +10 -12
  67. package/dist/{eventTypes-Ck6fD3ne.mjs → eventTypes-Do2KYeJx.mjs} +5 -8
  68. package/dist/events/index.d.mts +4 -16
  69. package/dist/events/index.mjs +8 -9
  70. package/dist/events/transports/redis-stream-entry.d.mts +1 -1
  71. package/dist/events/transports/redis-stream-entry.mjs +5 -6
  72. package/dist/events/transports/redis.d.mts +2 -4
  73. package/dist/events/transports/redis.mjs +3 -4
  74. package/dist/{externalPaths-CmGOxOtD.d.mts → externalPaths-BOqdq5wr.d.mts} +0 -2
  75. package/dist/factory/index.d.mts +4 -14
  76. package/dist/factory/index.mjs +12 -18
  77. package/dist/{fastify-augmentation-DRlCIWE9.d.mts → fastify-augmentation-Dtn0IIRn.d.mts} +4 -10
  78. package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
  79. package/dist/{fields-BRX0Krcj.mjs → fields-LnbCcvsw.mjs} +2 -3
  80. package/dist/{filter-merge-CDc7YMwX.mjs → filter-merge-BAWi019Q.mjs} +2 -3
  81. package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
  82. package/dist/{generate-hvg7V2g1.mjs → generate-oXoDnpJf.mjs} +7 -12
  83. package/dist/{headers-Cqkg4LzI.mjs → headers-DBd3Qheo.mjs} +3 -4
  84. package/dist/{health-PVt0VjOx.mjs → health-BlJu9GXS.mjs} +2 -3
  85. package/dist/{health-DyeP3mTW.mjs → health-Dp-3EC9o.mjs} +4 -7
  86. package/dist/hooks/index.d.mts +1 -1
  87. package/dist/hooks/index.mjs +2 -2
  88. package/dist/idempotency/index.d.mts +3 -9
  89. package/dist/idempotency/index.mjs +10 -13
  90. package/dist/idempotency/redis.d.mts +1 -1
  91. package/dist/idempotency/redis.mjs +3 -4
  92. package/dist/{index-Bxriq3so.d.mts → index-B5i9-vuP.d.mts} +4 -26
  93. package/dist/{index-Chgz3d0i.d.mts → index-BAXDo5eE.d.mts} +1 -7
  94. package/dist/{index-Beg3aNnK.d.mts → index-BTxzJ_MN.d.mts} +67 -25
  95. package/dist/{index-CUJvoyw3.d.mts → index-Bqfo8hLz.d.mts} +2 -24
  96. package/dist/{index-uhkUA5-U.d.mts → index-CUdaoCYt.d.mts} +13 -23
  97. package/dist/{index-WH7xgvxS.d.mts → index-DyJFTJLA.d.mts} +31 -92
  98. package/dist/index.d.mts +7 -9
  99. package/dist/index.mjs +12 -13
  100. package/dist/{init-jC3rMPzb.mjs → init-BOaNkLYb.mjs} +18 -35
  101. package/dist/{init-Cscs4lab.d.mts → init-CV2_Fw3H.d.mts} +0 -4
  102. package/dist/integrations/event-gateway.d.mts +3 -5
  103. package/dist/integrations/event-gateway.mjs +3 -4
  104. package/dist/integrations/index.d.mts +3 -3
  105. package/dist/integrations/index.mjs +1 -1
  106. package/dist/integrations/jobs/index.d.mts +1 -1
  107. package/dist/integrations/jobs/index.mjs +7 -11
  108. package/dist/integrations/mcp/index.d.mts +7 -39
  109. package/dist/integrations/mcp/index.mjs +8 -14
  110. package/dist/integrations/mcp/testing.d.mts +3 -5
  111. package/dist/integrations/mcp/testing.mjs +3 -4
  112. package/dist/integrations/streamline.d.mts +1 -3
  113. package/dist/integrations/streamline.mjs +4 -5
  114. package/dist/integrations/webhooks.d.mts +2 -4
  115. package/dist/integrations/webhooks.mjs +4 -5
  116. package/dist/integrations/websocket-pushref-redis.d.mts +2 -4
  117. package/dist/integrations/websocket-pushref-redis.mjs +2 -3
  118. package/dist/integrations/websocket-redis.d.mts +2 -4
  119. package/dist/integrations/websocket-redis.mjs +2 -3
  120. package/dist/integrations/websocket.d.mts +2 -2
  121. package/dist/integrations/websocket.mjs +13 -24
  122. package/dist/{interface-JJzwH4Ro.d.mts → interface-BmExzQRD.d.mts} +0 -2
  123. package/dist/{interface-BOk3YnTz.d.mts → interface-WR1U0K7t.d.mts} +0 -2
  124. package/dist/{jsonBody-ptwyzZQ-.mjs → jsonBody-DpRpKR_K.mjs} +3 -4
  125. package/dist/{keys-C1vFuSbv.mjs → keys-FBz6Ull-.mjs} +2 -3
  126. package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Bx1sKPnF.mjs} +4 -5
  127. package/dist/{loadResourcesFromEntry-BkHHTu_B.mjs → loadResourcesFromEntry-b_jcqbxh.mjs} +3 -4
  128. package/dist/logger/index.d.mts +1 -3
  129. package/dist/logger/index.mjs +2 -2
  130. package/dist/{logger-C5bvCiAK.mjs → logger-CbFcIEBZ.mjs} +3 -5
  131. package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-yix548XX.mjs} +41 -60
  132. package/dist/{memory-CxiTwT0j.mjs → memory-Bgw5dn8N.mjs} +4 -5
  133. package/dist/{metrics-Ckp2zRy-.mjs → metrics-CZDQWVjS.mjs} +4 -5
  134. package/dist/middleware/index.d.mts +1 -5
  135. package/dist/middleware/index.mjs +4 -5
  136. package/dist/migrations/index.d.mts +0 -2
  137. package/dist/migrations/index.mjs +3 -4
  138. package/dist/{module-CfnKuIuH.mjs → module-Dsc_nKL5.mjs} +2 -3
  139. package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-XCxAUlru.d.mts} +1 -5
  140. package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-B85ek8Kj.mjs} +2 -3
  141. package/dist/observeSend-BK-JN1jK.mjs +20 -0
  142. package/dist/{openapi-DAPxjYHX.mjs → openapi-Co7hl073.mjs} +18 -28
  143. package/dist/outbox-admin/index.d.mts +2 -4
  144. package/dist/outbox-admin/index.mjs +6 -7
  145. package/dist/{outbox-module-gZCHoE4H.d.mts → outbox-module-XvUThpqn.d.mts} +2 -8
  146. package/dist/{outbox-module-B4FAkx3A.mjs → outbox-module-mg9kDYkd.mjs} +13 -17
  147. package/dist/permissions/index.d.mts +4 -4
  148. package/dist/permissions/index.mjs +7 -7
  149. package/dist/{permissions-B14c3OMp.mjs → permissions-A1oKtpiC.mjs} +19 -29
  150. package/dist/{pipe-CQv7PsAK.mjs → pipe-Czpw9U2n.mjs} +3 -4
  151. package/dist/pipeline/index.d.mts +1 -9
  152. package/dist/pipeline/index.mjs +5 -8
  153. package/dist/{plan-CpnTykjb.mjs → plan-KVseuBCL.mjs} +5 -9
  154. package/dist/{plugin-DXTjVg_Q.mjs → plugin-DTWt_8C3.mjs} +130 -62
  155. package/dist/plugins/index.d.mts +8 -16
  156. package/dist/plugins/index.mjs +22 -26
  157. package/dist/plugins/response-cache.d.mts +2 -4
  158. package/dist/plugins/response-cache.mjs +10 -10
  159. package/dist/plugins/tracing-entry.d.mts +1 -1
  160. package/dist/plugins/tracing-entry.mjs +3 -4
  161. package/dist/{pluralize-C3VJKRGp.mjs → pluralize-msB9X3yw.mjs} +2 -3
  162. package/dist/presets/filesUpload.d.mts +4 -6
  163. package/dist/presets/filesUpload.mjs +6 -7
  164. package/dist/presets/index.d.mts +3 -19
  165. package/dist/presets/index.mjs +2 -2
  166. package/dist/presets/multiTenant.d.mts +1 -1
  167. package/dist/presets/multiTenant.mjs +7 -7
  168. package/dist/presets/search.d.mts +3 -5
  169. package/dist/presets/search.mjs +3 -4
  170. package/dist/{presets-CquqYJPy.mjs → presets-qKCehiJM.mjs} +11 -18
  171. package/dist/{projection-CgfSLOSM.mjs → projection-ClBqtsIw.mjs} +3 -4
  172. package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
  173. package/dist/{queryCachePlugin-D0HUISHJ.mjs → queryCachePlugin-3gJj5Rbz.mjs} +8 -10
  174. package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
  175. package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-Kro---xl.mjs} +2 -3
  176. package/dist/{realtime-CbWtVbqK.mjs → realtime-Ber8uJN2.mjs} +17 -19
  177. package/dist/{redis-BDgv9Glw.d.mts → redis-RpDMemdm.d.mts} +2 -4
  178. package/dist/{redis-stream-BMk-bpQS.d.mts → redis-stream-CS1N9dwM.d.mts} +1 -3
  179. package/dist/{redisShapes-CQksY67q.d.mts → redisShapes-CqBXTn_s.d.mts} +0 -2
  180. package/dist/registry/index.d.mts +2 -12
  181. package/dist/registry/index.mjs +3 -3
  182. package/dist/{registry-BVwpAuFI.mjs → registry-BA-_vFYk.mjs} +7 -12
  183. package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CMY8YOcc.mjs} +2 -3
  184. package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-DK9P_XSz.mjs} +3 -4
  185. package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-GYO_0gEw.mjs} +2 -3
  186. package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
  187. package/dist/{requirement-Cp_fsMDL.mjs → requirement-DeNjZIH3.mjs} +2 -3
  188. package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
  189. package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-tHLbrtWc.mjs} +3 -4
  190. package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-Kv1fZdLg.mjs} +2 -3
  191. package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-C_H5NanI.mjs} +2 -3
  192. package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-DWqbxkyw.mjs} +2 -3
  193. package/dist/{schedules-B693KXxa.mjs → schedules-eO_RzhCU.mjs} +132 -9
  194. package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DBJrPZN4.mjs} +3 -4
  195. package/dist/{schemaIR-REV2y7Wd.mjs → schemaIR-CEScKT2v.mjs} +3 -4
  196. package/dist/schemas/index.d.mts +0 -2
  197. package/dist/schemas/index.mjs +2 -3
  198. package/dist/scim/index.d.mts +0 -12
  199. package/dist/scim/index.mjs +10 -18
  200. package/dist/scope/index.d.mts +2 -6
  201. package/dist/scope/index.mjs +5 -5
  202. package/dist/{scope-Bevxy_ST.mjs → scope-B-Sm9m_E.mjs} +5 -6
  203. package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
  204. package/dist/{shutdown-CfrqPR7A.mjs → shutdown-DzLFbe27.mjs} +2 -3
  205. package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DOJhwQ8g.mjs} +2 -3
  206. package/dist/{sse-CuNNWr2z.mjs → sse-2972pVwV.mjs} +8 -9
  207. package/dist/{sseStream-C_2ujAVY.mjs → sseStream-AWLEeNV-.mjs} +3 -4
  208. package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
  209. package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-VzjgVTkM.mjs} +2 -3
  210. package/dist/{streaming-Bdq_M4d5.mjs → streaming-DvraWW6x.mjs} +2 -3
  211. package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-Bya56jsg.mjs} +2 -3
  212. package/dist/{tenancy-C5PCvm1h.mjs → tenancy-DSa_0hhw.mjs} +3 -4
  213. package/dist/{tenantPreparation-dYvWrgNa.mjs → tenantPreparation-BrpkQre3.mjs} +5 -6
  214. package/dist/testing/cleanupStoreContract.d.mts +2 -4
  215. package/dist/testing/cleanupStoreContract.mjs +2 -3
  216. package/dist/testing/index.d.mts +6 -32
  217. package/dist/testing/index.mjs +24 -37
  218. package/dist/testing/outboxStoreContract.d.mts +1 -3
  219. package/dist/testing/outboxStoreContract.mjs +3 -4
  220. package/dist/testing/requiredPorts.d.mts +2 -4
  221. package/dist/testing/requiredPorts.mjs +3 -4
  222. package/dist/testing/storageContract.d.mts +2 -4
  223. package/dist/testing/storageContract.mjs +2 -3
  224. package/dist/{timing-DCqsezX8.mjs → timing-6rQTuCwg.mjs} +3 -5
  225. package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
  226. package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-DaxYUEgH.mjs} +2 -3
  227. package/dist/{typeGuards-CEl10KPy.mjs → typeGuards-UKnX8wPX.mjs} +2 -3
  228. package/dist/types/index.d.mts +4 -4
  229. package/dist/types/index.mjs +1 -1
  230. package/dist/types/storage.d.mts +1 -1
  231. package/dist/types/storage.mjs +1 -1
  232. package/dist/{types-ByHn9rEO.d.mts → types-0Dqlbgn8.d.mts} +0 -2
  233. package/dist/{types-D3Ixsh00.d.mts → types-BYEb_dLW.d.mts} +2 -4
  234. package/dist/{types-BJ-2XqVF.d.mts → types-BeEJm-DV.d.mts} +114 -14
  235. package/dist/{types-DVLddu2q.d.mts → types-C0YJAiL0.d.mts} +0 -2
  236. package/dist/{types-D9NWjpYc.mjs → types-CuGjhn83.mjs} +5 -6
  237. package/dist/{types-Ddl9OjmE.d.mts → types-DnkIALZ8.d.mts} +0 -4
  238. package/dist/usage/index.d.mts +2 -10
  239. package/dist/usage/index.mjs +8 -12
  240. package/dist/{userHelpers-BHig1kHq.mjs → userHelpers-oX5_mOVs.mjs} +2 -3
  241. package/dist/utils/index.d.mts +5 -39
  242. package/dist/utils/index.mjs +12 -12
  243. package/dist/{utils-BG5P7_Vb.mjs → utils-CjjGOT4E.mjs} +20 -30
  244. package/dist/{validate-D_mdOCir.mjs → validate-4RlTKOJb.mjs} +5 -7
  245. package/dist/{versioning-DBGHjPh7.mjs → versioning-Dk2-19La.mjs} +4 -5
  246. package/dist/{versioning-Bqm_57Qt.d.mts → versioning-S18y2-0C.d.mts} +1 -15
  247. package/dist/{websocket-Cs4awVyD.d.mts → websocket-BGuc-WVZ.d.mts} +1 -15
  248. package/dist/{workScope-DPPfM4m6.mjs → workScope-DoBsoVo4.mjs} +3 -4
  249. package/llms.txt +37 -30
  250. package/package.json +9 -8
  251. package/skills/arc/SKILL.md +65 -844
  252. package/skills/arc/references/agent-auth.md +82 -193
  253. package/skills/arc/references/api-reference.md +41 -245
  254. package/skills/arc/references/auth-api-keys.md +99 -0
  255. package/skills/arc/references/auth-better-auth-overlay.md +87 -0
  256. package/skills/arc/references/auth-better-auth.md +78 -0
  257. package/skills/arc/references/auth-permissions.md +100 -0
  258. package/skills/arc/references/auth-strategies.md +122 -0
  259. package/skills/arc/references/boot.md +80 -0
  260. package/skills/arc/references/enterprise-auth.md +65 -81
  261. package/skills/arc/references/events-outbox.md +90 -0
  262. package/skills/arc/references/events.md +75 -440
  263. package/skills/arc/references/integrations-jobs.md +74 -0
  264. package/skills/arc/references/integrations-realtime.md +84 -0
  265. package/skills/arc/references/integrations-webhooks.md +71 -0
  266. package/skills/arc/references/integrations-workflows.md +47 -0
  267. package/skills/arc/references/mcp-auth.md +83 -0
  268. package/skills/arc/references/mcp-custom-tools.md +125 -0
  269. package/skills/arc/references/mcp-setup.md +115 -0
  270. package/skills/arc/references/mcp-testing.md +63 -0
  271. package/skills/arc/references/multi-tenancy.md +56 -230
  272. package/skills/arc/references/permissions-scope.md +81 -0
  273. package/skills/arc/references/production-api.md +119 -0
  274. package/skills/arc/references/production-audit.md +101 -0
  275. package/skills/arc/references/production-boot.md +91 -0
  276. package/skills/arc/references/production-caching.md +63 -0
  277. package/skills/arc/references/production-distributed.md +75 -0
  278. package/skills/arc/references/production-idempotency.md +83 -0
  279. package/skills/arc/references/production-observability.md +83 -0
  280. package/skills/arc/references/production-realtime.md +70 -0
  281. package/skills/arc/references/production-reliability.md +100 -0
  282. package/skills/arc/references/production-shutdown.md +43 -0
  283. package/skills/arc/references/querying.md +76 -0
  284. package/skills/arc/references/resources.md +97 -0
  285. package/skills/arc/references/schedules.md +79 -0
  286. package/skills/arc/references/scim.md +61 -208
  287. package/skills/arc/references/tenancy-scope-install.md +82 -0
  288. package/skills/arc/references/testing.md +101 -144
  289. package/skills/arc/references/usage-cleanup-capabilities.md +45 -0
  290. package/skills/arc/references/validation.md +91 -0
  291. package/skills/arc/references/writes-hooks-errors.md +80 -0
  292. package/skills/arc-code-review/SKILL.md +67 -114
  293. package/skills/arc-code-review/references/arc-cheatsheet.md +68 -167
  294. package/skills/arc-code-review/references/mongokit-repositories.md +104 -0
  295. package/skills/arc-code-review/references/recipe-events-cache-jobs.md +112 -0
  296. package/skills/arc-code-review/references/recipe-resource.md +100 -0
  297. package/skills/arc-code-review/references/recipe-schemas-fields.md +93 -0
  298. package/skills/arc-code-review/references/recipe-scope-permissions.md +82 -0
  299. package/skills/arc-code-review/references/scaffolding.md +61 -198
  300. package/skills/arc-code-review/references/severity.md +49 -102
  301. package/skills/arc-code-review/references/smells-auth-scope.md +80 -0
  302. package/skills/arc-code-review/references/smells-data-events.md +66 -0
  303. package/skills/arc-code-review/references/smells-imports-style.md +59 -0
  304. package/skills/arc-code-review/references/smells-platform.md +89 -0
  305. package/skills/arc-code-review/references/smells-routes-schemas.md +66 -0
  306. package/skills/arc-module-publishing/SKILL.md +82 -208
  307. package/skills/arc-module-publishing/references/action-presets-and-plugins.md +87 -0
  308. package/skills/arc-module-publishing/references/build-and-types.md +73 -0
  309. package/skills/arc-module-publishing/references/module-lifecycle.md +101 -0
  310. package/skills/arc-module-publishing/references/package-manifest.md +34 -122
  311. package/skills/arc-module-publishing/references/publishing-workflow.md +44 -140
  312. package/skills/arc-module-publishing/references/resource-assembly.md +102 -0
  313. package/skills/arc-module-publishing/references/testing-packages.md +82 -0
  314. package/skills/arc/references/auth.md +0 -729
  315. package/skills/arc/references/integrations.md +0 -452
  316. package/skills/arc/references/mcp.md +0 -691
  317. package/skills/arc/references/production.md +0 -835
  318. package/skills/arc-code-review/references/anti-patterns.md +0 -1008
  319. package/skills/arc-code-review/references/migration-recipes.md +0 -649
  320. package/skills/arc-code-review/references/mongokit-migration.md +0 -360
  321. package/skills/arc-module-publishing/references/authoring-modules.md +0 -327
@@ -1,691 +0,0 @@
1
- # Arc MCP Integration
2
-
3
- Expose Arc resources as MCP tools for AI agents. Two levels: zero-config auto-generation or fully custom tool definitions.
4
-
5
- **Requires:** `@modelcontextprotocol/sdk` (peer dep), `zod` (peer dep)
6
-
7
- ```bash
8
- npm install @modelcontextprotocol/sdk zod
9
- ```
10
-
11
- ## Level 1 — Auto-Generate from Resources
12
-
13
- ```typescript
14
- import { mcpPlugin } from '@classytic/arc/mcp';
15
- import { createApp, loadResources } from '@classytic/arc/factory';
16
-
17
- // Option A: Explicit resources
18
- const app = await createApp({
19
- resources: [productResource, taskResource],
20
- auth: false,
21
- plugins: async (f) => {
22
- await f.register(mcpPlugin, { resources: [productResource, taskResource], auth: false });
23
- },
24
- });
25
-
26
- // Option B: Auto-discover from directory
27
- const resources = await loadResources('./src/resources');
28
- const app = await createApp({
29
- resources,
30
- plugins: async (f) => {
31
- await f.register(mcpPlugin, { resources, auth: false });
32
- },
33
- });
34
- ```
35
-
36
- Per-resource overrides:
37
-
38
- ```typescript
39
- await app.register(mcpPlugin, {
40
- resources,
41
- auth: false,
42
- include: ['product', 'order'], // only these get MCP tools
43
- overrides: { product: { operations: ['list', 'get'] } },
44
- });
45
- ```
46
-
47
- Per resource, generates up to 5 tools: `list_{plural}`, `get_{name}`, `create_{name}`, `update_{name}`, `delete_{name}`.
48
-
49
- Resource `actions` (v2.8) also auto-generate MCP tools — each action becomes a tool named `{action}_{name}` with the action's input schema.
50
-
51
- Tool handlers call `BaseController` — same pipeline as REST (auth, org-scoping, hooks, field permissions, cache).
52
-
53
- **Query params on generated tools (2.20):** `list_*` accepts `page`/`limit` (offset) **and** `cursor` (keyset, stable under concurrent inserts — when set, `page` is ignored), plus `sort`/`search`/`select`/`populate`. `get_*` accepts `select` for field projection alongside `id`. Both mirror REST exactly (same `QueryResolver`).
54
-
55
- ### McpPluginOptions
56
-
57
- | Option | Type | Default | Description |
58
- |--------|------|---------|-------------|
59
- | `resources` | `ResourceDefinition[]` | required | Resources to expose |
60
- | `auth` | `BetterAuthHandler \| McpAuthResolver \| false` | `false` | Auth mode (see Auth section) |
61
- | `prefix` | `string` | `'/mcp'` | MCP endpoint path |
62
- | `serverName` | `string` | `'arc-mcp'` | Server identity |
63
- | `serverVersion` | `string` | `'1.0.0'` | Server version |
64
- | `instructions` | `string` | — | LLM guidance on tool usage |
65
- | `include` | `string[]` | — | Only these resources get tools (overrides `exclude`) |
66
- | `exclude` | `string[]` | — | Resource names to exclude |
67
- | `toolNamePrefix` | `string` | — | Global prefix: `'crm'` → `crm_list_products` |
68
- | `overrides` | `Record<string, McpResourceConfig>` | — | Per-resource overrides (see below) |
69
- | `authCacheTtlMs` | `number` | — | Cache auth results for N ms in stateless mode |
70
- | `extraTools` | `ToolDefinition[]` | — | Hand-written tools alongside auto-generated |
71
- | `extraPrompts` | `PromptDefinition[]` | — | Custom prompts |
72
- | `stateful` | `boolean` | `false` | `false` = stateless (default, scalable). `true` = session-cached. |
73
- | `sessionTtlMs` | `number` | `1800000` | Session TTL (stateful only) |
74
- | `maxSessions` | `number` | `1000` | Max concurrent sessions (stateful only) |
75
-
76
- ### Tool Annotations (auto-set)
77
-
78
- | Operation | Annotations |
79
- |-----------|-------------|
80
- | `list`, `get` | `readOnlyHint: true` |
81
- | `create` | `destructiveHint: false` |
82
- | `update`, `delete` | `destructiveHint: true, idempotentHint: true` |
83
-
84
- ### Per-Resource Overrides
85
-
86
- ```typescript
87
- await app.register(mcpPlugin, {
88
- resources,
89
- include: ['job', 'project'], // only expose these
90
- overrides: {
91
- job: {
92
- operations: ['list', 'get'], // restrict ops
93
- toolNamePrefix: 'db', // db_list_jobs, db_get_job
94
- names: { get: 'get_job_by_id' }, // custom name for specific op
95
- hideFields: ['internalScore'], // strip from schema
96
- descriptions: { list: 'Browse jobs' }, // custom descriptions
97
- },
98
- },
99
- });
100
- ```
101
-
102
- ### Permission Filters (v2.4.2)
103
-
104
- Resource permissions that return a row `policy` are automatically enforced in MCP tools — same as REST:
105
-
106
- ```typescript
107
- import { allow, deny } from '@classytic/arc/permissions';
108
-
109
- defineResource({
110
- name: 'task',
111
- permissions: {
112
- list: (ctx) =>
113
- ctx.user
114
- ? allow({ policy: { orgId: ctx.user.orgId, branchId: ctx.user.branchId } })
115
- : deny('Auth required'),
116
- create: (ctx) => !!ctx.user, // boolean works too
117
- delete: () => deny('Read-only'),
118
- },
119
- });
120
-
121
- // MCP tools automatically:
122
- // - list_tasks scopes by orgId + branchId from permission filters
123
- // - create_task allowed if user is authenticated
124
- // - delete_task returns "Permission denied: delete on task"
125
- ```
126
-
127
- No extra config. `PermissionResult.filters` flow into `_policyFilters` → `BaseController.AccessControl`.
128
-
129
- ### Multiple MCP Endpoints
130
-
131
- Mount separate servers scoped to different resource groups:
132
-
133
- ```typescript
134
- await app.register(mcpPlugin, { resources: catalogResources, prefix: '/mcp/catalog' });
135
- await app.register(mcpPlugin, { resources: orderResources, prefix: '/mcp/orders' });
136
- ```
137
-
138
- ## DNS-rebinding protection (`Host` / `Origin`)
139
-
140
- An MCP endpoint on loopback is reachable from any page the developer visits: if
141
- an attacker-controlled DNS name resolves to `127.0.0.1`, the browser treats the
142
- reply as same-origin and can read every tool's output. Validating `Host` breaks
143
- the chain.
144
-
145
- `dnsRebindingProtection` **defaults on when `auth: false`** (the local shape the
146
- attack targets) and **off when auth is configured** (a real deployment's `Host`
147
- is its own domain — defaulting on would 403 it; credentials are the gate there).
148
-
149
- ```typescript
150
- mcpPlugin({ resources, auth, dnsRebindingProtection: {} }); // localhost + auth
151
- mcpPlugin({ resources, dnsRebindingProtection: { allowedHosts: ['mcp.example.com'] } });
152
- mcpPlugin({ resources, auth: false, dnsRebindingProtection: false }); // deliberately public
153
- ```
154
-
155
- An absent `Origin` passes — non-browser MCP clients send none. A present but
156
- unlisted one is refused. `${prefix}/health` is exempt so probes keep working.
157
-
158
- ## Auth — Three Modes
159
-
160
- Arc doesn't enforce an auth strategy. You choose what fits.
161
-
162
- ### 1. No Auth (dev/testing/stdio)
163
-
164
- ```typescript
165
- await app.register(mcpPlugin, { resources, auth: false });
166
- ```
167
-
168
- All tools open. `ctx.user` is `null`, `scope.kind` is `"public"`. Permission guards like `!!ctx.user` correctly block — anonymous callers cannot bypass auth checks.
169
-
170
- ### 2. Better Auth OAuth 2.1 (production SaaS)
171
-
172
- Full MCP spec-compliant OAuth 2.1: authorization code + PKCE, token exchange, dynamic client registration.
173
-
174
- ```typescript
175
- // auth.config.ts — add mcp() plugin to Better Auth
176
- import { mcp } from 'better-auth/plugins/mcp'; // dedicated path — tree-shaking
177
- betterAuth({ plugins: [mcp({ loginPage: '/login' })] });
178
-
179
- // app.ts
180
- await app.register(mcpPlugin, { resources, auth: getAuth() });
181
- ```
182
-
183
- Auto-registers discovery endpoints:
184
- - `GET /.well-known/oauth-authorization-server` (RFC 8414)
185
- - `GET /.well-known/oauth-protected-resource` (RFC 9728)
186
-
187
- The auth flow:
188
- ```
189
- MCP Client → discovers OAuth endpoints → registers → user authorizes → gets token
190
- MCP Client → POST /mcp (Authorization: Bearer <token>)
191
- Arc → auth.api.getMcpSession({ headers }) → { userId, organizationId }
192
- Arc → BaseController scopes by org automatically
193
- ```
194
-
195
- ### 3. Better Auth API Key (machine clients, no OAuth dance)
196
-
197
- Hosts using Better Auth's `apiKey()` plugin should NOT hand-wire `verifyApiKey` — the helper handles the `referenceId` vs `userId` fallback, `metadata.organizationId` extraction, disabled / expired guards, and fail-closed exception handling.
198
-
199
- ```typescript
200
- import { createMcpAuthFromBetterAuthApiKey } from '@classytic/arc/mcp';
201
- import { getAuth } from './auth.config.js';
202
-
203
- await app.register(mcpPlugin, {
204
- resources,
205
- auth: createMcpAuthFromBetterAuthApiKey(getAuth(), {
206
- orgFromMetadata: true, // reads key.metadata.organizationId (default)
207
- // metadataOrgField: 'tenantId', // if you stored it under a different key
208
- // permissionScope: 'mcp', // permissions[scope] → result.scopes (default 'mcp')
209
- }),
210
- });
211
- ```
212
-
213
- Header precedence: `Authorization: Bearer <key>` first, then `x-api-key`. Keys with neither `userId` nor `referenceId` are treated as service principals (`clientId = key.id`) — `RequestScope.kind` becomes `"service"`.
214
-
215
- ### 4. Custom Auth Function (API key, gateway, static org)
216
-
217
- Pass an `McpAuthResolver` — a function that receives headers and returns identity:
218
-
219
- ```typescript
220
- type McpAuthResolver = (headers: Record<string, string | undefined>) =>
221
- Promise<McpAuthResult | null> | McpAuthResult | null;
222
- ```
223
-
224
- Return `McpAuthResult` to allow. Return `null` to reject (401).
225
-
226
- **`McpAuthResult` fields:**
227
- - `userId?` — human user ID (optional for machine principals)
228
- - `organizationId?` — org scope
229
- - `roles?` / `orgRoles?` — user roles
230
- - `clientId?` — set this to produce `kind: "service"` scope (machine-to-machine)
231
- - `scopes?` — OAuth scopes for service accounts
232
-
233
- ```typescript
234
- // Human user — API key
235
- auth: async (headers) => {
236
- if (headers['x-api-key'] !== process.env.MCP_API_KEY) return null;
237
- return { userId: 'alice', organizationId: 'org-123', roles: ['admin'] };
238
- },
239
-
240
- // Machine principal — service account (no userId needed)
241
- auth: async (headers) => {
242
- const key = headers['x-service-key'];
243
- if (key !== process.env.SVC_KEY) return null;
244
- return { clientId: 'ingestion-pipeline', organizationId: 'org-123', scopes: ['write:events'] };
245
- },
246
-
247
- // Gateway-validated JWT (token already verified upstream)
248
- auth: async (headers) => {
249
- const userId = headers['x-user-id'];
250
- const orgId = headers['x-org-id'];
251
- return userId ? { userId, organizationId: orgId } : null;
252
- },
253
-
254
- // Bearer token with custom validation
255
- auth: async (headers) => {
256
- const token = headers['authorization']?.replace('Bearer ', '');
257
- if (!token) return null;
258
- const payload = await verifyJwt(token);
259
- return payload ? { userId: payload.sub, organizationId: payload.org } : null;
260
- },
261
- ```
262
-
263
- ### Service Scope (machine-to-machine)
264
-
265
- When `clientId` is present in the auth result, Arc produces `kind: "service"` RequestScope:
266
-
267
- ```
268
- auth resolver returns { clientId: 'pipeline-v2', organizationId: 'org-a', scopes: ['read:all'] }
269
- → buildRequestContext sets _scope: { kind: 'service', clientId: 'pipeline-v2', organizationId: 'org-a', scopes: ['read:all'] }
270
- → ctx.user is null (machine principals don't masquerade as users)
271
- → isService(scope), getClientId(scope), getServiceScopes(scope) all work
272
- ```
273
-
274
- When `userId` is present (without `clientId`), Arc produces `kind: "member"` or `kind: "authenticated"` as before.
275
-
276
- ### Multi-Tenancy
277
-
278
- The `organizationId` from auth flows into BaseController's org-scoping automatically:
279
-
280
- ```
281
- auth resolver returns { userId: 'alice', organizationId: 'org-a' }
282
- → buildRequestContext sets _scope: { kind: 'member', organizationId: 'org-a' }
283
- → QueryResolver adds { organizationId: 'org-a' } to every query
284
- → Agent only sees org-a's data — no cross-tenant leaks
285
- ```
286
-
287
- Works with any `tenantField` (`organizationId`, `workspaceId`, `teamId`). Resources with `tenantField: false` are visible to all authenticated users.
288
-
289
- ## Tool-Name Collisions
290
-
291
- `createMcpServer()` resolves duplicate tool names BEFORE the MCP SDK sees them — the SDK's native `Tool already registered` error gave zero source attribution.
292
-
293
- - **Preset vs user** → auto-namespace. `softDelete`'s `restore_post` becomes `softdelete_restore_post` when the user defines `actions.restore`; the user's tool keeps the canonical name.
294
- - **User vs user / preset vs preset / 3-way+** → typed throw: `ArcError('arc.mcp.tool_name_collision')` naming both `source` strings (`crud:post:list`, `action:post:approve`, `route:post:GET /export`, `preset:softDelete:post:restore`).
295
-
296
- `resolveToolCollisions(tools)` is exported from `@classytic/arc/mcp` for test harnesses that want to exercise collision behaviour without booting a server.
297
-
298
- ## Level 2 — Custom Tools
299
-
300
- ```typescript
301
- import { createMcpServer, defineTool, definePrompt } from '@classytic/arc/mcp';
302
- import { z } from 'zod';
303
-
304
- const server = await createMcpServer({
305
- name: 'social-automation',
306
- version: '1.0.0',
307
- instructions: 'Use list_providers first.',
308
- tools: [
309
- defineTool('send_notification', {
310
- description: 'Send a notification to a user or channel',
311
- input: {
312
- channel: z.enum(['email', 'telegram', 'whatsapp']),
313
- recipient: z.string(),
314
- message: z.string(),
315
- },
316
- annotations: { openWorldHint: true },
317
- handler: async ({ channel, recipient, message }) => {
318
- const result = await notificationService.send(channel, recipient, message);
319
- return { content: [{ type: 'text', text: JSON.stringify(result) }] };
320
- },
321
- }),
322
- ],
323
- prompts: [
324
- definePrompt('content_calendar', {
325
- description: 'Plan a content calendar',
326
- args: { platforms: z.string(), theme: z.string().optional() },
327
- handler: ({ platforms, theme }) => ({
328
- messages: [{ role: 'user', content: { type: 'text', text: `Plan content for ${platforms}` } }],
329
- }),
330
- }),
331
- ],
332
- });
333
- ```
334
-
335
- ### defineTool() — Input is a flat Zod shape
336
-
337
- Pass `{ field: z.string() }`, NOT `z.object(...)`. The SDK wraps it internally.
338
-
339
- ```typescript
340
- defineTool('get_weather', {
341
- description: 'Get weather for a city',
342
- input: { city: z.string(), units: z.enum(['celsius', 'fahrenheit']).optional() },
343
- annotations: { readOnlyHint: true, openWorldHint: true },
344
- handler: async ({ city, units }) => ({
345
- content: [{ type: 'text', text: JSON.stringify(await weatherApi.get(city, units)) }],
346
- }),
347
- });
348
- ```
349
-
350
- ## Project Structure
351
-
352
- Resources stay in `src/resources/`. Custom MCP tools co-locate with their resource:
353
-
354
- ```
355
- src/resources/
356
- product/
357
- product.model.ts
358
- product.resource.ts
359
- product.mcp.ts ← custom MCP tools (optional)
360
- order/
361
- order.model.ts
362
- order.resource.ts
363
- order.mcp.ts ← domain-specific tools (fulfill, cancel, track)
364
- ```
365
-
366
- Generate with CLI: `arc generate resource order --mcp` or `arc generate mcp analytics`
367
-
368
- Wire in app.ts:
369
-
370
- ```typescript
371
- import { fulfillOrderTool } from './resources/order/order.mcp.js';
372
-
373
- await app.register(mcpPlugin, {
374
- resources,
375
- extraTools: [fulfillOrderTool],
376
- });
377
- ```
378
-
379
- ## Guards — Permissions for Custom Tools
380
-
381
- Auto-generated tools go through BaseController (permissions enforced automatically). Custom tools need explicit guards:
382
-
383
- ```typescript
384
- import { defineTool, guard, requireAuth, requireOrg, requireRole, customGuard } from '@classytic/arc/mcp';
385
- ```
386
-
387
- ### guard() Wrapper — Compose Guards
388
-
389
- ```typescript
390
- // Admin-only tool
391
- defineTool('delete_all', {
392
- description: 'Delete all records',
393
- handler: guard(requireAuth, requireOrg, requireRole('admin'), async (input, ctx) => {
394
- // Only runs if: authenticated + has org + has admin role
395
- return { content: [{ type: 'text', text: 'Deleted' }] };
396
- }),
397
- });
398
- ```
399
-
400
- ### Built-in Guards
401
-
402
- | Guard | Rejects when |
403
- |-------|-------------|
404
- | `requireAuth` | No session or anonymous |
405
- | `requireOrg` | No `organizationId` in session |
406
- | `requireRole('admin')` | User lacks the role (checks `session.roles`) |
407
- | `requireRole('admin', 'editor')` | User has neither role (OR logic) |
408
- | `requireOrgId('org-x')` | Session org doesn't match |
409
- | `customGuard(fn, msg)` | Predicate returns false |
410
-
411
- ### Inline Checks
412
-
413
- For conditional logic inside handlers instead of wrapping:
414
-
415
- ```typescript
416
- import { isAuthenticated, hasOrg, getUserId, getOrgId, denied } from '@classytic/arc/mcp';
417
-
418
- defineTool('flexible_action', {
419
- description: 'Does different things based on auth',
420
- handler: async (input, ctx) => {
421
- if (!isAuthenticated(ctx)) return denied('Login required');
422
-
423
- const userId = getUserId(ctx);
424
- const orgId = getOrgId(ctx);
425
-
426
- // Different behavior for different orgs
427
- if (orgId === 'org-premium') {
428
- // premium features
429
- }
430
-
431
- return { content: [{ type: 'text', text: `Done by ${userId}` }] };
432
- },
433
- });
434
- ```
435
-
436
- ### Custom Guard
437
-
438
- ```typescript
439
- const businessHours = customGuard(
440
- () => { const h = new Date().getHours(); return h >= 9 && h < 17; },
441
- 'Only available during business hours (9-5)',
442
- );
443
-
444
- const maxRequestsGuard = customGuard(
445
- async (ctx) => await rateLimiter.check(ctx.session?.userId),
446
- 'Rate limit exceeded',
447
- );
448
-
449
- defineTool('sensitive_op', {
450
- description: 'Time-restricted operation',
451
- handler: guard(requireAuth, businessHours, async (input, ctx) => { ... }),
452
- });
453
- ```
454
-
455
- ### Auth Resolver with Roles
456
-
457
- For guards to check roles, your auth resolver must return them:
458
-
459
- ```typescript
460
- auth: async (headers) => {
461
- const token = await verifyJwt(headers['authorization']);
462
- return {
463
- userId: token.sub,
464
- organizationId: token.org,
465
- roles: token.roles, // ← requireRole() checks this
466
- orgRoles: token.orgRoles, // ← for org-level permissions
467
- };
468
- },
469
- ```
470
-
471
- ## fieldRulesToZod — Schema Conversion
472
-
473
- Convert Arc's `schemaOptions.fieldRules` to flat Zod shapes for custom tools:
474
-
475
- ```typescript
476
- import { fieldRulesToZod } from '@classytic/arc/mcp';
477
-
478
- const createShape = fieldRulesToZod(resource.schemaOptions.fieldRules, {
479
- mode: 'create', // 'create' | 'update' | 'list'
480
- hiddenFields: ['internalScore'],
481
- readonlyFields: ['slug'],
482
- });
483
- // → { name: z.string(), price: z.number(), category: z.enum([...]) }
484
- ```
485
-
486
- ## AI SDK Bridge (v2.8.4+)
487
-
488
- Expose AI SDK `tool()` definitions over MCP without duplicating glue. The bridge handles `isAuthenticated` rejection, optional custom guards, `{ error }` → `isError: true` envelope translation, and thrown-error mapping.
489
-
490
- ```typescript
491
- import { bridgeToMcp, buildMcpToolsFromBridges, getUserId, hasOrg, type McpBridge } from '@classytic/arc/mcp';
492
- import { tool } from 'ai';
493
- import { z } from 'zod';
494
-
495
- function buildTriggerJobTool(companyId: string) {
496
- return tool({
497
- description: 'Start a job.',
498
- inputSchema: z.object({ phase: z.enum(['investigate', 'fix']) }),
499
- execute: async ({ phase }) => ({ jobId: `${companyId}-${phase}-${Date.now()}` }),
500
- });
501
- }
502
-
503
- export const triggerJobBridge: McpBridge = {
504
- name: 'trigger_job',
505
- description: 'Start a job.',
506
- inputSchema: { phase: z.enum(['investigate', 'fix']) },
507
- annotations: { destructiveHint: true },
508
- buildTool: (ctx) => buildTriggerJobTool(getUserId(ctx) ?? ''),
509
- guard: (ctx) => (hasOrg(ctx) ? null : 'Organization scope required'),
510
- };
511
-
512
- await app.register(mcpPlugin, {
513
- resources,
514
- extraTools: buildMcpToolsFromBridges([triggerJobBridge], {
515
- // Per-environment filtering — read-only deployments hide destructive tools
516
- exclude: process.env.DEPLOYMENT === 'readonly' ? ['trigger_job'] : [],
517
- }),
518
- });
519
- ```
520
-
521
- `buildMcpToolsFromBridges` also accepts `{ include: [...] }` for strict allowlists. `buildTool` is called fresh per request — safe for per-tenant dep resolution. `McpBridge.annotations` is the same `ToolAnnotations` shape as `defineTool`.
522
-
523
- ## Schema Discovery — MCP Resources
524
-
525
- Auto-registered for agent discovery:
526
-
527
- - `arc://schemas` — list all resources with field counts, operations, presets
528
- - `arc://schemas/{name}` — full schema for a specific resource
529
-
530
- ## Testing with Claude CLI
531
-
532
- ```bash
533
- claude mcp add --transport http my-api http://localhost:3000/mcp
534
- echo "List all products" | claude -p --allowedTools "mcp__my-api__*"
535
- claude mcp remove my-api
536
- ```
537
-
538
- ## Transport Modes
539
-
540
- ### Stateless (default) — Production
541
-
542
- Fresh server per request. No session tracking, no memory overhead. Best for horizontal scaling, serverless, edge.
543
-
544
- ```typescript
545
- await app.register(mcpPlugin, { resources, auth: false });
546
- // stateful defaults to false — stateless mode
547
- ```
548
-
549
- - `POST /mcp` — each request gets a fresh server + transport
550
- - `GET /mcp` — returns 405 (no SSE in stateless mode)
551
- - `DELETE /mcp` — no-op
552
-
553
- ### Stateful — When Needed
554
-
555
- Sessions cached with TTL. Use when you need server-initiated notifications or long-lived connections.
556
-
557
- ```typescript
558
- await app.register(mcpPlugin, {
559
- resources,
560
- stateful: true, // enable session persistence
561
- sessionTtlMs: 600000, // 10 min TTL
562
- maxSessions: 500, // max concurrent sessions
563
- });
564
- ```
565
-
566
- - `POST /mcp` — reuses session via `Mcp-Session-Id` header, or creates new
567
- - `GET /mcp` — SSE stream for server-initiated messages
568
- - `DELETE /mcp` — terminates session
569
-
570
- Sessions: lazily created, TTL-cached, LRU-evicted at max capacity, auto-cleaned on shutdown.
571
-
572
- ## Health Endpoint
573
-
574
- `GET /mcp/health` — no MCP protocol needed, plain JSON:
575
-
576
- ```json
577
- {
578
- "status": "ok",
579
- "mode": "stateless",
580
- "tools": 11,
581
- "resources": 2,
582
- "toolNames": ["list_products", "get_product", ...],
583
- "sessions": null
584
- }
585
- ```
586
-
587
- Use to verify the MCP server is alive before configuring Claude CLI.
588
-
589
- ## DX Helpers (v2.4.4)
590
-
591
- ### ArcRequest — Typed Fastify Request
592
-
593
- For `rawHandler` routes, use `ArcRequest` instead of `(req as any).user`:
594
-
595
- ```typescript
596
- import type { ArcRequest } from '@classytic/arc';
597
-
598
- rawHandler: async (req: ArcRequest, reply) => {
599
- req.user?.id; // typed
600
- req.scope.organizationId; // typed (when member)
601
- req.signal; // AbortSignal (Fastify 5 built-in)
602
- }
603
- ```
604
-
605
- ### envelope() — Response Helper
606
-
607
- ```typescript
608
- import { envelope } from '@classytic/arc';
609
-
610
- rawHandler: async (req, reply) => {
611
- const data = await service.getResults();
612
- return reply.send(envelope(data));
613
- // → { data }
614
- return reply.send(envelope(data, { total: 100, page: 1 }));
615
- // → { data, total: 100, page: 1 }
616
- }
617
- ```
618
-
619
- ### getOrgContext() — Canonical Org Extraction
620
-
621
- Eliminates duplicated `req.user.organizationId || req.headers['x-organization-id']` patterns:
622
-
623
- ```typescript
624
- import { getOrgContext } from '@classytic/arc/scope';
625
-
626
- rawHandler: async (req, reply) => {
627
- const { userId, organizationId, roles, orgRoles } = getOrgContext(req);
628
- // Works regardless of auth type (JWT, Better Auth, custom)
629
- }
630
- ```
631
-
632
- ### createDomainError() — Error Factory
633
-
634
- Eliminates manual `if (err.code) return status` mapping:
635
-
636
- ```typescript
637
- import { createDomainError } from '@classytic/arc';
638
-
639
- throw createDomainError('MEMBER_NOT_FOUND', 'Member does not exist', 404);
640
- throw createDomainError('SELF_REFERRAL', 'Cannot refer yourself', 422);
641
- throw createDomainError('INSUFFICIENT_BALANCE', 'Not enough credits', 402, { balance: 0 });
642
- // Arc's error handler auto-maps statusCode to HTTP response
643
- ```
644
-
645
- ### preAuth — Pre-Auth Handlers for SSE/WebSocket
646
-
647
- Run before auth middleware. Use for promoting `?token=` to `Authorization` header (EventSource can't set headers):
648
-
649
- ```typescript
650
- routes: [{
651
- method: 'GET',
652
- path: '/stream',
653
- permissions: requireAuth(),
654
- preAuth: [(req) => {
655
- const token = req.query?.token;
656
- if (token) req.headers.authorization = `Bearer ${token}`;
657
- }],
658
- rawHandler: sseHandler,
659
- }]
660
- ```
661
-
662
- ### streamResponse — SSE Route Flag
663
-
664
- Auto-sets SSE headers and bypasses Arc's response wrapper:
665
-
666
- ```typescript
667
- routes: [{
668
- method: 'POST',
669
- path: '/stream',
670
- streamResponse: true, // SSE headers + no { success, data } wrapper
671
- permissions: requireAuth(),
672
- rawHandler: async (request, reply) => {
673
- const { stream } = await generateStream({ abortSignal: request.signal });
674
- return reply.send(stream);
675
- },
676
- }]
677
- ```
678
-
679
- ## Test Coverage
680
-
681
- 165 test files, 2439 tests. MCP-specific:
682
-
683
- | Test File | Tests | Covers |
684
- |-----------|-------|--------|
685
- | `mcp-auth-e2e.test.ts` | 16 | All auth modes, multi-tenancy, permission filters, async permissions |
686
- | `mcp-dx-features.test.ts` | 14 | include, names, prefix, disableDefaultRoutes, mcpHandler, guards, CRUD lifecycle |
687
- | `resourceToTools.test.ts` | 12 | Tool generation, annotations, field hiding, soft delete |
688
- | `createMcpServer.test.ts` | 10 | Server creation, tool registration, InMemoryTransport |
689
- | `guards.test.ts` | 8 | requireAuth, requireOrg, requireRole, customGuard, composition |
690
- | `dx-features.test.ts` | 17 | envelope, getOrgContext, createDomainError, onRegister, preAuth, streamResponse |
691
- | Others | 32 | fieldRulesToZod, defineTool, definePrompt, buildRequestContext, sessionCache, authCache |