feat: added AWS S3 MCP - listBuckets, listObjects (#38)

chrisleekr · web-flow · commit 04ed8966ceab · 2025-08-05T00:11:16.000+10:00
diff --git a/.env.example b/.env.example
@@ -47,9 +47,11 @@ MCP_CONFIG_TOOLS_AWS_REGION=us-east-1
 MCP_CONFIG_TOOLS_AWS_PROFILE=default
 MCP_CONFIG_TOOLS_AWS_CREDENTIALS_ACCESS_KEY_ID=
 MCP_CONFIG_TOOLS_AWS_CREDENTIALS_SECRET_ACCESS_KEY=
+MCP_CONFIG_TOOLS_AWS_CREDENTIALS_SESSION_TOKEN=
 
 MCP_CONFIG_TOOLS_AWS_BEDROCK_REGION=us-east-1
 MCP_CONFIG_TOOLS_AWS_BEDROCK_PROFILE=default
 MCP_CONFIG_TOOLS_AWS_BEDROCK_CREDENTIALS_ACCESS_KEY_ID=
 MCP_CONFIG_TOOLS_AWS_BEDROCK_CREDENTIALS_SECRET_ACCESS_KEY=
+MCP_CONFIG_TOOLS_AWS_BEDROCK_CREDENTIALS_SESSION_TOKEN=
 MCP_CONFIG_TOOLS_AWS_BEDROCK_MODEL=anthropic.claude-3-5-sonnet-20241022-v2:0
diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml
@@ -1,4 +1,4 @@
-image: node:22.16.0-alpine
+image: node:22.17.0-alpine
 
 stages:
   - prepare
diff --git a/.nvmrc b/.nvmrc
@@ -1 +1 @@
-22.16.0
+22.17.0
diff --git a/Dockerfile b/Dockerfile
@@ -1,7 +1,7 @@
 # syntax=docker/dockerfile:1
 # hadolint global ignore=DL3018
 
-FROM node:22.16.0-alpine AS base
+FROM node:22.17.0-alpine AS base
 
 # Stage 1: Build stage
 FROM base AS development
diff --git a/README.md b/README.md
@@ -8,7 +8,7 @@ A playground for Model Context Protocol (MCP) server built with TypeScript and S
 - OAuth authentication/3rd party authorization: Implements an OAuth server for MCP clients to process 3rd party authorization servers like Auth0, providing Dynamic Application Registration for MCP server.
 - Storage: Provide storage for MCP server to store data like OAuth sessions, tokens, etc.
 - Session Management: Support stateful sessions by using replay of initial request.
-- Tools: `echo`, `system-time`, `streaming`, `project` for demonstration.
+- Tools: `aws-s3`, `echo`, `system-time`, `streaming`, `project` for demonstration.
 - Prompts: `echo`
 
 ## Why this project exists?
diff --git a/mcp-config.example.json b/mcp-config.example.json
@@ -16,7 +16,7 @@
         "--debug"
       ],
       "env": {
-        "PATH": "~/.local/share/nvm/v22.16.0/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
+        "PATH": "~/.local/share/nvm/v22.17.0/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"
       }
     }
   }
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -37,7 +37,9 @@
     "typescript",
     "boilerplate",
     "server",
-    "anthropic"
+    "anthropic",
+    "oauth",
+    "auth0"
   ],
   "author": "Chris Lee <git@chrislee.kr>",
   "repository": {
@@ -49,9 +51,11 @@
   },
   "homepage": "https://github.com/chrisleekr/mcp-server-playground#readme",
   "dependencies": {
-    "@aws-sdk/client-bedrock": "3.858.0",
-    "@aws-sdk/client-ecs": "3.858.0",
-    "@aws-sdk/client-s3": "3.858.0",
+    "@aws-sdk/client-bedrock": "3.859.0",
+    "@aws-sdk/client-ecs": "3.859.0",
+    "@aws-sdk/client-s3": "3.859.0",
+    "@aws-sdk/credential-provider-node": "3.859.0",
+    "@aws-sdk/credential-providers": "3.859.0",
     "@modelcontextprotocol/sdk": "1.17.1",
     "axios": "1.11.0",
     "base64url": "3.0.1",
@@ -69,6 +73,7 @@
     "zod-to-json-schema": "3.24.6"
   },
   "devDependencies": {
+    "@aws-sdk/types": "^3.840.0",
     "@commitlint/cli": "19.8.1",
     "@commitlint/config-conventional": "19.8.1",
     "@eslint/js": "9.32.0",
@@ -111,10 +116,10 @@
     ]
   },
   "engines": {
-    "node": ">=22.16.0"
+    "node": ">=22.17.0"
   },
   "volta": {
-    "node": ">=22.16.0",
-    "npm": ">=10.7.0"
+    "node": ">=22.17.0",
+    "npm": ">=11.5.2"
   }
 }
