### Start Command Examples

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

Examples demonstrating how to start the MCP server using different configurations and flags.

```bash
# Use default config locations
./alibabacloud-observability-mcp-server start

# Specify config file explicitly
./alibabacloud-observability-mcp-server start --config /etc/app/config.yaml

# Force stdio mode regardless of config
./alibabacloud-observability-mcp-server start --stdio

# With environment variables
export ALIBABA_CLOUD_ACCESS_KEY_ID=xxx
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=xxx
./alibabacloud-observability-mcp-server start
```

--------------------------------

### Get Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/toolkit-core.md

Example of getting a tool from the registry.

```go
tool, ok := registry.Get("sls_list_projects")
if !ok {
    return fmt.Errorf("tool not found")
}
```

--------------------------------

### Tool Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/toolkit-core.md

Example of how to define a Tool.

```go
tool := toolkit.Tool{
    Name: "my_tool",
    Description: "Does something useful\n\nParameters: ...",
    InputSchema: map[string]interface{}{
        "type": "object",
        "properties": map[string]interface{}{
            "param1": map[string]interface{}{
                "type":        "string",
                "description": "A parameter",
            },
        },
        "required": []string{"param1"},
    },
    Handler: func(ctx context.Context, params map[string]interface{}) (interface{}, error) {
        // Implementation
        return result, nil
    },
}
```

--------------------------------

### Register Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/toolkit-core.md

Example of registering a toolkit.

```go
paasToolkit := paas.NewPaaSToolkit(cmsClient)
registry.Register(paasToolkit)
```

--------------------------------

### Run Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/server.md

Example demonstrating how to run the MCP server.

```go
ctx := context.Background()
err := server.Run(ctx, cfg, srv)
if err != nil {
    slog.Error("server run failed", "error", err)
}
```

--------------------------------

### NewRegistry Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/toolkit-core.md

Example of creating a new Registry.

```go
registry := toolkit.NewRegistry()
```

--------------------------------

### Example .env File

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

Example of an .env file for setting credentials and runtime parameters.

```bash
ALIBABA_CLOUD_ACCESS_KEY_ID=AKIA2XXXXXXXXXX
ALIBABA_CLOUD_ACCESS_KEY_SECRET=xxxxxxxxxxxxxxxx
ALIBABA_CLOUD_SECURITY_TOKEN=optional-sts-token
ALIBABA_CLOUD_REGION=cn-hongkong
ALIBABA_CLOUD_WORKSPACE=default
```

--------------------------------

### Credential Provider Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/client.md

Example of creating and using a credential provider.

```go
cred := client.NewCredentialProvider(
    os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_ID"),
    os.Getenv("ALIBABA_CLOUD_ACCESS_KEY_SECRET"),
    os.Getenv("ALIBABA_CLOUD_SECURITY_TOKEN"),
)

accessKey, err := cred.GetAccessKeyID()
if err != nil {
    return err
}
```

--------------------------------

### SLS Client Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/client.md

Example of creating and using an SLS client.

```go
cfg, _ := config.Load("")
cred := client.NewCredentialProvider("", "", "")
slsClient := client.NewSLSClient(cred, cfg)

projects, err := slsClient.ListProjects(ctx, "cn-hongkong")
if err != nil {
    return err
}
```

--------------------------------

### Runtime Configuration Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

Example of runtime configuration settings.

```yaml
runtime:
  region: cn-hongkong
  workspace: default
```

--------------------------------

### Toolkit Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/toolkit-core.md

Example implementation of the Toolkit interface.

```go
type MyToolkit struct {
    tools []toolkit.Tool
}

func (t *MyToolkit) Name() string {
    return "my_toolkit"
}

func (t *MyToolkit) Tools() []toolkit.Tool {
    return t.tools
}
```

--------------------------------

### NewServer Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/server.md

Example demonstrating how to create a new Server instance with necessary clients and registry.

```go
cfg, _ := config.Load("")
registry := toolkit.NewRegistry()
slsClient := client.NewSLSClient(cred, cfg)
cmsClient := client.NewCMSClient(cred, cfg)
toolkit.RegisterToolkits(registry, cfg.Toolkit.Scope, cfg.Toolkit.EnabledTools, paasToolkit, iaasToolkit, sharedToolkit)

srv, err := server.NewServer(cfg, registry, slsClient, cmsClient)
if err != nil {
    return fmt.Errorf("create server: %w", err)
}
```

