aiexecode 1.0.89 → 1.0.90

package/mcp-agent-lib/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(mkdir:*)"
+    ],
+    "deny": [],
+    "ask": []
+  }
+}

package/mcp-agent-lib/example/01-basic-usage.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+
+/**
+ * 기본 사용 예제 - MCP Agent Client 시작하기
+ *
+ * 이 예제는 MCP Agent Client의 가장 기본적인 사용 방법을 보여줍니다.
+ * - 클라이언트 생성
+ * - 서버 연결
+ * - 도구 목록 조회
+ * - 도구 실행
+ */
+
+import { MCPAgentClient } from '../index.js';
+
+async function main() {
+  // 1. 클라이언트 인스턴스 생성
+  // logLevel을 'info'로 설정하여 진행 상황을 확인할 수 있습니다
+  const client = new MCPAgentClient({
+    logLevel: 'info',
+    enableConsoleDebug: true
+  });
+
+  try {
+    // 2. 서버 설정으로 초기화
+    // mcpServers 객체에 연결할 서버들을 정의합니다
+    await client.initialize({
+      mcpServers: {
+        // stdio 방식 서버 예시
+        'example-server': {
+          type: 'stdio',
+          command: 'node',
+          args: ['path/to/your/server.js'],
+          // 선택사항: 환경변수 설정
+          env: {
+            NODE_ENV: 'development'
+          }
+        }
+      }
+    });
+
+    console.log('✅ 클라이언트가 성공적으로 초기화되었습니다!');
+
+    // 3. 사용 가능한 도구 목록 조회
+    const tools = client.getAvailableTools();
+    console.log('\n📋 사용 가능한 도구 목록:');
+    tools.forEach(tool => {
+      console.log(`  - ${tool.name}: ${tool.description}`);
+      console.log(`    서버: ${tool.server}`);
+    });
+
+    // 4. 특정 도구 실행하기
+    if (tools.length > 0) {
+      const firstTool = tools[0];
+      console.log(`\n🔧 도구 실행 예시: ${firstTool.name}`);
+
+      // executeTool()은 도구 이름만으로 자동으로 서버를 찾아 실행합니다
+      const result = await client.executeTool(firstTool.name, {
+        // 여기에 도구에 필요한 인자를 전달합니다
+        // 예: { query: 'test', limit: 10 }
+      });
+
+      console.log('✅ 실행 결과:', result);
+    }
+
+    // 5. 클라이언트 상태 확인
+    const status = client.getStatus();
+    console.log('\n📊 클라이언트 상태:');
+    console.log(`  - 초기화 완료: ${status.initialized}`);
+    console.log(`  - 연결된 서버 수: ${status.connectedServers}/${status.totalServers}`);
+    console.log(`  - 사용 가능한 도구 수: ${status.totalTools}`);
+
+  } catch (error) {
+    console.error('❌ 오류 발생:', error.message);
+  } finally {
+    // 6. 리소스 정리 및 연결 해제
+    await client.disconnect();
+    console.log('\n👋 클라이언트 연결이 해제되었습니다.');
+  }
+}
+
+// 실행
+main().catch(console.error);

package/mcp-agent-lib/example/02-quick-start.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+/**
+ * 빠른 시작 예제 - quickStart() 함수 사용
+ *
+ * quickStart() 함수를 사용하면 클라이언트 생성과 초기화를
+ * 한 번에 수행할 수 있어 가장 간단하게 시작할 수 있습니다.
+ */
+
+import { quickStart } from '../index.js';
+
+async function main() {
+  // quickStart()는 클라이언트 생성 + 초기화를 한 번에 수행합니다
+  const client = await quickStart(
+    // 첫 번째 인자: 서버 설정
+    {
+      mcpServers: {
+        'my-server': {
+          type: 'stdio',
+          command: 'node',
+          args: ['server.js']
+        }
+      }
+    },
+    // 두 번째 인자: 클라이언트 옵션 (선택사항)
+    {
+      logLevel: 'info',
+      enableConsoleDebug: true,
+      timeout: 30000,      // 30초 타임아웃
+      retries: 3           // 실패 시 3회 재시도
+    }
+  );
+
+  try {
+    console.log('✅ 클라이언트 준비 완료!');
+
+    // 바로 도구를 사용할 수 있습니다
+    const tools = client.getAvailableTools();
+    console.log(`📋 ${tools.length}개의 도구를 사용할 수 있습니다.`);
+
+    // 도구 실행
+    if (tools.length > 0) {
+      const result = await client.executeTool(tools[0].name);
+      console.log('결과:', result);
+    }
+
+  } finally {
+    await client.disconnect();
+  }
+}
+
+main().catch(console.error);

