项目概述

Automotive-MCP 是一个基于 Model Context Protocol (MCP) 的汽车网络安全法规与标准查询服务器。该项目由 Ansvar Systems 开发，旨在为汽车网络安全工程师、合规性团队和自动化工具提供高效、准确的法规条款检索能力。

核心定位： 作为一个 MCP 服务器，Automotive-MCP 通过标准化的 JSON-RPC 接口，将汽车网络安全相关的联合国法规和国际标准组织起来，使用户能够在 AI 助手（如 Claude Desktop）中直接查询和分析法规条款。

版本信息： 当前稳定版本为 v1.0.2，包含了对源 ID 大小写不敏感的查询优化、搜索结果数量限制校验以及更友好的输入验证错误提示等改进。

资料来源：package.json:1-20 资料来源：CHANGELOG.md:1-10

前提条件

在开始之前，请确保您的开发环境满足以下要求：

系统要求

MCP 客户端要求

Automotive Cybersecurity MCP 需要兼容的 MCP 客户端，官方支持以下客户端：

• Claude Desktop - 官方推荐客户端
• 其他 MCP 兼容客户端 - 支持 stdio 或 HTTP 传输协议

安装步骤

方式一：从 npm 安装（推荐）

使用 npm 全局安装是最简单的安装方式：

npm install -g @ansvar/automotive-cybersecurity-mcp

安装完成后，验证安装：

automotive-mcp --version

资料来源：README.md:1-50

方式二：从源码构建

如果您需要自定义配置或参与开发，请从源码构建：

# 克隆仓库
git clone https://github.com/Ansvar-Systems/Automotive-MCP.git
cd Automotive-MCP

# 安装依赖
npm install

# 构建 TypeScript 代码
npm run build

# 构建数据库
npm run build:db

资料来源：DEPLOYMENT_CHECKLIST.md:1-30

配置 Claude Desktop

添加 MCP 服务器配置

编辑 Claude Desktop 配置文件：

macOS/Linux:

~/Library/Application Support/Claude/claude_desktop_config.json

Windows:

%APPDATA%\Claude\claude_desktop_config.json

在 mcpServers 部分添加以下配置：

{
  "mcpServers": {
    "automotive-cybersecurity": {
      "command": "automotive-mcp",
      "args": []
    }
  }
}

资料来源：README.md:50-80

配置参数说明

服务启动与验证

启动服务器

配置完成后，Claude Desktop 将自动启动 MCP 服务器。您也可以手动启动进行测试：

# 启动服务器（stdio 模式）
node dist/index.js

# 预期输出
Automotive Cybersecurity MCP server started

资料来源：DEPLOYMENT_CHECKLIST.md:50-60

协议握手验证

MCP 服务器应正确响应初始化请求：

// 初始化请求
{
  "jsonrpc": "2.0",
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "test-client",
      "version": "1.0.0"
    }
  },
  "id": 1
}

// 服务器响应
{
  "jsonrpc": "2.0",
  "result": {
    "protocolVersion": "2024-11-05",
    "capabilities": {
      "tools": {}
    },
    "serverInfo": {
      "name": "automotive-cybersecurity-mcp",
      "version": "1.0.2"
    }
  },
  "id": 1
}

资料来源：TEST_RESULTS.md:1-50

工具列表与发现

列出可用工具

通过 tools/list 方法获取所有可用工具：

{
  "jsonrpc": "2.0",
  "method": "tools/list",
  "id": 1
}

可用工具概览

资料来源：src/tools/list_sources.ts

基础工具使用示例

工具一：列出数据源

查看系统中所有可用的法规和标准：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "list_sources",
    "arguments": {}
  },
  "id": 2
}

预期响应：

{
  "source": "r155",
  "name": "UN Regulation No. 155",
  "version": "Revision 2",
  "type": "regulation",
  "description": "Cyber Security and Cyber Security Management System",
  "item_count": 1,
  "full_text_available": true
}

资料来源：TEST_RESULTS.md:50-80

工具二：获取法规条款

检索 UN R155 第 7.2.2.2 条的完整内容：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "get_requirement",
    "arguments": {
      "source": "r155",
      "reference": "7.2.2.2"
    }
  },
  "id": 3
}

