AWS Bedrock KB Retrieval

Amazon Bedrock Knowledge Base 검색 MCP 서버

Amazon Bedrock Knowledge Bases에 접근하기 위한 MCP 서버

기능

Knowledge Base 및 데이터 소스 검색

• 사용 가능한 모든 Knowledge Base 찾기 및 탐색
• 이름이나 태그로 Knowledge Base 검색
• 각 Knowledge Base와 연결된 데이터 소스 목록 표시

자연어로 Knowledge Base 쿼리

• 대화형 쿼리를 사용하여 정보 검색
• Knowledge Base에서 관련 구절 가져오기
• 모든 결과에 대한 인용 정보 접근

데이터 소스별 결과 필터링

• 특정 데이터 소스에 쿼리 집중
• 특정 데이터 소스 포함 또는 제외
• 특정 데이터 소스의 결과 우선순위 지정

관리형 Knowledge Base의 에이전트 검색

• 다단계 검색 전략을 계획하고 인용된 답변 종합
• 한 번의 호출로 여러 Knowledge Base 검색
• 에이전트의 계획 및 검색 단계에 대한 선택적 축약 추적
• 관리형 Knowledge Base 전용; 도구는 다른 유형을 명확한 메시지와 함께 거부

ACL 보호 콘텐츠 접근

• user_id 전달하여 ACL 인식 데이터 소스(SharePoint, OneDrive, 문서별 ACL이 있는 Confluence)에서 콘텐츠 검색
• 이 값이 없으면 해당 콘텐츠에 접근할 수 없으며, 에이전트 검색의 전체 문서 확장 단계가 "ACL 인식 데이터 소스에는 UserContext가 필요합니다" 오류와 함께 실패
• 결과는 해당 사용자가 볼 수 있도록 승인된 내용으로 필터링

관리형 및 벡터 Knowledge Base 모두 지원

• 벡터 Knowledge Base(type: VECTOR) 및 관리형 Knowledge Base(type: MANAGED)와 함께 작동
• Knowledge Base 유형이 자동으로 감지되고 올바른 Retrieve 구성이 전송됨(vectorSearchConfiguration 또는 managedSearchConfiguration)
• 데이터 소스 필터링은 Knowledge Base 유형에 적합한 메타데이터 키를 사용
• ListKnowledgeBases 도구는 각 Knowledge Base의 type을 보고

결과 재순위화

• 검색 결과의 관련성 향상
• Amazon Bedrock 재순위화 기능 사용
• 쿼리와의 관련성에 따라 결과 정렬

사전 요구 사항

설치 요구 사항

1. Astral 또는 GitHub README에서 uv 설치
2. uv python install 3.10을 사용하여 Python 설치

AWS 요구 사항

1. AWS CLI 구성: Amazon Bedrock 및 Knowledge Bases에 접근할 수 있는 자격 증명과 AWS_PROFILE로 AWS CLI가 구성되어 있어야 합니다.
2. Amazon Bedrock Knowledge Base: 값이 true인 태그 키 mcp-multirag-kb이 있는 Amazon Bedrock Knowledge Base가 하나 이상 있어야 합니다.
3. IAM 권한: IAM 역할/사용자에게 다음을 위한 적절한 권한이 있어야 합니다:
   • Knowledge Base 나열 및 설명
   • 데이터 소스 접근
   • Knowledge Base 쿼리

재순위화 요구 사항

재순위화 기능을 사용하려면 Bedrock Knowledge Base에 추가 권한이 필요합니다:

1. IAM 역할에 bedrock:Rerank 및 bedrock:InvokeModel 작업 모두에 대한 권한이 있어야 합니다.
2. Amazon Bedrock Knowledge Bases 서비스 역할에도 이러한 권한이 있어야 합니다.
3. 재순위화 가용성은 모델별로 다릅니다: amazon.rerank-v1:0은 us-east-1에서 제공되지 않지만 cohere.rerank-v3-5:0은 제공됩니다. 서버는 (리전, 모델) 쌍을 검증하고 명확한 메시지와 함께 빠르게 실패합니다. 지원되는 리전의 최신 목록은 공식 문서를 참조하세요.
4. 지정된 리전에서 사용 가능한 재순위화 모델에 대한 모델 접근을 활성화하세요.

에이전트 검색 요구 사항

AgenticQueryKnowledgeBases 도구는 관리형 Knowledge Base 전용(type: MANAGED)으로 지원되는 AgenticRetrieveStream을 호출합니다. 검색 전략을 계획하고, generate_response=false을 전달하지 않으면 인용된 답변을 작성하기 위해 파운데이션 모델을 호출합니다.