--------------------------------

### Introduction Tool Example Call

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/shared-tools.md

Example of how to call the introduction tool with empty parameters in Go.

```Go
// Call with empty parameters
params := map[string]interface{}{}
result, err := handler(ctx, params)
// Returns complete service introduction and reference information
```

--------------------------------

### Server Configuration Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

An example of how to configure the server transport, host, and port.

```yaml
server:
  transport: streamable-http
  host: "127.0.0.1"
  port: 8080
```

--------------------------------

### sls_list_projects Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/iaas-tools.md

Example parameters for the sls_list_projects tool.

```Go
params := map[string]interface{}{
    "regionId": "cn-hongkong",
    "project": "payment",
    "limit": 50,
}
```

--------------------------------

### Network Configuration Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

Example of network configuration settings.

```yaml
network:
  max_retry: 3
  retry_wait_seconds: 2
  read_timeout_ms: 600000    # 10 minutes for large queries
  connect_timeout_ms: 30000
```

--------------------------------

### Logging Configuration Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

An example of how to configure logging level and debug mode.

```yaml
logging:
  level: debug
  debug_mode: true
```

--------------------------------

### NewCMSClient Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/client.md

Example of creating and using a CMS client to list workspaces.

```go
cfg, _ := config.Load("")
cred := client.NewCredentialProvider("", "", "")
cmsClient := client.NewCMSClient(cred, cfg)

workspaces, err := cmsClient.ListWorkspaces(ctx, "cn-hongkong")
if err != nil {
    return err
}
```

--------------------------------

### Locale Configuration Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

Example of locale configuration settings.

```yaml
locale:
  timezone: America/New_York
  language: en-US
```

--------------------------------

### umodel_get_entities Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/paas-tools.md

Example demonstrating how to call the umodel_get_entities tool with specific parameters to retrieve entity information.

```go
params := map[string]interface{}{
    "workspace": "default",
    "domain": "apm",
    "entity_set_name": "apm.service",
    "regionId": "cn-hongkong",
    "entity_filter": "name=payment",
    "limit": 50,
}
result, err := handler(ctx, params)
```

--------------------------------

### Example Full Configuration

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

An example of a comprehensive configuration file including server, logging, toolkit, network, locale, endpoints, and runtime settings.

```yaml
# Server transport and network configuration
server:
  transport: streamable-http
  host: "127.0.0.1"
  port: 8080

# Logging configuration
logging:
  level: info
  debug_mode: false

# Toolkit scope and tool selection
toolkit:
  scope: all
  # Uncomment and list tools to enable only specific ones
  # enabled_tools:
  #   - sls_list_projects
  #   - sls_execute_sql
  #   - umodel_get_entities

# Network and retry configuration
network:
  max_retry: 1
  retry_wait_seconds: 1
  read_timeout_ms: 610000
  connect_timeout_ms: 30000

# Locale configuration
locale:
  timezone: Asia/Shanghai
  language: zh-CN

# Optional: custom endpoints for internal network access
endpoints:
  sls:
    cn-hongkong: "cn-hongkong-intranet.log.aliyuncs.com"
  cms:
    cn-hongkong: "cms-intranet.cn-hongkong.aliyuncs.com"

# Runtime defaults
runtime:
  region: cn-hongkong
  workspace: default
```

--------------------------------

### List Method Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/toolkit-core.md

Example usage of the List method to iterate through tools and print their names and descriptions.

```go
tools := registry.List()
for _, t := range tools {
    fmt.Printf("%s: %s\n", t.Name, t.Description)
}
```

--------------------------------

### Free Tools Configuration Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README.md

Example configuration to enable only free tools in the toolkit, avoiding unexpected costs.

```yaml
toolkit:
  scope: all
  enabled_tools:
    - sls_list_projects
    - sls_list_logstores
    - sls_execute_sql
    - sls_execute_spl
    - cms_execute_promql
    # ... 按需添加其他免费工具
```

--------------------------------

### RegisterToolkits Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/toolkit-core.md

Example of registering toolkits, specifying the scope and a list of enabled tools.