diff --git a/src/config/manager.ts b/src/config/manager.ts
@@ -56,13 +56,15 @@ export class ConfigManager {
           credentials: {
             accessKeyId: null,
             secretAccessKey: null,
+            sessionToken: null,
           },
           bedrock: {
             region: 'us-east-1',
             profile: 'default',
             credentials: {
               accessKeyId: null,
               secretAccessKey: null,
+              sessionToken: null,
             },
             model: 'anthropic.claude-3-5-sonnet-20240620-v1:0',
           },
diff --git a/src/config/type.ts b/src/config/type.ts
@@ -64,13 +64,15 @@ export const ToolsConfigSchema = z.object({
     credentials: z.object({
       accessKeyId: z.string().nullable(),
       secretAccessKey: z.string().nullable(),
+      sessionToken: z.string().nullable(),
     }),
     bedrock: z.object({
       region: z.string(),
       profile: z.string().nullable(),
       credentials: z.object({
         accessKeyId: z.string().nullable(),
         secretAccessKey: z.string().nullable(),
+        sessionToken: z.string().nullable(),
       }),
       model: z.string(),
     }),
diff --git a/src/libraries/aws/authentication.ts b/src/libraries/aws/authentication.ts
@@ -0,0 +1,23 @@
+import { fromSSO } from '@aws-sdk/credential-providers';
+import {
+  AwsCredentialIdentity,
+  AwsCredentialIdentityProvider,
+} from '@aws-sdk/types';
+
+import { config } from '@/config/manager';
+
+export function getCredentials():
+  | AwsCredentialIdentityProvider
+  | AwsCredentialIdentity {
+  if (config.tools.aws.profile !== null && config.tools.aws.profile !== '') {
+    return fromSSO({
+      profile: config.tools.aws.profile,
+    });
+  }
+
+  return {
+    accessKeyId: config.tools.aws.credentials.accessKeyId ?? '',
+    secretAccessKey: config.tools.aws.credentials.secretAccessKey ?? '',
+    sessionToken: config.tools.aws.credentials.sessionToken ?? '',
+  };
+}
diff --git a/src/libraries/aws/index.ts b/src/libraries/aws/index.ts
@@ -0,0 +1,2 @@
+export * from './authentication';
+export * from './s3';
diff --git a/src/libraries/aws/s3.ts b/src/libraries/aws/s3.ts
@@ -0,0 +1,98 @@
+import {
+  ListBucketsCommand,
+  ListBucketsCommandOutput,
+  ListObjectsV2Command,
+  ListObjectsV2CommandOutput,
+  S3Client,
+} from '@aws-sdk/client-s3';
+
+import { config } from '@/config/manager';
+import { loggingContext } from '@/core/server/http/context';
+
+import { getCredentials } from './authentication';
+
+const regionClients: Map<string, S3Client> = new Map();
+
+// Get region-specific S3 client
+export function getS3ClientForRegion(region: string): S3Client {
+  if (regionClients.has(region)) {
+    const client = regionClients.get(region);
+    if (!client) {
+      throw new Error(
+        `S3 client for region ${region} was unexpectedly undefined`
+      );
+    }
+    return client;
+  }
+
+  try {
+    const client = new S3Client({
+      region,
+      credentials: getCredentials(),
+    });
+
+    regionClients.set(region, client);
+    return client;
+  } catch (error) {
+    loggingContext.log('error', 'Failed to create S3 client for region', {
+      data: {
+        region,
+        error: {
+          message: error instanceof Error ? error.message : String(error),
+          name: error instanceof Error ? error.name : 'UnknownError',
+          stack: error instanceof Error ? error.stack : undefined,
+        },
+      },
+    });
+    throw new Error(
+      `Failed to create S3 client for region ${region}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
+// ListBuckets - https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/command/ListBucketsCommand/
+export interface ListBucketsParams {
+  maxBuckets?: number;
+  prefix?: string;
+}
+
+export function listBuckets({
+  maxBuckets,
+  prefix,
+}: ListBucketsParams): Promise<ListBucketsCommandOutput> {
+  const s3Client = getS3ClientForRegion(config.tools.aws.region);
+
+  loggingContext.log('info', 'Listing buckets', {
+    data: { maxBuckets, prefix },
+  });
+
+  return s3Client.send(
+    new ListBucketsCommand({ MaxBuckets: maxBuckets, Prefix: prefix })
+  );
+}
+
+// ListObjectsV2 - https://docs.aws.amazon.com/AWSJavaScriptSDK/v3/latest/client/s3/command/ListObjectsV2Command/
+export interface ListObjectsV2Params {
+  /**
+   * Directory buckets - When you use this operation with a directory bucket, you must use virtual-hosted-style requests in the format Bucket-name.s3express-zone-id.region-code.amazonaws.com. Path-style requests are not supported. Directory bucket names must be unique in the chosen Zone (Availability Zone or Local Zone). Bucket names must follow the format bucket-base-name--zone-id--x-s3 (for example, amzn-s3-demo-bucket--usw2-az1--x-s3). For information about bucket naming restrictions, see Directory bucket naming rules
+   */
+  bucket: string;
+  prefix?: string;
+  region?: string;
+}
+
+export function listObjectsV2({
+  bucket,
+  prefix,
+  region,
+}: ListObjectsV2Params): Promise<ListObjectsV2CommandOutput> {
+  const s3Client = getS3ClientForRegion(region ?? config.tools.aws.region);
+
+  loggingContext.log('info', 'Listing objects', {
+    data: { bucket, prefix },
+  });
+
+  return s3Client.send(
+    new ListObjectsV2Command({ Bucket: bucket, Prefix: prefix })
+  );
+}
diff --git a/src/tools/aws/s3/index.ts b/src/tools/aws/s3/index.ts
diff --git a/src/tools/aws/s3/types.ts b/src/tools/aws/s3/types.ts
diff --git a/src/tools/loader.ts b/src/tools/loader.ts
diff --git a/tsconfig.json b/tsconfig.json

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-image: node:22.16.0-alpine`
	`1`	`+image: node:22.17.0-alpine`
`2`	`2`
`3`	`3`	`stages:`
`4`	`4`	`- prepare`
Original file line number	Diff line number	Diff line change
`@@ -16,7 +16,7 @@`
`16`	`16`	`"--debug"`
`17`	`17`	`],`
`18`	`18`	`"env": {`
`19`		`- "PATH": "~/.local/share/nvm/v22.16.0/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"`
	`19`	`+ "PATH": "~/.local/share/nvm/v22.17.0/bin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin"`
`20`	`20`	`}`
`21`	`21`	`}`
`22`	`22`	`}`