@classytic/arc 2.45.2 → 2.47.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.
- package/README.md +1 -1
- package/dist/{EventTransport-DHb1tpu-.mjs → EventTransport-BHKy4_Bi.mjs} +5 -6
- package/dist/{EventTransport-CiicKz2Z.d.mts → EventTransport-CYEoCJGe.d.mts} +0 -2
- package/dist/{HookSystem-C1u0EUnt.mjs → HookSystem-CAIDVoKC.mjs} +3 -4
- package/dist/{QueryCache--5uAuYPW.d.mts → QueryCache-DdvrGG8Q.d.mts} +1 -3
- package/dist/{ResourceRegistry-D2jXWVN_.mjs → ResourceRegistry-23Ml6FNe.mjs} +15 -4
- package/dist/{acquire-DTkA8Lme.mjs → acquire-DoFX06fm.mjs} +2 -3
- package/dist/{actionPermissions-DRVk6m7x.mjs → actionPermissions-DXrlWHHK.mjs} +37 -42
- package/dist/audit/index.d.mts +2 -10
- package/dist/audit/index.mjs +8 -12
- package/dist/auth/audit.d.mts +0 -2
- package/dist/auth/audit.mjs +2 -3
- package/dist/auth/index.d.mts +9 -17
- package/dist/auth/index.mjs +26 -29
- package/dist/auth/redis-session.d.mts +2 -4
- package/dist/auth/redis-session.mjs +2 -3
- package/dist/{authorizationDecision-D48fUJv1.mjs → authorizationDecision-DYiubkYw.mjs} +5 -6
- package/dist/{base-CZyixEQR.d.mts → base-HXNgPQww.d.mts} +1 -7
- package/dist/{boundedMap-DkKiPifd.mjs → boundedMap-CtdzpJ3X.mjs} +2 -3
- package/dist/{buildHandler-BiZ4VATS.mjs → buildHandler-CARdmPNo.mjs} +5 -6
- package/dist/cache/index.d.mts +4 -10
- package/dist/cache/index.mjs +5 -6
- package/dist/{caching-Cj0as-P1.mjs → caching-QRiryDLs.mjs} +3 -4
- package/dist/{claimed-ChI13rUR.mjs → claimed-BLecr1j3.mjs} +2 -3
- package/dist/cleanup/index.d.mts +4 -18
- package/dist/cleanup/index.mjs +12 -20
- package/dist/cli/commands/describe.d.mts +1 -3
- package/dist/cli/commands/describe.mjs +4 -5
- package/dist/cli/commands/docs.d.mts +1 -3
- package/dist/cli/commands/docs.mjs +4 -5
- package/dist/cli/commands/doctor.d.mts +1 -3
- package/dist/cli/commands/doctor.mjs +2 -3
- package/dist/cli/commands/generate.d.mts +1 -1
- package/dist/cli/commands/generate.mjs +2 -2
- package/dist/cli/commands/init.d.mts +1 -1
- package/dist/cli/commands/init.mjs +2 -2
- package/dist/cli/commands/introspect.d.mts +1 -3
- package/dist/cli/commands/introspect.mjs +3 -4
- package/dist/cli/index.d.mts +2 -2
- package/dist/cli/index.mjs +3 -3
- package/dist/{constants-D_aiew34.mjs → constants-Cx7BcnHT.mjs} +2 -3
- package/dist/context/index.d.mts +0 -8
- package/dist/context/index.mjs +6 -7
- package/dist/core/index.d.mts +3 -3
- package/dist/core/index.mjs +8 -8
- package/dist/{core-QIZ2560Y.mjs → core-0WyMuo0f.mjs} +9 -12
- package/dist/{createActionRouter-CvH84dyx.mjs → createActionRouter-mLAGbpDV.mjs} +7 -8
- package/dist/{createAggregationRouter-DGyK2Hp6.mjs → createAggregationRouter-BEAjn3dA.mjs} +9 -10
- package/dist/{createApp-CKjZpmq9.mjs → createApp-QDP4vYWH.mjs} +49 -62
- package/dist/{createMcpServer-DSztofa9.d.mts → createMcpServer-DzXHX0SO.d.mts} +1 -3
- package/dist/{defineAggregation-BLza7Ca4.mjs → defineAggregation-CFNfvz-C.mjs} +2 -3
- package/dist/{defineResource-CEo0gDCb.mjs → defineResource-BROJmhzJ.mjs} +80 -29
- package/dist/discovery/index.d.mts +1 -3
- package/dist/discovery/index.mjs +2 -3
- package/dist/docs/index.d.mts +8 -8
- package/dist/docs/index.mjs +4 -5
- package/dist/{elevation-BW2J3tNj.d.mts → elevation-DPD0hcU-.d.mts} +0 -2
- package/dist/{elevation-BJTsSnke.mjs → elevation-DrXeEWWk.mjs} +9 -10
- package/dist/encryption/index.d.mts +1 -7
- package/dist/encryption/index.mjs +8 -13
- package/dist/{errorHandler--4rSMMvq.d.mts → errorHandler-B9r88jZV.d.mts} +8 -3
- package/dist/{errorHandler-2p4SL5zm.mjs → errorHandler-BiBXtxj4.mjs} +16 -6
- package/dist/{errors-JYc9vwqE.d.mts → errors-DTo0me1o.d.mts} +0 -2
- package/dist/{errors-grZkIA8N.mjs → errors-DnrUChAy.mjs} +2 -3
- package/dist/{eventPlugin-BtmA4-3P.d.mts → eventPlugin-BY38F6yK.d.mts} +1 -7
- package/dist/{eventPlugin-ItcYBGUs.mjs → eventPlugin-BhKLUe7H.mjs} +10 -12
- package/dist/{eventTypes-Ck6fD3ne.mjs → eventTypes-CCIRGakw.mjs} +5 -8
- package/dist/events/index.d.mts +5 -17
- package/dist/events/index.mjs +9 -9
- package/dist/events/transports/redis-stream-entry.d.mts +1 -1
- package/dist/events/transports/redis-stream-entry.mjs +5 -6
- package/dist/events/transports/redis.d.mts +2 -4
- package/dist/events/transports/redis.mjs +3 -4
- package/dist/{externalPaths-CmGOxOtD.d.mts → externalPaths-BOqdq5wr.d.mts} +0 -2
- package/dist/factory/index.d.mts +4 -14
- package/dist/factory/index.mjs +12 -18
- package/dist/{fastify-augmentation-DRlCIWE9.d.mts → fastify-augmentation-bzkWPt1f.d.mts} +4 -10
- package/dist/{fields-BRX0Krcj.mjs → fields-CYdpcV73.mjs} +2 -3
- package/dist/{fields-BBSpf8pS.d.mts → fields-JTkrtO-r.d.mts} +0 -2
- package/dist/{filter-merge-CDc7YMwX.mjs → filter-merge-6kasezRH.mjs} +2 -3
- package/dist/{generate-DCGuEbqI.d.mts → generate-C-g_KOkV.d.mts} +0 -4
- package/dist/{generate-hvg7V2g1.mjs → generate-DUkcbc4r.mjs} +7 -12
- package/dist/{headers-Cqkg4LzI.mjs → headers-KxhrKevA.mjs} +3 -4
- package/dist/{health-PVt0VjOx.mjs → health-CRJg3IIq.mjs} +2 -3
- package/dist/{health-DyeP3mTW.mjs → health-jkYNdobJ.mjs} +4 -7
- package/dist/hooks/index.d.mts +1 -1
- package/dist/hooks/index.mjs +2 -2
- package/dist/http-cache/index.d.mts +211 -0
- package/dist/http-cache/index.mjs +605 -0
- package/dist/http-cache/purgers/cloudflare.d.mts +13 -0
- package/dist/http-cache/purgers/cloudflare.mjs +46 -0
- package/dist/http-cache/purgers/fastly.d.mts +12 -0
- package/dist/http-cache/purgers/fastly.mjs +47 -0
- package/dist/http-cache/testing/index.d.mts +68 -0
- package/dist/http-cache/testing/index.mjs +168 -0
- package/dist/idempotency/index.d.mts +3 -9
- package/dist/idempotency/index.mjs +11 -14
- package/dist/idempotency/redis.d.mts +1 -1
- package/dist/idempotency/redis.mjs +3 -4
- package/dist/{index-Bxriq3so.d.mts → index-B5i9-vuP.d.mts} +4 -26
- package/dist/{index-Chgz3d0i.d.mts → index-BAXDo5eE.d.mts} +1 -7
- package/dist/{index-Beg3aNnK.d.mts → index-BxZS-8So.d.mts} +67 -25
- package/dist/{index-WH7xgvxS.d.mts → index-Cy2-QffW.d.mts} +40 -92
- package/dist/{index-uhkUA5-U.d.mts → index-D1X_C_qz.d.mts} +13 -23
- package/dist/{index-CUJvoyw3.d.mts → index-DFCCQ9AE.d.mts} +2 -24
- package/dist/index.d.mts +7 -9
- package/dist/index.mjs +12 -13
- package/dist/{init-jC3rMPzb.mjs → init-CACwpktI.mjs} +18 -35
- package/dist/{init-Cscs4lab.d.mts → init-CV2_Fw3H.d.mts} +0 -4
- package/dist/integrations/event-gateway.d.mts +3 -5
- package/dist/integrations/event-gateway.mjs +3 -4
- package/dist/integrations/index.d.mts +3 -3
- package/dist/integrations/index.mjs +1 -1
- package/dist/integrations/jobs/index.d.mts +1 -1
- package/dist/integrations/jobs/index.mjs +7 -11
- package/dist/integrations/mcp/index.d.mts +7 -39
- package/dist/integrations/mcp/index.mjs +8 -14
- package/dist/integrations/mcp/testing.d.mts +3 -5
- package/dist/integrations/mcp/testing.mjs +3 -4
- package/dist/integrations/streamline.d.mts +1 -3
- package/dist/integrations/streamline.mjs +4 -5
- package/dist/integrations/webhooks.d.mts +2 -4
- package/dist/integrations/webhooks.mjs +5 -5
- package/dist/integrations/websocket-pushref-redis.d.mts +2 -4
- package/dist/integrations/websocket-pushref-redis.mjs +2 -3
- package/dist/integrations/websocket-redis.d.mts +2 -4
- package/dist/integrations/websocket-redis.mjs +2 -3
- package/dist/integrations/websocket.d.mts +2 -2
- package/dist/integrations/websocket.mjs +13 -24
- package/dist/{interface-JJzwH4Ro.d.mts → interface-BmExzQRD.d.mts} +0 -2
- package/dist/{interface-BOk3YnTz.d.mts → interface-WR1U0K7t.d.mts} +0 -2
- package/dist/{jsonBody-ptwyzZQ-.mjs → jsonBody-CzDBkCme.mjs} +3 -4
- package/dist/{keys-C1vFuSbv.mjs → keys-Cbwf6r1B.mjs} +2 -3
- package/dist/{loadResources-CHPDyIPn.mjs → loadResources-Kr6vuljv.mjs} +4 -5
- package/dist/{loadResourcesFromEntry-BkHHTu_B.mjs → loadResourcesFromEntry-D2e0qoDR.mjs} +3 -4
- package/dist/logger/index.d.mts +1 -3
- package/dist/logger/index.mjs +2 -2
- package/dist/{logger-C5bvCiAK.mjs → logger-C110X5Yz.mjs} +3 -5
- package/dist/{mcpPlugin-C9qohJCF.mjs → mcpPlugin-4lIPr9OJ.mjs} +41 -60
- package/dist/{memory-CxiTwT0j.mjs → memory-D9qkhXiB.mjs} +4 -5
- package/dist/{metrics-Ckp2zRy-.mjs → metrics-B-qrrWfI.mjs} +4 -5
- package/dist/middleware/index.d.mts +1 -5
- package/dist/middleware/index.mjs +4 -5
- package/dist/migrations/index.d.mts +0 -2
- package/dist/migrations/index.mjs +3 -4
- package/dist/{module-CfnKuIuH.mjs → module-BD8xHgrz.mjs} +2 -3
- package/dist/{multiTenant-CAtYlW6H.d.mts → multiTenant-KZj8j1uJ.d.mts} +1 -5
- package/dist/{multipartBody-BFasGtP9.mjs → multipartBody-qU7KCn1l.mjs} +2 -3
- package/dist/observeSend-BnPtTotW.mjs +20 -0
- package/dist/{openapi-DAPxjYHX.mjs → openapi-DoVa5SVP.mjs} +18 -28
- package/dist/outbox-admin/index.d.mts +2 -4
- package/dist/outbox-admin/index.mjs +6 -7
- package/dist/{outbox-module-gZCHoE4H.d.mts → outbox-module-5Mnwcycy.d.mts} +3 -9
- package/dist/outbox-module-DyITEIop.mjs +297 -0
- package/dist/permissions/index.d.mts +4 -4
- package/dist/permissions/index.mjs +7 -7
- package/dist/{permissions-B14c3OMp.mjs → permissions-BBy4bOGi.mjs} +19 -29
- package/dist/{pipe-CQv7PsAK.mjs → pipe-BOm2o4UA.mjs} +3 -4
- package/dist/pipeline/index.d.mts +1 -9
- package/dist/pipeline/index.mjs +5 -8
- package/dist/{plan-CpnTykjb.mjs → plan-DDIGwuxr.mjs} +5 -9
- package/dist/{plugin-DXTjVg_Q.mjs → plugin-Bn4D_0XK.mjs} +156 -64
- package/dist/plugins/index.d.mts +8 -16
- package/dist/plugins/index.mjs +22 -26
- package/dist/plugins/response-cache.d.mts +2 -4
- package/dist/plugins/response-cache.mjs +10 -10
- package/dist/plugins/tracing-entry.d.mts +1 -1
- package/dist/plugins/tracing-entry.mjs +3 -4
- package/dist/{pluralize-C3VJKRGp.mjs → pluralize-ClEjcKlG.mjs} +2 -3
- package/dist/policy.types-DPqToKG1.d.mts +50 -0
- package/dist/presets/filesUpload.d.mts +4 -6
- package/dist/presets/filesUpload.mjs +6 -7
- package/dist/presets/index.d.mts +3 -19
- package/dist/presets/index.mjs +2 -2
- package/dist/presets/multiTenant.d.mts +1 -1
- package/dist/presets/multiTenant.mjs +7 -7
- package/dist/presets/search.d.mts +3 -5
- package/dist/presets/search.mjs +3 -4
- package/dist/{presets-CquqYJPy.mjs → presets-DK2jh5YR.mjs} +11 -18
- package/dist/{projection-CgfSLOSM.mjs → projection-BHH-sXyS.mjs} +3 -4
- package/dist/purger.types-2wNJK_89.mjs +24 -0
- package/dist/purger.types-DvPp4-yd.d.mts +26 -0
- package/dist/{pushref-registry-UxCkoA4C.d.mts → pushref-registry-d86QUaSq.d.mts} +0 -6
- package/dist/{queryCachePlugin-D0HUISHJ.mjs → queryCachePlugin-Ckqe98AM.mjs} +8 -10
- package/dist/{queryCachePlugin-C2lZjTxk.d.mts → queryCachePlugin-DYQUyeJ9.d.mts} +2 -4
- package/dist/{rateLimitKey-AvkBOMkl.mjs → rateLimitKey-CWAjlqcN.mjs} +2 -3
- package/dist/{realtime-CbWtVbqK.mjs → realtime-BIJi9USY.mjs} +17 -19
- package/dist/{redis-BDgv9Glw.d.mts → redis-RpDMemdm.d.mts} +2 -4
- package/dist/{redis-stream-BMk-bpQS.d.mts → redis-stream-CS1N9dwM.d.mts} +1 -3
- package/dist/{redisShapes-CQksY67q.d.mts → redisShapes-CqBXTn_s.d.mts} +0 -2
- package/dist/registry/index.d.mts +2 -12
- package/dist/registry/index.mjs +3 -3
- package/dist/{registry-BVwpAuFI.mjs → registry-y9ZA-R_J.mjs} +7 -12
- package/dist/{outbox-module-B4FAkx3A.mjs → relay-BNrC1CEP.mjs} +8 -306
- package/dist/{renewingLease-CykpeNcQ.mjs → renewingLease-CS43br5E.mjs} +2 -3
- package/dist/{replyHelpers-DA51IZio.mjs → replyHelpers-oZDzakGb.mjs} +3 -4
- package/dist/{requestContext-DIWHKDtQ.mjs → requestContext-fWb_YaV2.mjs} +2 -3
- package/dist/{requirement-Cp_fsMDL.mjs → requirement--2hWyyHi.mjs} +2 -3
- package/dist/{requirement-CbiLdQ1n.d.mts → requirement-CTRQjjQx.d.mts} +0 -2
- package/dist/{resourceRateLimit-BFuluodF.mjs → resourceRateLimit-1WbcyMZY.mjs} +3 -4
- package/dist/{resourceRateLimit-Wf6d6FL9.d.mts → resourceRateLimit-DCWglD7V.d.mts} +1 -3
- package/dist/{rolldown-runtime-D_lMdYOd.mjs → rolldown-runtime-yH2lHMo_.mjs} +2 -3
- package/dist/{routeValidator-DuLonYwr.mjs → routeValidator-BSlRIA5c.mjs} +2 -3
- package/dist/{runtimeCapabilities-CydRfm0i.mjs → runtimeCapabilities-CYCEtU1W.mjs} +2 -3
- package/dist/{schedules-B693KXxa.mjs → schedules-B5WGlYIT.mjs} +132 -9
- package/dist/{schemaConverter-DNvZWTV6.mjs → schemaConverter-DtNvts-6.mjs} +3 -4
- package/dist/{schemaIR-REV2y7Wd.mjs → schemaIR-uS_RHqa3.mjs} +3 -4
- package/dist/schemas/index.d.mts +0 -2
- package/dist/schemas/index.mjs +2 -3
- package/dist/scim/index.d.mts +0 -12
- package/dist/scim/index.mjs +10 -18
- package/dist/scope/index.d.mts +2 -6
- package/dist/scope/index.mjs +5 -5
- package/dist/{scope-Bevxy_ST.mjs → scope-BwVLSyNG.mjs} +5 -6
- package/dist/{sessionManager-qimlKV0P.d.mts → sessionManager-CdvDF04x.d.mts} +2 -4
- package/dist/{shutdown-CfrqPR7A.mjs → shutdown-BJiJN7FT.mjs} +2 -3
- package/dist/{simpleEqualityMatcher-BJwfuRKP.mjs → simpleEqualityMatcher-DGRLq-1k.mjs} +2 -3
- package/dist/{sse-CuNNWr2z.mjs → sse-B_50llZu.mjs} +8 -9
- package/dist/{sseStream-C_2ujAVY.mjs → sseStream-BjSo9Ult.mjs} +3 -4
- package/dist/{storage-Cx9Sz3Ou.d.mts → storage-odC5MNKN.d.mts} +0 -2
- package/dist/{store-helpers-C8uBGCbb.mjs → store-helpers-D-n5cwy5.mjs} +2 -3
- package/dist/{streaming-Bdq_M4d5.mjs → streaming-Dcgqa-hH.mjs} +2 -3
- package/dist/{subscriberIdentity-B-KpZkdl.mjs → subscriberIdentity-C9KhIXTF.mjs} +2 -3
- package/dist/{tenancy-C5PCvm1h.mjs → tenancy-COrhjPRZ.mjs} +3 -4
- package/dist/{tenantPreparation-dYvWrgNa.mjs → tenantPreparation-BElWHytd.mjs} +5 -6
- package/dist/testing/cleanupStoreContract.d.mts +2 -4
- package/dist/testing/cleanupStoreContract.mjs +2 -3
- package/dist/testing/index.d.mts +6 -32
- package/dist/testing/index.mjs +24 -37
- package/dist/testing/outboxStoreContract.d.mts +1 -3
- package/dist/testing/outboxStoreContract.mjs +3 -4
- package/dist/testing/requiredPorts.d.mts +2 -4
- package/dist/testing/requiredPorts.mjs +3 -4
- package/dist/testing/storageContract.d.mts +2 -4
- package/dist/testing/storageContract.mjs +2 -3
- package/dist/{timing-DCqsezX8.mjs → timing-CaxKbRk_.mjs} +3 -5
- package/dist/{tracing-Dro5eH6j.d.mts → tracing-JSFiBl5r.d.mts} +0 -2
- package/dist/{transactionContext-DrcNyjpv.mjs → transactionContext-8qKON0Nk.mjs} +2 -3
- package/dist/{typeGuards-CEl10KPy.mjs → typeGuards-DVjVSsXO.mjs} +2 -3
- package/dist/types/index.d.mts +4 -4
- package/dist/types/index.mjs +1 -1
- package/dist/types/storage.d.mts +1 -1
- package/dist/types/storage.mjs +1 -1
- package/dist/{types-ByHn9rEO.d.mts → types-0Dqlbgn8.d.mts} +0 -2
- package/dist/{types-BJ-2XqVF.d.mts → types-BeEJm-DV.d.mts} +114 -14
- package/dist/{types-DVLddu2q.d.mts → types-C0YJAiL0.d.mts} +0 -2
- package/dist/{types-D9NWjpYc.mjs → types-DZHqOuJE.mjs} +5 -6
- package/dist/{types-D3Ixsh00.d.mts → types-DeLiuaNv.d.mts} +2 -4
- package/dist/{types-Ddl9OjmE.d.mts → types-DnkIALZ8.d.mts} +0 -4
- package/dist/usage/index.d.mts +2 -10
- package/dist/usage/index.mjs +8 -12
- package/dist/{userHelpers-BHig1kHq.mjs → userHelpers-_eGj6kf0.mjs} +2 -3
- package/dist/utils/index.d.mts +5 -39
- package/dist/utils/index.mjs +12 -12
- package/dist/{utils-BG5P7_Vb.mjs → utils-Dd6MWpye.mjs} +20 -30
- package/dist/{validate-D_mdOCir.mjs → validate-BaF5wd0x.mjs} +5 -7
- package/dist/{versioning-DBGHjPh7.mjs → versioning-DyV7mwtK.mjs} +4 -5
- package/dist/{versioning-Bqm_57Qt.d.mts → versioning-S18y2-0C.d.mts} +1 -15
- package/dist/{websocket-Cs4awVyD.d.mts → websocket-BGuc-WVZ.d.mts} +1 -15
- package/dist/{workScope-DPPfM4m6.mjs → workScope-CmCBUmPR.mjs} +3 -4
- package/llms.txt +37 -30
- package/package.json +51 -22
- package/skills/arc/SKILL.md +65 -844
- package/skills/arc/references/agent-auth.md +82 -193
- package/skills/arc/references/api-reference.md +41 -245
- package/skills/arc/references/auth-api-keys.md +99 -0
- package/skills/arc/references/auth-better-auth-overlay.md +87 -0
- package/skills/arc/references/auth-better-auth.md +78 -0
- package/skills/arc/references/auth-permissions.md +100 -0
- package/skills/arc/references/auth-strategies.md +122 -0
- package/skills/arc/references/boot.md +80 -0
- package/skills/arc/references/enterprise-auth.md +65 -81
- package/skills/arc/references/events-outbox.md +90 -0
- package/skills/arc/references/events.md +75 -440
- package/skills/arc/references/integrations-jobs.md +74 -0
- package/skills/arc/references/integrations-realtime.md +84 -0
- package/skills/arc/references/integrations-webhooks.md +71 -0
- package/skills/arc/references/integrations-workflows.md +47 -0
- package/skills/arc/references/mcp-auth.md +83 -0
- package/skills/arc/references/mcp-custom-tools.md +125 -0
- package/skills/arc/references/mcp-setup.md +115 -0
- package/skills/arc/references/mcp-testing.md +63 -0
- package/skills/arc/references/multi-tenancy.md +56 -230
- package/skills/arc/references/permissions-scope.md +81 -0
- package/skills/arc/references/production-api.md +119 -0
- package/skills/arc/references/production-audit.md +101 -0
- package/skills/arc/references/production-boot.md +91 -0
- package/skills/arc/references/production-caching.md +63 -0
- package/skills/arc/references/production-distributed.md +75 -0
- package/skills/arc/references/production-idempotency.md +83 -0
- package/skills/arc/references/production-observability.md +83 -0
- package/skills/arc/references/production-realtime.md +70 -0
- package/skills/arc/references/production-reliability.md +100 -0
- package/skills/arc/references/production-shutdown.md +43 -0
- package/skills/arc/references/querying.md +76 -0
- package/skills/arc/references/resources.md +97 -0
- package/skills/arc/references/schedules.md +79 -0
- package/skills/arc/references/scim.md +61 -208
- package/skills/arc/references/tenancy-scope-install.md +82 -0
- package/skills/arc/references/testing.md +101 -144
- package/skills/arc/references/usage-cleanup-capabilities.md +45 -0
- package/skills/arc/references/validation.md +91 -0
- package/skills/arc/references/writes-hooks-errors.md +80 -0
- package/skills/arc-code-review/SKILL.md +67 -114
- package/skills/arc-code-review/references/arc-cheatsheet.md +68 -167
- package/skills/arc-code-review/references/mongokit-repositories.md +104 -0
- package/skills/arc-code-review/references/recipe-events-cache-jobs.md +112 -0
- package/skills/arc-code-review/references/recipe-resource.md +100 -0
- package/skills/arc-code-review/references/recipe-schemas-fields.md +93 -0
- package/skills/arc-code-review/references/recipe-scope-permissions.md +82 -0
- package/skills/arc-code-review/references/scaffolding.md +61 -198
- package/skills/arc-code-review/references/severity.md +49 -102
- package/skills/arc-code-review/references/smells-auth-scope.md +80 -0
- package/skills/arc-code-review/references/smells-data-events.md +66 -0
- package/skills/arc-code-review/references/smells-imports-style.md +59 -0
- package/skills/arc-code-review/references/smells-platform.md +89 -0
- package/skills/arc-code-review/references/smells-routes-schemas.md +66 -0
- package/skills/arc-module-publishing/SKILL.md +82 -208
- package/skills/arc-module-publishing/references/action-presets-and-plugins.md +87 -0
- package/skills/arc-module-publishing/references/build-and-types.md +73 -0
- package/skills/arc-module-publishing/references/module-lifecycle.md +101 -0
- package/skills/arc-module-publishing/references/package-manifest.md +34 -122
- package/skills/arc-module-publishing/references/publishing-workflow.md +44 -140
- package/skills/arc-module-publishing/references/resource-assembly.md +102 -0
- package/skills/arc-module-publishing/references/testing-packages.md +82 -0
- package/skills/arc/references/auth.md +0 -729
- package/skills/arc/references/integrations.md +0 -452
- package/skills/arc/references/mcp.md +0 -691
- package/skills/arc/references/production.md +0 -835
- package/skills/arc-code-review/references/anti-patterns.md +0 -1008
- package/skills/arc-code-review/references/migration-recipes.md +0 -649
- package/skills/arc-code-review/references/mongokit-migration.md +0 -360
- 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 |
|