MCP 服务器

LogScale MCP Server

Query CrowdStrike Falcon LogScale logs from AI assistants via the Model Context Protocol.

README

LogScale MCP Server Query CrowdStrike LogScale logs from AI assistants via the Model Context Protocol

<a href="#features">Features</a> • <a href="#quick-start">Quick Start</a> • <a href="#tools">Tools</a> • <a href="#usage">Usage</a> • <a href="#cql-query-examples">Queries</a> • <a href="#security">Security</a> • <a href="#ci-pipeline">CI</a> • <a href="#architecture">Architecture</a> • <a href="#contributing">Contributing</a>

Introduction

LogScale MCP Server lets you query CrowdStrike LogScale logs through natural language in VS Code Copilot Chat, Claude Desktop, or any MCP-compatible client. Instead of writing raw CQL queries and managing API calls, just ask:

"Show me errors in the xxxx namespace from the last hour"

"Find all 500 errors from the xyxyxy pod today"

"Search logs for request ID f6796646b043d231bf67f589b7306e9b"

The server handles query submission, polling, result formatting, and pagination automatically.

Features

2 MCP tools — search_logs and get_query_job for comprehensive log querying
CrowdStrike Query Language (CQL) — full support for filters, pipes, aggregations, and field searches
Automatic poll loop — submits query jobs and polls with server-suggested intervals until completion
Smart result formatting — structured output with field statistics, event counts, and metadata
Configurable defaults — custom timeouts, pagination limits, poll intervals, and max events
Time range support — relative (1h, 7d) and absolute (epoch milliseconds) time ranges
VS Code Extension — bundled extension with built-in configuration UI for LogScale connection settings
Monorepo architecture — clean separation between server (logscale-mcp-server) and extension (logscale-mcp-vscode)

Quality & Security

Area	Details
Test Coverage	97% statements · 91% branches · 95% functions — 67 tests across 6 suites
Type Safety	Strict TypeScript with `noEmit` type checking on every CI run
Linting	ESLint with `eslint-plugin-security` for vulnerability pattern detection
Formatting	Prettier-enforced code style across all source and test files
Static Analysis	GitHub CodeQL with `security-extended` query suite
Dependency Audit	`pnpm audit` at moderate+ severity — zero known vulnerabilities
SBOM & CVE Scan	Trivy filesystem scan for CRITICAL and HIGH severity vulnerabilities
Secret Scanning	Gitleaks in CI + pre-commit hook for local secret detection
Dependency Review	PR-level review blocking moderate+ severity and GPL-3.0/AGPL-3.0 licenses
Commit Standards	Conventional Commits enforced via commitlint
Multi-Node Testing	CI tests on Node.js 18, 20, and 22

Quick Start

Prerequisites

Node.js ≥ 18
pnpm (recommended) or npm
A LogScale instance with API access and a Bearer token

Install from npm

# Install globally
npm install -g logscale-mcp-server

# Or run directly with npx
npx logscale-mcp-server

Install from Source

git clone https://github.com/your-org/logscale-mcp-server.git
cd logscale-mcp-server
pnpm install
pnpm -r build

Configuration

Variable	Required	Description
`LOGSCALE_BASE_URL`	Yes	LogScale instance URL (include path prefix like `/logs` if needed)
`LOGSCALE_API_TOKEN`	Yes	Bearer token for authentication
`LOGSCALE_REPOSITORY`	No	Default repository name
`LOGSCALE_TIMEOUT_MS`	No	Max poll timeout (default: 60000)
`LOGSCALE_POLL_INTERVAL_MS`	No	Poll interval (default: 1000)
`LOGSCALE_MAX_EVENTS`	No	Default pagination limit (default: 200)

Tools

`search_logs`

Submit a CQL query, wait for results, and return formatted log events.

Parameter	Type	Required	Description
`queryString`	string	Yes	CQL query string
`start`	string/number	No	Start time — relative (`"1h"`, `"7d"`) or epoch ms
`end`	string/number	No	End time — `"now"` or epoch ms
`repository`	string	No	Target repository (overrides default)
`maxEvents`	number	No	Max events to return (default: 200, max: 500)

`get_query_job`

Check status or retrieve results of an existing query job.

Parameter	Type	Required	Description
`jobId`	string	Yes	Query job ID from a previous `search_logs` call
`repository`	string	No	Repository the job was submitted to
`maxEvents`	number	No	Max events to return

Usage

VS Code (MCP)

Add to .vscode/mcp.json:

{
  "servers": {
    "logscale": {
      "command": "npx",
      "args": ["-y", "logscale-mcp-server"],
      "env": {
        "LOGSCALE_BASE_URL": "https://your-logscale-instance.com",
        "LOGSCALE_API_TOKEN": "your-api-token",
        "LOGSCALE_REPOSITORY": "your-repository"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "logscale": {
      "command": "npx",
      "args": ["-y", "logscale-mcp-server"],
      "env": {
        "LOGSCALE_BASE_URL": "https://your-logscale-instance.com",
        "LOGSCALE_API_TOKEN": "your-api-token",
        "LOGSCALE_REPOSITORY": "your-repository"
      }
    }
  }
}

VS Code Extension

Install the bundled VS Code extension for a GUI-configured experience or download from marketplace:

# From VSCode Extensions marketplace
Search "LogScale MCP Server", install.

# From local VSIX
code --install-extension packages/vscode-extension/logscale-mcp-vscode-0.1.0.vsix

The extension provides VS Code settings for logscale.baseUrl, logscale.repository, logscale.timeoutMs, logscale.pollIntervalMs, and logscale.maxEvents.

Development

pnpm run dev                # Start server in dev mode
pnpm -r build               # Build all packages
pnpm run test:coverage      # Run tests with coverage
pnpm run ci                 # Full CI pipeline locally

Test with MCP Inspector

npx @modelcontextprotocol/inspector node packages/server/dist/index.js

CQL Query Examples

# Simple namespace filter
"kubernetes.namespace_name" = "your-namespace"

# Filter by namespace AND app label
"kubernetes.namespace_name" = "your-namespace"
| "kubernetes.labels.app_kubernetes_io/instance" = "your-instance-name"

# Search for errors in a namespace
kubernetes.namespace_name = "your-namespace" | ERROR

# Search by correlation ID
kubernetes.namespace_name = "your-namespace" | "f6796646b043d231bf67f589b7306e9b"

# Chain multiple filters
kubernetes.namespace_name = "your-namespace"
| 81bd572b6f202eccb9538408cb764c89
| "Pod Network CIDR is not provided"

# Aggregations
ERROR | groupBy(kubernetes.pod_name, function=count())
ERROR | top(log, limit=10)
ERROR | timechart(span=5m)

Time Ranges

Format	Example	Description
Relative	`"1h"`, `"24h"`, `"7d"`, `"30m"`	Lookback from now
Absolute	`1773599400000`	Epoch milliseconds
End	`"now"` or epoch ms	End of time window

Architecture

AI Client (VS Code Copilot, Claude Desktop)
    ↕  MCP (stdio transport)
LogScale MCP Server (TypeScript / Node.js)
    ↕  HTTPS (REST API)
CrowdStrike LogScale (Query Jobs API)

The server uses LogScale's 2-step Query Jobs API:

Submit — POST /api/v1/repositories/{repo}/queryjobs → returns job ID
Poll — GET /api/v1/repositories/{repo}/queryjobs/{id} → poll until done, return results

Security

Control	Implementation
Static Analysis	CodeQL `security-extended` queries on every push and PR
Dependency Audit	`pnpm audit` at moderate+ with zero tolerance
SBOM Scanning	Trivy filesystem scan for CRITICAL/HIGH CVEs
Secret Detection	Gitleaks CI job + pre-commit hook (full git history scan)
License Compliance	Dependency review blocks GPL-3.0 and AGPL-3.0
Security Linting	`eslint-plugin-security` catches unsafe patterns (eval, non-literal require, etc.)
Supply Chain	`pnpm.overrides` to force patched transitive dependency versions
Input Validation	Zod schemas for all tool parameters

CI Pipeline

The CI runs 11 jobs on every push and pull request:

┌─────────────┐  ┌───────────────────────┐  ┌──────────────────┐
│  typecheck   │  │  lint (ESLint+security)│  │  format (Prettier)│
└──────┬───────┘  └───────────┬────────────┘  └────────┬─────────┘
       │                      │                        │
       ▼                      ▼                        ▼
┌──────────────────────────────────────────────────────────────────┐
│              test (Node 18 / 20 / 22 + coverage)                │
└──────────────────────────────┬───────────────────────────────────┘
                               ▼
                    ┌──────────────────┐
                    │      build       │
                    └────────┬─────────┘
                             ▼
                 ┌───────────────────────┐
                 │  package-extension    │
                 │  (VSIX artifact)      │
                 └───────────────────────┘

     (parallel)
┌──────────────────┐  ┌──────────┐  ┌────────────────────┐  ┌──────────┐
│  security-audit  │  │  codeql  │  │ dependency-review  │  │ gitleaks │
│  (pnpm audit)    │  │          │  │   (PR only)        │  │          │
└──────────────────┘  └──────────┘  └────────────────────┘  └──────────┘
                               │
                               ▼
                    ┌──────────────────┐
                    │   sbom (Trivy)   │
                    └──────────────────┘

Troubleshooting

"Unexpected token '<'" / HTML response error

The LOGSCALE_BASE_URL is likely incorrect. Many LogScale deployments serve the API under a path prefix (e.g., /logs). Check the URL in your browser's network tab — if API calls go to https://host/logs/api/v1/..., set:

LOGSCALE_BASE_URL=https://your-host/logs

Authentication failures (401/403)

Verify your LOGSCALE_API_TOKEN is valid and has read permission on the target repository.

Repository not found (404)

Check the LOGSCALE_REPOSITORY name matches exactly (case-sensitive).

Contributing

Fork the repository
Create a feature branch: git checkout -b feat/my-feature
Make changes following Conventional Commits
Run the full CI locally: pnpm run ci
Submit a pull request

Commit Format

feat: add new search filter       → minor version bump
fix: handle empty results          → patch version bump
feat!: redesign query API          → major version bump

License

MIT