Skip to main content
Glama
enesjakozh
PovedaAqui

SuzieQ MCP Server

by PovedaAqui
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

SuzieQ 的 MCP 服务器

铁匠徽章

该项目提供了一个模型上下文协议 (MCP) 服务器，允许语言模型和其他 MCP 客户端通过其 REST API 与 SuzieQ 网络可观察性实例进行交互。

概述

服务器将 SuzieQ 的命令公开为 MCP 工具：

  • run_suzieq_show ：访问“show”命令来查询详细的网络状态表

  • run_suzieq_summarize ：访问“summarize”命令以获取汇总统计数据和摘要

这些工具使客户端（如 Claude Desktop）能够查询各种网络状态表（例如，接口、BGP、路由）并应用过滤器，直接从 SuzieQ 实例检索结果。

Related MCP server: OpsLevel MCP

先决条件

  • **Python：**建议使用3.8或更高版本。

  • **uv：**一个快速的 Python 软件包安装程序和解析器。（安装指南）

  • **SuzieQ 实例：**正在运行的 SuzieQ 实例，其 REST API 已启用且可访问。

  • **SuzieQ API 端点和密钥：**您需要 SuzieQ API 的 URL（例如， http://your-suzieq-host:8000/api/v2 ）和有效的 API 密钥（ access_token ）。

安装和设置

通过 Smithery 安装

要通过Smithery自动为 Claude Desktop 安装 suzieq-mcp：

npx -y @smithery/cli install @PovedaAqui/suzieq-mcp --client claude

手动安装

  1. **获取代码：**克隆此存储库或将main.py和server.py文件下载到专用项目目录中。

  2. **创建虚拟环境：**在终端中导航到您的项目目录并使用uv创建虚拟环境：

    uv venv

  3. 激活环境：

    • 在 macOS/Linux 上：

      source .venv/bin/activate

    • 在 Windows 上：

      GXP4 （您应该在提示符前看到(.venv) ）

  4. **安装依赖项：**使用uv安装所需的 Python 包：

    uv pip install mcp httpx python-dotenv

    • mcp ：模型上下文协议 SDK。

    • httpx ：用于与 SuzieQ API 通信的异步 HTTP 客户端。

    • python-dotenv ：用于从.env文件加载环境变量进行配置。

配置

服务器需要您的 SuzieQ API 端点和 API 密钥。使用.env文件进行安全且简单的配置：

  1. 创建.env文件：在项目目录的根目录中（与main.py相同的位置），创建一个名为.env的文件。

  2. **添加凭证：**将您的 SuzieQ 端点和密钥添加到.env文件。确保值两边没有引号，除非它们是密钥/端点本身的一部分。

    # .env
SUZIEQ_API_ENDPOINT=http://your-suzieq-host:8000/api/v2
SUZIEQ_API_KEY=your_actual_api_key

    将占位符值替换为您的实际端点和密钥。

  3. **安全的.env文件：**将.env添加到您的.gitignore文件中，以防止意外提交机密。

    echo ".env" >> .gitignore

  4. **代码集成：**提供的server.py在服务器启动时自动使用python-dotenv加载这些变量。

运行服务器

确保你的虚拟环境已激活。服务器将从当前目录中的.env文件加载配置。

1. 直接

直接从终端运行服务器：

uv run python main.py

服务器将启动，打印Starting SuzieQ MCP Server... ，并在标准输入/输出 (stdio) 上监听 MCP 连接。如果服务器成功通过该工具查询 API，您应该会看到[INFO]日志。按Ctrl+C停止服务器。

2. 使用 MCP Inspector（用于调试）

MCP 检查器对于直接测试该工具非常有用。如果您已安装 mcp CLI 工具（通过uv pip install "mcp[cli]" ），请运行：

uv run mcp dev main.py

这将启动一个交互式调试器。转到“工具”选项卡，选择run_suzieq_show ，输入参数（例如，table: "device"），然后点击“调用工具”进行测试。

与 Claude Desktop 一起使用

将服务器与 Claude Desktop 集成以实现无缝使用：

  1. **查找 Claude 桌面配置：**找到claude_desktop_config.json文件。

    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows： %APPDATA%\Claude\claude_desktop_config.json

    • 如果不存在，则创建文件和 Claude 目录。

  2. **编辑配置文件：**为该服务器添加一个条目。使用main.py的绝对路径。服务器从.env加载机密信息，因此它们不需要包含在该配置中。

