SNC Cribl MCP
一种模型上下文协议(MCP)服务器,提供查询Cribl部署的工具。
目录
- 它的作用
- 特性
- 安装
- 配置
- 用法
- 运行MCP服务器
- 可用的MCP工具
- 与Claude集成示例
- 项目结构
- 发展
- 认证
- 贡献
- 许可证
- 支持
它的作用
此MCP服务器连接到Cribl流和边缘部署,以检索和比较有关工作组、车队、来源、目的地、管道、路由和包的元数据。它还支持有针对性的跨领导者复制和验证工作流程,因此AI助手可以帮助保持多个领导者的一致性,而无需通过上下文传递整个配置。
服务器使用承载令牌处理身份验证,自动管理令牌刷新,并提供一个干净的JSON接口来探索您的Cribl基础设施。
特性
- 全面发现:列出部署中的所有工作组(Stream)和车队(Edge)。
- 配置检索:
- 检索所有产品和组中的已配置源。
- 检索所有产品和组中的配置目标。
- 检索所有产品和组中配置的管道,并提供完整的功能配置详细信息。
- 检索所有产品和组中的配置路由。
- 检索所有产品和组中配置的事件断路器。
- 检索所有产品和组中配置的查找。
- 包装管理:
- 列出并检查已安装的软件包。
- 从ID、URL、Git存储库或以前上传的Pack文件安装Pack。
- 通过cribl控制平面SDK上传、升级和卸载包。
- 交叉领导者同步工作流:
- 在配置的领导者之间复制支持的资源。
- 验证支持的资源在配置的领导者之间是否同步。
- 在复制和验证工作流程中解决不同的源组和目标组选择器。
- 类型化管道模型:41个具有完全类型安全的管道功能配置(eval、mask、sampling、regex_extract等)的Pydantic模型。
- 类型收集器型号:9个Pydantic模型,用于具有完全类型安全的收集器源配置(S3、REST、数据库、Splunk、Azure Blob、GCS、文件系统、脚本、健康检查)。
- 优雅的错误处理:SDK验证错误返回结构化、用户友好的响应,并提供可操作的指导,而不是崩溃。
- 强健的身份验证:客户管理部署的自动令牌管理和刷新。
- FastMCP集成:内置 FastMCP 3.x 便于与Claude和其他人工智能助手集成。
- 质量保证:全面的单元测试覆盖率和完整的打字支持。
安装
先决条件:
- Python 3.14或更高版本
- 紫外线 包管理器(必填)
- 使用有效凭据访问Cribl部署
步骤:```bash
Clone the repository
git clone
cd snc_cribl_mcp
Install dependencies using uv
uv sync
## 配置
创建一个 `config.toml` 包含Cribl服务器定义的项目根目录中的文件:```toml
[defaults]
verify_ssl = true
timeout_ms = 10_000
oauth_token_url = "https://login.cribl.cloud/oauth/token"
oauth_audience = "https://api.cribl.cloud"
# Optional for on-prem; defaults to snc-cribl-mcp:.
# keychain_name = "shared-cribl-login"
[golden.oak]
url = "http://localhost:19000"
# Optional for on-prem; defaults to your local macOS user.
# username = "admin"
# Optional for on-prem; overrides the default Keychain service name.
# keychain_name = "golden-oak-login"
[cribl.cloud]
url = "https://-.cribl.cloud"
client_id = "your-client-id"
client_secret = "${CRIBL_CLOUD_SECRET}"
对于本地服务器,省略 password 要使用本地凭据链,请执行以下操作:
- 使用已配置的
username,或默认为本地登录的macOS用户。 - 通过Python从macOS钥匙链读取密码
keyring,使用服务
keychain_name当在中配置时[defaults]或服务器部分。如果省略,服务默认为
snc-cribl-mcp:以及已解析的用户名。对于[golden.oak],默认服务为
snc-cribl-mcp:golden.oak服务器级别keychain_name覆盖[defaults]. - 回退到从加载的每服务器环境变量
.env或者你的壳。对于[golden.oak],
解析器检查SNC_CRIBL_MCP_GOLDEN_OAK_PASSWORD,CRIBL_GOLDEN_OAK_PASSWORD,
GOLDEN_OAK_PASSWORD那么GOLDEN_OAK_PASS.
要存储本地钥匙串密码,请执行以下操作:```bash
uv run keyring set snc-cribl-mcp:golden.oak "$(whoami)"
如果你使用 `${VAR}` 占位符,在 `.env` 文件(或shell环境)。明确的
占位符值仍然优先于键链查找,并且在引用时必须存在。
当工具调用省略服务器名称时,第一个非-`[defaults]` 部分在 `config.toml` 使用。
日志记录仍然通过 `LOG_LEVEL` 环境变量(默认值: `INFO`).
**配置选项:**
|章节|关键|描述|必填|
| :----------- | :---------------- | :--------------------------------------------------------- | :------- |
| `[defaults]` | `verify_ssl` |验证SSL证书|否|
| `[defaults]` | `timeout_ms` |API请求超时(以毫秒为单位)|否|
| `[defaults]` | `oauth_token_url` |Cribl的OAuth令牌URL。云|否|
| `[defaults]` | `oauth_audience` |Cribl的OAuth受众。云|否|
| `[defaults]` | `keychain_name` |本地密码的共享macOS钥匙链服务名称|否|
| `[server]` | `url` |Cribl部署的基本URL(自动附加 `/api/v1`)|是|
| `[server]` | `username` |本地用户名;默认为本地macOS用户|否\*|
| `[server]` | `password` |本地密码;默认为Keychain/env查找|否\*|
| `[server]` | `keychain_name` |每台服务器macOS钥匙串服务名称覆盖|否|
| `[server]` | `client_id` |哎呀。云客户端ID |是\*|
| `[server]` | `client_secret` |哎呀。云客户端机密|是\*|
\*哎呀。云URL(以结尾 `.cribl.cloud`)要求 `client_id`/`client_secret`本地URL最终需要
已解析用户名/密码对,但密码可以来自macOS Keychain或每台服务器的环境回退。
## 用法
### 运行MCP服务器
直接启动服务器:```bash
uv run snc-cribl-mcp
或者使用Python模块:```bash
uv run python -m snc_cribl_mcp.server
### 可用的MCP工具
服务器公开了17个MCP工具并且还将面向读取的数据镜像为MCP资源(例如。, `cribl://groups`, `cribl://sources`, `cribl://destinations`, `cribl://pipelines`, `cribl://routes`, `cribl://breakers`, `cribl://lookups`, `cribl://packs`):
#### `list_groups`
列出Cribl部署中的所有Stream工作组和Edge车队。
- **退货:** JSON包含按产品(流和边缘)组织的组,元数据包括组ID、名称、描述和配置。
#### `list_sources`
列出所有组和产品中的所有配置源,包括常规源(来自 `/system/inputs`)和收集器来源(来自 `/lib/jobs`).
- **退货:** JSON包含按产品和组组织的源,包括源ID、类型和配置。收集器源(S3、REST、数据库等)与每个组的常规源合并。
#### `list_destinations`
列出所有组和产品中的所有配置目标。
- **退货:** JSON包含按产品和组组织的目标,包括目标ID、类型和配置。
#### `list_pipelines`
列出所有组和产品中的所有已配置管道。
- **退货:** JSON包含按产品和组组织的管道,包括管道ID、名称和配置。
#### `list_routes`
列出所有组和产品中的所有配置路由。
- **退货:** JSON包含按产品和组组织的路由,包括路由ID、名称、过滤器、目的地和引用的管道。
#### `list_breakers`
列出所有组和产品中所有已配置的事件断路器。
- **退货:** JSON包含按产品和组组织的事件断路器,包括规则集ID、规则和配置。
#### `list_lookups`
列出所有组和产品中的所有配置查找。
- **退货:** JSON包含按产品和组组织的查找,包括查找ID、文件信息和配置。
#### `list_packs`
列出已安装的包。可选通过 `with_="inputs"`, `with_="outputs"`,或 `with_="inputs,outputs"` 包括包输入/输出计数。对于分布式环境,请通过 `product="stream"` 或 `product="edge"` 和 `group=""` 将请求范围限定为 `/m/{group}`.
- **退货:** JSON包含包ID、源、版本、元数据和任何请求的计数。
#### `get_pack`
获取一个已安装的逐包ID。默认情况下,这将返回包元数据以及包的源、目标、管道、路由、知识类别和设置类别的有界摘要。通过 `kind` 钻入一个混凝土部分或类别, `object_id` 为了获取一个对象, `detail="full"` 包括来自所选部分/类别的原始有效载荷,以及 `cursor`/`limit` 对所选部分/类别进行分页。
- **支持 `kind` 值:** `sources`, `destinations`, `pipelines`, `routes`, `knowledge`, `knowledge.lookups`, `knowledge.breakers`, `knowledge.parsers`, `knowledge.variables`, `knowledge.samples`, `knowledge.regexes`, `knowledge.grok`, `knowledge.schemas`, `knowledge.functions`, `knowledge.hmac_functions`, `knowledge.appscope_configs`, `knowledge.database_connections`, `settings`, `settings.system`, `settings.cribl`, `settings.conf`, `settings.auth`, `settings.git`.
- **退货:** JSON包含Pack元数据和部分摘要或请求的Pack对象详细信息。
- **分布式范围:** 支持相同的可选功能 `product` 和 `group` 论点如 `list_packs`.
#### `install_pack`
使用SDK包请求体安装包。该请求可以按ID创建空包,从URL安装,从 `git+` 存储库URL,或从由返回的上传包源安装 `upload_pack`.
- **退货:** JSON包含已安装的Pack元数据和Cribl返回的任何警告。
- **分布式范围:** 支持相同的可选功能 `product` 和 `group` 论点如 `list_packs`.
#### `upload_pack`
上传本地 `.crbl` 打包文件。
- **退货:** 包含上传内容的JSON `source` 要传递的值 `install_pack`.
- **分布式范围:** 支持相同的可选功能 `product` 和 `group` 论点如 `list_packs`.
#### `update_pack`
从源URL或上传的源ID升级已安装的包。
- **退货:** 包含升级包元数据的JSON。
- **分布式范围:** 支持相同的可选功能 `product` 和 `group` 论点如 `list_packs`.
#### `delete_pack`
卸载已安装的Pack by Pack ID。
- **退货:** 包含Cribl返回的卸载元数据的JSON。
- **分布式范围:** 支持相同的可选功能 `product` 和 `group` 论点如 `list_packs`.
#### `get_config_objects`
通过一个有界读取工具查询支持的配置对象:组、源、目标、管道、路由、断路器和查找。
- **退货:** 默认情况下,压缩摘要包括产品、组、ID、类型、启用状态、可选依赖关系引用、截断状态和用于后续调用的游标。使用 `detail="full"` 使用过滤器,例如 `selector`, `product`,以及 `group_id` 以在不淹没MCP响应的情况下检索所选有效载荷。
#### `validate_config_objects`
从语义上比较两个配置的领导者之间的组、源、目的地、管道或路由。
- **退货:** 功能验证结果将差异分为阻塞功能漂移、非阻塞环境身份差异或易失性元数据差异。报告主机名、端点服务器列表、生成的ID、凭据引用和时间戳,但不计入功能漂移。
#### `copy_resource_config`
将组、源、目标、管道或路线从一个配置的引线复制到另一个。
- **退货:** JSON描述了所采取的复制操作,包括创建、更新、附加、跳过和不支持的项目。对于组范围的资源,响应包括所请求的源组和目标组选择器以及每个领导者上使用的已解析组ID。
#### `validate_resource_sync`
比较两个配置的引线之间的组、源、目标、管道或路由。
- **退货:** JSON描述所选项目或范围是否同步,以及每个项目的状态和不同的路径。对于组范围的资源,响应包括所请求的源组和目标组选择器以及每个领导者上使用的已解析组ID。
### 与Claude集成示例
将此服务器添加到您的Claude桌面应用程序配置中:```json
{
"mcpServers": {
"snc-cribl-mcp": {
"command": "uv",
"args": [
"run",
"--directory",
"path-to-project-directory",
"snc-cribl-mcp"
],
"env": {
"LOG_LEVEL": "INFO"
}
}
}
}
项目结构```text
snc_cribl_mcp/
├── src/snc_cribl_mcp/ # Main package (src-layout)
│ ├── client/ # Cribl client and token management
│ │ ├── cribl_client.py # Control plane client factory
│ │ └── token_manager.py # Bearer token lifecycle management
│ ├── models/ # Pydantic models for Cribl data structures
│ │ ├── collectors.py # Typed models for 9 collector source types
│ │ └── pipeline_functions.py # Typed models for 41 pipeline function types
│ ├── operations/ # Core business logic
│ │ ├── common.py # Shared utilities and generic collectors
│ │ ├── groups.py # Group collection and serialization
│ │ ├── sources.py # Source collection helpers
│ │ ├── destinations.py # Destination collection helpers
│ │ ├── pipelines.py # Pipeline collection helpers
│ │ ├── routes.py # Route collection helpers
│ │ ├── breakers.py # Event breaker collection helpers
│ │ ├── lookups.py # Lookup collection helpers
│ │ ├── packs.py # Top-level Pack management helpers
│ │ ├── config_objects.py # Consolidated config object response shaping
│ │ ├── resource_actions.py # Context-free CRUD helpers over the SDK
│ │ ├── semantic_diff.py # Functional vs environment identity comparison
│ │ ├── sync.py # Cross-leader copy and validation helpers
│ │ └── validation_errors.py # SDK validation error handling
│ ├── tools/ # MCP tool registrations
│ │ ├── common.py # Shared tool registration utilities
│ │ ├── copy_resource_config.py
│ │ ├── list_groups.py
│ │ ├── list_sources.py
│ │ ├── list_destinations.py
│ │ ├── list_pipelines.py
│ │ ├── list_routes.py
│ │ ├── list_breakers.py
│ │ ├── list_lookups.py
│ │ ├── packs.py
│ │ ├── get_config_objects.py
│ │ ├── validate_config_objects.py
│ │ ├── sync_common.py
│ │ └── validate_resource_sync.py
│ ├── config.py # Configuration management
│ ├── prompts.py # MCP prompt definitions
│ ├── resources.py # MCP resource definitions
│ └── server.py # FastMCP app entry point
├── tests/
│ └── unit/ # Unit tests with pytest
├── docs/ # Additional documentation
├── pyproject.toml # Project dependencies and tool config
└── .env # Local configuration (not committed)
## 发展
### 运行测试```bash
# Run all tests
uv run pytest
# Run with coverage
uv run pytest --cov=src/snc_cribl_mcp
# Run specific test file
uv run pytest tests/unit/test_server.py
代码质量```bash
Type checking
uv run pyright
Linting and formatting
uv run ruff check
uv run ruff format
```
添加新工具
- 在中创建实现逻辑
src/snc_cribl_mcp/operations/. - 在中创建新的工具文件
src/snc_cribl_mcp/tools/遵循现有模式。 - 在中注册该工具
src/snc_cribl_mcp/server.py在_register_capabilities()功能。 - 在中添加相应的测试
tests/unit/.
认证
服务器根据配置的服务器类型自动检索承载令牌:
- 哎呀。云:使用OAuth客户端凭据(
client_id/client_secret)并自动刷新令牌。 - 内部部署:使用已解决的
username/password配对以获取承载令牌,默认为本地macOS用户和
在退回到每台服务器的环境变量之前,macOS Keychain。它使用JWT刷新exp索赔时
可用。
令牌根据您的Cribl设置过期(默认值:本地1小时,Cribl.Cloud 24小时)。对于生产使用,请配置TLS并使用HTTPS。
贡献
欢迎投稿!以下是如何开始:
- 分叉存储库。
- 创建要素分支(
git checkout -b feature/amazing-feature). - 进行更改并添加测试。
- 运行测试套件(
uv run pytest). - 运行类型检查和除尘(
uv run pyright && uv run ruff check). - 用描述性消息提交您的更改。
- 推到您的分支(
git push origin feature/amazing-feature). - 打开拉取请求。
在提交PR之前,请确保所有测试都通过并保持代码覆盖率。
许可证
本项目根据麻省理工学院无署名许可证(MIT-0)获得许可。请参阅 许可证 文件以获取详细信息。
支持
对于问题、疑问或功能请求,请在存储库中打开问题。
