Cdash MCP

CDash GraphQL MCP服务器

一种模型上下文协议（MCP）服务器，通过内置缓存对CDash实例提供通用的GraphQL查询执行。

特性

• 通用GraphQL查询执行器：对CDash实例执行任何GraphQL查询
• 智能缓存：具有可配置TTL的LRU缓存，以提高性能
• 不要求进行验证：适用于公共CDash实例（例如open.CDash.org）
• 灵活的配置：在服务器启动时自定义缓存大小和TTL
• MCP资源：内置模式文档以帮助构建查询

安装

# Create virtual environment (recommended)
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package
pip install .

建筑

服务器使用通用的GraphQL查询执行器，而不是为每个CDash操作实现单独的函数。这允许LLM构建他们需要的任何GraphQL查询，而服务器则处理缓存和执行。

关键部件：

• CDashClient：用于执行查询的通用GraphQL客户端
• QueryCache：LRU缓存，支持TTL查询结果
• MCP资源：通过以下方式公开的架构文档 cdash://schema_reference

用法

服务器

使用可选缓存配置启动服务器：

# Start stdio server (for MCP clients)
cdash-mcp-server

# Start HTTP server with custom cache settings
cdash-mcp-server --transport http --port 8000 --cache-size 200 --cache-ttl 600

# Start with minimal caching (for testing)
cdash-mcp-server --cache-size 10 --cache-ttl 60

服务器选项：

• --transport：通信协议（stdio或http，默认：stdio）
• --host：HTTP服务器主机（默认值：127.0.0.1）
• --port：HTTP服务器端口（默认值：8000）
• --cache-size：缓存查询的最大数量（默认值：100）
• --cache-ttl：默认缓存TTL（秒）（默认值：300）

MCP工具

服务器提供六个MCP工具：

1.execute_graphql_query

对CDash实例执行任何GraphQL查询。

参数：

• query （string，必填）：GraphQL查询字符串
• base_url （字符串）：CDash实例URL（默认值：“https://open.cdash.org")
• variables （dict）：GraphQL变量（可选）
• use_cache （bool）：是否使用缓存（默认值：true）
• cache_ttl （int）：自定义TTL（秒）（可选）

查询示例：

列出所有项目：

query {
  projects {
    edges {
      node {
        id
        name
        description
        buildCount
      }
    }
  }
}

获取项目的构建：

query GetBuilds($projectName: String!, $first: Int) {
  project(name: $projectName) {
    builds(first: $first) {
      edges {
        node {
          id
          name
          startTime
          endTime
          failedTestsCount
          passedTestsCount
          site {
            name
          }
        }
      }
    }
  }
}

变量： {"projectName": "MyProject", "first": 50}

获取特定的构建详细信息：

query GetBuild($buildId: ID!) {
  build(id: $buildId) {
    id
    name
    stamp
    failedTestsCount
    passedTestsCount
    project {
      name
    }
  }
}

变量： {"buildId": "123"}

2.get_cache_stats

获取查询缓存的统计信息。

退货：

• size：当前缓存的项目数
• max_size：最大缓存大小
• expired_items：过期项目的数量
• default_ttl：默认TTL（秒）

3.clear_cache

清除所有缓存的查询结果。

4.describe_schema

使用内省获取并描述CDash GraphQL模式。

参数：

• base_url （字符串）：CDash实例URL（默认值：“https://open.cdash.org")

退货：

• 详细的架构信息，包括类型、查询、字段和参数
• 重点关注查询、项目、构建、站点和用户等重要类型

例子：

{
  "success": true,
  "query_type": "Query",
  "mutation_type": "Mutation",
  "types": [...]
}

5.get_query_示例

获取按类别组织的常见CDash GraphQL查询示例。

退货：

• 项目、构建、过滤和分页的分类示例
• 带有示例变量的即用型查询
• 日期过滤和高级使用技巧

类别包括：

• 项目（列出所有项目，按名称获取）
• 构建（列出最近的，按ID获取）
• 筛选和排序（分页）
• 日期筛选提示