package/mcp-agent-lib/example/03-http-server.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+/**
+ * HTTP 서버 연결 예제
+ *
+ * stdio 방식 대신 HTTP/HTTPS를 통해 원격 MCP 서버에 연결하는 방법입니다.
+ * 인증이 필요한 경우 Bearer 토큰을 헤더에 포함시킬 수 있습니다.
+ */
+
+import { MCPAgentClient } from '../index.js';
+
+async function main() {
+  const client = new MCPAgentClient({
+    logLevel: 'info',
+    enableConsoleDebug: true
+  });
+
+  try {
+    await client.initialize({
+      mcpServers: {
+        // HTTP 방식 서버 (인증 없음)
+        'public-api': {
+          type: 'http',
+          url: 'https://api.example.com/mcp'
+        },
+
+        // HTTP 방식 서버 (Bearer 토큰 인증)
+        'secured-api': {
+          type: 'http',
+          url: 'https://secure-api.example.com/mcp',
+          headers: {
+            'Authorization': 'Bearer YOUR_TOKEN_HERE',
+            'X-API-Key': 'your-api-key'
+          }
+        },
+
+        // 로컬 HTTP 서버
+        'local-http': {
+          type: 'http',
+          url: 'http://localhost:3000/mcp'
+        }
+      }
+    });
+
+    console.log('✅ HTTP 서버들에 연결되었습니다.');
+
+    // 연결된 서버별 상태 확인
+    const status = client.getStatus();
+    console.log('\n📊 서버별 상태:');
+    for (const [serverName, serverStatus] of Object.entries(status.servers)) {
+      console.log(`\n${serverName}:`);
+      console.log(`  - 상태: ${serverStatus.status}`);
+      console.log(`  - 타입: ${serverStatus.type}`);
+      console.log(`  - 도구 수: ${serverStatus.toolCount}`);
+    }
+
+    // 특정 서버의 도구만 조회
+    const publicTools = client.getServerTools('public-api');
+    console.log('\n🔧 public-api의 도구:');
+    publicTools.forEach(tool => {
+      console.log(`  - ${tool.name}: ${tool.description}`);
+    });
+
+  } catch (error) {
+    console.error('❌ 오류:', error.message);
+
+    // HTTP 인증 실패 시 자세한 정보가 로그에 출력됩니다
+    if (error.message.includes('401')) {
+      console.error('💡 인증 토큰을 확인해주세요.');
+    }
+  } finally {
+    await client.disconnect();
+  }
+}
+
+main().catch(console.error);