预期响应：

{
  "source": "r155",
  "reference": "7.2.2.2",
  "title": "Cyber Security Management System Requirements",
  "text": "The Cyber Security Management System shall be appropriate to the type of vehicle and shall address the following areas as they apply to the vehicle type: (a) vehicle type related risk assessment in relation to cyber-attacks...",
  "guidance": ""
}

资料来源：src/tools/get_requirement.ts

工具三：全文搜索

使用 FTS5 全文搜索引擎查找相关内容：

{
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "name": "search_requirements",
    "arguments": {
      "query": "risk assessment",
      "sources": ["r155"],
      "limit": 10
    }
  },
  "id": 4
}

预期响应：

[
  {
    "source": "r155",
    "reference": "7.2.2.2",
    "title": "Cyber Security Management System Requirements",
    "snippet": "The Cyber Security Management System shall be appropriate to the type of vehicle and shall address the following areas as they apply to the vehicle type: (a) vehicle type related **risk** **assessment**...",
    "relevance": -0.000002
  }
]

资料来源：src/tools/search_requirements.ts

数据流程图

sequenceDiagram
    participant Client as MCP 客户端
    participant Server as MCP 服务器
    participant DB as SQLite 数据库
    participant FTS as FTS5 搜索引擎

    Client->>Server: 初始化请求 (initialize)
    Server-->>Client: 协议版本、能力集
    
    Client->>Server: 工具列表请求 (tools/list)
    Server->>DB: 查询可用数据源
    DB-->>Server: 数据源列表
    Server-->>Client: 工具定义
    
    Client->>Server: 获取条款请求 (get_requirement)
    Server->>DB: 查询法规/标准内容
    DB-->>Server: 条款详情
    Server-->>Client: JSON 响应
    
    Client->>Server: 搜索请求 (search_requirements)
    Server->>FTS: 执行全文搜索
    FTS-->>Server: BM25 排序结果
    Server-->>Client: 搜索结果（含高亮片段）

常见问题与解决方案

问题一：服务器启动失败

症状： 执行 automotive-mcp 命令无响应或报错

解决方案：

``bash node --version ``

1. 确认 Node.js 版本满足要求（18+）

``bash npm uninstall -g @ansvar/automotive-cybersecurity-mcp npm install -g @ansvar/automotive-cybersecurity-mcp ``

1. 重新安装依赖

问题二：数据库未找到

症状： 错误提示 "Database not found"

解决方案：

``bash npm run build:db ``

1. 确保数据库已构建

``bash ls -la data/automotive.db ``

1. 检查数据目录

资料来源：DEPLOYMENT_CHECKLIST.md:30-50

问题三：源 ID 大小写问题

症状： 搜索 R155 返回 "Source not found"

解决方案： 从 v1.0.2 起，源 ID 已支持大小写不敏感查询。R155、r155、R155 均能正确匹配。

资料来源：社区更新日志 - v1.0.2

问题四：搜索结果为空

症状： 搜索查询返回空数组

可能原因：

1. 查询词不精确：例如搜索 "cyber attack" 但数据库中只有 "cyber-attacks"（带连字符）
2. 数据源为空：指定的数据源可能没有可搜索内容
3. 超出限制：检查 limit 参数是否被正确限制在 [0, 100] 范围内

建议：

• 使用更宽泛的搜索词
• 省略 sources 参数以搜索所有数据源
• 检查 list_sources 确认数据源是否包含预期内容

资料来源：TEST_RESULTS.md:100-130

性能基准

所有查询均在亚毫秒级完成，远低于 10ms 的目标阈值。

资料来源：TEST_RESULTS.md:150-180

后续步骤

完成快速入门后，您可以：

``bash npm test ``

1. 深入阅读文档 - 了解所有工具的完整参数和用法
2. 运行测试套件 - 验证安装是否正确
3. 探索数据内容 - 使用 list_sources 了解可用的法规和标准
4. 配置集成 - 将 MCP 服务器与您的开发工作流集成

相关资源

• 主 README 文档 - 项目概述和详细说明
• 工具参考 - 所有 MCP 工具的完整 API 文档
• 数据源说明 - 支持的法规和标准详解
• 部署指南 - 生产环境部署配置