```go
registry := toolkit.NewRegistry()
paasToolkit := paas.NewPaaSToolkit(cmsClient)
iaasToolkit := iaas.NewIaaSToolkit(slsClient, cmsClient)
sharedToolkit := shared.New(cmsClient)

// Load all toolkits but only enable specific tools
toolkit.RegisterToolkits(registry, "all", []string{
    "sls_list_projects",
    "sls_execute_sql",
    "list_workspace",
}, paasToolkit, iaasToolkit, sharedToolkit)
```

--------------------------------

### Example Usage of umodel_search_entities

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/paas-tools.md

Demonstrates how to call the umodel_search_entities tool with required parameters.

```go
params := map[string]interface{}{
    "workspace": "default",
    "search_text": "payment",
    "regionId": "cn-hongkong",
}
```

--------------------------------

### cms_text_to_promql Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/iaas-tools.md

Example of converting natural language to PromQL queries.

```go
params := map[string]interface{}{
    "text": "show me average request latency in the last hour",
    "project": "my_project",
    "metricstore": "my_metric_store",
    "regionId": "cn-hongkong",
}
```

--------------------------------

### sls_execute_sql Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/iaas-tools.md

Example parameters for the sls_execute_sql tool, demonstrating a SQL query.

```Go
params := map[string]interface{}{
    "project": "my_project",
    "logstore": "my_logstore",
    "query": "SELECT * FROM sls_log WHERE level='ERROR' LIMIT 100",
    "regionId": "cn-hongkong",
    "from_time": "last_1h",
}
```

--------------------------------

### Typical Workflow Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/shared-tools.md

A step-by-step example demonstrating a common workflow using shared tools.

```text
1. introduction()
   ↓ Learn service capabilities and requirements
   
2. list_workspace(regionId="cn-hongkong")
   ↓ Get available workspaces (e.g., "default")
   
3. list_domains(workspace="default", regionId="cn-hongkong")
   ↓ Get entity domains (e.g., "apm", "k8s")
   
4. Use domain in PaaS tools
   - umodel_get_entities(domain="apm", ...)
   - umodel_search_entities(domain="apm", ...)
   - etc.
```

--------------------------------

### Start the Server

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Commands to start the MCP server in stdio or network mode.

```bash
# Start in stdio mode (invoked directly by MCP clients)
./alibabacloud-observability-mcp-server start --stdio

# Start in network mode (transport configured in config.yaml)
./alibabacloud-observability-mcp-server start --config config.yaml
```

--------------------------------

### Download and Install Binaries

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Instructions for downloading and extracting the server binary for Linux and macOS.

```bash
# Linux amd64
wget https://github.com/aliyun/alibabacloud-observability-mcp-server/releases/latest/download/alibabacloud-observability-mcp-server-linux-amd64.tar.gz
tar -xzf alibabacloud-observability-mcp-server-linux-amd64.tar.gz

# macOS arm64 (M1/M2)
wget https://github.com/aliyun/alibabacloud-observability-mcp-server/releases/latest/download/alibabacloud-observability-mcp-server-darwin-arm64.tar.gz
tar -xzf alibabacloud-observability-mcp-server-darwin-arm64.tar.gz
```

--------------------------------

### Toolkit Configuration Example - Enable only free tools

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

Example configuration to enable only free tools by specifying them in enabled_tools.

```yaml
toolkit:
  scope: all
  enabled_tools:
    - sls_list_projects
    - sls_list_logstores
    - sls_execute_sql
    - sls_execute_spl
    - cms_execute_promql
    - umodel_get_entities
    - umodel_get_metrics
    - list_workspace
    - list_domains
    - introduction
```

--------------------------------

### umodel_get_metrics Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/paas-tools.md

Example Go code demonstrating how to query metric data using umodel_get_metrics, including options for time series comparison and anomaly detection.

```go
// Basic metric query
params := map[string]interface{}{
    "workspace": "default",
    "domain": "apm",
    "entity_set_name": "apm.service",
    "metric_domain_name": "apm.metric.apm.service",
    "metric": "request_count",
    "regionId": "cn-hongkong",
    "time_range": "last_1h",
}

// With time series comparison
params["offset"] = "1d"

// With anomaly detection
params["analysis_mode"] = "anomaly_detection"
```

--------------------------------

### config.yaml Structure Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

An example structure of the config.yaml file showing various configuration options.

