OpenSearch Logs MCP Server

MCP (Model Context Protocol) server for querying OpenTelemetry logs in OpenSearch. Supports development (dev) and production (prod) environments.

Architecture

The server follows SOLID principles and 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

Applied Principles

• Single Responsibility (SRP): Each module has a single responsibility

• Open/Closed (OCP): Easy to add new tools without modifying existing code

• Dependency Inversion (DIP): Services depend on abstractions (interfaces)

• Builder Pattern: QueryBuilder for fluent query construction

Related MCP server: otel-mcp-server

Installation

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

Configuration in Cursor

Add this to your Cursor configuration (~/.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"
      }
    }
  }
}

Available Tools

search_logs

Free-text search with Lucene syntax.

Examples:

• "Search for logs containing 'error' in dev from the last hour"

• "Search for logs with status 500 in prod from the last 6 hours"

search_by_trace

Search all logs for an OpenTelemetry trace.

Example:

• "Give me all logs for trace abc123 in dev"

search_by_service

Filter logs by service name.

Examples:

• "Search for logs from the stori-ios service in prod"

• "Give me errors from the stori-ios service in dev"

search_errors

Search for logs with level ERROR or higher (severityNumber >= 17).

Examples:

• "Give me errors from the last hour in prod"

• "Search for errors related to KYC in dev"

get_field_values

Get the most common values for a field (aggregation).

Examples:

• "What values does the 'event' field have in prod?"

• "Give me the most common error types in dev"

search_by_field

Search by a specific field and value.

Example:

• "Search for logs with transactionId=abc123 in prod"

get_mapping

Get the index field mapping.

Example:

• "What fields are available in the prod logs?"

get_sample_log

Get a sample log to see the structure.

Example:

• "Give me a sample log from prod to see the structure"

Lucene Search Syntax

The query field supports full Lucene syntax:

Time Ranges

Development

# Desarrollo con watch mode
npm run dev

# Build
npm run build

# Lint
npm run lint

OpenTelemetry Log Structure

Logs follow the OpenTelemetry schema:

{
  "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"
  }
}