@genobank/biofs 2.6.0 → 2.6.1

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.
@@ -1,1029 +0,0 @@
1
- # BioFS CLI - AI Agent & MCP Server Integration Manual
2
-
3
- **Version 2.4.1** | **For AI Agents, LLMs, and MCP Server Implementations**
4
-
5
- This manual provides structured information for AI agents to programmatically interact with the BioFS CLI for genomic data management on the Sequentia blockchain.
6
-
7
- ---
8
-
9
- ## Overview
10
-
11
- BioFS CLI enables:
12
- - **BioNFT-Gated Access**: Blockchain-verified consent for genomic data
13
- - **GDPR Compliance**: Right to access, erasure, and data minimization
14
- - **Decentralized Processing**: GPU-accelerated genomic analysis jobs
15
- - **x402 Payments**: Atomic USDC payments for services
16
-
17
- **Sequentia Network Configuration:**
18
- ```json
19
- {
20
- "chainId": 15132025,
21
- "rpcUrl": "http://52.90.163.112:8545",
22
- "contracts": {
23
- "bioCIDRegistry": "0x6Fb51DB12AE422F8360a31a27B3E960f4DC0004b",
24
- "consentManager": "0x2ff3FB85c71D6cD7F1217A08Ac9a2d68C02219cd",
25
- "bioPIL": "0x6474485F6fE3c19Ac0cD069D4cBc421656942DA9",
26
- "openCravatJobs": "0xB384A7531d59cFd45f98f71833aF736b921a5FCB",
27
- "paymentRouter": "0x4b46D8A0533bc17503349F86a909C2FEcFD04489",
28
- "labNFT": "0x24f42752F491540e305384A5C947911649C910CF",
29
- "usdcToken": "0xD837B344e931cc265ec54879A0B388DE6F0015c9"
30
- }
31
- }
32
- ```
33
-
34
- ---
35
-
36
- ## MCP Tool Definitions
37
-
38
- ### Authentication Tools
39
-
40
- #### `biofs_login`
41
- Authenticate user with Web3 wallet signature.
42
-
43
- ```typescript
44
- interface BiofsLoginParams {
45
- wallet?: string; // Wallet address for direct auth
46
- signature?: string; // Web3 signature for direct auth
47
- timeout?: number; // Auth timeout in seconds
48
- noBrowser?: boolean; // Skip browser opening
49
- }
50
-
51
- interface BiofsLoginResult {
52
- success: boolean;
53
- wallet: string;
54
- expiresAt: number; // Unix timestamp
55
- }
56
- ```
57
-
58
- **MCP Tool Schema:**
59
- ```json
60
- {
61
- "name": "biofs_login",
62
- "description": "Authenticate with GenoBank.io using Web3 wallet signature",
63
- "inputSchema": {
64
- "type": "object",
65
- "properties": {
66
- "wallet": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
67
- "signature": { "type": "string", "pattern": "^0x[a-fA-F0-9]+$" },
68
- "timeout": { "type": "integer", "minimum": 10, "maximum": 300 }
69
- }
70
- }
71
- }
72
- ```
73
-
74
- **CLI Execution:**
75
- ```bash
76
- # Interactive (opens browser)
77
- biofs login
78
-
79
- # Direct authentication (for automation)
80
- biofs login --wallet 0x... --signature 0x...
81
- ```
82
-
83
- #### `biofs_whoami`
84
- Get current authenticated session.
85
-
86
- ```typescript
87
- interface BiofsWhoamiResult {
88
- authenticated: boolean;
89
- wallet: string | null;
90
- signature: string | null;
91
- expiresAt: number | null;
92
- }
93
- ```
94
-
95
- **CLI Execution:**
96
- ```bash
97
- biofs whoami --json
98
- ```
99
-
100
- ---
101
-
102
- ### File Discovery Tools
103
-
104
- #### `biofs_list_files`
105
- Discover all BioFiles from GenoBank ecosystem.
106
-
107
- ```typescript
108
- interface BiofsListFilesParams {
109
- filter?: "vcf" | "fastq" | "bam" | "pdf" | "sqlite" | "csv";
110
- source?: "story" | "avalanche" | "s3" | "biofs";
111
- update?: boolean; // Force refresh from blockchain
112
- }
113
-
114
- interface BioFile {
115
- filename: string;
116
- biocid: string; // biocid://OWNER/bioip/IP_ID
117
- format: string; // vcf, fastq, bam, etc.
118
- size: number; // bytes
119
- source: string; // story, avalanche, s3, biofs
120
- ipId?: string; // Story Protocol IP ID
121
- owner: string; // Wallet address
122
- createdAt: string; // ISO 8601
123
- s3Path?: string; // S3 storage path
124
- fingerprint?: string; // Bloom filter fingerprint (hex)
125
- }
126
-
127
- interface BiofsListFilesResult {
128
- files: BioFile[];
129
- totalCount: number;
130
- sources: {
131
- story: number;
132
- avalanche: number;
133
- s3: number;
134
- biofs: number;
135
- };
136
- }
137
- ```
138
-
139
- **MCP Tool Schema:**
140
- ```json
141
- {
142
- "name": "biofs_list_files",
143
- "description": "List all BioFiles accessible to the authenticated user",
144
- "inputSchema": {
145
- "type": "object",
146
- "properties": {
147
- "filter": {
148
- "type": "string",
149
- "enum": ["vcf", "fastq", "bam", "pdf", "sqlite", "csv"]
150
- },
151
- "source": {
152
- "type": "string",
153
- "enum": ["story", "avalanche", "s3", "biofs"]
154
- },
155
- "update": { "type": "boolean", "default": false }
156
- }
157
- }
158
- }
159
- ```
160
-
161
- **CLI Execution:**
162
- ```bash
163
- biofs biofiles --json
164
- biofs biofiles --filter vcf --json
165
- biofs biofiles --source s3 --update --json
166
- ```
167
-
168
- ---
169
-
170
- ### File Operations Tools
171
-
172
- #### `biofs_download`
173
- Download a file with GDPR consent verification.
174
-
175
- ```typescript
176
- interface BiofsDownloadParams {
177
- biocidOrFilename: string; // BioCID URL or filename
178
- destination?: string; // Local path
179
- stream?: boolean; // Stream large files
180
- skipConsent?: boolean; // Skip GDPR consent (automation)
181
- }
182
-
183
- interface BiofsDownloadResult {
184
- success: boolean;
185
- localPath: string;
186
- size: number;
187
- fingerprint: string;
188
- consentVerified: boolean;
189
- }
190
- ```
191
-
192
- **MCP Tool Schema:**
193
- ```json
194
- {
195
- "name": "biofs_download",
196
- "description": "Download a genomic file with GDPR consent verification",
197
- "inputSchema": {
198
- "type": "object",
199
- "required": ["biocidOrFilename"],
200
- "properties": {
201
- "biocidOrFilename": { "type": "string" },
202
- "destination": { "type": "string" },
203
- "stream": { "type": "boolean", "default": false },
204
- "skipConsent": { "type": "boolean", "default": false }
205
- }
206
- }
207
- }
208
- ```
209
-
210
- **CLI Execution:**
211
- ```bash
212
- biofs download sample.vcf ./output/ --skip-consent --quiet
213
- biofs download biocid://0x.../bioip/123 --stream --output ./large-file.bam
214
- ```
215
-
216
- #### `biofs_upload`
217
- Upload a file to GenoBank S3 storage.
218
-
219
- ```typescript
220
- interface BiofsUploadParams {
221
- filePath: string;
222
- type?: "vcf" | "fastq" | "bam" | "pdf";
223
- tokenize?: boolean; // Mint as NFT after upload
224
- shareWith?: string; // Lab wallet to share with
225
- public?: boolean; // Make publicly discoverable
226
- }
227
-
228
- interface BiofsUploadResult {
229
- success: boolean;
230
- s3Path: string;
231
- biocid?: string; // If tokenized
232
- ipId?: string; // If tokenized
233
- sharedWith?: string; // If shared
234
- }
235
- ```
236
-
237
- **CLI Execution:**
238
- ```bash
239
- biofs upload ./genome.vcf --type vcf --tokenize --quiet
240
- ```
241
-
242
- ---
243
-
244
- ### Tokenization Tools
245
-
246
- #### `biofs_tokenize_file`
247
- Tokenize a genomic file as BioNFT on Sequentia.
248
-
249
- ```typescript
250
- interface BiofsTokenizeParams {
251
- filePath: string;
252
- title?: string;
253
- description?: string; // AI-generated if omitted
254
- license?: "commercial" | "non-commercial";
255
- collection?: string; // Collection address override
256
- noAi?: boolean; // Skip AI classification
257
- yes?: boolean; // Auto-confirm
258
- }
259
-
260
- interface BiofsTokenizeResult {
261
- success: boolean;
262
- biocid: string; // biocid://OWNER/bioip/IP_ID
263
- ipId: string; // Story Protocol IP ID
264
- nftAddress: string; // NFT contract address
265
- tokenId: string; // NFT token ID
266
- txHash: string; // Blockchain transaction hash
267
- fingerprint: string; // Bloom filter fingerprint
268
- collection: string; // Collection address
269
- license: string;
270
- }
271
- ```
272
-
273
- **MCP Tool Schema:**
274
- ```json
275
- {
276
- "name": "biofs_tokenize_file",
277
- "description": "Tokenize a genomic file as BioNFT with AI classification",
278
- "inputSchema": {
279
- "type": "object",
280
- "required": ["filePath"],
281
- "properties": {
282
- "filePath": { "type": "string" },
283
- "title": { "type": "string", "maxLength": 100 },
284
- "description": { "type": "string", "maxLength": 500 },
285
- "license": { "type": "string", "enum": ["commercial", "non-commercial"] },
286
- "collection": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }
287
- }
288
- }
289
- }
290
- ```
291
-
292
- **CLI Execution:**
293
- ```bash
294
- biofs tokenize file ./exome.vcf --license non-commercial --yes
295
- ```
296
-
297
- #### `biofs_tokenize_fastqs`
298
- Create BioNFT consent for existing FASTQ files.
299
-
300
- ```typescript
301
- interface BiofsTokenizeFastqsParams {
302
- biosampleSerial: string; // e.g., "55052008714000"
303
- recipient?: string; // Wallet to grant access
304
- license?: string;
305
- yes?: boolean;
306
- }
307
-
308
- interface BiofsTokenizeFastqsResult {
309
- success: boolean;
310
- biosampleSerial: string;
311
- biocid: string;
312
- txHash: string;
313
- filesIncluded: string[]; // List of FASTQ files
314
- accessGrantedTo?: string;
315
- }
316
- ```
317
-
318
- **CLI Execution:**
319
- ```bash
320
- biofs tokenize fastqs 55052008714000 --recipient 0xLabWallet --yes
321
- ```
322
-
323
- ---
324
-
325
- ### Access Control Tools
326
-
327
- #### `biofs_access_grant`
328
- Grant access to a BioNFT asset.
329
-
330
- ```typescript
331
- interface BiofsAccessGrantParams {
332
- biocidOrIpId: string;
333
- walletAddress: string;
334
- expiresIn?: string; // e.g., "30d", "90d", "1y"
335
- }
336
-
337
- interface BiofsAccessGrantResult {
338
- success: boolean;
339
- biocid: string;
340
- grantedTo: string;
341
- expiresAt: number; // Unix timestamp (0 = never)
342
- txHash: string;
343
- }
344
- ```
345
-
346
- **MCP Tool Schema:**
347
- ```json
348
- {
349
- "name": "biofs_access_grant",
350
- "description": "Grant access to a BioNFT asset (owner only)",
351
- "inputSchema": {
352
- "type": "object",
353
- "required": ["biocidOrIpId", "walletAddress"],
354
- "properties": {
355
- "biocidOrIpId": { "type": "string" },
356
- "walletAddress": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
357
- "expiresIn": { "type": "string", "pattern": "^\\d+[dmy]$" }
358
- }
359
- }
360
- }
361
- ```
362
-
363
- **CLI Execution:**
364
- ```bash
365
- biofs access grant biocid://0x.../bioip/123 0xResearcher --expires-in 90d
366
- ```
367
-
368
- #### `biofs_access_revoke`
369
- Revoke access from a wallet.
370
-
371
- ```typescript
372
- interface BiofsAccessRevokeParams {
373
- biocidOrIpId: string;
374
- walletAddress: string;
375
- yes?: boolean; // Skip confirmation
376
- }
377
- ```
378
-
379
- **CLI Execution:**
380
- ```bash
381
- biofs access revoke biocid://0x.../bioip/123 0xResearcher --yes
382
- ```
383
-
384
- #### `biofs_access_list`
385
- List permissions for an asset or accessible assets.
386
-
387
- ```typescript
388
- interface BiofsAccessListParams {
389
- biocidOrIpId?: string; // Optional: specific asset
390
- mine?: boolean; // List assets I can access
391
- status?: "active" | "pending" | "revoked";
392
- }
393
-
394
- interface AccessPermission {
395
- biocid: string;
396
- wallet: string;
397
- role: "owner" | "permittee";
398
- status: "active" | "pending" | "revoked";
399
- grantedAt: string;
400
- expiresAt: string | null;
401
- }
402
-
403
- interface BiofsAccessListResult {
404
- permissions: AccessPermission[];
405
- }
406
- ```
407
-
408
- **CLI Execution:**
409
- ```bash
410
- biofs access list biocid://0x.../bioip/123 --json
411
- biofs access list --mine --status active --json
412
- ```
413
-
414
- #### `biofs_access_check`
415
- Check access level to a specific asset.
416
-
417
- ```typescript
418
- interface BiofsAccessCheckParams {
419
- biocidOrIpId: string;
420
- }
421
-
422
- interface BiofsAccessCheckResult {
423
- hasAccess: boolean;
424
- accessLevel: "none" | "read" | "analyze" | "download" | "owner";
425
- expiresAt: string | null;
426
- operations: string[]; // ["read", "analyze", "download", "share"]
427
- }
428
- ```
429
-
430
- **CLI Execution:**
431
- ```bash
432
- biofs access check biocid://0x.../bioip/123
433
- ```
434
-
435
- ---
436
-
437
- ### Data Sharing Tools
438
-
439
- #### `biofs_share`
440
- Share a file with an approved lab.
441
-
442
- ```typescript
443
- interface BiofsShareParams {
444
- biocidOrFilename: string;
445
- lab: string; // Lab wallet address (required)
446
- license?: "non-commercial" | "commercial" | "commercial-remix";
447
- }
448
-
449
- interface BiofsShareResult {
450
- success: boolean;
451
- biocid: string;
452
- sharedWith: string;
453
- licenseType: string;
454
- txHash: string;
455
- labName?: string;
456
- }
457
- ```
458
-
459
- **MCP Tool Schema:**
460
- ```json
461
- {
462
- "name": "biofs_share",
463
- "description": "Share genomic file with approved research lab",
464
- "inputSchema": {
465
- "type": "object",
466
- "required": ["biocidOrFilename", "lab"],
467
- "properties": {
468
- "biocidOrFilename": { "type": "string" },
469
- "lab": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" },
470
- "license": {
471
- "type": "string",
472
- "enum": ["non-commercial", "commercial", "commercial-remix"],
473
- "default": "non-commercial"
474
- }
475
- }
476
- }
477
- }
478
- ```
479
-
480
- **CLI Execution:**
481
- ```bash
482
- biofs share sample.vcf --lab 0xLabWallet --license non-commercial
483
- ```
484
-
485
- #### `biofs_list_labs`
486
- List approved research labs.
487
-
488
- ```typescript
489
- interface BiofsListLabsParams {
490
- filter?: string; // Specialization filter
491
- location?: string;
492
- }
493
-
494
- interface Lab {
495
- wallet: string;
496
- name: string;
497
- specialization: string;
498
- location: string;
499
- website?: string;
500
- email?: string;
501
- accessLevel: "RESEARCH_ONLY" | "CLINICAL_NON_CRITICAL" | "CLINICAL_CRITICAL" | "COMMERCIAL";
502
- ga4ghLevel: "NONE" | "BASIC" | "LITE" | "FULL";
503
- reputation: number; // 0-100
504
- }
505
-
506
- interface BiofsListLabsResult {
507
- labs: Lab[];
508
- }
509
- ```
510
-
511
- **CLI Execution:**
512
- ```bash
513
- biofs labnfts --json
514
- biofs labnfts --filter cancer --json
515
- ```
516
-
517
- ---
518
-
519
- ### Research Job Tools
520
-
521
- #### `biofs_job_create`
522
- Create a genomic analysis job.
523
-
524
- ```typescript
525
- interface BiofsJobCreateParams {
526
- prompt: string; // Natural language description
527
- fileRef: string; // BioCID or filename
528
- pipeline?: string; // Pipeline template name
529
- }
530
-
531
- interface BiofsJobCreateResult {
532
- success: boolean;
533
- jobId: string;
534
- status: "pending";
535
- pipeline: string;
536
- estimatedCost: number; // USDC
537
- estimatedTime: string; // e.g., "30 minutes"
538
- }
539
- ```
540
-
541
- **MCP Tool Schema:**
542
- ```json
543
- {
544
- "name": "biofs_job_create",
545
- "description": "Create genomic analysis job from natural language prompt",
546
- "inputSchema": {
547
- "type": "object",
548
- "required": ["prompt", "fileRef"],
549
- "properties": {
550
- "prompt": { "type": "string", "minLength": 10 },
551
- "fileRef": { "type": "string" },
552
- "pipeline": { "type": "string" }
553
- }
554
- }
555
- }
556
- ```
557
-
558
- **CLI Execution:**
559
- ```bash
560
- biofs job create "Find pathogenic BRCA variants" exome.vcf --json
561
- ```
562
-
563
- #### `biofs_job_status`
564
- Check job execution status.
565
-
566
- ```typescript
567
- interface BiofsJobStatusParams {
568
- jobId: string;
569
- }
570
-
571
- interface BiofsJobStatusResult {
572
- jobId: string;
573
- status: "pending" | "assigned" | "in_progress" | "completed" | "failed";
574
- progress: number; // 0-100
575
- currentStep?: string;
576
- startedAt?: string;
577
- completedAt?: string;
578
- error?: string;
579
- assignedLab?: string;
580
- }
581
- ```
582
-
583
- **CLI Execution:**
584
- ```bash
585
- biofs job status abc123 --json
586
- ```
587
-
588
- #### `biofs_job_results`
589
- Get job results and download URLs.
590
-
591
- ```typescript
592
- interface BiofsJobResultsParams {
593
- jobId: string;
594
- step?: number; // Specific step
595
- }
596
-
597
- interface JobResult {
598
- step: number;
599
- name: string;
600
- status: "completed" | "failed";
601
- outputFiles: {
602
- filename: string;
603
- biocid?: string;
604
- downloadUrl: string;
605
- size: number;
606
- }[];
607
- }
608
-
609
- interface BiofsJobResultsResult {
610
- jobId: string;
611
- status: "completed";
612
- results: JobResult[];
613
- totalCost: number; // USDC charged
614
- }
615
- ```
616
-
617
- **CLI Execution:**
618
- ```bash
619
- biofs job results abc123 --json
620
- ```
621
-
622
- #### `biofs_job_submit_clara`
623
- Submit Clara Parabricks GPU job (FASTQ → VCF).
624
-
625
- ```typescript
626
- interface BiofsJobSubmitClaraParams {
627
- biosampleId: string;
628
- fastqR1?: string; // Auto-discovered if omitted
629
- fastqR2?: string;
630
- jobId?: string; // Custom job ID
631
- reference?: string; // Default: "hg38"
632
- captureKit?: string; // Default: "agilent_v8"
633
- sequencingType?: "WES" | "WGS";
634
- intervalFile?: string; // BED file path
635
- }
636
-
637
- interface BiofsJobSubmitClaraResult {
638
- success: boolean;
639
- jobId: string;
640
- biosampleId: string;
641
- fastqFiles: string[];
642
- reference: string;
643
- estimatedTime: string;
644
- txHash?: string;
645
- }
646
- ```
647
-
648
- **CLI Execution:**
649
- ```bash
650
- biofs job submit-clara 55052008714000 --sequencing-type WES --json
651
- ```
652
-
653
- ---
654
-
655
- ### GDPR Compliance Tools
656
-
657
- #### `biofs_verify`
658
- Verify file integrity using DNA fingerprint.
659
-
660
- ```typescript
661
- interface BiofsVerifyParams {
662
- biocidOrFilename: string;
663
- localFile: string;
664
- }
665
-
666
- interface BiofsVerifyResult {
667
- match: boolean;
668
- storedFingerprint: string;
669
- computedFingerprint: string;
670
- similarity: number; // 0-100
671
- }
672
- ```
673
-
674
- **CLI Execution:**
675
- ```bash
676
- biofs verify biocid://0x.../bioip/123 ./local-copy.vcf --json
677
- ```
678
-
679
- #### `biofs_dissect`
680
- Extract phenotype-specific SNP subset (data minimization).
681
-
682
- ```typescript
683
- interface BiofsDissectParams {
684
- phenotypeQuery: string; // e.g., "cardiovascular risk"
685
- sourceFile: string;
686
- share?: string; // Wallet to share derivative
687
- license?: string;
688
- minSnps?: number; // Default: 10
689
- output?: string; // Local output path
690
- }
691
-
692
- interface BiofsDissectResult {
693
- success: boolean;
694
- sourceFile: string;
695
- derivativeFile: string;
696
- snpsExtracted: number;
697
- phenotypes: string[];
698
- biocid?: string; // If tokenized
699
- sharedWith?: string;
700
- }
701
- ```
702
-
703
- **CLI Execution:**
704
- ```bash
705
- biofs dissect "cardiovascular variants" exome.vcf --share 0xResearcher --json
706
- ```
707
-
708
- #### `biofs_revoke_consent`
709
- Revoke consent for data access (GDPR Right to Withdraw).
710
-
711
- ```typescript
712
- interface BiofsRevokeConsentParams {
713
- ipId?: string; // Specific asset
714
- all?: boolean; // Revoke all consents
715
- force?: boolean; // Skip confirmation
716
- }
717
-
718
- interface BiofsRevokeConsentResult {
719
- success: boolean;
720
- revokedAssets: string[];
721
- txHashes: string[];
722
- }
723
- ```
724
-
725
- **CLI Execution:**
726
- ```bash
727
- biofs access revoke-consent --all --force
728
- ```
729
-
730
- ---
731
-
732
- ### Utility Tools
733
-
734
- #### `biofs_report`
735
- Generate diagnostic health check.
736
-
737
- ```typescript
738
- interface BiofsReportResult {
739
- authentication: {
740
- authenticated: boolean;
741
- wallet: string | null;
742
- };
743
- network: {
744
- sequentiaConnected: boolean;
745
- rpcUrl: string;
746
- blockNumber: number;
747
- };
748
- storage: {
749
- s3Connected: boolean;
750
- bucket: string;
751
- };
752
- agent: {
753
- available: boolean;
754
- url: string;
755
- gpuStatus?: string;
756
- };
757
- }
758
- ```
759
-
760
- **CLI Execution:**
761
- ```bash
762
- biofs report --json
763
- ```
764
-
765
- #### `biofs_agent_health`
766
- Check GPU processing agent status.
767
-
768
- ```typescript
769
- interface BiofsAgentHealthResult {
770
- available: boolean;
771
- url: string;
772
- gpuModel?: string;
773
- gpuMemory?: number;
774
- queueLength: number;
775
- estimatedWait: string;
776
- }
777
- ```
778
-
779
- **CLI Execution:**
780
- ```bash
781
- biofs agent-health --json
782
- ```
783
-
784
- ---
785
-
786
- ## Error Handling
787
-
788
- All tools return structured errors:
789
-
790
- ```typescript
791
- interface BiofsError {
792
- success: false;
793
- error: {
794
- code: string; // e.g., "AUTH_REQUIRED", "ACCESS_DENIED"
795
- message: string;
796
- details?: any;
797
- };
798
- }
799
- ```
800
-
801
- **Common Error Codes:**
802
-
803
- | Code | Description | Resolution |
804
- |------|-------------|------------|
805
- | `AUTH_REQUIRED` | Not authenticated | Call `biofs_login` |
806
- | `AUTH_EXPIRED` | Session expired | Call `biofs_login` |
807
- | `ACCESS_DENIED` | No permission for asset | Request access or check ownership |
808
- | `FILE_NOT_FOUND` | File doesn't exist | Verify BioCID or filename |
809
- | `CONSENT_REQUIRED` | GDPR consent needed | User must provide consent |
810
- | `CONSENT_REVOKED` | Consent was revoked | Contact data owner |
811
- | `NETWORK_ERROR` | Blockchain connection failed | Check RPC URL |
812
- | `INSUFFICIENT_FUNDS` | Not enough USDC | Top up wallet |
813
- | `JOB_FAILED` | Analysis job failed | Check job logs |
814
-
815
- ---
816
-
817
- ## Workflow Examples
818
-
819
- ### Workflow 1: Download and Analyze VCF
820
-
821
- ```typescript
822
- // 1. Check authentication
823
- const session = await biofs_whoami();
824
- if (!session.authenticated) {
825
- await biofs_login({ wallet: userWallet, signature: userSig });
826
- }
827
-
828
- // 2. List available VCF files
829
- const files = await biofs_list_files({ filter: "vcf" });
830
-
831
- // 3. Download file
832
- const download = await biofs_download({
833
- biocidOrFilename: files.files[0].biocid,
834
- destination: "/tmp/analysis/",
835
- skipConsent: true // For automation
836
- });
837
-
838
- // 4. Submit analysis job
839
- const job = await biofs_job_create({
840
- prompt: "Find pathogenic variants in cancer genes",
841
- fileRef: download.localPath
842
- });
843
-
844
- // 5. Poll for completion
845
- let status;
846
- do {
847
- status = await biofs_job_status({ jobId: job.jobId });
848
- await sleep(5000);
849
- } while (status.status !== "completed" && status.status !== "failed");
850
-
851
- // 6. Get results
852
- const results = await biofs_job_results({ jobId: job.jobId });
853
- ```
854
-
855
- ### Workflow 2: Tokenize and Share FASTQ
856
-
857
- ```typescript
858
- // 1. Tokenize existing FASTQ files
859
- const tokenized = await biofs_tokenize_fastqs({
860
- biosampleSerial: "55052008714000",
861
- license: "non-commercial",
862
- yes: true
863
- });
864
-
865
- // 2. Find approved labs
866
- const labs = await biofs_list_labs({ filter: "cancer" });
867
-
868
- // 3. Grant access to lab
869
- const access = await biofs_access_grant({
870
- biocidOrIpId: tokenized.biocid,
871
- walletAddress: labs.labs[0].wallet,
872
- expiresIn: "90d"
873
- });
874
-
875
- // 4. Submit Clara job
876
- const job = await biofs_job_submit_clara({
877
- biosampleId: "55052008714000",
878
- sequencingType: "WES"
879
- });
880
- ```
881
-
882
- ### Workflow 3: GDPR Data Subject Request
883
-
884
- ```typescript
885
- // 1. List all user's data
886
- const files = await biofs_list_files({ update: true });
887
-
888
- // 2. List all access permissions
889
- const access = await biofs_access_list({ mine: true });
890
-
891
- // 3. Export data (Right to Access)
892
- for (const file of files.files) {
893
- await biofs_download({
894
- biocidOrFilename: file.biocid,
895
- destination: "/export/"
896
- });
897
- }
898
-
899
- // 4. Revoke all consents (Right to Withdraw)
900
- await biofs_revoke_consent({ all: true, force: true });
901
- ```
902
-
903
- ---
904
-
905
- ## MCP Server Implementation
906
-
907
- ### Server Configuration
908
-
909
- ```json
910
- {
911
- "name": "biofs-mcp-server",
912
- "version": "1.0.0",
913
- "description": "MCP server for BioFS genomic data management",
914
- "tools": [
915
- "biofs_login",
916
- "biofs_whoami",
917
- "biofs_list_files",
918
- "biofs_download",
919
- "biofs_upload",
920
- "biofs_tokenize_file",
921
- "biofs_tokenize_fastqs",
922
- "biofs_access_grant",
923
- "biofs_access_revoke",
924
- "biofs_access_list",
925
- "biofs_access_check",
926
- "biofs_share",
927
- "biofs_list_labs",
928
- "biofs_job_create",
929
- "biofs_job_status",
930
- "biofs_job_results",
931
- "biofs_job_submit_clara",
932
- "biofs_verify",
933
- "biofs_dissect",
934
- "biofs_revoke_consent",
935
- "biofs_report",
936
- "biofs_agent_health"
937
- ]
938
- }
939
- ```
940
-
941
- ### Tool Execution Pattern
942
-
943
- ```typescript
944
- async function executeBiofsTool(
945
- toolName: string,
946
- params: Record<string, any>
947
- ): Promise<any> {
948
- // Build CLI command
949
- const args = buildCLIArgs(toolName, params);
950
-
951
- // Execute with JSON output
952
- const result = await exec(`biofs ${args} --json`);
953
-
954
- // Parse and return
955
- return JSON.parse(result.stdout);
956
- }
957
-
958
- function buildCLIArgs(toolName: string, params: Record<string, any>): string {
959
- const toolToCommand: Record<string, string> = {
960
- "biofs_login": "login",
961
- "biofs_whoami": "whoami",
962
- "biofs_list_files": "biofiles",
963
- "biofs_download": "download",
964
- "biofs_upload": "upload",
965
- "biofs_tokenize_file": "tokenize file",
966
- "biofs_tokenize_fastqs": "tokenize fastqs",
967
- "biofs_access_grant": "access grant",
968
- "biofs_access_revoke": "access revoke",
969
- "biofs_access_list": "access list",
970
- "biofs_access_check": "access check",
971
- "biofs_share": "share",
972
- "biofs_list_labs": "labnfts",
973
- "biofs_job_create": "job create",
974
- "biofs_job_status": "job status",
975
- "biofs_job_results": "job results",
976
- "biofs_job_submit_clara": "job submit-clara",
977
- "biofs_verify": "verify",
978
- "biofs_dissect": "dissect",
979
- "biofs_revoke_consent": "access revoke-consent",
980
- "biofs_report": "report",
981
- "biofs_agent_health": "agent-health"
982
- };
983
-
984
- let cmd = toolToCommand[toolName];
985
-
986
- // Add positional arguments
987
- // Add options with --flag format
988
- // ...
989
-
990
- return cmd;
991
- }
992
- ```
993
-
994
- ---
995
-
996
- ## Rate Limits & Best Practices
997
-
998
- ### Rate Limits
999
- | Operation | Limit |
1000
- |-----------|-------|
1001
- | Authentication | 10/minute |
1002
- | File listing | 60/minute |
1003
- | Downloads | 100/hour |
1004
- | Uploads | 50/hour |
1005
- | Tokenization | 20/hour |
1006
- | Job submission | 10/hour |
1007
-
1008
- ### Best Practices for AI Agents
1009
-
1010
- 1. **Cache authentication**: Store session credentials, don't re-authenticate per request
1011
- 2. **Use JSON output**: Always add `--json` for structured parsing
1012
- 3. **Handle consent**: For automation, use `--skip-consent` only when user has pre-approved
1013
- 4. **Poll with backoff**: When checking job status, use exponential backoff
1014
- 5. **Verify before processing**: Use `biofs_verify` before analyzing downloaded files
1015
- 6. **Respect GDPR**: Always provide data minimization options to users
1016
-
1017
- ---
1018
-
1019
- ## Support
1020
-
1021
- - **API Documentation**: https://docs.genobank.io/biofs/api
1022
- - **MCP Server Source**: https://github.com/Genobank/biofs-mcp-server
1023
- - **Issues**: https://github.com/Genobank/biofs-cli/issues
1024
-
1025
- ---
1026
-
1027
- *BioFS CLI v2.4.1 - GenoBank.io Sequentia Protocol*
1028
-
1029
-