Metadata-Version: 2.4
Name: opc-ontology-mcp
Version: 0.1.0
Summary: MCP server for OPC order-center ontology queries (stdio only)
Author-email: zhouxinhai <your.email@example.com>
License-Expression: MIT
Project-URL: Homepage, https://gitee.com/zhouxinhai/opc-ontology-mcp
Project-URL: Repository, https://gitee.com/zhouxinhai/opc-ontology-mcp
Project-URL: Issues, https://gitee.com/zhouxinhai/opc-ontology-mcp/issues
Keywords: mcp,ontology,knowledge-graph,order-center
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp[cli]<2,>=1.0.0
Dynamic: license-file

# OPC-Ontology-MCP

OPC 订单中心本体查询 MCP 服务器。它加载 `opc-gen-ontology` 技能生成的最终本体层（`gen_ontology/ontology/`），
通过 MCP 协议（stdio）向 AI 智能体暴露只读查询能力，为代码分析、影响面评估、故障定位等任务提供判断推理依据。

## 功能特性

- **本体概览** —— 对象/属性/关系/动作计数、关系置信度与来源分布、表类型分布、域列表、业务场景清单
- **语义搜索** —— 按表名/中文名/概念/业务场景/域关键词检索
- **实体详情** —— 单张表的完整推理上下文（字段、双向关系、动作、sqlId、DAO 方法、读写字段）
- **关系扩展** —— BFS 邻居扩展，支持深度、方向、业务关系类型、业务子类型、置信度、来源过滤与节点上限
- **业务场景** —— 按场景 ID 或名称查询涉及表及每表动作摘要
- **概念/域查询** —— 按业务概念或信息模块（域）列出相关表
- **关系路径** —— 两张表之间最短关系路径推理，可同时应用关系类型/子类型/置信度/来源过滤
- **字段检索** —— 跨表按字段名/注释/角色检索
- **热重载** —— 本体重新生成后无需重启进程即可刷新数据
- **stdio 传输** —— 仅支持 stdio，由 MCP 客户端本地拉起，不占用网络端口
- **只读安全** —— 只读取 `ontology/` 最终层 JSON，不连接数据库，不写入任何本体文件

## 环境要求

| 依赖 | 要求 |
| ---- | ---- |
| Python | 3.11+ |
| 数据库 | 无需 |
| Java | 无需 |

本体数据由 `opc-gen-ontology` 技能生成，启动时通过 `--ontology-dir` 指向 `gen_ontology` 输出目录。

## 安装

### 方式一：uvx 直接运行（推荐，需已发布到 PyPI）

```bash
# 直接运行，无需安装，首次会自动下载依赖
uvx opc-ontology-mcp --ontology-dir D:/code/java/crm/git/OPC/gen_ontology
```

> **注意**：本方式要求 `opc-ontology-mcp` 已发布到 PyPI。发布前请先使用方式四（本地源码运行）。

### 方式二：uv tool 安装（需要全局命令时）

#### 发布后：从 PyPI 安装

```powershell
# 安装到 uv 工具环境，提供全局 opc-ontology-mcp 命令
uv tool install opc-ontology-mcp

# 运行
opc-ontology-mcp --ontology-dir D:/code/java/crm/git/OPC/gen_ontology
```

#### 发布前：从本地源码安装

```powershell
# 进入包含 pyproject.toml 的项目根目录
cd D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp

# 从当前目录安装本地项目
uv tool install .

# 运行
opc-ontology-mcp --ontology-dir D:/code/java/crm/git/OPC/gen_ontology
```

也可以直接使用绝对路径，避免受当前 shell 所在目录影响：

```powershell
uv tool install D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp
```

### 方式三：pip 安装

#### 发布后：从 PyPI 安装

```bash
pip install opc-ontology-mcp
opc-ontology-mcp --ontology-dir D:/code/java/crm/git/OPC/gen_ontology
```

#### 发布前：从本地源码安装

```powershell
# 进入包含 pyproject.toml 的项目根目录
cd D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp

# 从当前目录安装本地项目
pip install .

# 运行
opc-ontology-mcp --ontology-dir D:/code/java/crm/git/OPC/gen_ontology
```

也可以直接使用绝对路径：

```powershell
pip install D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp
```

### 方式四：本地源码运行（发布前的推荐方式）