6.列表_建筑

用于列出的便利工具具有高级过滤和排序功能。

参数：

• project_name （string，必填）：CDash项目的名称
• limit （int）：要返回的最大内部版本数（默认值：10）
• order_by （字符串）：要排序的字段-“buildDuration”、“configureDuration”、“testDuration”，“startTime”、“endTime”
• order_direction （string）：排序方向-“ASC”或“DESC”（默认值：“DESC）
• date （string）：日期过滤器支持：

- 相对日期：“昨天”、“今天”、“最近7天”、“最后一周” - 绝对日期：“2025-11-26”（YYYY-MM-DD格式）

• site_name （string）：按站点名称构建筛选器（完全匹配，不区分大小写）
• base_url （字符串）：CDash实例URL（默认值：“https://open.cdash.org")
• use_cache （bool）：是否使用缓存结果（默认值：true）

退货：

• 经过筛选和排序的构建
• 关于提取总量与过滤总量的元数据
• 应用过滤器信息

示例：

# Get 10 slowest builds from yesterday
list_builds("ParaView", limit=10, order_by="buildDuration", date="yesterday")

# Get builds from specific site
list_builds("ParaView", site_name="gitlab-ci", limit=20)

# Get builds from last week, sorted by test duration
list_builds("ParaView", limit=15, order_by="testDuration", date="last_7_days")

注： 由于CDash GraphQL对服务器端过滤的支持有限，因此该工具可以获取更大的数据集，并执行客户端过滤和排序，以获得更好的结果。

MCP资源

cdash://schema_reference

访问CDash GraphQL模式文档，包括：

• 常见查询模式
• 可用的顶级查询
• 分页信息
• 最佳实践

CLI客户端

提供了一个简单的CLI客户端用于测试：

# List available tools
cdash-mcp-client list-tools

# Execute a GraphQL query
cdash-mcp-client query 'query { projects { edges { node { id name } } } }'

# Execute a query with variables
cdash-mcp-client query 'query GetBuilds($name: String!) {
  project(name: $name) {
    builds(first: 10) {
      edges { node { id name } }
    }
  }
}' --variables '{"name": "MyProject"}'

# Execute query without caching
cdash-mcp-client query 'query { projects { edges { node { id } } } }' --no-cache

# Get cache statistics
cdash-mcp-client cache-stats

# Clear cache
cdash-mcp-client clear-cache

# Use custom server and CDash URL
cdash-mcp-client --host localhost --port 8000 --base-url https://cdash.spack.io query 'query { projects { edges { node { id name } } } }'

发展

# Create and activate virtual environment
python -m venv venv
source venv/bin/activate

# Install in development mode with test dependencies
pip install -e ".[test]"

# Start the server
cdash-mcp-server --transport http --port 8000

# In another terminal, test with the CLI client
cdash-mcp-client query 'query { projects { edges { node { id name } } } }'

# Or test with curl
curl -X POST http://localhost:8000/mcp/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "execute_graphql_query",
      "arguments": {
        "query": "query { projects { edges { node { id name } } } }"
      }
    }
  }'

测试

安装测试依赖项：

pip install -e ".[test]"

运行测试：

# Run all tests
pytest

# Run with verbose output
pytest -v

# Run specific test files
pytest tests/test_cache.py
pytest tests/test_cdash_client.py
pytest tests/test_server_functions.py

# Run specific test types using markers
pytest -m unit                  # Unit tests only
pytest -m integration           # Integration tests only

缓存行为

• 查询根据查询字符串、变量和base_url进行缓存
• 查询字符串被规范化（空格差异不影响缓存）
• 默认TTL为5分钟（300秒）
• 缓存达到max_size时LRU被驱逐
• 可以通过以下方式禁用每个查询的缓存 use_cache=false
• 使用 get_cache_stats 监控缓存性能
• 使用 clear_cache 使所有缓存条目无效

作者

• 维森特·博莱亚

许可证

麻省理工学院