1. 概述

Automotive-MCP 是一个基于 Model Context Protocol (MCP) 的汽车网络安全法规查询服务器。它为 Claude 等 AI 助手提供对 UN R155、UN R156 和 ISO/SAE 21434 等汽车网络安全标准的结构化访问能力。

核心功能：

• 列出可用的法规来源和标准
• 根据来源和引用编号检索特定要求
• 使用 FTS5 全文搜索引擎跨所有内容进行搜索
• 导出合规性矩阵和工作产品信息

技术栈：

资料来源：package.json

概述

Automotive-MCP 项目采用 SQLite 作为数据持久化存储，结合 FTS5（Full-Text Search 5） 全文搜索引擎实现对汽车网络安全法规和标准的检索功能。数据库架构设计旨在支持三个核心工具的查询操作：list_sources（列出数据源）、get_requirement（获取具体条款）和 search_requirements（全文搜索）。

当前版本为 Phase 1，包含有限但经过验证的示例数据，主要涵盖 UN R155、UN R156 法规以及 ISO/SAE 21434 标准的关键条款。

核心设计目标

资料来源：TEST_RESULTS.md

架构概览

Automotive-MCP 作为 Model Context Protocol (MCP) 服务器运行，通过标准输入/输出 (stdio) 与 MCP 客户端通信。服务器内部采用模块化架构，将工具定义、数据库操作和数据类型分离管理。

graph TD
    A[MCP 客户端] -->|JSON-RPC 2.0| B[Automotive-MCP 服务器]
    B --> C[工具注册表]
    C --> D[list_sources]
    C --> E[get_requirement]
    C --> F[search_requirements]
    C --> G[list_work_products]
    C --> H[export_compliance_matrix]
    C --> I[about]
    D --> J[(SQLite 数据库)]
    E --> J
    F --> J
    G --> J
    H --> J
    J --> K[FTS5 全文索引]

工具清单

资料来源：src/tools/list.ts

概述

list_sources 是 Automotive-MCP 项目提供的三个核心工具之一，用于列出所有可用的法规和标准信息源。该工具是用户与汽车网络安全法规知识库交互的主要入口点，允许用户发现系统中注册的所有数据源，包括联合国法规（UN Regulation）和国际标准（ISO/SAE 标准）。

根据测试结果，list_sources 工具已通过全部功能验证测试，能够正确返回数据源的完整元数据信息，包括数据源标识符、名称、版本、类型、描述、项目计数和全文可用性标志等关键字段。

工具功能说明

核心能力

list_sources 工具提供以下核心功能：

1. 全量列表查询：返回系统中所有已注册的数据源
2. 类型过滤：支持按数据源类型（regulation/standard）进行筛选
3. 元数据完整返回：每个数据源包含完整的描述性信息
4. 全文可用性指示：标识哪些数据源提供完整文本内容

该工具通过 MCP（Model Context Protocol）协议进行调用，返回 JSON 格式的结构化数据，便于客户端程序进行解析和处理。

返回数据结构

每个数据源对象包含以下字段：

使用方式

基本调用

获取所有可用数据源的完整列表：

{
  "name": "list_sources",
  "arguments": {}
}

此调用返回系统中所有注册的数据源信息。

按类型过滤

仅获取法规类型的数据源：

{
  "name": "list_sources",
  "arguments": {
    "source_type": "regulation"
  }
}

仅获取标准类型的数据源：

{
  "name": "list_sources",
  "arguments": {
    "source_type": "standard"
  }
}

当前数据源

UN 法规

ISO 标准

测试验证结果

功能测试摘要

根据测试结果文档，list_sources 工具在所有测试场景中表现良好：

响应示例

全量列表响应：

[
  {
    "id": "r155",
    "name": "UN Regulation No. 155",
    "version": "Revision 2",
    "type": "regulation",
    "description": "Cyber Security and Cyber Security Management System",
    "item_count": 1,
    "full_text_available": true
  },
  {
    "id": "r156",
    "name": "UN Regulation No. 156",
    "version": "Revision 2",
    "type": "regulation",
    "description": "Software Update and Software Updates Management System",
    "item_count": 0,
    "full_text_available": true
  },
  {
    "id": "iso_21434",
    "name": "ISO/SAE 21434:2021",
    "version": "2021",
    "type": "standard",
    "description": "Road vehicles — Cybersecurity engineering",
    "item_count": 1,
    "full_text_available": false
  }
]