```yaml
# Server configuration
server:
  transport: streamable-http  # stdio, sse, streamable-http
  host: "0.0.0.0"
  port: 8080

# Logging configuration
logging:
  level: info                 # debug, info, warn, error
  debug_mode: false

# Toolkit configuration
toolkit:
  scope: all                  # all, paas, iaas
  # Fine-grained tool selection (optional; when non-empty, only listed tools are registered)
  # enabled_tools:
  #   - list_workspace
  #   - umodel_get_entities
  #   - sls_execute_sql

# Network configuration
network:
  max_retry: 1
  retry_wait_seconds: 1
  read_timeout_ms: 610000
  connect_timeout_ms: 30000

# Locale configuration
locale:
  timezone: Asia/Shanghai
  language: zh-CN

# Runtime defaults (optional)
# Priority: environment variables > .env file > config.yaml
runtime:
  region: cn-hangzhou
  # workspace: ""

# Endpoint overrides (optional, for internal network access)
# endpoints:
#   sls:

```

--------------------------------

### sls_log_explore Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/iaas-tools.md

Example of how to use the sls_log_explore tool for log exploration and analysis with grouping.

```go
params := map[string]interface{}{
    "project": "my_project",
    "logstore": "my_logstore",
    "logfield": "level",
    "regionId": "cn-hongkong",
    "filter_query": "level='ERROR'",
    "groupfield": "service",
}
```

--------------------------------

### Time Series Comparison Analysis Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README.md

Example of using `umodel_get_metrics` with the `offset` parameter for time series comparison.

```go
umodel_get_metrics(
    domain="apm", entity_set_name="apm.service",
    metric_domain_name="apm.metric.apm.service", metric="request_count",
    time_range="last_1h", offset="1d"
)
```

--------------------------------

### cms_execute_promql Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/iaas-tools.md

Example of executing a PromQL query against CMS metric stores.

```go
params := map[string]interface{}{
    "project": "my_project",
    "metricstore": "my_metric_store",
    "query": "rate(http_requests_total[5m])",
    "regionId": "cn-hongkong",
    "from_time": "last_1h",
}
```

--------------------------------

### Configuration File Backup and Setup

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Commands to back up the default configuration and set up the .env file for credentials.

```bash
cp config.yaml config.yaml.bak       # Back up default config (optional)
cp .env.example .env                  # Credentials (AccessKey)
```

--------------------------------

### Toolkit Configuration Example - Disable all tools except specific ones

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

Example configuration to disable all tools except a specific list.

```yaml
toolkit:
  scope: all
  enabled_tools:
    - sls_execute_sql
    - sls_execute_spl
```

--------------------------------

### FilterByNames Method Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/toolkit-core.md

Example usage of FilterByNames to keep only specific tools.

```go
registry.FilterByNames([]string{"sls_list_projects", "sls_list_logstores"})
```

--------------------------------

### list_domains Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/shared-tools.md

Example of how to use the list_domains tool to list all available entity domains within a workspace and region.

```go
params := map[string]interface{}{
    "workspace": "default",
    "regionId": "cn-hongkong",
}
result, err := handler(ctx, params)
// Returns:
// {
//     "error": false,
//     "data": [
//         {"__domain__": "apm", "cnt": 150},
//         {"__domain__": "k8s", "cnt": 45},
//         {"__domain__": "cloud", "cnt": 30}
//     ],
//     "query": ".entity with(domain='*', type='*', topk=1000) | stats ...",
//     "workspace": "default",
//     "message": "success"
// }
```

--------------------------------

### list_workspace Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/shared-tools.md

Example of how to use the list_workspace tool to list available CMS workspaces in a region.

```go
params := map[string]interface{}{
    "regionId": "cn-hongkong",
}
result, err := handler(ctx, params)
// Returns:
// {
//     "error": false,
//     "workspaces": [
//         {"name": "default", "id": "12345", "description": "Default workspace"},
//         {"name": "prod", "id": "67890", "description": "Production"}
//     ],
//     "total_count": 2,
//     "region": "cn-hongkong",
//     "message": "Successfully retrieved 2 workspaces from region cn-hongkong"
// }
```

--------------------------------

### Start Server (streamable-http mode)

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Command to start the Alibaba Cloud Observability MCP Server in streamable-http mode.

```bash
./bin/alibabacloud-observability-mcp-server start
```