package/mcp-agent-lib/example/04-multiple-servers.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+
+/**
+ * 다중 서버 연결 예제
+ *
+ * 여러 MCP 서버에 동시에 연결하여 사용하는 방법입니다.
+ * 각 서버는 서로 다른 전송 방식(stdio, HTTP, SSE)을 사용할 수 있습니다.
+ */
+
+import { MCPAgentClient } from '../index.js';
+
+async function main() {
+  const client = new MCPAgentClient({
+    logLevel: 'info',
+    enableConsoleDebug: true
+  });
+
+  try {
+    // 여러 서버에 동시 연결
+    await client.initialize({
+      mcpServers: {
+        // 파일 시스템 도구를 제공하는 서버
+        'filesystem': {
+          type: 'stdio',
+          command: 'node',
+          args: ['servers/filesystem-server.js']
+        },
+
+        // 데이터베이스 도구를 제공하는 서버
+        'database': {
+          type: 'stdio',
+          command: 'python',
+          args: ['-m', 'mcp_server_db']
+        },
+
+        // 원격 API 서버
+        'remote-api': {
+          type: 'http',
+          url: 'https://api.example.com/mcp',
+          headers: {
+            'Authorization': 'Bearer TOKEN'
+          }
+        },
+
+        // 실시간 이벤트 서버
+        'event-stream': {
+          type: 'sse',
+          url: 'https://events.example.com/mcp'
+        }
+      }
+    });
+
+    console.log('✅ 모든 서버에 연결되었습니다.');
+
+    // 1. 전체 도구 목록 조회 (모든 서버의 도구)
+    const allTools = client.getAvailableTools();
+    console.log(`\n📋 총 ${allTools.length}개의 도구 사용 가능:`);
+
+    // 서버별로 그룹화하여 출력
+    const toolsByServer = {};
+    allTools.forEach(tool => {
+      if (!toolsByServer[tool.server]) {
+        toolsByServer[tool.server] = [];
+      }
+      toolsByServer[tool.server].push(tool);
+    });
+
+    for (const [serverName, tools] of Object.entries(toolsByServer)) {
+      console.log(`\n${serverName} (${tools.length}개):`);
+      tools.forEach(tool => {
+        console.log(`  - ${tool.name}: ${tool.description}`);
+      });
+    }
+
+    // 2. 특정 서버의 도구만 사용
+    console.log('\n🔧 filesystem 서버의 도구 실행:');
+    const fsTools = client.getServerTools('filesystem');
+    if (fsTools.length > 0) {
+      // callTool()을 사용하여 특정 서버의 도구를 직접 호출
+      const result = await client.callTool('filesystem', fsTools[0].name, {
+        path: '/tmp'
+      });
+      console.log('결과:', result);
+    }
+
+    // 3. 도구 이름만으로 자동 실행 (어느 서버의 도구인지 자동 검색)
+    console.log('\n🔍 자동 서버 검색으로 도구 실행:');
+    if (allTools.length > 0) {
+      // executeTool()은 도구 이름만으로 자동으로 서버를 찾습니다
+      const result = await client.executeTool(allTools[0].name);
+      console.log(`${allTools[0].name} (서버: ${result.server}):`, result.data);
+    }
+
+    // 4. 리소스 목록 조회 (모든 서버)
+    const resources = await client.listAllResources();
+    console.log(`\n📄 사용 가능한 리소스: ${resources.length}개`);
+    resources.forEach(resource => {
+      console.log(`  - ${resource.name} (${resource.serverName})`);
+      console.log(`    URI: ${resource.uri}`);
+    });
+
+    // 5. 프롬프트 목록 조회 (모든 서버)
+    const prompts = await client.listAllPrompts();
+    console.log(`\n💬 사용 가능한 프롬프트: ${prompts.length}개`);
+    prompts.forEach(prompt => {
+      console.log(`  - ${prompt.name} (${prompt.serverName})`);
+      console.log(`    ${prompt.description}`);
+    });
+
+  } catch (error) {
+    console.error('❌ 오류:', error.message);
+  } finally {
+    await client.disconnect();
+  }
+}
+
+main().catch(console.error);