```bash
git clone https://gitee.com/zhouxinhai/opc-ontology-mcp.git
cd opc-ontology-mcp
uv sync

# 本地运行
uv run opc-ontology-mcp --ontology-dir D:/code/java/crm/git/OPC/gen_ontology
```

### 安装方式对比

| 安装方式 | 命令 | 适用场景 | 后续升级 |
| -------- | ---- | -------- | -------- |
| uvx | `uvx opc-ontology-mcp` | 临时运行、MCP 客户端配置 | `@latest` / `==版本` / `--refresh` |
| uv tool | `opc-ontology-mcp` | 长期使用、全局命令 | `uv tool upgrade` |
| pip | `opc-ontology-mcp` | 无 uv 环境 | `pip install --upgrade` |
| 本地源码 | `uv run opc-ontology-mcp` | 二次开发、发布前验证 | `git pull` + `uv sync` |

> **注意**：uv tool 与 pip 二选一即可，不要同时安装。两者生成的命令同名，
> PATH 中哪个目录靠前就执行哪个，可能出现“刚升级却还是旧版”的问题。

> **路径规则**：`uv tool install .` 和 `pip install .` 中的路径按**当前 shell 的工作目录**解析，
> 不是相对 README.md 文件所在目录；路径必须指向包含 `pyproject.toml` 的项目根目录。
> 不确定当前目录时，优先使用上文的绝对路径写法。

## 升级

### uvx 方式

```bash
# 强制拉取最新版
uvx opc-ontology-mcp@latest --ontology-dir D:/code/java/crm/git/OPC/gen_ontology

# 固定版本（MCP 客户端长期配置推荐）
uvx opc-ontology-mcp==0.1.0 --ontology-dir D:/code/java/crm/git/OPC/gen_ontology

# 缓存异常时强制刷新
uvx --refresh opc-ontology-mcp --ontology-dir D:/code/java/crm/git/OPC/gen_ontology
```

### uv tool 方式

```powershell
uv tool upgrade opc-ontology-mcp
uv tool list   # 查看已安装版本
```

### pip 方式

```bash
pip install --upgrade opc-ontology-mcp
pip show opc-ontology-mcp   # 查看已安装版本
```

### 本地源码方式

```bash
git pull
uv sync
```

## 配置与启动

### 启动参数

| 参数 | 必填 | 说明 |
| ---- | ---- | ---- |
| `--ontology-dir` | 是 | `gen_ontology` 根目录或其下的 `ontology/` 目录。传入根目录时自动定位 `<dir>/ontology/`；直接传 `ontology/` 目录也兼容 |
| `--log-level` | 否 | 日志级别：`DEBUG` / `INFO` / `WARNING` / `ERROR`，默认 `INFO`。日志仅输出到 stderr，不会污染 stdio 协议 |

`--ontology-dir` 也可以通过环境变量 `OPC_ONTOLOGY_DIR` 指定；命令行参数优先于环境变量。

```bash
# 传入 gen_ontology 根目录（推荐）
uv run opc-ontology-mcp --ontology-dir D:/code/java/crm/git/OPC/gen_ontology

# 直接传入最终产物目录，同样支持
uv run opc-ontology-mcp --ontology-dir D:/code/java/crm/git/OPC/gen_ontology/ontology
```

### 数据加载范围

启动时一次性加载最终本体层，加载逻辑与 `opc-gen-ontology` 技能中的
`scripts/ontology_graph.html` 完全一致：

| 文件 | 内容 |
| ---- | ---- |
| `ontology/object_types/*.json` | 对象类型（表头信息、主键、分区/归档字段等） |
| `ontology/property_types/*.json` | 属性骨架（字段名、注释、角色、场景引用） |
| `ontology/link_types.json` | 关系边（from/to 表和字段、业务关系类型、业务子类型、置信度、证据来源） |
| `ontology/action_types.json` | 动作（场景、sqlId、DAO 方法、读写字段） |
| `ontology/ontology_manifest.json` | 全量索引（by_table / by_scenario / by_domain / by_concept） |

**不会读取** `raw/`、`intermediate/`、`progress.json`、`run_config.json` 等中间产物。
DDL 级字段详情不在本体内，需要时请配合 `opc-mcp` 的 `query_table_desc` 实时查询。

## MCP 客户端配置

stdio 模式由 MCP 客户端自动拉起并管理服务器进程，无需手动启动服务。

### Claude Code / WorkBuddy：uvx 方式（发布到 PyPI 后）