--------------------------------

### Development Setup Recommendation

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

Recommended configuration for a development environment.

```yaml
server:
  transport: stdio
logging:
  level: debug
  debug_mode: true
toolkit:
  scope: all
```

--------------------------------

### Introduction Tool Response Structure Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/shared-tools.md

Example JSON structure for the response from the introduction tool, detailing service metadata.

```json
{
    "name": "Alibaba Cloud Observability MCP Server",
    "version": "1.0.0",
    "description": "...",
    "capabilities": {
        "data_access": [...],
        "ai_features": [...] 
    },
    "tool_layers": {
        "paas": {
            "description": "...",
            "capabilities": [...],
            "prerequisites": "...",
            "note": "..."
        },
        "iaas": {...},
        "shared": {...}
    },
    "important_notes": [...],
    "references": {
        "cloudmonitor_2_0": "...",
        "sls_overview": "...",
        "github": "..."
    }
}
```

--------------------------------

### sls_text_to_sql Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/iaas-tools.md

Example of how to use the sls_text_to_sql tool to convert a natural language question to an SQL query.

```go
params := map[string]interface{}{
    "text": "show me error logs in the last hour",
    "project": "my_project",
    "logstore": "my_logstore",
    "regionId": "cn-hongkong",
}
```

--------------------------------

### Fine-Grained Tool Selection

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Example of configuring `toolkit.enabled_tools` for granular control over tool categories.

```yaml
toolkit:
  scope: all
  enabled_tools:
    - list_workspace
    - list_domains
    - umodel_get_entities
    - umodel_get_metrics
    - sls_execute_sql
```

--------------------------------

### sls_get_context_logs Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/iaas-tools.md

Example of how to use the sls_get_context_logs tool to retrieve context logs around an anchor log entry.

```go
params := map[string]interface{}{
    "project": "my_project",
    "logstore": "my_logstore",
    "pack_id": "...",
    "pack_meta": "...",
    "regionId": "cn-hongkong",
    "back_lines": 50,
    "forward_lines": 50,
}
```

--------------------------------

### Standard Parameter Schema Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/types.md

Example of a standard input schema for object parameters with string types.

```go
"input_schema": map[string]interface{}{
    "type": "object",
    "properties": map[string]interface{}{
        "param_name": map[string]interface{}{
            "type":        "string",
            "description": "Parameter description",
        },
    },
    "required": []string{"required_param"},
}
```

--------------------------------

### umodel_get_neighbor_entities Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/paas-tools.md

Example demonstrating how to call the umodel_get_neighbor_entities tool to retrieve related entities based on source entity information and direction.

```go
params := map[string]interface{}{
    "workspace": "default",
    "src_entity_domain": "apm",
    "src_name": "apm.service",
    "src_entity_ids": "service-123,service-456",
    "regionId": "cn-hongkong",
    "direction": "out",
}
```

--------------------------------

### Production Setup Recommendation

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

Recommended configuration for a production environment, emphasizing security and performance.

```yaml
server:
  transport: streamable-http
  host: "10.0.0.100"  # Internal IP
  port: 8080
logging:
  level: warn
toolkit:
  scope: all
  enabled_tools: [...]  # Specify only needed tools
network:
  max_retry: 3
  retry_wait_seconds: 2
```

--------------------------------

### Env File for Credentials

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Example of creating a .env file with Alibaba Cloud access key ID and secret.

```text
ALIBABA_CLOUD_ACCESS_KEY_ID=xxx
ALIBABA_CLOUD_ACCESS_KEY_SECRET=xxx
```

--------------------------------

### Integer Parameter Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/types.md

Example of an input schema for an integer parameter, including type, description, default value, and minimum/maximum constraints.

```go
"limit": map[string]interface{}{
    "type":        "integer",
    "description": "Number of results",
    "default":     10,
    "minimum":     1,
    "maximum":     1000,
}
```

--------------------------------

### Enable Tool in Configuration

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Example configuration snippet to enable a specific tool.

```yaml
toolkit:
  scope: all
  enabled_tools:
    - tool_name_here
```

--------------------------------

### Time-Series Comparison Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Compares data from the last 1 hour with data from 1 day ago using the `umodel_get_metrics` tool with the `offset` parameter.