package/mcp-agent-lib/example/05-error-handling.js

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+
+/**
+ * 에러 처리 및 재시도 예제
+ *
+ * MCP 클라이언트의 강력한 에러 처리와 자동 재시도 기능을 보여줍니다.
+ * - 자동 재시도 설정
+ * - 타임아웃 처리
+ * - 서버 연결 끊김 감지
+ * - 이벤트 기반 에러 모니터링
+ */
+
+import { MCPAgentClient } from '../index.js';
+
+async function main() {
+  const client = new MCPAgentClient({
+    logLevel: 'info',
+    enableConsoleDebug: true,
+
+    // 재시도 설정
+    timeout: 10000,        // 10초 타임아웃
+    retries: 5,            // 최대 5회 재시도
+    retryDelay: 1000,      // 첫 재시도는 1초 후
+    maxRetryDelay: 30000   // 최대 30초까지 지연
+  });
+
+  // 1. 서버 에러 이벤트 리스너
+  client.on('serverError', (serverName, error) => {
+    console.error(`⚠️ 서버 에러 [${serverName}]:`, error.message);
+  });
+
+  // 2. 서버 연결 해제 이벤트 리스너
+  client.on('serverDisconnected', (serverName) => {
+    console.warn(`🔌 서버 연결 끊김: ${serverName}`);
+  });
+
+  // 3. 서버 상태 변경 이벤트 리스너
+  client.on('serverStatusChange', ({ serverName, status, previousStatus }) => {
+    console.log(`📡 ${serverName}: ${previousStatus} → ${status}`);
+  });
+
+  try {
+    await client.initialize({
+      mcpServers: {
+        'test-server': {
+          type: 'stdio',
+          command: 'node',
+          args: ['server.js']
+        }
+      }
+    });
+
+    // 예제 1: 기본 재시도 (클라이언트 설정 사용)
+    try {
+      console.log('\n🔧 도구 실행 (자동 재시도 활성화)...');
+      const result = await client.executeTool('some-tool', {
+        param: 'value'
+      });
+      console.log('✅ 성공:', result);
+    } catch (error) {
+      console.error('❌ 모든 재시도 실패:', error.message);
+    }
+
+    // 예제 2: 커스텀 재시도 설정
+    try {
+      console.log('\n🔧 도구 실행 (커스텀 타임아웃/재시도)...');
+      const result = await client.executeTool(
+        'slow-tool',
+        { query: 'test' },
+        {
+          timeout: 5000,   // 이 호출만 5초 타임아웃
+          retries: 2       // 이 호출만 2회 재시도
+        }
+      );
+      console.log('✅ 성공:', result);
+    } catch (error) {
+      console.error('❌ 실패:', error.message);
+    }
+
+    // 예제 3: 서버 상태 확인 후 실행
+    const status = client.getStatus();
+    console.log('\n📊 현재 서버 상태:');
+    for (const [serverName, serverStatus] of Object.entries(status.servers)) {
+      console.log(`${serverName}: ${serverStatus.status}`);
+
+      if (serverStatus.status === 'connected') {
+        console.log(`  ✅ 연결됨 - ${serverStatus.toolCount}개 도구 사용 가능`);
+      } else if (serverStatus.status === 'partially_connected') {
+        console.log(`  ⚠️ 부분 연결 - 일부 기능만 사용 가능`);
+      } else {
+        console.log(`  ❌ 연결 안됨 - 사용 불가`);
+      }
+    }
+
+    // 예제 4: 특정 서버 연결 해제 및 재연결 처리
+    console.log('\n🔌 test-server 연결 해제...');
+    await client.disconnectServer('test-server');
+
+    const updatedStatus = client.getStatus();
+    console.log(`연결된 서버: ${updatedStatus.connectedServers}/${updatedStatus.totalServers}`);
+
+  } catch (error) {
+    // 초기화 실패 처리
+    if (error.message.includes('not allowed')) {
+      console.error('❌ 보안 에러: 허용되지 않은 명령어 또는 인자');
+    } else if (error.message.includes('timeout')) {
+      console.error('❌ 타임아웃: 서버 응답 없음');
+    } else {
+      console.error('❌ 예상치 못한 에러:', error.message);
+    }
+  } finally {
+    await client.disconnect();
+  }
+}
+
+main().catch(console.error);

package/mcp-agent-lib/example/06-resources-and-prompts.js

