loggly-mcp 是一个只读的 Model Context Protocol（MCP）服务器，面向 Loggly 的 /apiv2/* API，并集成 IP 情报服务（RDAP、GreyNoise、AbuseIPDB）。它暴露 Loggly 搜索、分析、字段工具，以聚合优先的流量工具，以及 IP 上下文工具，同时阻止写入端点。
用途 该服务器用于通过 MCP 客户端（如 Claude Code）以只读方式查询 Loggly 日志，并进行聚合分析与 IP 情报关联。它适合需要高效检索日志、减少 token 消耗并进行摘要的场景，建议与 skill 配合使用。
主要能力
- Loggly 只读 API 封装：connection_test、search_and_get_events、iterate_events_page、iterate_events_next 等底层工具。
- 聚合优先的流量工具：search_logs、traffic_by_ip、traffic_by_host、traffic_by_path、group_by_ip、group_by_path、group_by_user_agent、timeline、sample_events。这些工具返回摘要（总计、Top-N 分解、分桶时间线、少量代表性样本），而非原始事件转储。
- 字段发现：对于未显式覆盖的角色（host_field / path_field / status_field / user_agent_field / ip_field 参数，或 LOGGLY_FIELD_HOST / _PATH / _STATUS / _USER_AGENT / _IP 环境变量），工具会检查 /apiv2/fields/ 并匹配已知角色模式。唯一匹配自动使用；多个可能匹配不猜测，报告为 ambiguous_fields 并回退到配置默认值；无匹配回退到默认值（host、path、status、user_agent、ip）。
- IP 情报：rdap_lookup（无需 API 密钥）、ip_reputation（需 GREYNOISE_API_KEY / ABUSEIPDB_API_KEY，缺失时对应来源返回 available: false）、get_ip_context（结合 Loggly 流量与 IP 情报，跨所有配置的 Loggly 账户检查，并标记 cross_domain_correlation）。
使用方式
- 从 npm 安装，配置 MCP 客户端。
- 从源码运行：编辑 .env 填入 Loggly 凭据后运行。在 Codex 中信任仓库后，也可通过 .codex/config.toml 自动启动 MCP 服务器。服务器启动时从工作目录加载 .env。
- 环境变量：LOGGLY_SUBDOMAIN（Loggly 账户子域名或完整 URL）、LOGGLY_TOKEN（API 令牌）、LOGGLY_AUTH_MODE（bearer 默认或 basic）、LOGGLY_MAX_RETRIES（默认 2）、LOGGLY_REQUEST_TIMEOUT_MS（默认 15000）、LOGGLY_LOG_LEVEL（error、warn、info 默认、debug）。
- 远程 HTTP 服务器：编辑 .env 填入 Loggly 凭据及 MCP_BEARER_TOKEN（可用 node -e "console.log(require('crypto').randomBytes(32).toString('hex'))" 生成），启动无状态 Streamable HTTP MCP 服务器，端口 MCP_HTTP_PORT（默认 8787）。GET /healthz 为无需认证的存活检查；POST /mcp 为 MCP 端点，需 Authorization: Bearer <MCP_BEARER_TOKEN>，否则返回 401。Loggly 凭据保留在服务器端，所有连接共享同一 Loggly 账户访问。MCP_BEARER_TOKEN 仅用于控制对 MCP 服务器本身的访问，应视为机密并在泄露时轮换。仅应在内部网络/VPN 后运行，不要直接暴露于公网，因为使用单一共享令牌而非每用户认证。
- 从 Claude Code 连接：每个组织成员添加一次远程服务器，替换为部署的内部主机名/端口和分配的令牌。
- Docker 运行。
- 多账户/域名：设置 LOGGLY_ACCOUNTS 为 JSON 对象，映射账户名到凭据。设置后替换 LOGGLY_SUBDOMAIN / LOGGLY_TOKEN / LOGGLY_AUTH_MODE。每个工具接受可选 account 参数选择账户。省略 account 时，使用 LOGGLY_DEFAULT_ACCOUNT（若设置），否则 "default"，否则唯一配置的账户。未知账户值返回错误并列出已配置账户名。iterate_events_next 在省略 account 时也可从 next_url 主机推断账户，只要恰好一个配置账户匹配该主机。现有单账户设置继续工作，视为名为 "default" 的账户。
适用场景
- 需要以只读方式查询 Loggly 日志并进行聚合分析。
- 需要结合 IP 情报（RDAP、GreyNoise、AbuseIPDB）进行机器人流量分类与调查。
- 团队通过远程 HTTP 服务器共享 Loggly 访问。
- 多 Loggly 账户/域名的统一查询。
限制
- 只读：阻止写入端点。
- IP 情报输出应作为多个输入之一，身份/声誉数据权重应低于自有日志的行为证据。
- 远程 HTTP 服务器仅应在内部网络/VPN 后运行，使用单一共享令牌。
- 日志写入 stderr 以避免干扰 MCP stdio 流量。
- 请求有超时与重试机制；聚合工具通过 Promise.all 扇出多个请求，LOGGLY_MAX_CONCURRENT_REQUESTS（默认 4）限制每账户并发数。
- 工具元数据存储在 tool-manifest.json 并与 src/server.js 验证。
- 冒烟测试可通过 LOGGLY_SMOKE_TEST=1 在无 Loggly 凭据下运行。
- .env 文件绝不能提交。令牌和 API 密钥（LOGGLY_TOKEN、LOGGLY_ACCOUNTS、GREYNOISE_API_KEY、ABUSEIPDB_API_KEY、MCP_BEARER_TOKEN）视为机密。
- IP 情报调用为对第三方服务的只读 GET 请求；不会向它们发送 Loggly 凭据，也不会向 Loggly 发送 IP 情报密钥。