验证要点

测试结果确认以下功能特性：

• ✅ 返回 3 个数据源的完整信息
• ✅ 所有数据源的元数据完整
• ✅ 项目计数准确
• ✅ 全文可用性标志正确标记
• ✅ JSON 格式可正常解析

与其他工具的协作

list_sources 工具是Automotive-MCP工具链的起点，用户通常按照以下流程使用：

graph TD
    A[调用 list_sources] --> B{了解可用数据源}
    B --> C[使用 get_requirement 获取特定条款]
    B --> D[使用 search_requirements 搜索内容]
    C --> E[查看完整文本或指导说明]
    D --> F[浏览搜索结果]
    F --> C

工具对比

性能特性

根据性能基准测试，list_sources 工具具有以下性能特征：

该工具的响应时间在所有测试场景中均保持在毫秒级以下，满足实时应用需求。

常见使用场景

场景一：数据源发现

用户首次使用系统时，首先调用 list_sources 了解系统中可用的法规和标准：

1. 调用 list_sources 获取完整列表
2. 查看各数据源的描述和项目数量
3. 根据需要选择特定数据源进行深入查询

场景二：类型过滤

用户仅关注法规要求时：

1. 调用 list_sources 并设置 source_type 为 regulation
2. 仅获取联合国法规列表（r155、r156）
3. 排除 ISO 标准等非法规内容

场景三：内容可用性检查

用户需要确认数据源是否提供完整文本：

1. 检查返回数据中的 full_text_available 字段
2. 对于 true 的数据源（如 r155、r156），可获取完整法规文本
3. 对于 false 的数据源（如 iso_21434），仅能获取指导说明

版本兼容性说明

根据 v1.0.2 版本的更新说明，list_sources 工具与以下功能共享相同的ID规范化机制：

Case-insensitive source IDs：所有工具现在将源ID规范化为小写，因此 R155 和 r155 的行为一致。

这意味着 list_sources 返回的源ID格式与用户在其他工具中使用的格式保持兼容，确保跨工具使用的一致性。

技术实现细节

数据来源

list_sources 工具从 SQLite 数据库的以下表读取数据：

• regulations - 存储联合国法规信息
• standards - 存储 ISO/SAE 标准信息

工具实现位于 src/tools/list.ts 文件中，通过统一的工具注册表模式进行注册和管理。

类型定义

工具的输入输出类型定义位于 src/types/index.ts，定义了 list_sources 工具的参数接口和返回数据结构。

故障排查

常见问题

Q: 返回的数据源数量与预期不符？

可能原因：

• 数据库未正确构建
• 种子数据未加载

解决方法：运行 npm run build:db 重新构建数据库

Q: item_count 显示为 0？

可能原因：

• 该数据源尚未添加条款数据
• 数据库连接问题

解决方法：检查数据库构建日志，确认数据加载成功

另请参阅

• get_requirement 工具 - 获取特定条款详情
• search_requirements 工具 - 全文搜索功能
• 数据库架构文档 - 数据存储结构说明
• MCP 协议集成指南 - 与 MCP 客户端的集成方式

概述

get_requirement 是 Automotive-MCP 服务器提供的三个核心工具之一，专门用于检索汽车网络安全法规和标准的具体条款内容。该工具通过 Model Context Protocol (MCP) 接口提供服务，允许用户根据来源标识符（如 r155、r156、iso_21434）和条款引用编号获取精确的法规要求。

作为 Automotive-MCP Phase 1 的核心功能组件，get_requirement 工具在 v1.0.2 版本中已实现大小写不敏感的源 ID 处理，确保 R155 和 r155 具有相同的查询效果。资料来源：TEST_RESULTS.md

概述

search_requirements 是 Automotive-MCP 服务器提供的三大核心工具之一，专门用于对汽车网络安全法规和标准进行全文搜索。该工具基于 SQLite 的 FTS5（Full-Text Search 5）虚拟表实现，结合 BM25（Best Matching 25）算法进行相关性排序，能够在海量法规文本中快速定位用户所需的内容。