@@ -0,0 +1,174 @@
+#!/usr/bin/env node
+
+/**
+ * 리소스와 프롬프트 사용 예제
+ *
+ * MCP 서버의 도구(Tools) 외에도 리소스(Resources)와 프롬프트(Prompts)를
+ * 사용하는 방법을 보여줍니다.
+ *
+ * - Resources: 파일, 데이터, 문서 등을 읽을 수 있는 URI 기반 리소스
+ * - Prompts: 미리 정의된 프롬프트 템플릿
+ */
+
+import { MCPAgentClient } from '../index.js';
+
+async function main() {
+  const client = new MCPAgentClient({
+    logLevel: 'info',
+    enableConsoleDebug: true
+  });
+
+  try {
+    await client.initialize({
+      mcpServers: {
+        'content-server': {
+          type: 'stdio',
+          command: 'node',
+          args: ['content-server.js']
+        }
+      }
+    });
+
+    // ========================================
+    // 1. 리소스(Resources) 사용하기
+    // ========================================
+
+    console.log('📄 리소스 목록 조회...\n');
+
+    // 모든 서버의 리소스 목록
+    const allResources = client.getAvailableResources();
+    console.log(`총 ${allResources.length}개의 리소스 발견:`);
+    allResources.forEach(resource => {
+      console.log(`\n- ${resource.name}`);
+      console.log(`  서버: ${resource.serverName}`);
+      console.log(`  URI: ${resource.uri}`);
+      if (resource.description) {
+        console.log(`  설명: ${resource.description}`);
+      }
+      if (resource.mimeType) {
+        console.log(`  타입: ${resource.mimeType}`);
+      }
+    });
+
+    // 리소스 읽기 - 방법 1: URI로 자동 검색
+    if (allResources.length > 0) {
+      console.log('\n📖 리소스 읽기 (자동 서버 검색)...');
+      const resourceUri = allResources[0].uri;
+
+      try {
+        const content = await client.readResource(resourceUri);
+        console.log(`\n✅ ${resourceUri} 내용:`);
+        console.log(`타입: ${content.mimeType}`);
+        console.log(`데이터: ${content.data?.substring(0, 200)}...`);
+      } catch (error) {
+        console.error(`❌ 리소스 읽기 실패: ${error.message}`);
+      }
+    }
+
+    // 리소스 읽기 - 방법 2: 특정 서버에서 읽기
+    if (allResources.length > 0) {
+      console.log('\n📖 리소스 읽기 (특정 서버 지정)...');
+      const resource = allResources[0];
+
+      try {
+        const content = await client.readResourceFromServer(
+          resource.serverName,
+          resource.uri
+        );
+        console.log(`✅ 읽기 성공: ${content.uri}`);
+      } catch (error) {
+        console.error(`❌ 실패: ${error.message}`);
+      }
+    }
+
+    // ========================================
+    // 2. 프롬프트(Prompts) 사용하기
+    // ========================================
+
+    console.log('\n\n💬 프롬프트 목록 조회...\n');
+
+    // 모든 서버의 프롬프트 목록
+    const allPrompts = client.getAvailablePrompts();
+    console.log(`총 ${allPrompts.length}개의 프롬프트 발견:`);
+    allPrompts.forEach(prompt => {
+      console.log(`\n- ${prompt.name}`);
+      console.log(`  서버: ${prompt.serverName}`);
+      if (prompt.description) {
+        console.log(`  설명: ${prompt.description}`);
+      }
+      if (prompt.arguments && prompt.arguments.length > 0) {
+        console.log(`  인자:`);
+        prompt.arguments.forEach(arg => {
+          console.log(`    - ${arg.name}: ${arg.description || '(설명 없음)'}`);
+          console.log(`      필수: ${arg.required ? '예' : '아니오'}`);
+        });
+      }
+    });
+
+    // 프롬프트 실행 - 방법 1: 이름으로 자동 검색
+    if (allPrompts.length > 0) {
+      console.log('\n🎯 프롬프트 실행 (자동 서버 검색)...');
+      const promptName = allPrompts[0].name;
+
+      try {
+        const result = await client.executePrompt(promptName, {
+          // 프롬프트에 필요한 인자 전달
+          // 예: { topic: 'AI', style: 'formal' }
+        });
+        console.log(`\n✅ ${promptName} 실행 결과:`);
+        console.log(result);
+      } catch (error) {
+        console.error(`❌ 프롬프트 실행 실패: ${error.message}`);
+      }
+    }
+
+    // 프롬프트 실행 - 방법 2: 특정 서버에서 실행
+    if (allPrompts.length > 0) {
+      console.log('\n🎯 프롬프트 실행 (특정 서버 지정)...');
+      const prompt = allPrompts[0];
+
+      try {
+        const result = await client.getPrompt(
+          prompt.serverName,
+          prompt.name,
+          {
+            // 프롬프트 인자
+            customParam: 'value'
+          }
+        );
+        console.log(`✅ 실행 성공`);
+        console.log(result);
+      } catch (error) {
+        console.error(`❌ 실패: ${error.message}`);
+      }
+    }
+
+    // ========================================
+    // 3. 통합 정보 조회
+    // ========================================
+
+    console.log('\n\n📊 서버별 기능 요약:\n');
+    const status = client.getStatus();
+
+    for (const [serverName, serverStatus] of Object.entries(status.servers)) {
+      console.log(`${serverName}:`);
+      console.log(`  상태: ${serverStatus.status}`);
+      console.log(`  도구: ${serverStatus.toolCount}개`);
+
+      // 해당 서버의 리소스 수
+      const serverResources = allResources.filter(r => r.serverName === serverName);
+      console.log(`  리소스: ${serverResources.length}개`);
+
+      // 해당 서버의 프롬프트 수
+      const serverPrompts = allPrompts.filter(p => p.serverName === serverName);
+      console.log(`  프롬프트: ${serverPrompts.length}개`);
+    }
+
+  } catch (error) {
+    console.error('❌ 오류:', error.message);
+  } finally {
+    await client.disconnect();
+  }
+}
+
+main().catch(console.error);