```go
# Compare data from the last 1 hour with 1 day ago
umodel_get_metrics(
    domain="apm", entity_set_name="apm.service",
    metric_domain_name="apm.metric.apm.service", metric="request_count",
    time_range="last_1h", offset="1d"
)
```

--------------------------------

### Validate Configuration Command

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Bash command to start the server and check for configuration errors during startup.

```bash
# The server validates config on startup
./alibabacloud-observability-mcp-server start --config config.yaml 2>&1 | grep -i error
```

--------------------------------

### Avoid Unexpected Charges Configuration

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Example of using `enabled_tools` to include only free tools and avoid unexpected charges.

```yaml
toolkit:
  scope: all
  enabled_tools:
    - sls_list_projects
    - sls_list_logstores
    - sls_execute_sql
    - sls_execute_spl
    - cms_execute_promql
    # ... add other free tools as needed
```

--------------------------------

### Tool Response Format Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/paas-tools.md

Standard JSON response format for all PaaS tools.

```json
{
    "error": false,
    "data": [...],
    "message": "success",
    "query": "SPL query executed",
    "time_range": {
        "from": 1706864400,
        "to": 1706868000,
        "from_readable": "2024-02-02 10:10:10",
        "to_readable": "2024-02-02 10:20:10",
        "expression": "last_1h"
    }
}
```

--------------------------------

### Discover Available Metric Sets

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Example command to discover available metric sets for a given entity set.

```text
umodel_list_data_set(domain, entity_set_name, data_set_types="metric_set")
```

--------------------------------

### APIError Error() Method Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Demonstrates how to use the Error() method of the APIError struct to get a formatted error string.

```go
err := &errors.APIError{
    HTTPStatus:  400,
    Code:        "InvalidParameter",
    Message:     "Invalid region parameter",
    Description: "提供的区域参数无效",
    Solution:    "请使用有效的区域ID，例如 cn-hongkong, cn-beijing",
}
fmt.Println(err.Error())  // Output: [400] InvalidParameter: Invalid region parameter
```

--------------------------------

### Environment Variables for Credentials

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Example of setting environment variables for Alibaba Cloud access key ID and secret.

```bash
export ALIBABA_CLOUD_ACCESS_KEY_ID=your_access_key_id
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=your_access_key_secret
```

--------------------------------

### Invalid Parameter Example: Invalid Region

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Illustrates an example of an invalid 'regionId' parameter and provides valid examples.

```text
Parameter: regionId = "invalid-region"
Valid values: cn-hongkong, cn-beijing, cn-shanghai, etc.
Solution: Use valid region IDs from Alibaba Cloud documentation
```

--------------------------------

### Valid Server Configuration in config.yaml

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Example of valid server, port, and logging level configurations in config.yaml.

```yaml
server:
  transport: streamable-http  # Must be: stdio, sse, or streamable-http
  port: 8080                  # Must be 1-65535

logging:
  level: info                 # Must be: debug, info, warn, error
```

--------------------------------

### Specifying Config File Path with Flag

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Example of using the --config flag to specify the path to the config.yaml file.

```bash
./alibabacloud-observability-mcp-server start --config /path/to/config.yaml
```

--------------------------------

### Get Method Signature

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/toolkit-core.md

Returns the tool with the given name and true, or a zero Tool and false if no tool with that name is registered.

```go
func (r *Registry) Get(name string) (Tool, bool)
```

--------------------------------

### EndpointsConfig Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/types.md

Example YAML configuration for EndpointsConfig.

```yaml
endpoints:
  sls:
    cn-hongkong: "cn-hongkong-intranet.log.aliyuncs.com"
  cms:
    cn-hongkong: "cms.cn-hongkong.aliyuncs.com"
```

--------------------------------

### Introduction Tool Input Schema

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/shared-tools.md

The introduction tool requires no parameters and can be called directly.

```Go
// Empty parameters object
params := map[string]interface{}{}
```

--------------------------------

### Endpoint Configuration Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/configuration.md

Example of endpoint configuration for overriding SLS and CMS endpoints.

```yaml
endpoints:
  sls:
    cn-hongkong: "cn-hongkong-intranet.log.aliyuncs.com"
  cms:
    cn-hongkong: "cms-intranet.cn-hongkong.aliyuncs.com"
```

--------------------------------

### Build from Source

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Commands to build the server from source code.