search_requirements 工具的主要职责包括：

• 跨数据源搜索：同时搜索联合国法规（UN R155、R156）和 ISO/SAE 标准（ISO 21434）中的相关内容
• 智能相关性排序：根据 BM25 算法计算每个结果的相关性得分，按得分从高到低排序
• 上下文摘要提取：为每个搜索结果生成包含关键词上下文的摘要片段
• 多源过滤：支持限制搜索范围到特定的数据源
• 搜索结果分页：通过 limit 参数控制返回结果的数量上限

该工具在 v1.0.2 版本中进行了重要修复，包括源 ID 大小写规范化（R155 与 r155 等效）和搜索限制值钳制（限制参数被约束在 0-100 范围内）。资料来源：TEST_RESULTS.md

功能特性

核心能力

搜索性能

根据基准测试数据，search_requirements 工具展现出卓越的搜索性能：

所有查询均在亚毫秒级完成，远低于 10ms 的可接受阈值。资料来源：TEST_RESULTS.md:120-140

工作原理

系统架构

graph TD
    A[用户查询请求] --> B[search_requirements 工具]
    B --> C{查询参数验证}
    C -->|有效| D[查询预处理]
    C -->|无效| E[返回错误]
    D --> F[FTS5 全文搜索引擎]
    F --> G[BM25 相关性评分]
    G --> H[结果排序]
    H --> I[摘要生成]
    I --> J[高亮标记处理]
    J --> K[返回结果集]
    K --> L[limit 参数钳制]
    L --> M[最终响应]

FTS5 全文搜索引擎

Automotive-MCP 使用 SQLite 的 FTS5 虚拟表实现全文搜索功能。FTS5 是 SQLite 3.9.0+ 引入的高性能全文搜索模块，支持以下特性：

1. 倒排索引：FTS5 在内部维护倒排索引，将每个词映射到包含该词的文档列表
2. 高效匹配：使用 B-tree 结构存储索引，支持快速词项查找
3. 短语搜索：支持双引号包裹的精确短语匹配
4. 前缀搜索：支持星号后缀的前缀匹配（如 secu* 匹配 security）

数据库构建脚本 scripts/build-db.ts 负责创建 FTS5 虚拟表并将法规内容索引化：

// 资料来源：scripts/build-db.ts
CREATE VIRTUAL TABLE regulation_content_fts USING fts5(
    reference,
    title,
    content,
    content='regulation_content',
    content_rowid='rowid'
);

BM25 相关性评分算法

BM25（Best Matching 25）是信息检索领域最经典的文本相关性评分算法之一。该算法基于词频（TF）和逆文档频率（IDF）计算每个文档与查询的相关性得分：

BM25(d, q) = Σ IDF(t) × (tf(t,d) × (k1 + 1)) / (tf(t,d) + k1 × (1 - b + b × |d|/avgdl))

其中：

• t 为查询词项
• tf(t,d) 为词项 t 在文档 d 中的词频
• k1 和 b 为调节参数（通常 k1=1.2, b=0.75）
• |d| 为文档长度，avgdl 为平均文档长度

在 Automotive-MCP 中，BM25 评分用于对搜索结果进行排序。评分越低（负值越大），表示相关性越高。资料来源：TEST_RESULTS.md:150-160

搜索流程详解

sequenceDiagram
    participant 用户
    participant MCP客户端
    participant search工具
    participant FTS5引擎
    participant 数据库

    用户->>MCP客户端: search_requirements({query, sources?, limit?})
    MCP客户端->>search工具: 调用工具
    
    alt 参数验证
        search工具->>search工具: 规范化源 ID（小写）
        search工具->>search工具: 钳制 limit 到 [0, 100]
    end
    
    search工具->>FTS5引擎: 构建 FTS5 MATCH 查询
    FTS5引擎->>数据库: 执行 SELECT ... WHERE rowid IN (MATCH ...)
    数据库-->>FTS5引擎: 返回匹配文档 ID 列表
    FTS5引擎->>FTS5引擎: 计算 BM25 评分
    FTS5引擎->>FTS5引擎: 按评分升序排序
    
    alt 生成摘要
        FTS5引擎->>FTS5引擎: 提取上下文片段（32 tokens）
        FTS5引擎->>FTS5引擎: 标记匹配关键词 **term**
    end
    
    FTS5引擎-->>search工具: 返回结果集
    search工具->>search工具: 应用 limit 截断
    search工具-->>MCP客户端: 返回 JSON 响应
    MCP客户端-->>用户: 显示搜索结果