{
  "mcpServers": {
    "suzieq-server": {
      // Use 'uv' if it's in the system PATH Claude uses,
      // otherwise provide the full path to the uv executable.
      "command": "uv",
      "args": [
        "run",
        "python",
        // --- VERY IMPORTANT: Use the ABSOLUTE path below ---
        "/full/path/to/your/project/mcp-suzieq-server/main.py"
      ],
      // 'env' block is not needed here if .env is in the project directory above
      "workingDirectory": "/full/path/to/your/project/mcp-suzieq-server/" // Optional, but recommended
    }
    // Add other servers here if needed
  }
}

  • 将/full/path/to/your/project/mcp-suzieq-server/main.py替换为系统上的正确绝对路径。

  • 将/full/path/to/your/project/mcp-suzieq-server/替换为包含main.py和.env目录的绝对路径。设置workingDirectory有助于确保找到.env文件。

  • 如果 Claude 没有找到uv ，则将"uv"替换为其绝对路径（通过which uv或where uv查找）。

  • 在 Windows 上，如果遇到文本编码问题，则可能需要"env": { "PYTHONUTF8": "1" } 。

  1. **重新启动 Claude Desktop：**完全关闭并重新打开 Claude Desktop。

  2. **验证：**在 Claude Desktop 中查找 MCP 工具指示器（锤子图标 🔨）。点击它应该会同时显示run_suzieq_show和run_suzieq_summarize工具。

工具使用（run_suzieq_show）

run_suzieq_show(table: str, filters: Optional[Dict[str, Any]] = None) -> str

  • 表：（字符串，必需）SuzieQ 表名称（例如，“设备”、“接口”、“bgp”）。

  • filters ：（字典，可选）用于过滤的键值对（例如， "hostname": "leaf01" ）。省略或使用{}表示不使用过滤器。

  • 返回：包含结果或错误的 JSON 字符串。

示例调用（概念）：

显示所有设备：

{ "table": "device" }

显示主机名“spine01”的 BGP 邻居：

{ "table": "bgp", "filters": { "hostname": "spine01" } }

显示 VRF‘默认’中的‘启动’接口：

{ "table": "interface", "filters": { "vrf": "default", "state": "up" } }

工具使用（run_suzieq_summarize）

run_suzieq_summarize(table: str, filters: Optional[Dict[str, Any]] = None) -> str

  • 表：（字符串，必需）要汇总的 SuzieQ 表名称（例如，“设备”、“接口”、“bgp”）。

  • filters ：（字典，可选）用于过滤的键值对（例如， "hostname": "leaf01" ）。省略或使用{}表示不使用过滤器。

  • 返回：包含汇总结果或错误的 JSON 字符串。

示例调用（概念）：

汇总所有设备：

{ "table": "device" }

按主机名“spine01”汇总 BGP 会话：

{ "table": "bgp", "filters": { "hostname": "spine01" } }

总结 VRF‘默认’中的接口状态：

{ "table": "interface", "filters": { "vrf": "default" } }

故障排除

错误：“SuzieQ API 端点或密钥未配置...”

  • 确保.env文件与main.py位于同一目录中。

  • 验证SUZIEQ_API_ENDPOINT和SUZIEQ_API_KEY拼写正确且在.env中具有有效值。

  • 如果使用 Claude Desktop，请确保claude_desktop_config.json中的workingDirectory指向包含.env的目录。

HTTP 错误（4xx、5xx）：

  • 检查 SuzieQ API 密钥（ SUZIEQ_API_KEY ）是否正确（401/403 错误）。

  • 验证SUZIEQ_API_ENDPOINT是否正确以及 API 服务器是否正在运行。

Available Tools

2 tools
run_suzieq_showA
Runs a SuzieQ 'show' query via its REST API.

Args:
    table: The name of the SuzieQ table to query (e.g., 'device', 'bgp', 'interface', 'route').
    filters: An optional dictionary of filter parameters for the SuzieQ query
             (e.g., {"hostname": "leaf01", "vrf": "default", "state": "Established"}).
             Keys should match SuzieQ filter names. Values can be strings or lists of strings.
             If no filters are needed, this can be None, null, or an empty dictionary.

Returns:
    A JSON string representing the result from the SuzieQ API, or a JSON string with an error message.
