s3db.js 12.0.0 → 12.1.0

package/mcp/entrypoint.js

@@ -2,7 +2,7 @@
 
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
 import { S3db, CachePlugin, CostsPlugin } from '../dist/s3db.es.js';
 import { FilesystemCache } from '../src/plugins/cache/filesystem-cache.class.js';
@@ -10,6 +10,7 @@ import { config } from 'dotenv';
 import { fileURLToPath } from 'url';
 import { dirname, join } from 'path';
 import { readFileSync } from 'fs';
+import express from 'express';
 
 // Load environment variables
 config();
@@ -1109,70 +1110,103 @@ class S3dbMCPServer {
   }
 
   setupTransport() {
-    const transport = process.argv.includes('--transport=sse') || process.env.MCP_TRANSPORT === 'sse'
-      ? new SSEServerTransport('/sse', process.env.MCP_SERVER_HOST || '0.0.0.0', parseInt(process.env.MCP_SERVER_PORT || '17500'))
-      : new StdioServerTransport();
-
-    this.server.connect(transport);
-    
-    // SSE specific setup
-    if (transport instanceof SSEServerTransport) {
-      const host = process.env.MCP_SERVER_HOST || '0.0.0.0';
-      const port = process.env.MCP_SERVER_PORT || '17500';
-      
-      console.log(`S3DB MCP Server running on http://${host}:${port}/sse`);
-      
-      // Add health check endpoint for SSE transport
-      this.setupHealthCheck(host, port);
+    const useHttp = process.argv.includes('--transport=http') || process.env.MCP_TRANSPORT === 'http';
+
+    if (useHttp) {
+      // Setup Express server for Streamable HTTP transport
+      this.setupHttpTransport();
+    } else {
+      // Use stdio transport (default)
+      const transport = new StdioServerTransport();
+      this.server.connect(transport);
     }
   }
 
-  setupHealthCheck(host, port) {
-    import('http').then(({ createServer }) => {
-      const healthServer = createServer((req, res) => {
-        if (req.url === '/health') {
-          const healthStatus = {
-            status: 'healthy',
-            timestamp: new Date().toISOString(),
-            uptime: process.uptime(),
-            version: SERVER_VERSION,
-            database: {
-              connected: database ? database.isConnected() : false,
-              bucket: database?.bucket || null,
-              keyPrefix: database?.keyPrefix || null,
-              resourceCount: database ? Object.keys(database.resources || {}).length : 0
-            },
-            memory: process.memoryUsage(),
-            environment: {
-              nodeVersion: process.version,
-              platform: process.platform,
-              transport: 'sse'
-            }
-          };
+  setupHttpTransport() {
+    const host = process.env.MCP_SERVER_HOST || '0.0.0.0';
+    const port = parseInt(process.env.MCP_SERVER_PORT || '17500');
+
+    const app = express();
+    app.use(express.json());
+
+    // Enable CORS for browser-based clients
+    app.use((req, res, next) => {
+      res.header('Access-Control-Allow-Origin', '*');
+      res.header('Access-Control-Allow-Methods', 'GET, POST, DELETE, OPTIONS');
+      res.header('Access-Control-Allow-Headers', 'Content-Type, Mcp-Session-Id');
+      res.header('Access-Control-Expose-Headers', 'Mcp-Session-Id');
+
+      if (req.method === 'OPTIONS') {
+        return res.sendStatus(200);
+      }
+      next();
+    });
+
+    // Streamable HTTP endpoint (stateless mode - recommended)
+    app.post('/mcp', async (req, res) => {
+      try {
+        // Create a new transport for each request to prevent request ID collisions
+        const transport = new StreamableHTTPServerTransport({
+          sessionIdGenerator: undefined,
+          enableJsonResponse: true
+        });
+
+        res.on('close', () => {
+          transport.close();
+        });
 
-          res.writeHead(200, {
-            'Content-Type': 'application/json',
-            'Access-Control-Allow-Origin': '*',
-            'Access-Control-Allow-Methods': 'GET',
-            'Access-Control-Allow-Headers': 'Content-Type'
+        await this.server.connect(transport);
+        await transport.handleRequest(req, res, req.body);
+      } catch (error) {
+        console.error('Error handling MCP request:', error);
+        if (!res.headersSent) {
+          res.status(500).json({
+            jsonrpc: '2.0',
+            error: {
+              code: -32603,
+              message: 'Internal server error'
+            },
+            id: null
           });
-          res.end(JSON.stringify(healthStatus, null, 2));
-        } else {
-          res.writeHead(404, { 'Content-Type': 'text/plain' });
-          res.end('Not Found');
         }
-      });
+      }
+    });
 
-      // Listen on a different port for health checks to avoid conflicts
-      const healthPort = parseInt(port) + 1;
-      healthServer.listen(healthPort, host, () => {
-        console.log(`Health check endpoint: http://${host}:${healthPort}/health`);
-      });
-    }).catch(err => {
-      console.warn('Could not setup health check endpoint:', err.message);
+    // Health check endpoint
+    app.get('/health', (req, res) => {
+      const healthStatus = {
+        status: 'healthy',
+        timestamp: new Date().toISOString(),
+        uptime: process.uptime(),
+        version: SERVER_VERSION,
+        database: {
+          connected: database ? database.isConnected() : false,
+          bucket: database?.bucket || null,
+          keyPrefix: database?.keyPrefix || null,
+          resourceCount: database ? Object.keys(database.resources || {}).length : 0
+        },
+        memory: process.memoryUsage(),
+        environment: {
+          nodeVersion: process.version,
+          platform: process.platform,
+          transport: 'streamable-http'
+        }
+      };
+
+      res.json(healthStatus);
+    });
+
+    // Start Express server
+    app.listen(port, host, () => {
+      console.log(`S3DB MCP Server running on http://${host}:${port}/mcp`);
+      console.log(`Health check endpoint: http://${host}:${port}/health`);
+    }).on('error', error => {
+      console.error('Server error:', error);
+      process.exit(1);
     });
   }
 
+
   // 📖 DOCUMENTATION TOOLS HANDLERS
 
   async handleS3dbQueryDocs(args) {
@@ -2718,8 +2752,8 @@ async function main() {
 
   console.log(`S3DB MCP Server v${SERVER_VERSION} started`);
   console.log(`Transport: ${args.transport}`);
-  if (args.transport === 'sse') {
-    console.log(`URL: http://${args.host}:${args.port}/sse`);
+  if (args.transport === 'http') {
+    console.log(`URL: http://${args.host}:${args.port}/mcp`);
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "s3db.js",
-  "version": "12.0.0",
+  "version": "12.1.0",
   "description": "Use AWS S3, the world's most reliable document storage, as a database with this ORM.",
   "main": "dist/s3db.cjs.js",
   "module": "dist/s3db.es.js",
@@ -65,11 +65,12 @@
     "UNLICENSE"
   ],
   "dependencies": {
-    "@aws-sdk/client-s3": "^3.906.0",
-    "@modelcontextprotocol/sdk": "^1.19.1",
-    "@smithy/node-http-handler": "^4.3.0",
+    "@aws-sdk/client-s3": "^3.914.0",
+    "@modelcontextprotocol/sdk": "^1.20.1",
+    "@smithy/node-http-handler": "^4.4.2",
     "@supercharge/promise-pool": "^3.2.0",
     "dotenv": "^17.2.3",
+    "express": "^5.1.0",
     "fastest-validator": "^1.19.1",
     "flat": "^6.0.1",
     "glob": "^11.0.3",
@@ -114,36 +115,35 @@
     }
   },
   "devDependencies": {
-    "@aws-sdk/client-sqs": "^3.0.0",
+    "@aws-sdk/client-sqs": "^3.914.0",
     "@babel/core": "^7.28.4",
     "@babel/preset-env": "^7.28.3",
-    "@google-cloud/bigquery": "^7.0.0",
-    "@rollup/plugin-commonjs": "^28.0.6",
+    "@google-cloud/bigquery": "^7.9.4",
+    "@rollup/plugin-commonjs": "^28.0.8",
     "@rollup/plugin-json": "^6.1.0",
-    "@rollup/plugin-node-resolve": "^16.0.2",
+    "@rollup/plugin-node-resolve": "^16.0.3",
     "@rollup/plugin-replace": "^6.0.2",
     "@rollup/plugin-terser": "^0.4.4",
     "@types/node": "24.7.0",
     "@xenova/transformers": "^2.17.2",
-    "amqplib": "^0.10.8",
+    "amqplib": "^0.10.9",
     "babel-loader": "^10.0.0",
     "chalk": "^5.6.2",
     "cli-table3": "^0.6.5",
     "commander": "^14.0.1",
-    "esbuild": "^0.25.10",
-    "inquirer": "^12.9.6",
+    "esbuild": "^0.25.11",
+    "inquirer": "^12.10.0",
     "jest": "^30.2.0",
-    "node-cron": "^4.0.0",
+    "node-cron": "^4.2.1",
     "node-loader": "^2.1.0",
     "ora": "^9.0.0",
-    "pg": "^8.0.0",
+    "pg": "^8.16.3",
     "pkg": "^5.8.1",
-    "rollup": "^4.52.4",
+    "rollup": "^4.52.5",
     "rollup-plugin-copy": "^3.5.0",
     "rollup-plugin-esbuild": "^6.2.1",
     "rollup-plugin-polyfill-node": "^0.13.0",
     "rollup-plugin-shebang-bin": "^0.1.0",
-    "rollup-plugin-terser": "^7.0.2",
     "tsx": "^4.20.6",
     "typescript": "5.9.3",
     "uuid": "^13.0.0",

package/src/client.class.js

@@ -203,7 +203,21 @@ export class Client extends EventEmitter {
       Key: keyPrefix ? path.join(keyPrefix, key) : key,
     };
 
-    const [ok, err, response] = await tryFn(() => this.sendCommand(new HeadObjectCommand(options)));
+    const [ok, err, response] = await tryFn(async () => {
+      const res = await this.sendCommand(new HeadObjectCommand(options));
+
+      // Smart decode metadata values (same as getObject)
+      if (res.Metadata) {
+        const decodedMetadata = {};
+        for (const [key, value] of Object.entries(res.Metadata)) {
+          decodedMetadata[key] = metadataDecode(value);
+        }
+        res.Metadata = decodedMetadata;
+      }
+
+      return res;
+    });
+
     this.emit('headObject', err || response, { key });
 
     if (!ok) {
@@ -218,15 +232,36 @@ export class Client extends EventEmitter {
     return response;
   }
 
-  async copyObject({ from, to }) {
+  async copyObject({ from, to, metadata, metadataDirective, contentType }) {
+    const keyPrefix = typeof this.config.keyPrefix === 'string' ? this.config.keyPrefix : '';
     const options = {
       Bucket: this.config.bucket,
-      Key: this.config.keyPrefix ? path.join(this.config.keyPrefix, to) : to,
-      CopySource: path.join(this.config.bucket, this.config.keyPrefix ? path.join(this.config.keyPrefix, from) : from),
+      Key: keyPrefix ? path.join(keyPrefix, to) : to,
+      CopySource: path.join(this.config.bucket, keyPrefix ? path.join(keyPrefix, from) : from),
     };
 
+    // Add metadata directive if specified
+    if (metadataDirective) {
+      options.MetadataDirective = metadataDirective; // 'COPY' or 'REPLACE'
+    }
+
+    // Add metadata if specified (and encode values)
+    if (metadata && typeof metadata === 'object') {
+      const encodedMetadata = {};
+      for (const [key, value] of Object.entries(metadata)) {
+        const { encoded } = metadataEncode(value);
+        encodedMetadata[key] = encoded;
+      }
+      options.Metadata = encodedMetadata;
+    }
+
+    // Add content type if specified
+    if (contentType) {
+      options.ContentType = contentType;
+    }
+
     const [ok, err, response] = await tryFn(() => this.sendCommand(new CopyObjectCommand(options)));
-    this.emit('copyObject', err || response, { from, to });
+    this.emit('copyObject', err || response, { from, to, metadataDirective });
 
     if (!ok) {
       throw mapAwsError(err, {

package/src/concerns/plugin-storage.js

@@ -456,7 +456,9 @@ export class PluginStorage {
    * @returns {Promise<boolean>} True if extended, false if not found or no TTL
    */
   async touch(key, additionalSeconds) {
-    const [ok, err, response] = await tryFn(() => this.client.getObject(key));
+    // Optimization: Use HEAD + COPY instead of GET + PUT for metadata-only updates
+    // This avoids transferring the body when only updating the TTL
+    const [ok, err, response] = await tryFn(() => this.client.headObject(key));
 
     if (!ok) {
       return false;
@@ -465,50 +467,34 @@ export class PluginStorage {
     const metadata = response.Metadata || {};
     const parsedMetadata = this._parseMetadataValues(metadata);
 
-    let data = parsedMetadata;
-
-    if (response.Body) {
-      const [ok, err, result] = await tryFn(async () => {
-        const bodyContent = await response.Body.transformToString();
-        if (bodyContent && bodyContent.trim()) {
-          const body = JSON.parse(bodyContent);
-          return { ...parsedMetadata, ...body };
-        }
-        return parsedMetadata;
-      });
-
-      if (!ok) {
-        return false; // Parse error
-      }
-
-      data = result;
-    }
-
     // S3 lowercases metadata keys
-    const expiresAt = data._expiresat || data._expiresAt;
+    const expiresAt = parsedMetadata._expiresat || parsedMetadata._expiresAt;
     if (!expiresAt) {
       return false; // No TTL to extend
     }
 
     // Extend TTL - use the standard field name (will be lowercased by S3)
-    data._expiresAt = expiresAt + (additionalSeconds * 1000);
-    delete data._expiresat; // Remove lowercased version
-
-    // Save back (reuse same behavior)
-    const { metadata: newMetadata, body: newBody } = this._applyBehavior(data, 'body-overflow');
-
-    const putParams = {
-      key,
-      metadata: newMetadata,
-      contentType: 'application/json'
-    };
-
-    if (newBody !== null) {
-      putParams.body = JSON.stringify(newBody);
+    parsedMetadata._expiresAt = expiresAt + (additionalSeconds * 1000);
+    delete parsedMetadata._expiresat; // Remove lowercased version
+
+    // Encode metadata for S3
+    const encodedMetadata = {};
+    for (const [metaKey, metaValue] of Object.entries(parsedMetadata)) {
+      const { encoded } = metadataEncode(metaValue);
+      encodedMetadata[metaKey] = encoded;
     }
 
-    const [putOk] = await tryFn(() => this.client.putObject(putParams));
-    return putOk;
+    // Use COPY with MetadataDirective: REPLACE to update metadata atomically
+    // This preserves the body without re-transferring it
+    const [copyOk] = await tryFn(() => this.client.copyObject({
+      from: key,
+      to: key,
+      metadata: encodedMetadata,
+      metadataDirective: 'REPLACE',
+      contentType: response.ContentType || 'application/json'
+    }));
+
+    return copyOk;
   }
 
   /**
@@ -675,12 +661,56 @@ export class PluginStorage {
   /**
    * Increment a counter value
    *
+   * Optimization: Uses HEAD + COPY for existing counters to avoid body transfer.
+   * Falls back to GET + PUT for non-existent counters or those with additional data.
+   *
    * @param {string} key - S3 key
    * @param {number} amount - Amount to increment (default: 1)
    * @param {Object} options - Options (e.g., ttl)
    * @returns {Promise<number>} New value
    */
   async increment(key, amount = 1, options = {}) {
+    // Try optimized path first: HEAD + COPY for existing counters
+    const [headOk, headErr, headResponse] = await tryFn(() => this.client.headObject(key));
+
+    if (headOk && headResponse.Metadata) {
+      // Counter exists, use optimized HEAD + COPY
+      const metadata = headResponse.Metadata || {};
+      const parsedMetadata = this._parseMetadataValues(metadata);
+
+      const currentValue = parsedMetadata.value || 0;
+      const newValue = currentValue + amount;
+
+      // Update only the value field
+      parsedMetadata.value = newValue;
+
+      // Handle TTL if specified
+      if (options.ttl) {
+        parsedMetadata._expiresAt = Date.now() + (options.ttl * 1000);
+      }
+
+      // Encode metadata
+      const encodedMetadata = {};
+      for (const [metaKey, metaValue] of Object.entries(parsedMetadata)) {
+        const { encoded } = metadataEncode(metaValue);
+        encodedMetadata[metaKey] = encoded;
+      }
+
+      // Atomic update via COPY
+      const [copyOk] = await tryFn(() => this.client.copyObject({
+        from: key,
+        to: key,
+        metadata: encodedMetadata,
+        metadataDirective: 'REPLACE',
+        contentType: headResponse.ContentType || 'application/json'
+      }));
+
+      if (copyOk) {
+        return newValue;
+      }
+    }
+
+    // Fallback: counter doesn't exist or has body data, use traditional path
     const data = await this.get(key);
     const value = (data?.value || 0) + amount;
     await this.set(key, { value }, options);

package/src/plugins/api/index.js

@@ -37,6 +37,11 @@ import { ApiServer } from './server.js';
 import { requirePluginDependency } from '../concerns/plugin-dependencies.js';
 import tryFn from '../../concerns/try-fn.js';
 
+/**
+ * API Plugin class
+ * @class
+ * @extends Plugin
+ */
 export class ApiPlugin extends Plugin {
   /**
    * Create API Plugin instance

package/src/plugins/api/server.js

@@ -12,6 +12,10 @@ import { errorHandler } from './utils/error-handler.js';
 import * as formatter from './utils/response-formatter.js';
 import { generateOpenAPISpec } from './utils/openapi-generator.js';
 
+/**
+ * API Server class
+ * @class
+ */
 export class ApiServer {
   /**
    * Create API server

package/src/plugins/plugin.class.js

@@ -176,6 +176,11 @@ export class Plugin extends EventEmitter {
    * - Pode modificar argumentos/resultados.
    */
   addMiddleware(resource, methodName, middleware) {
+    // Safety check: verify method exists
+    if (typeof resource[methodName] !== 'function') {
+      throw new Error(`Cannot add middleware to "${methodName}": method does not exist on resource "${resource.name || 'unknown'}"`);
+    }
+
     if (!resource._pluginMiddlewares) {
       resource._pluginMiddlewares = {};
     }