API 参考

工具定义

{
  "name": "search_requirements",
  "description": "Full-text search across regulations and standards using FTS5",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Search query text"
      },
      "sources": {
        "type": "array",
        "items": { "type": "string" },
        "description": "Optional list of source IDs to filter (e.g., ['r155', 'iso_21434'])"
      },
      "limit": {
        "type": "integer",
        "description": "Maximum number of results to return (clamped to 0-100, default: 10)"
      }
    }
  }
}

参数说明

返回值结构

interface SearchResult {
  source: string;       // 数据源 ID（如 "r155"、"iso_21434"）
  reference: string;    // 条款引用（如 "7.2.2.2"、"9.3"）
  title: string;        // 条款标题
  snippet: string;     // 包含匹配上下文的摘要，关键词用 ** 包裹
  relevance: number;   // BM25 相关性评分（负值，越小越相关）
}

返回值示例

搜索 "risk assessment" 的结果：

[
  {
    "source": "r155",
    "reference": "7.2.2.2",
    "title": "Cyber Security Management System Requirements",
    "snippet": "The Cyber Security Management System shall be appropriate to the type of vehicle and shall address the following areas as they apply to the vehicle type: (a) vehicle type related **risk** **assessment** in relation to cyber-attacks...",
    "relevance": -0.000002
  }
]

搜索 "vulnerability" 并限定源为 iso_21434：

[
  {
    "source": "iso_21434",
    "reference": "9.3",
    "title": "Vulnerability analysis",
    "snippet": "**Vulnerability** analysis",
    "relevance": -0.000001375
  }
]

资料来源：TEST_RESULTS.md:70-110

使用示例

基础搜索

搜索包含 "security" 的所有法规条款：

{
  "name": "search_requirements",
  "arguments": {
    "query": "security"
  }
}

带源过滤的搜索

仅在 ISO 21434 标准中搜索 "vulnerability" 相关内容：

{
  "name": "search_requirements",
  "arguments": {
    "query": "vulnerability",
    "sources": ["iso_21434"]
  }
}

多源联合搜索

同时搜索 R155 和 ISO 21434 中的 "management" 相关内容：

{
  "name": "search_requirements",
  "arguments": {
    "query": "management",
    "sources": ["r155", "iso_21434"]
  }
}

限制结果数量

只返回前 5 条最相关的结果：

{
  "name": "search_requirements",
  "arguments": {
    "query": "risk assessment",
    "limit": 5
  }
}

完整参数示例

{
  "name": "search_requirements",
  "arguments": {
    "query": "vulnerability management disclosure",
    "sources": ["r155", "iso_21434"],
    "limit": 20
  }
}

常见问题与限制

已知的搜索限制

v1.0.2 版本修复内容

根据社区发布的最新版本信息，v1.0.2 对 search_requirements 工具进行了以下修复：

1. 大小写规范化：源 ID 参数（如 R155）会自动转换为小写（r155），避免因大小写不匹配导致的搜索失败
2. limit 参数钳制：limit 参数被强制约束在 [0, 100] 范围内，防止传入负数或极大值导致异常
3. 输入验证增强：无效的枚举值现在会返回更具描述性的错误信息

资料来源：TEST_RESULTS.md:1-20

性能注意事项

虽然 search_requirements 在当前数据量下表现优异（亚毫秒级响应），但随着数据增长，建议：

• 始终设置合理的 limit 值（推荐 ≤ 50）
• 使用具体的源过滤（sources 参数）减少搜索范围
• 避免过于宽泛的查询词（如单个字母）

数据完整性说明

当前版本（Phase 1）仅包含有限的种子数据：