```json
{
  "mcpServers": {
    "opc-ontology-mcp": {
      "command": "uvx",
      "args": [
        "opc-ontology-mcp",
        "--ontology-dir", "D:/code/java/crm/git/OPC/gen_ontology"
      ]
    }
  }
}
```

### Claude Code / WorkBuddy：本地源码方式（发布前）

```json
{
  "mcpServers": {
    "opc-ontology-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp",
        "opc-ontology-mcp",
        "--ontology-dir", "D:/code/java/crm/git/OPC/gen_ontology"
      ]
    }
  }
}
```

> **提示**：JSON 配置中的 Windows 路径建议使用 `/` 分隔符，避免转义问题。

### Codex：uvx 方式（发布到 PyPI 后）

Codex 使用 TOML 配置，写入全局 `~/.codex/config.toml`，或项目下的
`.codex/config.toml`（例如 `D:/code/java/crm/git/OPC/.codex/config.toml`）：

```toml
[mcp_servers.opc-ontology-mcp]
command = "uvx"
args = [
  "opc-ontology-mcp",
  "--ontology-dir", "D:/code/java/crm/git/OPC/gen_ontology",
]
```

如果 Codex 启动 MCP 子进程时，`uvx` 也报“拒绝访问 / Failed to persist temporary
file / Failed to query Python interpreter”，原因与 `uv run` 类似：`uvx` 同样需要写
uv 缓存。建议显式设置 `UV_CACHE_DIR` 到可写目录，并固定版本：

```toml
[mcp_servers.opc-ontology-mcp]
command = "uvx"
args = [
  "opc-ontology-mcp==0.1.0",
  "--ontology-dir", "D:/code/java/crm/git/OPC/gen_ontology",
]

[mcp_servers.opc-ontology-mcp.env]
UV_CACHE_DIR = 'D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp/.uv-cache'
```

说明：

- `uvx` 首次运行需要访问包索引；运行成功后，后续可复用缓存。
- 固定 `==版本号` 可以减少每次启动时的版本解析变化。
- `UV_CACHE_DIR` 不建议指向只读目录或系统临时目录；放在项目或工作区下的稳定路径更可靠。
- 若仍需要排除 PATH 差异，可将 `command = "uvx"` 改为绝对路径的 `uvx.exe`。

也可以用命令添加；如需同时写入缓存目录环境变量，可加 `--env`：

```powershell
codex mcp add --env UV_CACHE_DIR=D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp/.uv-cache opc-ontology-mcp -- uvx opc-ontology-mcp==0.1.0 --ontology-dir D:/code/java/crm/git/OPC/gen_ontology
```

### Codex：本地源码方式（发布前）

推荐直接使用项目虚拟环境中已安装的启动命令，避免 Codex 启动 MCP 子进程时再次触发
`uv run` 的解释器检测和缓存写入：

```toml
[mcp_servers.opc-ontology-mcp]
command = 'D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp/.venv/Scripts/opc-ontology-mcp.exe'
args = [
  "--ontology-dir", "D:/code/java/crm/git/OPC/gen_ontology",
]
```

也可以继续使用 `uv run`：

```toml
[mcp_servers.opc-ontology-mcp]
command = "uv"
args = [
  "run",
  "--directory", "D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp",
  "opc-ontology-mcp",
  "--ontology-dir", "D:/code/java/crm/git/OPC/gen_ontology",
]
```

如果 Codex 启动 MCP 子进程时，`uv` 报“拒绝访问 / Failed to persist temporary file /
Failed to query Python interpreter”，建议使用绝对路径的 `uv.exe`，并通过
`--no-sync` 与 `UV_CACHE_DIR` 避免每次启动都写入默认缓存：

```toml
[mcp_servers.opc-ontology-mcp]
command = 'C:/Users/admin/AppData/Local/Programs/Python/Python313/Scripts/uv.exe'
args = [
  "run", "--no-sync",
  "--directory", "D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp",
  "opc-ontology-mcp",
  "--ontology-dir", "D:/code/java/crm/git/OPC/gen_ontology",
]

[mcp_servers.opc-ontology-mcp.env]
UV_CACHE_DIR = 'D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp/.uv-cache'
```

对应的添加命令：

```powershell
codex mcp add opc-ontology-mcp -- uv run --directory D:/code/java/crm/git/OPC_AI/OPC_MCP_SERVER/opc-ontology-mcp opc-ontology-mcp --ontology-dir D:/code/java/crm/git/OPC/gen_ontology
```

