API仕様変更・セキュリティポリシー見直し・ドキュメント整備 (#9)

poad · web-flow · commit 60cd1a15c175 · 2025-11-06T01:20:04.000+09:00
* API仕様変更に伴い、READMEの使い方例とパッケージのTSDocコメントを修正

- createHonoAppの利用方法をファクトリ関数渡しに統一
- 使い方サンプルを現行APIに合わせて修正
- package/src/index.tsのドキュメントコメントをTSDoc形式に変更

* リポジトリの内容に合わせてSECURITY.mdを修正

- AWS Lambda用MCPサーバー向けのセキュリティ運用に更新
- Secrets管理、依存性脆弱性管理、CI/CDチェック、バリデーション等の注意事項を明記
- 脆弱性報告手順も明確化

* リソースリークの修正

* リソースリークの修正
diff --git a/.github/SECURITY.md b/.github/SECURITY.md
@@ -1,19 +1,32 @@
-# Security Policy
+# セキュリティポリシー
 
-## Supported Versions
+## サポート対象バージョン
 
-This project is currently in active development (version 0.x.x). Security updates are provided for the latest version only. As this is an AWS Bedrock application, we prioritize security issues related to AWS credentials, data handling, and API interactions.
+本プロジェクト（aws-lambda-mcp-server）は現在アクティブに開発されています。  
+セキュリティアップデートは最新版（0.x.x系）のみ提供しています。
 
-| Version | Supported          |
-| ------- | ------------------ |
-| 0.x.x   | :white_check_mark: |
+| バージョン | サポート状況         |
+| ---------- | ------------------- |
+| 0.x.x      | ✅                  |
 
-## Reporting a Vulnerability
+## セキュリティに関するご注意
 
-Please report security vulnerabilities through GitHub's Security Advisories feature:
+- 本リポジトリは AWS Lambda 上で動作する MCP（Model Context Protocol）サーバー用ライブラリです。
+- APIキー、シークレット、パスワード等のハードコーディングは禁止です。開発時は `.env` ファイル（.gitignore対象）、本番では環境変数や AWS Secrets Manager / Parameter Store をご利用ください。
+- 依存パッケージの脆弱性は `pnpm audit` や dependabot で定期的にチェックし、脆弱性が報告された場合は速やかにアップデートしてください。
+- CI/CD では静的解析（SAST）や依存性チェックを自動実行しています。
+- 外部から受け取るデータは型チェック・バリデーション（zod等）を必ず行ってください。
+- ログやエラーメッセージに認証情報・個人情報・シークレット等を出力しないでください。
+- クライアントへ返すデータは適切にエスケープし、XSS等の攻撃を防止してください。
+- IAMロール・ポリシーは最小権限の原則で設計してください。
+- セキュリティ上の懸念やインシデントが発生した場合は、速やかにご報告ください。
 
-1. Go to the Security tab of this repository
-2. Click "Report a vulnerability"
-3. Fill out the private vulnerability report form
+## 脆弱性の報告方法
 
-We will respond to security reports within 48 hours and provide regular updates on the remediation process.
+脆弱性を発見された場合は、GitHub の Security Advisories 機能を利用してご報告ください。
+
+1. このリポジトリの「セキュリティ」タブに移動
+2. 「脆弱性の報告」をクリック
+3. フォームに詳細を記入し、送信
+
+ご報告いただいた内容には48時間以内に初回対応し、修正状況について随時ご連絡いたします。
diff --git a/AGENTS.md b/AGENTS.md
@@ -27,6 +27,7 @@
 - 依存関係の更新はdependabotで行われるが、`pnpm up -r`での更新は可
 - `pnpm audit` による依存パッケージの脆弱性チェック実施は必須
 - 変数の破壊的再代入は禁止
+- TypeScript のドキュメンテーションコメントは TSDoc で記述する
 
 ## セキュリティベストプラクティス
 
diff --git a/README.md b/README.md
@@ -25,29 +25,33 @@ TypeScriptでの利用例です。
 
 ```typescript
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { handler } from 'aws-lambda-mcp-server';
+import { createHonoApp } from 'aws-lambda-mcp-server';
 import { handle } from 'hono/aws-lambda';
-
-// MCPサーバーのインスタンスを作成
-const server = new McpServer({
-  name: 'my-mcp-server',
-  version: '1.0.0',
-});
-
-// MCPサーバーのインスタンスにToolsやResourcesなどを設定する
-server.tool(
-  "say_hello",
-  { who: z.string() },
-  async ({ who }) => ({
-    content: [{
-      type: "text",
-      text: `${who} さん、こんにちは！`
-    }]
-  })
-);
+import { z } from 'zod';
+
+// MCPサーバーのファクトリ関数を用意
+const createMcpServer = () => {
+  const server = new McpServer({
+    name: 'my-mcp-server',
+    version: '1.0.0',
+  });
+
+  // MCPサーバーのインスタンスにToolsやResourcesなどを設定する
+  server.tool(
+    'say_hello',
+    { who: z.string() },
+    async ({ who }) => ({
+      content: [{
+        type: 'text',
+        text: `${who} さん、こんにちは！`
+      }]
+    })
+  );
+  return server;
+};
 
 // Hono アプリケーションを作成
-const app = createHonoApp(server);
+const app = createHonoApp(createMcpServer);
 
 // AWS Lambdaのエントリポイントとして利用
 export const handler = handle(app);
diff --git a/SECURITY.md b/SECURITY.md
diff --git a/example/lambda/index.ts b/example/lambda/index.ts
@@ -6,23 +6,25 @@ import { createHonoApp } from 'aws-lambda-mcp-server';
 
 const logger = new Logger();
 
-const server = new McpServer({
-  name: 'hello-server',
-  version: '1.0.0',
-});
-
-server.tool(
-  'say_hello',
-  { who: z.string() },
-  async ({ who }) => ({
-    content: [{
-      type: 'text',
-      text: `${who} さん、こんにちは！`,
-    }],
-  }),
-);
+const createMcpServer = () => {
+  const server = new McpServer({
+    name: 'hello-server',
+    version: '1.0.0',
+  });
 
-const app = createHonoApp(server);
+  server.tool(
+    'say_hello',
+    { who: z.string() },
+    async ({ who }) => ({
+      content: [{
+        type: 'text',
+        text: `${who} さん、こんにちは！`,
+      }],
+    }),
+  );
+  return server;
+};
+const app = createHonoApp(createMcpServer);
 
 // Lambda handler
 export const handler = handle(app);
diff --git a/package/README.md b/package/README.md
@@ -21,29 +21,33 @@ TypeScriptでの利用例です。
 
 ```typescript
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { handler } from 'aws-lambda-mcp-server';
+import { createHonoApp } from 'aws-lambda-mcp-server';
 import { handle } from 'hono/aws-lambda';
-
-// MCPサーバーのインスタンスを作成
-const server = new McpServer({
-  name: 'my-mcp-server',
-  version: '1.0.0',
-});
-
-// MCPサーバーのインスタンスにToolsやResourcesなどを設定する
-server.tool(
-  "say_hello",
-  { who: z.string() },
-  async ({ who }) => ({
-    content: [{
-      type: "text",
-      text: `${who} さん、こんにちは！`
-    }]
-  })
-);
+import { z } from 'zod';
+
+// MCPサーバーのファクトリ関数を用意
+const createMcpServer = () => {
+  const server = new McpServer({
+    name: 'my-mcp-server',
+    version: '1.0.0',
+  });
+
+  // MCPサーバーのインスタンスにToolsやResourcesなどを設定する
+  server.tool(
+    'say_hello',
+    { who: z.string() },
+    async ({ who }) => ({
+      content: [{
+        type: 'text',
+        text: `${who} さん、こんにちは！`
+      }]
+    })
+  );
+  return server;
+};
 
 // Hono アプリケーションを作成
-const app = createHonoApp(server);
+const app = createHonoApp(createMcpServer);
 
 // AWS Lambdaのエントリポイントとして利用
 export const handler = handle(app);
diff --git a/package/src/index.ts b/package/src/index.ts
@@ -1,11 +1,37 @@
+/**
+ * Model Context Protocol (MCP) サーバーを Hono フレームワーク上で動作させるエントリーポイント。
+ *
+ * @remarks
+ * `createHonoApp` 関数を通じて、/mcp エンドポイントでMCPサーバーを提供します。
+ * - POST/GET /mcp: MCPリクエストの受信・処理
+ * - その他のHTTPメソッド: 405 Method Not Allowed
+ *
+ * 内部的にエラーハンドリングやリソースクローズ処理も行います。
+ */
+
 import { Logger } from '@aws-lambda-powertools/logger';
 import { StreamableHTTPTransport } from '@hono/mcp';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { Context, Hono } from 'hono';
 import { BlankEnv, BlankInput } from 'hono/types';
 
+/**
+ * ロガーインスタンス（AWS Lambda Powertools）。
+ *
+ * @private
+ */
 const logger = new Logger();
 
+/**
+ * 許可されていないHTTPメソッドに対するハンドラーです。
+ *
+ * @remarks
+ * 405エラーのJSONレスポンスを返します。
+ *
+ * @param c Honoのコンテキスト
+ * @returns 405エラーのJSONレスポンス
+ * @private
+ */
 const methodNotAllowedHandler = async (
   c: Context<BlankEnv, '/mcp', BlankInput>,
 ) => {
@@ -22,6 +48,18 @@ const methodNotAllowedHandler = async (
   );
 };
 
+/**
+ * サーバーエラー発生時の共通エラーハンドラーです。
+ *
+ * @remarks
+ * エラー内容をロギングし、500エラーのJSONレスポンスを返します。
+ *
+ * @param c Honoのコンテキスト
+ * @param reason エラー理由
+ * @param logMessage ログ出力用メッセージ
+ * @returns 500エラーのJSONレスポンス
+ * @private
+ */
 const handleError = (
   c: Context<BlankEnv, '/mcp', BlankInput>,
   reason: unknown,
@@ -44,6 +82,17 @@ const handleError = (
   );
 };
 
+/**
+ * MCPサーバーおよびトランスポートのリソースをクローズします。
+ *
+ * @remarks
+ * どちらか一方のクローズに失敗しても、もう一方は必ず実行されます。
+ *
+ * @param server MCPサーバーインスタンス
+ * @param transport トランスポートインスタンス
+ * @returns void
+ * @private
+ */
 const closeResources = async (server: McpServer, transport: StreamableHTTPTransport) => {
   // 両方のクローズを確実に実行（片方が失敗してももう片方を実行）
   const closeResults = await Promise.allSettled([
@@ -64,38 +113,69 @@ const closeResources = async (server: McpServer, transport: StreamableHTTPTransp
   });
 };
 
-const handleRequest = async (server: McpServer, c: Context<BlankEnv, '/mcp', BlankInput>) => {
+/**
+ * MCPリクエストを処理します。
+ *
+ * @remarks
+ * サーバーとトランスポートの接続・リクエスト処理・エラーハンドリングを行います。
+ *
+ * @param createMcpServer MCPサーバーインスタンスを生成するファクトリ関数
+ * @param c Honoのコンテキスト
+ * @returns MCPレスポンス
+ * @private
+ */
+const handleRequest = async (createMcpServer: () => McpServer, c: Context<BlankEnv, '/mcp', BlankInput>) => {
   const transport = new StreamableHTTPTransport({
     sessionIdGenerator: undefined, // セッションIDを生成しない（ステートレスモード）
     enableJsonResponse: true,
   });
+  const server = createMcpServer();
   try {
     await server.connect(transport);
     logger.trace('MCP リクエストを受信');
     return await transport.handleRequest(c);
   } catch (error) {
+    return handleError(c, error, 'MCP 接続中のエラー:');
+  } finally {
+    // エラーの有無に関わらず必ずリソースをクローズ
     try {
       await closeResources(server, transport);
     } catch (closeError) {
+      // クローズエラーは既にcloseResources内でログ出力されているため、
+      // ここでは追加のエラーハンドリングは不要だが、エラーの詳細を記録
       const errorDetails = closeError instanceof Error
         ? { message: closeError.message, stack: closeError.stack }
         : closeError;
-      logger.error('Transport close failed after connection error:', { closeError: errorDetails });
+      logger.error('リソースクローズ中に追加エラーが発生しましたが、処理を継続します', { closeError: errorDetails });
     }
-    return handleError(c, error, 'MCP 接続中のエラー:');
   }
-
 };
 
-export const createHonoApp = (server: McpServer) => {
+/**
+ * Honoアプリケーションを生成し、/mcpエンドポイントでMCPサーバーを提供します。
+ *
+ * @remarks
+ * POST/GET /mcp でMCPリクエストを受け付け、他のHTTPメソッドは405を返します。
+ *
+ * @param createMcpServer MCPサーバーインスタンスを生成するファクトリ関数
+ * @returns Honoアプリケーションインスタンス
+ *
+ * @example
+ * ```ts
+ * import { createHonoApp } from '...';
+ * import { createMcpServer } from './your-mcp-server';
+ * const app = createHonoApp(createMcpServer);
+ * ```
+ */
+export const createHonoApp = (createMcpServer: () => McpServer) => {
   const app = new Hono();
 
   app.post('/mcp', async (c) => {
-    return await handleRequest(server, c);
+    return await handleRequest(createMcpServer, c);
   });
 
   app.get('/mcp', async (c) => {
-    return await handleRequest(server, c);
+    return await handleRequest(createMcpServer, c);
   });
 
   app.put('/mcp', methodNotAllowedHandler);
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