因此，搜索结果可能受限。随着后续版本扩展数据内容，搜索覆盖范围将逐步完善。资料来源：SUMMARY.md:40-60

错误处理

常见错误及解决方案

特殊字符处理

search_requirements 工具内置查询清理机制，会自动处理以下特殊字符：

• 连字符（-）：如 risk-assessment 会被处理为 risk assessment
• 括号（()）：会被移除或转义
• 引号（"）：用于短语搜索，可保留

相关文件

参见

• get_requirement 工具 - 获取特定法规条款的详细信息
• list_sources 工具 - 列出所有可用的法规和标准数据源
• Automotive-MCP 概述 - 服务器整体架构说明

export_compliance_matrix 工具

automotive-mcp 是一个面向「安全审查与权限治理」的开源项目，重点覆盖 安全审查与权限治理、知识库问答；Doramagic 已整理安装入口、说明书、上下文包和风险边界，方便先判断再试用。

概述

种子数据结构是Automotive-MCP项目的核心数据资产，用于初始化SQLite数据库中的汽车网络安全法规和标准内容。该数据模型定义了法规（Regulations）、标准（Standards）以及跨框架映射（Cross-Mappings）三类核心实体的结构规范，为MCP服务器提供可查询的法规条款和标准指导。

种子数据采用JSON格式存储于data/seed/目录下，通过scripts/build-db.ts脚本构建脚本在数据库初始化时加载到SQLite中。所有种子数据均经过FTS5全文索引处理，支持基于BM25算法的相关性搜索功能。

资料来源：scripts/build-db.ts:1-50

数据架构

整体数据模型

graph TD
    A[seed数据目录] --> B[regulations.json]
    A --> C[standards.json]
    A --> D[cross-mappings.json]
    B --> E[SQLite regulations表]
    C --> F[SQLite standards表]
    D --> G[SQLite mappings表]
    E --> H[FTS5全文索引]
    F --> H
    G --> I[查询结果返回]
    H --> I

核心实体关系

资料来源：scripts/build-db.ts:80-150

法规数据结构

法规JSON结构

regulations.json文件定义了汽车网络安全相关法规的完整结构。每个法规条目包含基本信息、元数据和条款内容三个层级：

{
  "id": "r155",
  "name": "UN Regulation No. 155",
  "version": "Revision 2",
  "type": "regulation",
  "description": "Cyber Security and Cyber Security Management System",
  "full_text_available": true,
  "items": [
    {
      "reference": "7.2.2.2",
      "title": "Cyber Security Management System Requirements",
      "text": "The Cyber Security Management System shall be appropriate to the type of vehicle...",
      "guidance": ""
    }
  ]
}

字段定义

条款对象结构

资料来源：data/seed/regulations.json

标准数据结构

标准JSON结构

standards.json文件存储ISO/SAE等汽车行业标准信息。与法规不同，标准条目通常不包含完整文本（需要付费许可），但提供详细的实施指导和工件清单：

{
  "id": "iso_21434",
  "name": "ISO/SAE 21434:2021",
  "version": "2021",
  "type": "standard",
  "description": "Road vehicles — Cybersecurity engineering",
  "full_text_available": false,
  "clauses": [
    {
      "reference": "9.3",
      "title": "Vulnerability analysis",
      "text": null,
      "guidance": "Monitor for vulnerabilities in components throughout vehicle lifetime...",
      "work_products": ["[WP-09-03]"]
    }
  ]
}

字段定义

条款对象结构

资料来源：data/seed/standards.json

跨框架映射结构

映射JSON结构

cross-mappings.json定义了不同法规和标准之间的关联关系，支持跨框架查询功能：

[
  {
    "source_type": "regulation",
    "source_id": "r155",
    "source_reference": "7.2.2.2",
    "target_type": "standard",
    "target_id": "iso_21434",
    "target_reference": "8.3",
    "relationship": "related",
    "description": "Risk assessment relates to threat analysis"
  }
]

字段定义

资料来源：data/seed/cross-mappings.json

数据加载流程

数据库构建流程

