loggly-mcp

Loggly MCP

Loggly /apiv2/* API 的只读 Model Context Protocol (MCP) 服务，另提供 IP 情报（RDAP、GreyNoise、AbuseIPDB）。提供 Loggly 搜索、分析和字段工具、以聚合为先的流量工具，以及 IP 上下文工具，同时阻止写入端点。

---

技能用法

如需高效检索日志（减少 token 使用量）并进行摘要，请将此服务与技能搭配使用。

---

快速入门

从 npm 安装

LOGGLY_SUBDOMAIN=your-subdomain LOGGLY_TOKEN=your-token npx -y @andrewbabu/loggly-mcp

MCP 客户端配置：

{
  "mcpServers": {
    "loggly": {
      "command": "npx",
      "args": ["-y", "@andrewbabu/loggly-mcp"],
      "env": {
        "LOGGLY_SUBDOMAIN": "your-subdomain",
        "LOGGLY_TOKEN": "your-token"
      }
    }
  }
}

从源代码运行

git clone https://github.com/andrewbabu/loggly-mcp.git
cd loggly-mcp
npm install
cp .env.example .env

使用 Loggly 凭据编辑 .env，然后运行：

npm start

在 Codex 中信任此仓库后，也可以通过 .codex/config.toml 自动启动 MCP 服务。

---

配置

服务启动时会从其工作目录加载 .env。

必需项

• LOGGLY_SUBDOMAIN
  Loggly 账户子域名或完整的 Loggly URL（例如 your-subdomain 或 https://your-subdomain.loggly.com）
• LOGGLY_TOKEN
  Loggly API 令牌

可选项

• LOGGLY_AUTH_MODE
bearer（默认）或 basic
• LOGGLY_MAX_RETRIES
  默认值：2
• LOGGLY_REQUEST_TIMEOUT_MS
  默认值：15000
• LOGGLY_LOG_LEVEL
error、warn、info（默认）或 debug

---

远程（HTTP）服务

如需让团队中的任何人都能从 Claude Code 访问 stdio 服务，而无需在本地检出代码，请改为运行 HTTP 版本，并将其托管在内部服务或 VM 上。

cp .env.example .env

使用 Loggly 凭据和 MCP_BEARER_TOKEN 编辑 .env（使用 node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" 生成令牌），然后：

npm run start:http

这将在 MCP_HTTP_PORT（默认值为 8787）上启动无状态的 Streamable HTTP MCP 服务：

• GET /healthz — 无需身份验证的运行状态检查。
• POST /mcp — MCP 端点。需要 Authorization: Bearer <MCP_BEARER_TOKEN>；对 /mcp 的任何其他请求都会返回 401。

Loggly 凭据保留在服务端——所有连接者共享同一个 Loggly 账户的访问权限。MCP_BEARER_TOKEN 仅用于控制对 MCP 服务本身的访问，因此请将其视为机密；如果泄露，请轮换令牌（例如，重新生成并重新分发）。

只能在内部网络或 VPN 后运行此服务，不要直接暴露到公共互联网——该服务使用单个共享令牌，而不是针对每位用户进行身份验证。

从 Claude Code 连接

每位组织成员只需添加一次远程服务：

claude mcp add --transport http loggly https://your-internal-host:8787/mcp \
  --header "Authorization: Bearer <MCP_BEARER_TOKEN>"

将其替换为你部署服务的内部主机名和端口，以及分配给你的令牌。

使用 Docker 运行

docker build -t loggly-mcp .
docker run -d --name loggly-mcp -p 8787:8787 --env-file .env loggly-mcp

---

多个账户／域名

该服务可以同时保存多个 Loggly 账户的凭据（不同的子域名和令牌），并在每次工具调用时指定目标账户。

将 LOGGLY_ACCOUNTS 设置为一个 JSON 对象，其中账户名称映射到对应凭据：

LOGGLY_ACCOUNTS={"acme":{"subdomain":"acme","token":"acme_token","authMode":"bearer"},"beta":{"subdomain":"beta","token":"beta_token"}}

设置 LOGGLY_ACCOUNTS 后，它会取代 LOGGLY_SUBDOMAIN／LOGGLY_TOKEN／LOGGLY_AUTH_MODE。此后，每个工具都会接受可选的 account 参数（例如 account: "acme"），用于选择此次调用要使用的账户凭据。

• 如果省略 account，服务会使用已设置的 LOGGLY_DEFAULT_ACCOUNT，否则使用 "default"；如果只配置了一个账户，则使用该账户。
• 如果 account 的值未知，则会返回错误并列出已配置的账户名称。
• 如果省略 account，且恰好有一个已配置账户与 next_url 主机匹配，iterate_events_next 也可以根据该主机推断账户。

现有的单账户配置（仅使用 LOGGLY_SUBDOMAIN／LOGGLY_TOKEN）仍可照常运行，不受影响——它们会被视为名为 "default" 的单个账户。

---

以聚合为先的流量工具

原始事件转储难以分析，既耗时又费钱。这些工具会返回摘要——总量、前 N 项细分、分桶时间线和少量代表性样本：

• search_logs — 通用版本：输入查询和时间范围，输出聚合摘要。
• traffic_by_ip / traffic_by_host / traffic_by_path — 相同的聚合，但预先限定为单个 IP/主机名/路径。
• group_by_ip / group_by_path / group_by_user_agent — 仅提供分面计数（基于 field_facets 的轻量封装），适用于只需要细分数据、不需要完整聚合结果的情况。
• timeline — 对指定范围内的计数进行分桶，通过客户端重复调用 /apiv2/events/count 计算（Loggly 的 volume-metrics 端点不接受自由文本查询，因此这是获取任意搜索时间线的唯一方式）。
• sample_events — 少量具有代表性的原始事件，适用于需要示例而非完整结果集的情况。

字段命名取决于每个 Loggly 来源解析日志的方式，而且不同账户之间，甚至同一账户的不同标签之间，字段命名也可能不同。因此，这些工具会先发现字段，再进行匹配：对于未明确覆盖的角色（host_field/path_field/status_field/user_agent_field/ip_field 参数，或 LOGGLY_FIELD_HOST/_PATH/_STATUS/_USER_AGENT/_IP 环境变量），它们会检查 /apiv2/fields/ 中的实际查询字段，并将候选字段与已知角色模式匹配：

• 恰好匹配一项 → 自动使用，并在结果的 discovered_fields 下报告。
• 存在多个可能的匹配项（例如，某个来源同时有 ClientIp 和 CustIP）→ 不会擅自选取，而是在 ambiguous_fields 下报告，并回退到已配置的默认值。请通过相应的 *_field 参数明确传入正确的字段。
• 没有匹配项 → 回退到已配置的默认值（host、path、status、user_agent、ip）。

如果想在决定覆盖项前查看所有候选字段，可以自行运行 list_fields。

---

IP 情报

• rdap_lookup — 通过公开 RDAP（rdap.org）查询 IP 所有权和网络注册信息（RIR、网段、组织、国家/地区）。无需 API 密钥。
• ip_reputation — 查询 GreyNoise（互联网范围的扫描噪声）和 AbuseIPDB（社区滥用报告）中的 IP 信息。需要 GREYNOISE_API_KEY / ABUSEIPDB_API_KEY；缺少其中任意一个时，对应来源只会返回 available: false，不会报错。
• get_ip_context — 将上述所有信息与 Loggly 流量数据结合起来（1 小时/24 小时/30 天的计数、首次/最后出现时间、主机、热门路径）；除非指定 account，否则会检查所有已配置的 Loggly 账户。如果该 IP 在多个账户中都有活动记录，还会标记 cross_domain_correlation。根据 bot-traffic-triage 操作手册，这种跨域模式是区分有针对性的侦察活动与背景噪声的最有力信号。

应将所有 IP 情报输出视为多项参考信息之一——身份/信誉数据（IP 所有者、第三方扫描报告）的权重应低于来自自有日志的行为证据。完整调查方法请参阅 bot-traffic-triage 技能。

---

日志记录

日志写入 stderr，以避免干扰 MCP 标准输入输出流。
使用 LOGGLY_LOG_LEVEL 控制详细程度。默认值为 info。

---

超时、重试与并发

请求会执行每次调用级别的超时，超时时长为 LOGGLY_REQUEST_TIMEOUT_MS（默认值为 15000）。
临时故障（429、响应正文类似超时的 500、503、504 或网络超时）最多会重试 LOGGLY_MAX_RETRIES 次。若 Loggly 在 429 响应中发送了 Retry-After 标头，则会遵循该标头；否则使用指数退避。

聚合工具（search_logs、traffic_by_*、get_ip_context 等）会通过 Promise.all 在每次调用中并行发起多个请求（分面、时间线数据桶和样本）。LOGGLY_MAX_CONCURRENT_REQUESTS（默认值为 4）会限制每个账户同时运行的请求数量，避免并行请求本身触发 Loggly 的速率限制。如果单次聚合调用仍出现 429，请调低此值；如果 Loggly 的限制更宽松，则可调高此值。

---

工具清单

工具元数据存储在 tool-manifest.json 中，并会与 src/server.js 进行验证。

npm run verify:manifest

---

冒烟测试

将 LOGGLY_SMOKE_TEST=1 设为启用状态，即可在没有 Loggly 凭据的情况下运行冒烟测试。

npm run smoke

---

已实现的 MCP 工具

底层 Loggly API 封装：

• connection_test
• create_search
• get_events
• search_and_get_events
• iterate_events_page
• iterate_events_next
• count_events
• volume_metrics
• stats_query
• list_fields
• field_facets
• raw_api_call

以聚合为主的流量工具：

• search_logs
• traffic_by_ip
• traffic_by_host
• traffic_by_path
• group_by_ip
• group_by_path
• group_by_user_agent
• timeline
• sample_events

IP 情报：

• rdap_lookup
• ip_reputation
• get_ip_context

---

示例

工具参数示例内容位于 examples/ 中。

---

开发

npm test

npm test 会运行清单验证和冒烟测试。CI 会在 .github/workflows/ci.yml 中运行相同的检查。

---

版本管理

• VERSION 包含当前发行版本。
• CHANGELOG.md 按发行版本记录变更。

---

安全说明

• 不得提交 .env 文件。
• Token 和 API 密钥（LOGGLY_TOKEN、LOGGLY_ACCOUNTS、GREYNOISE_API_KEY、 ABUSEIPDB_API_KEY、MCP_BEARER_TOKEN）均视为机密。
• 此服务仅允许对 Loggly /apiv2/* 端点进行只读访问。IP 情报调用 （RDAP/GreyNoise/AbuseIPDB）仅向这些第三方服务发送只读 GET 请求；绝不会向其发送 Loggly 凭据，也不会向 Loggly 发送任何 IP 情报密钥。