> **提示**：
>
> - Codex 的 stdio MCP 配置使用 `command` + `args`，不要写 `type = "http"` 和 `url`；
>   `type = "http"` / `url` 只适用于 HTTP MCP 服务。
> - TOML 中建议 Windows 路径使用 `/` 分隔符；如果使用反斜杠，应使用单引号字面量字符串，
>   例如 `command = 'D:\path\to\program.exe'`。
> - 修改配置后，需要重启 Codex 会话或按客户端提示重新加载 MCP 服务。

## 工具说明

所有查询工具均为只读；除 `reload_ontology` 外都标记了 `readOnlyHint`。
表名、场景 ID、概念、域的匹配均为大小写不敏感。

### get_ontology_overview

获取本体整体概览。

| 参数 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| 无 | - | - | - |

```json
{
  "status": "ok",
  "version": "v1.2",
  "object_count": 345,
  "property_count": 6008,
  "link_count": 1179,
  "link_by_confidence": { "high": 115, "low": 940, "medium": 124 },
  "link_by_source": { "column_naming": 940, "code_semantic": 2, "doc_semantic": 113, "sql_join": 124 },
  "link_by_relation": { "belongs_to": 45, "contains": 2, "maps_to": 1, "produces": 1, "references": 1130 },
  "link_by_relation_subtype": { "cust_order_contains_order_line": 1, "operation_produces_feedback": 1 },
  "action_by_kind": { "crud": 972, "semantic": 423 },
  "table_types": { "工单表": 46, "流水表": 26, "资料表": 96 },
  "scenario_count": 61
}
```

### search_ontology

按关键词搜索实体（表名/中文名）、概念、业务场景（ID/名称）、信息模块（域）、业务关系类型、业务关系子类型。

| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ---- | ---- | ---- | ---- |
| query | string | 是 | - | 搜索关键词 |
| limit | integer | 否 | 20 | 返回匹配数量上限（1-200） |

```json
{
  "status": "ok",
  "query": "订单",
  "matches": [
    { "kind": "concept", "key": "订单", "description": "12 张表" },
    { "kind": "scenario", "key": "ORDER_ACCEPT", "description": "订单受理" },
    { "kind": "relation", "key": "belongs_to", "description": "关系语义类型" },
    { "kind": "relation_subtype", "key": "order_item_belongs_to_cust_order", "description": "业务关系子类型" },
    { "kind": "entity", "key": "OR_CUST_ORDER", "description": "客户订单" }
  ]
}
```

### get_entity

获取单张表的完整推理上下文：对象头信息、字段、双向关系、动作。

| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ---- | ---- | ---- | ---- |
| table_name | string | 是 | - | 表名，大小写不敏感 |
| include_properties | boolean | 否 | true | 是否返回字段详情 |
| include_links | boolean | 否 | true | 是否返回双向关系 |
| include_actions | boolean | 否 | true | 是否返回动作详情 |

```json
{
  "status": "ok",
  "entity": {
    "table_name": "OR_OPERATION",
    "display_name": "工单",
    "table_type": "工单表",
    "domains": ["未知"],
    "primary_key": ["OPERATION_ID", "REGION_CODE"],
    "property_count": 49,
    "link_count": 14,
    "action_count": 9
  },
  "properties": [
    { "name": "OPERATION_ID", "comment": "工单标识", "roles": ["pk"], "scenario_refs": ["OPERATION_EXECUTE"] }
  ],
  "links": [
    { "id": "LNK-0020", "from_table": "OR_OPERATION", "from_column": "ORDER_ID",
      "to_table": "OR_CUST_ORDER", "to_column": "ORDER_ID",
      "relation": "belongs_to", "relation_subtype": "operation_belongs_to_order",
      "confidence": "high", "source": "doc_semantic", "direction": "out" }
  ],
  "actions": [
    { "id": "ACT-OR_OPERATION-OPERATION_EXECUTE", "scenario_id": "OPERATION_EXECUTE",
      "operation_types": ["INSERT", "UPDATE"], "sql_ids": ["10510327"],
      "dao_methods": ["insertOperation"], "read_fields": ["ORDER_ID"],
      "write_fields": ["STATUS"] }
  ]
}
```

### get_entity_relations

从指定表出发做 BFS 关系扩展，返回邻居节点与边。

| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ---- | ---- | ---- | ---- |
| table_name | string | 是 | - | 中心表名，大小写不敏感 |
| depth | integer | 否 | 2 | BFS 扩展深度（1-99） |
| direction | string | 否 | both | `out` 出边 / `in` 入边 / `both` 双向 |
| confidence | string[] | 否 | null | 置信度过滤：`high` / `medium` / `low` |
| source | string[] | 否 | null | 证据来源过滤：`physical_fk` / `sql_join` / `code_semantic` / `doc_semantic` / `column_naming` |
| relation | string[] | 否 | null | 业务关系类型过滤：`belongs_to` / `references` / `contains` / `produces` / `maps_to` / `parallel_of` / `history_of` |
| relation_subtype | string[] | 否 | null | 业务关系子类型过滤；可用值见 `get_ontology_overview` 的 `link_by_relation_subtype` |
| max_nodes | integer | 否 | 40 | 节点数量上限（含中心表，1-9999） |

```json
{
  "status": "ok",
  "center": "OR_OPERATION",
  "depth": 2,
  "direction": "both",
  "node_count": 18,
  "edge_count": 14,
  "truncated": false,
  "nodes": [
    { "table_name": "OR_OPERATION", "display_name": "工单", "depth": 0 },
    { "table_name": "OR_CUST_ORDER", "display_name": "客户订单", "depth": 1 }
  ],
  "edges": [
    { "id": "LNK-0020", "from_table": "OR_OPERATION", "to_table": "OR_CUST_ORDER",
      "relation": "belongs_to", "relation_subtype": "operation_belongs_to_order",
      "confidence": "high", "source": "doc_semantic" }
  ]
}
```

### get_scenario

按业务场景 ID（大小写不敏感）或场景名称查询涉及表及动作摘要。

| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ---- | ---- | ---- | ---- |
| scenario | string | 是 | - | 场景 ID 或场景名称 |
| limit | integer | 否 | 100 | 返回表数量上限（1-1000） |

```json
{
  "status": "ok",
  "scenario_id": "ORDER_ACCEPT",
  "scenario_name": "订单受理",
  "table_count": 3,
  "tables": [
    {
      "table_name": "OR_TEST_ORDER",
      "display_name": "测试订单",
      "actions": [
        {
          "scenario_id": "ORDER_ACCEPT",
          "operation_types": ["INSERT", "SELECT"],
          "sql_ids": ["900001", "900002"],
          "dao_methods": ["insertOrder"],
          "write_fields": ["CUST_ID", "STATUS"]
        }
      ]
    }
  ]
}
```

### get_concept_tables

按业务概念查询相关表清单。

| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ---- | ---- | ---- | ---- |
| concept | string | 是 | - | 业务概念名称 |
| limit | integer | 否 | 100 | 返回表数量上限（1-1000） |

```json
{
  "status": "ok",
  "concept": "订单",
  "table_count": 2,
  "tables": [
    { "table_name": "OR_TEST_ORDER", "display_name": "测试订单", "table_type": "工单表" }
  ]
}
```

### get_domain_tables

按信息模块（域）查询相关表清单。

| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ---- | ---- | ---- | ---- |
| domain | string | 是 | - | 信息模块（域）名称 |
| limit | integer | 否 | 100 | 返回表数量上限（1-1000） |

```json
{
  "status": "ok",
  "domain": "订单域",
  "table_count": 2,
  "tables": [
    { "table_name": "OR_TEST_ORDER", "display_name": "测试订单" }
  ]
}
```

### find_relation_path

推理两张表之间的关系路径：在过滤后的关系图上查找最短路径（可返回多条）。

| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ---- | ---- | ---- | ---- |
| from_table | string | 是 | - | 起始表名，大小写不敏感 |
| to_table | string | 是 | - | 目标表名，大小写不敏感 |
| max_depth | integer | 否 | 4 | 最大路径长度（1-8 跳） |
| max_paths | integer | 否 | 3 | 最多返回路径数（1-10） |
| confidence | string[] | 否 | null | 置信度过滤 |
| source | string[] | 否 | null | 证据来源过滤 |
| relation | string[] | 否 | null | 业务关系类型过滤 |
| relation_subtype | string[] | 否 | null | 业务关系子类型过滤；可用值见 `get_ontology_overview` |