graph TD
    A[npm run build:db] --> B[读取seed JSON文件]
    B --> C[验证JSON schema]
    C --> D{格式正确?}
    D -->|是| E[清空现有数据]
    E --> F[插入regulations数据]
    F --> G[插入standards数据]
    G --> H[插入mappings数据]
    H --> I[构建FTS5索引]
    I --> J[生成automotive.db]
    D -->|否| K[输出验证错误]
    J --> L[数据库就绪]

数据表结构

数据库创建包含以下核心表：

资料来源：scripts/build-db.ts:50-80

当前数据内容

Phase 1 种子数据

当前Phase 1仅包含最小可行数据集，用于验证系统功能和API接口。实际部署时需要补充完整的法规和标准内容。

示例数据内容

法规条款示例（R155 7.2.2.2）：

The Cyber Security Management System shall be appropriate to the type of vehicle and shall address the following areas as they apply to the vehicle type: (a) vehicle type related risk assessment in relation to cyber-attacks...

标准条款示例（ISO 21434 9.3）：

Monitor for vulnerabilities in components throughout vehicle lifetime. Establish processes for vulnerability disclosure, triage, and remediation. Interface with PSIRT for coordination.

资料来源：TEST_RESULTS.md

数据质量验证

测试覆盖

性能指标

所有查询均保持在亚毫秒级别，FTS5索引工作正常。

资料来源：QUALITY_ASSESSMENT_REPORT.md

扩展数据源

添加新法规

1. 编辑data/seed/regulations.json，添加新法规条目
2. 在items数组中添加条款内容
3. 运行npm run build:db重建数据库
4. 执行npm test验证数据加载

添加新标准

1. 编辑data/seed/standards.json，添加新标准条目
2. 在clauses数组中添加条款内容
3. 包含guidance和work_products字段
4. 重建数据库并测试

添加跨框架映射

1. 编辑data/seed/cross-mappings.json
2. 定义source和target的关联关系
3. 重建数据库使映射生效

资料来源：R155_R156_INTEGRATION_SUMMARY.md

版本兼容性说明

v1.0.2 更新

最新版本对种子数据查询进行了以下优化：

这些改进确保种子数据查询的健壮性和一致性。

相关资源

参见

• MCP工具接口 - 了解如何使用种子数据进行查询
• 数据库架构 - 深入了解SQLite表结构
• 全文搜索机制 - 了解FTS5和BM25算法

Pitfall Log / 踩坑日志

项目：ansvar-systems/automotive-mcp

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

1. 身份坑 · 仓库名和安装名不一致

• 严重度：medium
• 证据强度：runtime_trace
• 发现：仓库名 automotive-mcp 与安装入口 @ansvar/automotive-cybersecurity-mcp 不完全一致。
• 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
• 建议检查：在 npm/PyPI/GitHub 上确认包名映射和官方 README 说明。
• 复现命令：npx @ansvar/automotive-cybersecurity-mcp
• 防护动作：页面必须同时展示 repo 名和真实安装入口，避免用户搜索错包。
• 证据：identity.distribution | mcp_registry:io.github.Ansvar-Systems/automotive-cybersecurity:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Ansvar-Systems%2Fautomotive-cybersecurity/versions/1.0.1 | repo=automotive-mcp; install=@ansvar/automotive-cybersecurity-mcp

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | mcp_registry:io.github.Ansvar-Systems/automotive-cybersecurity:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Ansvar-Systems%2Fautomotive-cybersecurity/versions/1.0.1 | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.Ansvar-Systems/automotive-cybersecurity:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Ansvar-Systems%2Fautomotive-cybersecurity/versions/1.0.1 | last_activity_observed missing

4. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | mcp_registry:io.github.Ansvar-Systems/automotive-cybersecurity:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Ansvar-Systems%2Fautomotive-cybersecurity/versions/1.0.1 | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | mcp_registry:io.github.Ansvar-Systems/automotive-cybersecurity:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Ansvar-Systems%2Fautomotive-cybersecurity/versions/1.0.1 | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.Ansvar-Systems/automotive-cybersecurity:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Ansvar-Systems%2Fautomotive-cybersecurity/versions/1.0.1 | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | mcp_registry:io.github.Ansvar-Systems/automotive-cybersecurity:1.0.1 | https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Ansvar-Systems%2Fautomotive-cybersecurity/versions/1.0.1 | release_recency=unknown