Merge pull request #13 from Beyond-Better/staging

cngarrison · web-flow · commit 576915fac42f · 2025-10-06T00:00:41.000+11:00
Proper docs for exported modules
diff --git a/deno.jsonc b/deno.jsonc
@@ -1,6 +1,6 @@
 {
   "name": "@beyondbetter/bb-mcp-server",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Comprehensive library for building Deno-based MCP servers",
   "license": "MIT",
   "copyright": "2025 - Beyond Better <charlie@beyondbetter.app>",
diff --git a/examples/1-simple/main.ts b/examples/1-simple/main.ts
@@ -1,7 +1,9 @@
-#!/usr/bin/env -S deno run --allow-all
+#!/usr/bin/env -S deno run --allow-all --unstable-kv
 
 /**
- * Simple MCP Server - Minimal Setup with Basic Plugin Tools
+ * @module examples/1-simple
+ * 
+ * # Simple MCP Server - Minimal Setup with Basic Plugin Tools
  *
  * This demonstrates the simplest approach for bb-mcp-server:
  * - Zero custom dependencies (uses library defaults)
@@ -53,10 +55,10 @@
  * ======
  *
  * # STDIO transport (default):
- * deno run --allow-all main.ts
+ * deno run --allow-all --unstable-kv main.ts
  *
  * # HTTP transport:
- * MCP_TRANSPORT=http deno run --allow-all main.ts
+ * MCP_TRANSPORT=http deno run --allow-all --unstable-kv main.ts
  * # Then access: http://localhost:3000
  *
  * NEXT STEPS:
@@ -66,6 +68,34 @@
  * 1. Try 2-plugin-workflows to learn about multi-step processes
  * 2. Explore 3-plugin-api-auth for external API integration
  * 3. Study 4-manual-deps for complete infrastructure control
+ * 
+ * @example Run this example directly from JSR
+ * ```bash
+ * # Run with STDIO transport (default)
+ * deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/1-simple
+ * 
+ * # Run with HTTP transport
+ * MCP_TRANSPORT=http deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/1-simple
+ * ```
+ * 
+ * @example Basic server setup
+ * ```typescript
+ * import { AppServer } from 'jsr:@beyondbetter/bb-mcp-server';
+ * 
+ * const appServer = await AppServer.create({
+ *   serverConfig: {
+ *     name: 'my-mcp-server',
+ *     version: '1.0.0',
+ *     title: 'My MCP Server',
+ *     description: 'My custom MCP server',
+ *   },
+ * });
+ * 
+ * await appServer.start();
+ * ```
+ * 
+ * @see {@link https://github.com/beyond-better/bb-mcp-server/tree/main/examples/1-simple | Full example documentation}
+ * @see {@link https://github.com/beyond-better/bb-mcp-server/tree/main/examples | All examples}
  */
 
 // Import the bb-mcp-server library - handles ALL infrastructure
diff --git a/examples/2-plugin-workflows/main.ts b/examples/2-plugin-workflows/main.ts
@@ -1,7 +1,9 @@
-#!/usr/bin/env -S deno run --allow-all
+#!/usr/bin/env -S deno run --allow-all --unstable-kv
 
 /**
- * Plugin-Workflows MCP Server - Multi-Step Workflow Demonstrations
+ * @module examples/2-plugin-workflows
+ * 
+ * # Plugin-Workflows MCP Server - Multi-Step Workflow Demonstrations
  *
  * This demonstrates advanced workflow capabilities with bb-mcp-server:
  * - Multi-step workflow implementations with state management
@@ -63,14 +65,14 @@
  * ======
  *
  * # STDIO transport (default):
- * deno run --allow-all main.ts
+ * deno run --allow-all --unstable-kv main.ts
  *
  * # HTTP transport:
- * MCP_TRANSPORT=http deno run --allow-all main.ts
+ * MCP_TRANSPORT=http deno run --allow-all --unstable-kv main.ts
  * # Then access: http://localhost:3000
  *
  * # Test workflows:
- * deno test --allow-all src/tests/
+ * deno test --allow-all --unstable-kv src/tests/
  *
  * WORKFLOW EXAMPLES:
  * ==================
@@ -108,6 +110,30 @@
  * 1. Try 3-plugin-api-auth to learn OAuth and external API integration
  * 2. Explore 4-manual-deps for complete infrastructure control
  * 3. Build your own workflows for specific business processes
+ * 
+ * @example Run this example directly from JSR
+ * ```bash
+ * # Run with STDIO transport (default)
+ * deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/2-plugin-workflows
+ * 
+ * # Run with HTTP transport
+ * MCP_TRANSPORT=http deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/2-plugin-workflows
+ * ```
+ * 
+ * @example Execute a workflow
+ * ```typescript
+ * // Data processing workflow example
+ * const result = await workflow.execute({
+ *   userId: 'user123',
+ *   data: [{name: 'Alice', score: 95}],
+ *   transformations: ['normalize', 'sort'],
+ *   outputFormat: 'json',
+ *   analysisType: 'summary'
+ * });
+ * ```
+ * 
+ * @see {@link https://github.com/beyond-better/bb-mcp-server/tree/main/examples/2-plugin-workflows | Full example documentation}
+ * @see {@link https://github.com/beyond-better/bb-mcp-server/tree/main/examples/1-simple | Previous example: Simple MCP Server}
  */
 
 // Import the bb-mcp-server library - handles ALL infrastructure
@@ -155,7 +181,7 @@ async function main(): Promise<void> {
     console.log('   - content_generation_pipeline (plan → generate → review → publish)');
     console.log('🛠️ Available tools: current_datetime, validate_json');
     console.log('🔄 Transport:', process.env.MCP_TRANSPORT || 'stdio');
-    console.log('🧪 Run tests: deno test --allow-all src/tests/');
+    console.log('🧪 Run tests: deno test --allow-all --unstable-kv src/tests/');
   } catch (error) {
     console.error('❌ Failed to start Plugin-Workflows MCP Server:', error);
     Deno.exit(1);
diff --git a/examples/3-plugin-api-auth/main.ts b/examples/3-plugin-api-auth/main.ts
@@ -1,7 +1,9 @@
-#!/usr/bin/env -S deno run --allow-all
+#!/usr/bin/env -S deno run --allow-all --unstable-kv
 
 /**
- * Plugin-API-Auth MCP Server - OAuth and External API Integration
+ * @module examples/3-plugin-api-auth
+ * 
+ * # Plugin-API-Auth MCP Server - OAuth and External API Integration
  *
  * This demonstrates advanced capabilities with bb-mcp-server:
  * - OAuth authentication with external APIs
@@ -53,10 +55,10 @@
  * ======
  *
  * # STDIO transport:
- * deno run --allow-all main.ts
+ * deno run --allow-all --unstable-kv main.ts
  *
  * # HTTP transport with OAuth endpoints:
- * MCP_TRANSPORT=http deno run --allow-all main.ts
+ * MCP_TRANSPORT=http deno run --allow-all --unstable-kv main.ts
  * # Then access: http://localhost:3000
  *
  * NEXT STEPS:
@@ -66,6 +68,36 @@
  * 1. Try 4-manual-deps for complete infrastructure control
  * 2. Build your own OAuth integrations for different providers
  * 3. Implement custom authentication and API patterns
+ * 
+ * @example Run this example directly from JSR (requires OAuth credentials)
+ * ```bash
+ * # Set up OAuth credentials first
+ * export OAUTH_CONSUMER_CLIENT_ID=your-client-id
+ * export OAUTH_CONSUMER_CLIENT_SECRET=your-client-secret
+ * 
+ * # Run with STDIO transport
+ * deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/3-plugin-api-auth
+ * 
+ * # Run with HTTP transport (includes OAuth endpoints)
+ * MCP_TRANSPORT=http deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/3-plugin-api-auth
+ * ```
+ * 
+ * @example Custom OAuth consumer setup
+ * ```typescript
+ * import { OAuthConsumer } from 'jsr:@beyondbetter/bb-mcp-server';
+ * 
+ * const oauthConsumer = new ExampleOAuthConsumer({
+ *   provider: 'examplecorp',
+ *   authUrl: 'https://api.example.com/oauth/authorize',
+ *   tokenUrl: 'https://api.example.com/oauth/token',
+ *   clientId: process.env.OAUTH_CONSUMER_CLIENT_ID,
+ *   clientSecret: process.env.OAUTH_CONSUMER_CLIENT_SECRET,
+ *   scopes: ['read', 'write'],
+ * });
+ * ```
+ * 
+ * @see {@link https://github.com/beyond-better/bb-mcp-server/tree/main/examples/3-plugin-api-auth | Full example documentation}
+ * @see {@link https://github.com/beyond-better/bb-mcp-server/tree/main/examples/2-plugin-workflows | Previous example: Multi-step Workflows}
  */
 
 // Import the bb-mcp-server library - handles ALL infrastructure
diff --git a/examples/4-manual-deps/main.ts b/examples/4-manual-deps/main.ts
@@ -1,7 +1,9 @@
-#!/usr/bin/env -S deno run --allow-all
+#!/usr/bin/env -S deno run --allow-all --unstable-kv
 
 /**
- * Manual-Deps MCP Server - Complete Infrastructure Control
+ * @module examples/4-manual-deps
+ * 
+ * # Manual-Deps MCP Server - Complete Infrastructure Control
  *
  * This demonstrates expert-level capabilities with bb-mcp-server:
  * - Complete control over dependency creation and configuration
@@ -50,10 +52,10 @@
  * ======
  *
  * # STDIO transport:
- * deno run --allow-all main.ts
+ * deno run --allow-all --unstable-kv main.ts
  *
  * # HTTP transport with OAuth endpoints:
- * MCP_TRANSPORT=http deno run --allow-all main.ts
+ * MCP_TRANSPORT=http deno run --allow-all --unstable-kv main.ts
  * # Then access: http://localhost:3000
  *
  * EXPERT PATTERNS:
@@ -64,6 +66,39 @@
  * - Manual registration within library lifecycle
  * - Advanced configuration and environment handling
  * - Integration with existing enterprise infrastructure
+ * 
+ * @example Run this example directly from JSR
+ * ```bash
+ * # Run with STDIO transport (default)
+ * deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/4-manual-deps
+ * 
+ * # Run with HTTP transport and OAuth endpoints
+ * MCP_TRANSPORT=http deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/4-manual-deps
+ * ```
+ * 
+ * @example Manual dependency creation
+ * ```typescript
+ * import { AppServer } from 'jsr:@beyondbetter/bb-mcp-server';
+ * 
+ * // Custom dependency function with complete control
+ * async function createManualDependencies(baseConfig) {
+ *   // Manually create all dependencies
+ *   const toolRegistry = await getToolRegistry(logger, errorHandler);
+ *   const workflowRegistry = await getWorkflowRegistry(logger, errorHandler);
+ *   
+ *   // Manual registration with custom logic
+ *   toolRegistry.registerTool('my_tool', definition, handler);
+ *   workflowRegistry.registerWorkflow(myWorkflow);
+ *   
+ *   return { toolRegistry, workflowRegistry, ...otherDeps };
+ * }
+ * 
+ * const appServer = await AppServer.create(createManualDependencies);
+ * await appServer.start();
+ * ```
+ * 
+ * @see {@link https://github.com/beyond-better/bb-mcp-server/tree/main/examples/4-manual-deps | Full example documentation}
+ * @see {@link https://github.com/beyond-better/bb-mcp-server/tree/main/examples/3-plugin-api-auth | Previous example: OAuth and API Integration}
  */
 
 // Import the bb-mcp-server library
diff --git a/examples/chunked-storage-demo/main.ts b/examples/chunked-storage-demo/main.ts
@@ -1,14 +1,62 @@
 /**
- * Chunked Storage Demo - MCP Server with Large Message Support
+ * @module examples/chunked-storage-demo
+ * 
+ * # Chunked Storage Demo - MCP Server with Large Message Support
  *
  * This example demonstrates how to use the TransportEventStoreChunked
  * to handle large messages that exceed Deno KV's 64KB limit.
  *
  * Features demonstrated:
- * - Automatic chunking of large messages
- * - Compression for efficient storage
+ * - Automatic chunking of large messages (60KB chunks)
+ * - Compression for efficient storage (gzip)
  * - Monitoring and statistics
  * - Error handling for oversized messages
+ * 
+ * The chunked storage system automatically splits messages larger than 60KB into
+ * smaller chunks, stores them separately in Deno KV, and reassembles them on retrieval.
+ * Compression is applied when beneficial (typically 20-80% size reduction for text).
+ * 
+ * @example Run this example directly from JSR
+ * ```bash
+ * # Run with STDIO transport (default)
+ * deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/chunked-storage-demo
+ * 
+ * # Run with HTTP transport
+ * MCP_TRANSPORT=http deno run --allow-all --unstable-kv jsr:@beyondbetter/bb-mcp-server/examples/chunked-storage-demo
+ * ```
+ * 
+ * @example Test large message handling
+ * ```bash
+ * # After starting the server, use MCP client to generate large messages:
+ * # Generate a 500KB JSON message
+ * generate_large_message({"size": 500, "content": "json"})
+ * 
+ * # Check storage statistics
+ * get_storage_stats({})
+ * 
+ * # Generate very large message (2MB)
+ * generate_large_message({"size": 2048, "content": "mixed"})
+ * ```
+ * 
+ * @example Using chunked storage in your project
+ * ```typescript
+ * import { TransportEventStoreChunked, KVManager } from 'jsr:@beyondbetter/bb-mcp-server';
+ * 
+ * const eventStore = new TransportEventStoreChunked(
+ *   kvManager,
+ *   ['events'],
+ *   logger,
+ *   {
+ *     maxChunkSize: 60 * 1024,           // 60KB chunks
+ *     enableCompression: true,            // Enable gzip compression
+ *     compressionThreshold: 1024,         // Compress messages > 1KB
+ *     maxMessageSize: 10 * 1024 * 1024,  // 10MB max message size
+ *   },
+ * );
+ * ```
+ * 
+ * @see {@link https://github.com/beyond-better/bb-mcp-server/tree/main/examples/chunked-storage-demo | Full example documentation}
+ * @see {@link https://github.com/beyond-better/bb-mcp-server/tree/main/examples | All examples}
  */
 
 import {

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@beyondbetter/bb-mcp-server",`
`3`		`- "version": "0.1.5",`
	`3`	`+ "version": "0.1.6",`
`4`	`4`	`"description": "Comprehensive library for building Deno-based MCP servers",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"copyright": "2025 - Beyond Better <charlie@beyondbetter.app>",`