OpenSearch Logs MCP Server

OpenSearch에서 OpenTelemetry 로그를 쿼리하기 위한 MCP(Model Context Protocol) 서버입니다. 개발(dev) 및 운영(prod) 환경을 지원합니다.

아키텍처

이 서버는 SOLID 원칙과 Clean Architecture를 따릅니다:

src/
├── index.ts # Entry point
├── server.ts # MCP Server setup
├── config/
│ └── environments.ts # Environment configuration
├── types/
│ └── index.ts # Type definitions
├── services/
│ ├── opensearch-client.ts # HTTP client for OpenSearch
│ └── log-search.service.ts # Business logic
├── tools/
│ ├── tool-definitions.ts # Tool schemas
│ └── tool-handlers.ts # Tool execution
└── utils/
 ├── query-builder.ts # Query construction (Builder pattern)
 └── time-range.ts # Time utilities

적용된 원칙

• 단일 책임 원칙 (SRP): 각 모듈은 단일 책임을 가집니다.

• 개방-폐쇄 원칙 (OCP): 기존 코드를 수정하지 않고도 새로운 도구를 쉽게 추가할 수 있습니다.

• 의존성 역전 원칙 (DIP): 서비스는 추상화(인터페이스)에 의존합니다.

• 빌더 패턴 (Builder Pattern): 쿼리 생성을 위한 QueryBuilder를 사용합니다.

설치

cd Tools/mcp-opensearch-logs
npm install
npm run build

Cursor 설정

Cursor 설정(~/.cursor/mcp.json)에 다음을 추가하세요:

{
 "mcpServers": {
 "opensearch-logs": {
 "command": "node",
 "args": ["/ruta/al/proyecto/Tools/mcp-opensearch-logs/dist/index.js"],
 "env": {
 "OPENSEARCH_DEV_USERNAME": "tu-usuario-dev",
 "OPENSEARCH_DEV_PASSWORD": "tu-password-dev",
 "OPENSEARCH_PROD_USERNAME": "tu-usuario-prod",
 "OPENSEARCH_PROD_PASSWORD": "tu-password-prod"
 }
 }
 }
}

사용 가능한 도구

search_logs

Lucene 구문을 사용한 자유 검색.

예시:

• "지난 1시간 동안 dev 환경에서 'error'가 포함된 로그 검색"

• "지난 6시간 동안 prod 환경에서 상태 코드 500인 로그 검색"

search_by_trace

OpenTelemetry 트레이스의 모든 로그를 검색합니다.

예시:

• "dev 환경에서 trace abc123의 모든 로그를 보여줘"

search_by_service

서비스 이름으로 로그를 필터링합니다.

예시:

• "prod 환경에서 stori-ios 서비스의 로그 검색"

• "dev 환경에서 stori-ios 서비스의 오류 로그 검색"

search_errors

ERROR 수준 이상의 로그를 검색합니다 (severityNumber >= 17).

예시:

• "prod 환경에서 지난 1시간 동안의 오류 검색"

• "dev 환경에서 KYC 관련 오류 검색"

get_field_values

특정 필드의 가장 일반적인 값을 가져옵니다 (집계).

예시:

• "prod 환경에서 'event' 필드의 값은 무엇인가요?"

• "dev 환경에서 가장 일반적인 오류 유형을 보여줘"

search_by_field

특정 필드와 값으로 검색합니다.

예시:

• "prod 환경에서 transactionId=abc123인 로그 검색"

get_mapping

인덱스의 필드 매핑을 가져옵니다.

예시:

• "prod 로그에서 사용할 수 있는 필드는 무엇인가요?"

get_sample_log

구조를 확인하기 위해 샘플 로그를 가져옵니다.

예시:

• "구조를 확인하기 위해 prod 샘플 로그를 보여줘"

Lucene 검색 구문

query 필드는 전체 Lucene 구문을 지원합니다:

시간 범위

개발

# Desarrollo con watch mode
npm run dev

# Build
npm run build

# Lint
npm run lint

OpenTelemetry 로그 구조

로그는 OpenTelemetry 스키마를 따릅니다:

{
 "time": "2024-01-15T10:30:00.000Z",
 "severityText": "ERROR",
 "severityNumber": 17,
 "body": "Error message",
 "attributes": {
 "event": "kyc_error",
 "kycFlow": "creditL1",
 "transactionId": "abc123"
 },
 "resource": {
 "service.name": "stori-ios",
 "service.version": "1.0.0"
 }
}

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• get_field_valuesB
• get_mappingA
• get_sample_logB
• search_by_fieldC
• search_by_serviceC
• search_by_traceA
• search_errorsC
• search_logsA