```json
{
  "status": "ok",
  "from_table": "OR_TEST_ORDER_ITEM",
  "to_table": "OR_TEST_CUSTOMER",
  "path_count": 1,
  "paths": [
    {
      "length": 2,
      "nodes": [
        { "table_name": "OR_TEST_ORDER_ITEM" },
        { "table_name": "OR_TEST_ORDER" },
        { "table_name": "OR_TEST_CUSTOMER" }
      ],
      "edges": [
        { "id": "LNK-0001", "from_table": "OR_TEST_ORDER_ITEM", "to_table": "OR_TEST_ORDER",
          "relation": "belongs_to", "relation_subtype": "order_item_belongs_to_cust_order",
          "confidence": "high", "source": "doc_semantic", "traversal": "out" },
        { "id": "LNK-0002", "from_table": "OR_TEST_ORDER", "to_table": "OR_TEST_CUSTOMER",
          "relation": "references", "relation_subtype": "cust_order_references_customer",
          "confidence": "medium", "source": "sql_join", "traversal": "out" }
      ]
    }
  ]
}
```

### search_fields

跨表检索字段：字段名（大小写不敏感）或注释包含关键词，可按表与角色过滤。

| 参数 | 类型 | 必填 | 默认 | 说明 |
| ---- | ---- | ---- | ---- | ---- |
| keyword | string | 是 | - | 字段名或注释关键词 |
| table_name | string | 否 | null | 限定表名，大小写不敏感 |
| role | string | 否 | null | 限定字段角色，如 `pk` / `status` / `order_id` / `dict` |
| limit | integer | 否 | 50 | 返回结果数量上限（1-500） |

```json
{
  "status": "ok",
  "query": "cust",
  "count": 3,
  "fields": [
    { "table_name": "OR_TEST_ORDER", "field": "CUST_ID", "comment": "客户标识", "roles": ["fk"] }
  ]
}
```

### reload_ontology

本体文件重新生成后，从原目录热重载；失败时保留旧数据并返回错误信息。

| 参数 | 类型 | 必填 | 说明 |
| ---- | ---- | ---- | ---- |
| 无 | - | - | - |

```json
{
  "status": "ok",
  "reloaded": true,
  "version": "v1.2",
  "object_count": 345,
  "property_count": 6008,
  "link_count": 1176,
  "action_count": 1395
}
```

## 常见问题

### Q1：启动报“未能在以下位置找到本体最终产物”

检查 `--ontology-dir` 是否指向 `gen_ontology` 根目录或其下的 `ontology/` 目录。
目录中必须同时存在 `ontology_manifest.json` 和 `object_types/` 子目录。
若本体尚未生成，请先运行 `opc-gen-ontology` 技能。

### Q2：本体重新生成后如何刷新数据？

优先调用 `reload_ontology` 工具，无需重启 MCP 客户端；
也可以重启 MCP 客户端让服务器进程随配置重新拉起。热重载失败时会保留旧数据，修正文件后再试。

### Q3：启动报“JSON 解析失败”

按报错中的文件路径检查对应 JSON 是否完整。本体文件由脚本确定性渲染，
不要手工编辑；重新运行 `opc-gen-ontology` 即可恢复。

### Q4：uvx 提示找不到包？

`opc-ontology-mcp` 尚未发布到 PyPI 时，uvx / pip / uv tool 方式不可用。
请先使用本地源码方式：`uv sync` 后 `uv run opc-ontology-mcp ...`。

## 项目结构

```text
opc-ontology-mcp/
├── src/opc_ontology_mcp/
│   ├── main.py        # 入口：参数解析、stdio 保护、启动加载
│   ├── store.py       # 本体加载、路径识别、内存索引、热重载
│   ├── queries.py     # 纯查询函数（概览/搜索/实体/关系/场景/路径/字段）
│   ├── register.py    # FastMCP 工具注册（10 个工具）
│   └── __init__.py
├── tests/             # pytest 单元测试 + stdio 集成测试 + 固定样本
├── pyproject.toml     # 项目配置（uv + setuptools）
├── uv.lock            # 依赖锁定
└── README.md          # 安装与使用手册
```

## 版本历史

| 版本 | 变更 |
| ---- | ---- |
| 0.1.0 | 初始版本：10 个查询工具、stdio 传输、路径自动识别、热重载 |

## 发布到 PyPI（维护者）

```bash
# 1. 构建
uv build

# 2. 上传（需要 PyPI 账号和 token）
uv run twine upload dist/*
```

发布后，uvx / pip / uv tool 安装方式即可使用；发布前请使用本地源码方式运行。

## License

MIT