1. IAM 역할에는 위에 나열된 권한 외에도 Knowledge Base에 대한 bedrock:AgenticRetrieveStream이 필요합니다.
2. 파운데이션 모델을 호출하므로 QueryKnowledgeBases보다 호출당 비용이 훨씬 더 많이 듭니다. 합성 없이 검색만 하려면 generate_response=false을 전달하세요.
3. RetrieveAndGenerate은 관리형 Knowledge Base에서 지원되지 않으므로 generate_response=true을 사용한 에이전트 검색이 생성된 답변을 얻는 방법입니다.

재순위화 제어

BEDROCK_KB_RERANKING_ENABLED 환경 변수를 사용하여 재순위화를 전역적으로 활성화하거나 비활성화할 수 있습니다:

• false(기본값)으로 설정: 명시적으로 활성화하지 않는 한 모든 쿼리에 대해 재순위화 비활성화
• true으로 설정: 명시적으로 비활성화하지 않는 한 모든 쿼리에 대해 재순위화 활성화

환경 변수는 다양한 형식을 허용합니다:

• 활성화: 'true', '1', 'yes' 또는 'on'(대소문자 구분 없음)
• 비활성화: 다른 값 또는 설정되지 않음(기본 동작)

이 설정은 전역 기본값을 제공하며, 개별 API 호출에서 reranking 매개변수를 명시적으로 설정하여 재정의할 수 있습니다.

Knowledge Base 설정에 대한 자세한 지침은 다음을 참조하세요:

• Knowledge Base 생성
• Amazon Bedrock Knowledge Bases 권한 관리
• Amazon Bedrock 재순위화 권한

설치

Kiro	Cursor	VS Code

MCP 클라이언트 구성에서 MCP 서버를 구성하세요(예: Kiro의 경우 ~/.kiro/settings/mcp.json 편집):

{
  "mcpServers": {
    "awslabs.bedrock-kb-retrieval-mcp-server": {
      "command": "uvx",
      "args": ["awslabs.bedrock-kb-retrieval-mcp-server@latest"],
      "env": {
        "AWS_PROFILE": "your-profile-name",
        "AWS_REGION": "us-east-1",
        "FASTMCP_LOG_LEVEL": "ERROR",
        "KB_INCLUSION_TAG_KEY": "optional-tag-key-to-filter-kbs",
        "BEDROCK_KB_RERANKING_ENABLED": "false"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Windows 설치

Windows 사용자의 경우 MCP 서버 구성 형식이 약간 다릅니다:

{
  "mcpServers": {
    "awslabs.bedrock-kb-retrieval-mcp-server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--from",
        "awslabs.bedrock-kb-retrieval-mcp-server@latest",
        "awslabs.bedrock-kb-retrieval-mcp-server.exe"
      ],
      "env": {
        "FASTMCP_LOG_LEVEL": "ERROR",
        "AWS_PROFILE": "your-aws-profile",
        "AWS_REGION": "us-east-1"
      }
    }
  }
}

또는 docker build -t awslabs/bedrock-kb-retrieval-mcp-server . 성공 후 docker:

# fictitious `.env` file with AWS temporary credentials
AWS_ACCESS_KEY_ID=ASIAIOSFODNN7EXAMPLE
AWS_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
AWS_SESSION_TOKEN=AQoEXAMPLEH4aoAH0gNCAPy...truncated...zrkuWJOgQs8IZZaIv2BXIa2R4Olgk

  {
    "mcpServers": {
      "awslabs.bedrock-kb-retrieval-mcp-server": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "--interactive",
          "--env",
          "FASTMCP_LOG_LEVEL=ERROR",
          "--env",
          "KB_INCLUSION_TAG_KEY=optional-tag-key-to-filter-kbs",
          "--env",
          "BEDROCK_KB_RERANKING_ENABLED=false",
          "--env",
          "AWS_REGION=us-east-1",
          "--env-file",
          "/full/path/to/file/above/.env",
          "awslabs/bedrock-kb-retrieval-mcp-server:latest"
        ],
        "env": {},
        "disabled": false,
        "autoApprove": []
      }
    }
  }

참고: 자격 증명은 호스트에서 계속 새로 고쳐야 합니다.

제한 사항

• IMAGE 콘텐츠 유형의 결과는 KB 쿼리 응답에 포함되지 않습니다.
• reranking 매개변수는 추가 권한, Amazon Bedrock 모델 접근이 필요하며 특정 리전에서만 사용할 수 있습니다.