```bash
# Clone the repository
git clone https://github.com/aliyun/alibabacloud-observability-mcp-server.git
cd alibabacloud-observability-mcp-server

# Build for current platform
make build

# Build for all platforms (linux/darwin/windows x amd64/arm64)
make build-all
```

--------------------------------

### Build Command

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README.md

Command to build the project.

```bash
make build
```

--------------------------------

### Invalid Parameter Example: Missing Domain

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Illustrates an example of a missing required parameter ('domain') for the 'umodel_get_entities' tool.

```text
Tool: umodel_get_entities
Missing: domain (cannot be '*')
Solution: Provide domain parameter with value like 'apm', 'k8s'
```

--------------------------------

### MapTeaException Usage Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Example demonstrating the usage of MapTeaException to map a potential API error to a structured APIError.

```go
err := someAPICall()
apiErr := errors.MapTeaException(err)
if apiErr != nil {
    slog.Error("api error", 
        "code", apiErr.Code,
        "message", apiErr.Message,
        "solution", apiErr.Solution,
    )
}
```

--------------------------------

### NewServer Constructor

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/server.md

Creates a new Server, registers all tools from the toolkit registry, and wires up tool handlers.

```go
func NewServer(
    cfg *config.Config,
    registry *toolkit.Registry,
    slsClient client.SLSClient,
    cmsClient client.CMSClient,
) (*Server, error)
```

--------------------------------

### Run Tests

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Command to run all tests.

```bash
# Run tests
make test
```

--------------------------------

### CLI Commands

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Basic CLI commands for checking version and listing tools.

```bash
# Show version info
./alibabacloud-observability-mcp-server version

# List all registered tools
./alibabacloud-observability-mcp-server tools
```

--------------------------------

### Run All Unit Tests

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README.md

Command to run all unit tests.

```bash
go test ./... -v
```

--------------------------------

### Lint Project

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Command to lint the project.

```bash
# Lint
make lint
```

--------------------------------

### Enum Parameter Example

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/types.md

Example of an input schema for an enum parameter, specifying string type, description, default value, and allowed enum values.

```go
"direction": map[string]interface{}{
    "type":        "string",
    "description": "Direction: in, out, or both",
    "default":     "both",
    "enum":        []string{"in", "out", "both"},
}
```

--------------------------------

### Configure Credentials

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Environment variables to set for Alibaba Cloud AccessKey.

```bash
# Set Alibaba Cloud AccessKey
export ALIBABA_CLOUD_ACCESS_KEY_ID=<your_access_key_id>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your_access_key_secret>
```

--------------------------------

### Timeout Configuration in config.yaml

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/errors.md

Example of increasing network timeout values in the config.yaml file.

```yaml
network:
  connect_timeout_ms: 60000  # 60 seconds
  read_timeout_ms: 900000    # 15 minutes for long queries
```

--------------------------------

### Run Tests Command

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README.md

Command to run all tests.

```bash
make test
```

--------------------------------

### List Domains Tool Usage

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/shared-tools.md

Example of how to call the list_domains tool and its subsequent use in other tools.

```text
list_domains(workspace, regionId)
  → returns entity domains
  → use domain parameter in:
     - umodel_get_entities
     - umodel_get_neighbor_entities
     - umodel_search_entities
     - And other entity query tools
```

--------------------------------

### List Workspace Tool Usage

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/shared-tools.md

Example of how to call the list_workspace tool and its subsequent use in other tools.

```text
list_workspace(regionId)
  → returns workspace names
  → use workspace parameter in:
     - umodel_* tools (all PaaS tools)
     - list_domains
     - cms_natural_language_query
```

--------------------------------

### Clean Build Artifacts

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/README_EN.md

Command to clean build artifacts.

```bash
# Clean build artifacts
make clean
```

--------------------------------

### Introduction Tool Usage

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/shared-tools.md

Summary of the capabilities and output of the introduction tool.

```text
introduction()
  → returns service metadata
  → provides tool layer information
  → explains prerequisites and constraints
  → offers reference documentation
```

--------------------------------

### List Method

Source: https://github.com/aliyun/alibabacloud-observability-mcp-server/blob/master/_autodocs/api-reference/toolkit-core.md

Returns all registered tools sorted by name for deterministic output.

```go
func (r *Registry) List() []Tool
```