ParametersJSON Schema
NameRequiredDescriptionDefault
filtersNo
tableYes

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden for behavioral disclosure. It mentions the REST API mechanism and error handling in returns, but doesn't cover important aspects like rate limits, authentication needs, timeout behavior, or what constitutes valid table names beyond examples. For a tool with no annotation coverage, this leaves significant gaps in understanding operational constraints.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is well-structured with clear sections (Args, Returns) and uses bullet-like formatting for parameter details. While somewhat verbose, each sentence adds value by explaining parameter usage. The front-loaded purpose statement is clear, though some details could be more concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no annotations, no output schema, and 2 parameters, the description does a good job with parameter semantics but lacks completeness in other areas. It doesn't explain the return structure beyond 'JSON string', doesn't cover error scenarios comprehensively, and omits behavioral constraints. For a query tool with REST API dependencies, more operational context would be helpful.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description fully compensates by providing comprehensive parameter documentation. It clearly explains both parameters: 'table' with specific examples and 'filters' with detailed syntax, format examples, and handling of optional/null values. The description adds substantial meaning beyond what the bare schema provides.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Runs a SuzieQ show query') and mechanism ('via its REST API'), providing a specific verb+resource combination. It distinguishes from the sibling tool 'run_suzieq_summarize' by specifying this is for 'show' queries rather than 'summarize' operations, though it doesn't explicitly contrast them in the text.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage context through the examples of tables and filters, suggesting when to use this tool for querying network data. However, it lacks explicit guidance on when to choose this over 'run_suzieq_summarize' or other alternatives, and doesn't mention prerequisites like API connectivity or authentication requirements.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

run_suzieq_summarizeB
Runs a SuzieQ 'summarize' query via its REST API.

Args:
    table: The name of the SuzieQ table to summarize (e.g., 'device', 'bgp', 'interface', 'route').
    filters: An optional dictionary of filter parameters for the SuzieQ query
             (e.g., {"hostname": "leaf01", "vrf": "default"}).
             Keys should match SuzieQ filter names. Values can be strings or lists of strings.
             If no filters are needed, this can be None, null, or an empty dictionary.

Returns:
    A JSON string representing the summarized result from the SuzieQ API,
    or a JSON string with an error message.
ParametersJSON Schema
NameRequiredDescriptionDefault
filtersNo
tableYes

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It mentions the tool runs via REST API and returns JSON or error messages, but lacks details on authentication needs, rate limits, side effects, or what 'summarize' entails behaviorally (e.g., aggregation, statistics). This is a significant gap for a tool with no annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded with the core purpose. The Args and Returns sections are structured clearly, though the 'filters' explanation is slightly verbose. Most sentences earn their place by adding value, with minimal redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 2 parameters, no annotations, no output schema, and moderate complexity, the description covers purpose and parameters well but lacks behavioral context and explicit usage guidelines. It is adequate as a minimum viable description but has clear gaps in transparency and guidance.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema description coverage is 0%, so the description must compensate. It effectively adds meaning by explaining 'table' as the SuzieQ table name with examples and 'filters' as an optional dictionary with examples and usage notes. This goes beyond the schema's minimal titles, providing practical context for both parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool 'runs a SuzieQ summarize query via its REST API', specifying the verb (runs), resource (SuzieQ summarize query), and mechanism (REST API). It distinguishes from the sibling tool 'run_suzieq_show' by focusing on 'summarize' queries rather than 'show' queries, though the distinction could be more explicit.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for SuzieQ summarize queries but does not explicitly state when to use this tool versus the sibling 'run_suzieq_show' or other alternatives. It provides context about the REST API mechanism but lacks explicit guidance on scenarios or prerequisites for choosing this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observedrun_suzieq_show
    • First observedrun_suzieq_summarize
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: run_suzieq_show performs a 'show' query to retrieve data, while run_suzieq_summarize performs a 'summarize' query to aggregate data. Their descriptions explicitly differentiate between querying and summarizing operations, leaving no ambiguity about which tool to use for each task.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern with 'run_suzieq_' as a prefix, followed by the specific operation ('show' or 'summarize'). This naming convention is predictable and helps users understand the tools' functions at a glance, with no deviations or mixed styles.

Tool Count2/5

With only two tools, the server feels thin for its apparent scope of network monitoring and analysis via SuzieQ. While the tools cover basic query and summarize operations, the domain suggests a need for more comprehensive functionality, such as additional query types or data manipulation tools, making the count insufficient for robust agent workflows.

Completeness2/5

The tool surface is severely incomplete for network monitoring and analysis. It lacks essential operations like data filtering beyond basic queries, configuration management, or integration with other network tools. The two tools provide only a minimal subset of what a full SuzieQ interface would offer, leaving significant gaps that will hinder agent effectiveness.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers