{"id":51053673,"url":"https://github.com/hi-space/websearch-agentcore-gateway","last_synced_at":"2026-06-22T19:30:33.467Z","repository":{"id":366144915,"uuid":"1247420482","full_name":"hi-space/websearch-agentcore-gateway","owner":"hi-space","description":"Unified web-search gateway on AWS Bedrock AgentCore — 9 Lambda search/extraction engines + a hosted Tavily MCP target, JWT auth, full observability, Terraform IaC.","archived":false,"fork":false,"pushed_at":"2026-06-20T14:07:13.000Z","size":874,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-20T14:15:56.740Z","etag":null,"topics":["agentcore","aws","bedrock","lambda","mcp","serverless","terraform","web-search"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hi-space.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-23T09:40:55.000Z","updated_at":"2026-06-20T14:07:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hi-space/websearch-agentcore-gateway","commit_stats":null,"previous_names":["hi-space/websearch-agentcore-gateway"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hi-space/websearch-agentcore-gateway","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hi-space%2Fwebsearch-agentcore-gateway","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hi-space%2Fwebsearch-agentcore-gateway/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hi-space%2Fwebsearch-agentcore-gateway/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hi-space%2Fwebsearch-agentcore-gateway/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hi-space","download_url":"https://codeload.github.com/hi-space/websearch-agentcore-gateway/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hi-space%2Fwebsearch-agentcore-gateway/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34663520,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-22T02:00:06.391Z","response_time":106,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentcore","aws","bedrock","lambda","mcp","serverless","terraform","web-search"],"created_at":"2026-06-22T19:30:27.784Z","updated_at":"2026-06-22T19:30:33.459Z","avatar_url":"https://github.com/hi-space.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# WebSearch Tool Gateway\n\n**통합 검색 엔진 게이트웨이 with Bedrock AgentCore**\n\n## 30초 소개\n\nWebSearch Tool Gateway는 AWS Bedrock AgentCore를 통해 여러 검색·추출 엔진(Serper, Exa, DuckDuckGo, Perplexity, Brave, Anthropic, Firecrawl, You.com, Tavily)을 단일 MCP 게이트웨이로 통합하고, Cowork 3P 클라이언트를 통해 Claude에게 접근을 제공하는 완전 관리형 인프라입니다.\n\n```mermaid\nflowchart TD\n    Client[\"Cowork 3P Client\u003cbr/\u003e(macOS / Windows)\"]\n    Gateway[\"Bedrock AgentCore Gateway\u003cbr/\u003e(Custom JWT + MCP Targets)\"]\n\n    Client --\u003e|\"Managed MCP Server\u003cbr/\u003e(JWT headers)\"| Gateway\n\n    Gateway --\u003e Lambda[\"Lambda Tool Targets\u003cbr/\u003e(9개 · 토글로 활성화)\"]\n    Gateway --\u003e MCP[\"MCP Server Target\u003cbr/\u003eTavily 호스팅 · mcp.tavily.com\"]\n\n    Lambda --\u003e L1[\"serper · exa · duckduckgo · perplexity\"]\n    Lambda --\u003e L2[\"brave · anthropic · firecrawl\"]\n    Lambda --\u003e L3[\"you · tavily_lambda\"]\n```\n\n### 핵심 기능\n\n- **Unified Search Interface**: 9개 Lambda 엔진 + 1개 호스팅 MCP 타겟(Tavily) 통합, API 키 유무에 따라 토글\n- **AgentCore Gateway**: JWT 기반 인증, 허용 클라이언트 기반 접근 제어\n- **Cowork Integration**: macOS/Windows 자동 설정/제거 (idempotent setup/uninstall scripts)\n- **Observability**: CloudWatch Logs + Metrics + X-Ray 트레이스 (대시보드 연동)\n- **Infrastructure as Code**: Terraform 기반 완전 자동화 배포\n\n---\n\n## 5분 빠른 시작\n\n### 전제 조건\n\n- AWS 계정 (us-east-1 리전)\n- Terraform 1.7+\n- AWS CLI v2\n- macOS/Linux 또는 Windows PowerShell\n\n### 1단계: 인프라 배포\n\n```bash\ncd infra/environments/dev\n\n# terraform.tfvars 생성 (엔진 토글 + API 키 입력)\ncp terraform.tfvars.example terraform.tfvars\n# 편집: enable_* 플래그와 serper_api_key, exa_api_key, perplexity_api_key 등\n\n# 배포\nterraform init\nterraform plan\nterraform apply\n```\n\n\u003e 각 엔진은 `enable_\u003cengine\u003e` 플래그로 켜고 끕니다. 키가 비어 있으면 해당 Lambda/타겟은 생성되지 않습니다. DuckDuckGo는 API 키 없이 동작합니다.\n\n배포 완료 후:\n```bash\nterraform output -json \u003e ../../../outputs.json\n```\n\n### 2단계: Cowork 3P 클라이언트 설정 (macOS)\n\n```bash\ncd cowork\n./setup-mac.sh\n# → Cognito M2M 토큰 생성 → mobileconfig 렌더링 → 설치\n```\n\n**Windows:**\n```powershell\ncd cowork\n.\\setup-windows.ps1\n# → Windows 레지스트리 업데이트\n```\n\n### 3단계: 대시보드 실행 (옵션, 로컬 테스트용)\n\n```bash\ncd dashboard\ncp .env.example .env.local\n# terraform outputs를 .env.local에 입력\n\npnpm install\npnpm dev\n# → http://localhost:3000\n```\n\n---\n\n## 상세 문서\n\n각 워크트랙별 기술 가이드:\n\n### infra/ — Terraform IaC\n\n**배포 가이드**: [infra/README.md](./infra/README.md)\n- 모듈 구조 (auth, gateway, identity-providers, observability)\n- 환경 변수 및 API 키 관리\n- 배포 및 파괴 스크립트\n\n### tools/ — Python Lambda 핸들러\n\n**개발 가이드**: [tools/README.md](./tools/README.md)\n- Lambda 핸들러 9종 (serper, exa, duckduckgo, perplexity, brave, anthropic, firecrawl, you, tavily_lambda)\n- 공유 `SearchResponse` 계약 스키마 (`_shared/response.py`)\n- API 키 관리: env-var 직접 주입 또는 AgentCore Identity 조회 (`_shared/identity.py`)\n- 테스트 (`tools/tests/test_handlers.py`) 및 패키징\n\n### dashboard/ — Next.js 16 대시보드\n\n**기술 설명**: [dashboard/README.md](./dashboard/README.md)\n- 페이지별 기능 (Inspector, Observability, Traces, Playground, Audit)\n- API 라우트 및 서버사이드 AWS SDK 호출 (`/api/access`, `/api/mcp`, `/api/cw`, `/api/xray`, `/api/eval`)\n- 로컬 개발 환경 설정\n\n### cowork/ — Cowork 3P 설정\n\n**설정 가이드**: [cowork/README.md](./cowork/README.md)\n- macOS mobileconfig 렌더링 및 설치\n- Windows 레지스트리 업데이트\n- 토큰 갱신 메커니즘 (JWT auto-refresh)\n\n---\n\n## 디렉토리 구조\n\n```\nwebsearch-tool-gateway/\n├── README.md                  # 이 파일\n├── .gitignore                 # 보안: 상태 파일, 환경 변수 제외\n├── ARCHITECTURE.md            # 기술 아키텍처 (영문)\n│\n├── infra/                     # Terraform IaC\n│   ├── README.md              # 배포 가이드\n│   ├── bootstrap/             # S3 + DynamoDB 상태 관리\n│   ├── environments/dev/      # dev 환경 설정 (main.tf, terraform.tfvars.example)\n│   ├── modules/               # auth, gateway, gateway-lambda-tool,\n│   │                          #   gateway-mcp-target, identity-providers, observability\n│   └── scripts/               # 자동화 (deploy.sh, destroy.sh, seed-api-keys.sh)\n│\n├── tools/                     # Python 3.12 Lambda 핸들러\n│   ├── README.md              # 개발 가이드\n│   ├── pyproject.toml         # 패키지 설정\n│   ├── requirements*.txt      # 런타임 / dev 의존성\n│   ├── _shared/               # 공유 라이브러리\n│   │   ├── identity.py        # AgentCore API 키 조회\n│   │   ├── response.py        # SearchResponse 정규화\n│   │   ├── otel.py            # OpenTelemetry 트레이싱\n│   │   └── constants.py       # 상수 및 제한값\n│   ├── serper/  exa/  duckduckgo/  perplexity/   # 검색 엔진 핸들러\n│   ├── brave/  anthropic/  firecrawl/  you/      # 추가 검색/추출 핸들러\n│   ├── tavily_lambda/         # Lambda 백엔드 Tavily (호스팅 MCP와 별개)\n│   └── tests/                 # test_handlers.py\n│\n├── dashboard/                 # Next.js 16 대시보드\n│   ├── package.json           # pnpm 의존성\n│   ├── .env.example           # 환경 변수 템플릿\n│   ├── src/\n│   │   ├── app/               # Next.js 앱 라우터\n│   │   │   ├── inspector/     # MCP 도구 인스펙터\n│   │   │   ├── observability/ # CloudWatch 메트릭\n│   │   │   ├── traces/        # X-Ray 트레이스 조회\n│   │   │   ├── playground/    # 다중 엔진 비교\n│   │   │   ├── audit/         # Logs Insights 로그 조회\n│   │   │   └── api/           # 서버사이드 라우트 (access, mcp, cw, xray, eval, auth)\n│   │   ├── lib/               # 유틸리티 (AWS 타입, MCP 클라이언트, constants)\n│   │   └── components/        # shadcn/ui 컴포넌트 + shell(nav)\n│   └── public/                # 정적 자산\n│\n├── cowork/                    # Cowork 3P 설정\n│   ├── README.md              # 설정 가이드\n│   ├── setup-mac.sh / setup-windows.ps1        # 자동 설정\n│   ├── uninstall-mac.sh / uninstall-windows.ps1 # 설정 제거\n│   ├── agentcore-token.sh / agentcore-token.ps1 # JWT 갱신 헬퍼\n│   └── templates/             # mobileconfig + registry 템플릿\n│\n└── docs/                      # 한글 가이드 (추가 리소스)\n    ├── 01-deployment-guide.md\n    ├── 02-cowork-setup-mac.md\n    ├── 02-cowork-setup-windows.md\n    ├── 03-observability.md\n    └── 04-troubleshooting.md\n```\n\n---\n\n## 아키텍처 (기술)\n\n전체 시스템 아키텍처는 [ARCHITECTURE.md](./ARCHITECTURE.md)를 참고하세요.\n\n**핵심 컴포넌트**:\n\n1. **Bedrock AgentCore Gateway** — JWT 인증 기반 중앙 MCP 라우터\n2. **Lambda Tool Targets** — 검색/추출 API 래퍼 9종 (serper, exa, duckduckgo, perplexity, brave, anthropic, firecrawl, you, tavily_lambda)\n3. **MCP Server Target** — 외부 호스팅 MCP 서버 (Tavily, `mcp.tavily.com`)\n4. **Identity Providers** — AgentCore API Key Credential Provider (엔진별 키 보관)\n5. **Cognito User Pool** — M2M + App + Web 클라이언트 인증\n6. **CloudWatch + X-Ray Observability** — Vended logs + metrics + traces\n\n---\n\n## 일반적인 작업\n\n### API 키 추가/변경\n\n```bash\ncd infra/environments/dev\n# terraform.tfvars 편집\nterraform apply\n```\n\n### 로그 조회\n\n```bash\n# 게이트웨이 ID는 terraform output gateway_id 로 확인\n# 대시보드의 /audit 페이지 또는:\naws logs start-query \\\n  --log-group-name \"/aws/vendedlogs/bedrock-agentcore/gateway/APPLICATION_LOGS/\u003cgateway-id\u003e\" \\\n  --start-time $(date -d '1 hour ago' +%s) \\\n  --end-time $(date +%s) \\\n  --query-string 'fields @timestamp, @message | filter @message like /error/ | stats count() by bin(1m)'\n```\n\n### 환경 초기화 (개발)\n\n```bash\ncd infra\n./scripts/destroy.sh  # 대화형 확인 후 모든 리소스 제거\n```\n\n---\n\n## 문제 해결\n\n### Cowork 설정 실패\n\n1. Terraform 출력 확인:\n   ```bash\n   cd infra/environments/dev\n   terraform output gateway_url\n   terraform output cognito_domain\n   ```\n\n2. JWT 토큰 갱신 로그 확인:\n   ```bash\n   cat ~/.websearch-gw/agentcore-token.log\n   ```\n\n3. mobileconfig 설치 재시도:\n   ```bash\n   cd cowork\n   ./setup-mac.sh --force-login\n   ```\n\n### Lambda 함수 테스트\n\n```bash\n# 함수명 규칙: \u003cproject_name\u003e-\u003cenvironment\u003e-tool-\u003cengine\u003e (기본 websearch-gw-dev-tool-serper)\naws lambda invoke \\\n  --function-name websearch-gw-dev-tool-serper \\\n  --payload '{\"query\": \"test\", \"num_results\": 5}' \\\n  --region us-east-1 \\\n  response.json\ncat response.json | jq\n```\n\n### CloudWatch 메트릭 확인\n\n```bash\naws cloudwatch get-metric-statistics \\\n  --namespace Bedrock/AgentCore \\\n  --metric-name GatewayInvocations \\\n  --dimensions Name=GatewayId,Value=\u003cgateway-id\u003e \\\n  --statistics Sum Average \\\n  --start-time $(date -d '1 hour ago' -Iseconds) \\\n  --end-time $(date -Iseconds) \\\n  --period 300 \\\n  --region us-east-1\n```\n\n---\n\n## 보안 고려사항\n\n- ✅ **상태 파일**: S3 암호화 + DynamoDB 잠금 (Terraform backend)\n- ✅ **API 키**: AgentCore Identity Credential Provider 보관 또는 Lambda 환경변수 주입 (Terraform 변수는 `sensitive=true`)\n- ✅ **접근 제어**: JWT 인증 + 허용 클라이언트 목록 (Cognito M2M / App / Web)\n- ✅ **JWT 토큰**: 만료 전 자동 갱신 (Cowork 클라이언트)\n- ✅ **로그**: CloudWatch Vended Logs + X-Ray 트레이스 중앙화 (감사 추적)\n\n**주의**: `terraform.tfvars` 및 `.env.local` 파일을 git에 커밋하지 마세요.\n\n---\n\n## 기여\n\n이 프로젝트는 완전 자동화된 멀티 워크트랙 시스템입니다.\n\n- **infra/**: Terraform 모듈 수정 시 `terraform fmt -recursive .` 실행\n- **tools/**: Python 핸들러 수정 시 `pytest` 실행\n- **dashboard/**: UI 변경 시 `pnpm build` 검증\n- **cowork/**: 스크립트 수정 시 macOS/Windows 양쪽 테스트\n\n---\n\n## 라이선스\n\nAWS 샘플 코드. MIT 라이선스 참고.\n\n---\n\n## 지원\n\n- 📖 [ARCHITECTURE.md](./ARCHITECTURE.md) — 기술 아키텍처\n- 📋 [infra/README.md](./infra/README.md) — 배포 세부사항\n- 🛠️ [tools/README.md](./tools/README.md) — Lambda 개발\n- 🎨 [dashboard/README.md](./dashboard/README.md) — Next.js 기술\n- 🔧 [cowork/README.md](./cowork/README.md) — Cowork 설정\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhi-space%2Fwebsearch-agentcore-gateway","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhi-space%2Fwebsearch-agentcore-gateway","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhi-space%2Fwebsearch-agentcore-gateway/lists"}