kangminlee-maker/onto-mcp
GitHub: kangminlee-maker/onto-mcp
该项目是一个 MCP 原生的本体工具，帮助 LLM 审查各类产物的逻辑一致性并从真实来源推导结构化的领域本体。
Stars: 0 | Forks: 0
# 进入 MCP
[](https://www.npmjs.com/package/onto-mcp)
MCP 原生的本体（ontology）工具，帮助 LLM **审查产物的本体完整性** —— 即其概念、权威性和目的的逻辑一致性 —— 并从真实来源中**推导本体**，通过 runtime 校验门控确保每一个结构化声明都有据可查。
```
.onto contracts and domain documents
-> TS review/reconstruct runtime
-> core API facade
-> MCP tools
-> provider adapters
```
其公共接口是 MCP 原生的：只需安装一次该 server，将其注册到你的 MCP host 中，然后通过工具来驱动它。目标不一定要是代码 —— runtime 契约会在选择观察、校验或 adapter 行为之前，对材料形态进行分类（`code`、`spreadsheet`、`document`、`database`、`mixed` 或 `unknown`）。
## 你可以用它做什么
将 LLM host 指向该 server，并通过工具驱动它来：
- **审查产物的本体完整性** —— 检查其*概念、权威性和目的*是否保持逻辑一致（定义、权威席位和既定目标是否一致？）。产物可以采取任何形式 —— 代码、电子表格、文档、数据库或混合包；形态只是读取本体的层。独立的视角、可控的审议和保守的综合；发现的问题将以*实质性材料问题*的形式呈现。 → `onto_review`
- **从真实来源推导领域本体** —— 从实际的代码库 / 电子表格 / 文档中重建一个有边界的、经过校验的本体种子，并将其优化直至具有可操作性。 → `onto_reconstruct`
**适用场景** 当你的目标是*检查某个产物在概念上是否自洽* —— 即其概念、权威性和目的的逻辑 / 本体完整性 —— 或者是*从真实来源中推导出结构化的领域本体*，并且你希望每一个结构化声明都由 runtime 校验门控负责（显式失败，而非尽力而为）。代码在此范围内，因为代码只有在逻辑一致时才能正常工作。
**不适用场景** linting/格式化、运行测试、一次性聊天摘要、自由生成，或者针对操作 / runtime bug（边缘情况、崩溃、性能）的对抗性挖掘 —— 后者由一个单独的对抗性多视角工具来补充。
| 如果你的目标是… | 使用 |
|---|---|
| 检查产物的概念 / 权威性 / 目的一致性（任何形式：代码、电子表格、文档、DB） | `onto_review`（然后使用 `onto_review_read` 获取结果） |
| 从真实来源推导 / 重建领域本体 | `onto_reconstruct`（然后使用 `onto_reconstruct_read`） |
| 发现可用的视角、领域或源配置文件 | `onto_list` |
## 快速开始
```
npm install -g onto-mcp
onto register # interactive: pick detected MCP hosts
```
`npm install` 只会将 `onto` 二进制文件放在 PATH 中 —— 每个 MCP host（Claude Code, Codex, Claude Desktop, Cursor）都必须额外被告知去启动它。`onto register` 一步即可完成此操作；同一个全局二进制文件由每个 host 共享。注册后请重启 host 应用程序。
```
onto register --all --yes # non-interactive: every detected host
onto register --hosts cursor,codex --yes
onto register --list # show detection status, write nothing
onto register --hosts cursor --dry-run # preview the change, write nothing
```
| Host | 注册方式 |
|---|---|
| Claude Code | `claude mcp add onto -s user -- onto mcp`（user 作用域 = 所有项目） |
| Codex CLI | `codex mcp add onto -- onto mcp` |
| Claude Desktop | 在 `claude_desktop_config.json` 中编辑 `mcpServers.onto` |
| Cursor | 在 `~/.cursor/mcp.json` 中编辑 `mcpServers.onto` |
对于基于 CLI 的 host，`onto register` 会优先使用官方 CLI，如果不在 PATH 中，则回退到打印手动说明。它会在 `mcp add` 之后验证结果，如果 CLI 成功退出但随后未列出 server，则会报告 `failed`（而不是虚假的 `registered`）。JSON 编辑会保留任何已存在的 server，并且是幂等的。注册仅写入 host 拥有的配置；它从不写入 onto 运行时数据。使用 `--command ` / `--name ` 覆盖启动的命令或 server 名称。
**Claude Code 配置文件。** Claude Code 按配置目录（`CLAUDE_CONFIG_DIR`）存储 MCP server。要在一条命令中注册每个配置文件，请让 `onto` 发现它们 —— 它会扫描 `~/.claude` 和 `~/.claude-*` 以查找真实的配置目录（那些包含 `settings.json`、`.credentials.json`、`.claude.json` 或 `projects/` 的目录）以及任何环境的 `CLAUDE_CONFIG_DIR`，并逐一注册：
```
onto register --hosts claude-code --all-claude-profiles --yes # every profile
onto register --all --all-claude-profiles --yes # profiles + other hosts
onto register --all-claude-profiles --list # preview discovered profiles
```
如果要单独针对某个配置文件，请明确指定其名称（与 `--all-claude-profiles` 互斥）：
```
onto register --hosts claude-code --claude-config-dir ~/.claude-1 --yes
```
对于项目本地安装：
```
npm install --save-dev onto-mcp
npm exec -- onto mcp
```
在运行审查之前，请在 `.onto/settings.json` 或 `~/.onto/settings.json` 中配置 LLM provider（参见[配置](#configuration))。
## onto CLI
`onto` 二进制文件公开了一小组命令；实际的产品工作由你的 host 通过 MCP 工具驱动。
| 命令 | 作用 |
|---|---|
| `onto mcp` | 启动 MCP stdio 工具 server —— 每个 MCP host 都会启动它（参见[快速开始](#quickstart)) |
| `onto register` | 将 server 注册到受支持的 MCP host 中（参见[快速开始](#quickstart)) |
| `onto configure-provider` | 将 LLM provider/model 设置写入 settings.json 链中（参见[配置](#configuration)) |
| `onto seats` | 打印 runtime 可以分发的每个 LLM model seat 的只读清单，根据 settings.json 链进行解析（使用 `--json` 进行机器输出）；不写入任何内容 |
| `onto watch [session]` | 在审查 / 重建会话上打开实时的、只读的 TUI —— 传递会话 id 子字符串或路径，或者省略它以查看最近的一次（参见[观察运行](#observing-a-run)) |
## 它的作用
### 审查
`onto_review` 对目标运行结构化的多视角审查：
1. 调用解释与绑定
2. 执行准备产物
3. 隔离的并行视角执行（上下文隔离的视角）
4. 问题台账和问题立场关闭产物
5. 可控的视角审议
6. 保守综合
7. `ReviewRecord` 组装
8. 简明的人类可读最终输出
两种编排模式共享同一个 runtime：默认的 runtime 编排路径（`onto_review` 驱动一切），以及 host 编排路径（MCP host 一轮一轮地自行执行单元（`onto_review_round` / `onto_review_advance`）），同时 onto 保留产物真值、校验和门控。
审查会话会将产物写入 `.onto/review//` 下：
| 产物 | 用途 |
|---|---|
| `execution-plan.yaml` | 有边界的 runtime 计划 |
| `issue-ledger.yaml` | 规范化的问题列表 |
| `issue-stance-matrix.yaml` | 每个参与视角对每个问题的立场 |
| `deliberation.md` | teamlead 控制的审议结果 |
| `problem-framing.yaml` | 审查结束时的问题分类 |
| `review-run-manifest.yaml` | packet/output 引用和哈希值 |
| `review-record.yaml` | 主要的结构化审查产物 |
| `final-output.md` | 面向主体的报告，包含 `Final Review Result` 解释 |
### 重建
`onto_reconstruct` 从真实来源推导出有边界的本体种子并使其成熟：对目标材料进行分类，在安全和血缘门控之后观察来源，编写并校验 `ontology-seed.yaml`，然后迭代成熟循环（问题边界 → 答案支持 → 本体扩展 → 收敛），直到结果变为 `actionable_ready`、`actionable_limited` 或被明确阻塞。每个结构化声明都由 runtime 校验门控负责；当 provider 凭证、LLM 编写的产物格式、不支持的材料或 runtime 门控无效时，运行会显式失败。
最小的 MCP 调用形式：
```
{
"name": "onto_reconstruct",
"arguments": {
"projectRoot": "/path/to/project",
"targetRefs": ["src/example.ts"],
"intent": "Create a bounded reconstruct Seed from this target.",
"domain": "ontology",
"sessionRoot": ".onto/reconstruct/example-run"
}
}
```
产物和门控目录的权威性来源是机器可读的 [reconstruct 契约注册表](https://github.com/kangminlee-maker/onto-mcp/blob/main/.onto/processes/reconstruct/reconstruct-contract-registry.yaml)；语义和基本原理位于 [`.onto/processes/reconstruct/`](https://github.com/kangminlee-maker/onto-mcp/tree/main/.onto/processes/reconstruct) 下的叙述性契约中。一个可读的时间点映射（v0.4.7 快照，不维护）保存在 [development-records/design/reconstruct-runtime-reference-v0.4.7-snapshot.md](https://github.com/kangminlee-maker/onto-mcp/blob/main/development-records/design/reconstruct-runtime-reference-v0.4.7-snapshot.md) 中。
## MCP 工具
| 工具 | 用途 |
|---|---|
| `onto_review` | 运行完整的审查路径并返回产物引用及摘要 |
| `onto_prepare_review` | 准备审查会话和 prompt packet |
| `onto_review_continue` | 从台账边界继续准备好的或已暂停的审查 |
| `onto_review_round` | Host 编排：返回现在准备执行的单元，并实例化 prompt packet |
| `onto_review_advance` | Host 编排：报告 host 执行的单元；onto 校验 seat、记录结果并返回下一轮 |
| `onto_review_cancel` | 请求取消正在运行的审查会话 |
| `onto_review_read` | 读取审查会话 —— 运行时查看实时性的唯一入口，以及完成后获取有边界结果的入口；`projectionLevel` `compact`/`standard`/`full`（`full` 添加 `review-record.yaml` 和最终输出） |
| `onto_list` | 按 `kind` 列出注册表：`lenses`（规范视角集）、`domains`（可用的领域 ID）或 `source_profiles`（重建源配置文件） |
| `onto_observe_source` | 实例化重建材料配置文件、清单、来源观察记录和初始记录 |
| `onto_validate_reconstruct_directive` | 校验 LLM 编写的重建产物 |
| `onto_reconstruct` | 通过 runtime 校验门控运行具有材料感知能力的直接调用重建路径 |
| `onto_reconstruct_read` | 读取重建会话 —— 阶段进度、实时性和计数，或在 `projectionLevel=full` 时读取完整记录、运行 manifest 和最终输出 |
MCP 结果包含 `llmPresentation` prompt：runtime 提供有边界的事实，host LLM 使用这些 prompt 来解释开篇简报和最终结果，而无需捏造设置或发现。
### 工具调用 schema
每个工具完整的、权威的输入 schema 都会在 runtime 通过 MCP `tools/list`（JSON Schema）提供给你的 host，并定义在 [`src/mcp/tool-schemas.ts`](https://github.com/kangminlee-maker/onto-mcp/blob/main/src/mcp/tool-schemas.ts) 中。
两个主要入口点：
**`onto_review`** —— 必需的 `target`（审查什么）和 `intent`（为什么审查）；常见的可选项：`reviewMode`（`core-axis` | `full`）、`domain`（或 `noDomain: true`）、`targetScopeKind`（`file` | `directory` | `bundle`）、`diffRange`、`projectRoot`、`prepareOnly`、`returnRunningAfterMs`、`llmOverride`。
```
{
"name": "onto_review",
"arguments": {
"target": "src/payments/",
"intent": "Review the refund path for material correctness and safety issues.",
"reviewMode": "full",
"projectRoot": "/path/to/project"
}
}
```
**`onto_reconstruct`** —— 必需的 `projectRoot`、`targetRefs`、`intent`；常见的可选项：`domain`、`sessionRoot`、`resumeMode`（`fresh` | `reuse_existing_authored_artifacts`）、`judgeModel`、`judgeLlmEffort`、`llmOverride`（参见上面的 [重建](#reconstruct) 示例）。
**读取结果** —— `onto_review_read` / `onto_reconstruct_read` 接受 `projectionLevel`（`compact` | `standard` | `full`）；在 token 受限的 host 中使用 `compact`，使用 `full` 以包含记录和最终输出。
**单次调用的 LLM 覆盖（`llmOverride`）** —— `onto_review` 和 `onto_reconstruct` 接受一个可选的 `llmOverride`，它会**仅针对该次调用**覆盖设置解析出的 LLM（设置不变，默认关闭）。字段是设置 `llm` 块的子集 —— `{ provider?, auth?, model?, effort?, service_tier? }` —— 只有你设置的字段会被覆盖。设置 `provider` 需要明确的 `model`。支持的 model id 编写在 [`.onto/authority/supported-models.yaml`](https://github.com/kangminlee-maker/onto-mcp/blob/main/.onto/authority/supported-models.yaml) 中。
```
{
"name": "onto_review",
"arguments": {
"target": "src/example.ts",
"intent": "Second-opinion review with a stronger model.",
"llmOverride": { "model": "gpt-5.6-sol", "effort": "high" }
}
}
```
### 自文档化
该 server 会公布 MCP `resources` 和 `prompts`，以便 host LLM 无需外部文档即可了解 onto：
- **Resource `onto://usage`** —— provider 设置、审查和重建工作流、运行句柄轮询模式以及输出大小指导。
- **Prompts** —— 规范的任务模板 `review_target`（参数：`target`、`intent`、`reviewMode`）和 `reconstruct_seed`（参数：`targetRefs`、`intent`）。
`onto_review_read` 接受 `projectionLevel`（`compact` |standard` | `full`）；在 token 受限的 host 中使用 `compact`。
### 观察运行
`onto watch` 在审查或重建会话上打开一个实时的、只读的 TUI：浏览工作流树、节点详细信息和日志。传递会话 id 子字符串或会话路径，或者省略它以附加到最近的会话（`--project-root` 选择在哪里查找 `.onto/{review,reconstruct}`）。它仅用于观察 —— 不写入任何内容，也不驱动任何内容。
runtime 还会写入会话本地的 `runtime-events.ndjson` 流，并尝试在受支持的终端（tmux、Warp、Cursor、iTerm2、Apple Terminal、Codex Desktop（配置了启动器的情况下））中自动打开观察者。设置 `ONTO_RUNTIME_WATCHER=0` 以禁用，或者设置 `ONTO_RUNTIME_WATCHER_COMMAND` 并提供用于不受支持 host 的 `{watcherCommand}` 模板。
## 配置
runtime 设置存在于 `settings.json` 中（JSON 格式；接受 `#` 注释）：
| 路径 | 作用 |
|---|---|
| `{project}/.onto/settings.json` | 项目本地设置 |
| `~/.onto/settings.json` | 用户默认设置 |
对于标量键，项目设置会覆盖用户默认设置。在 `settings.json/v3` 中，actor `llm` 块是完整的 model 设置；它们不会从根 `llm.default` 继承。
最小的 Codex OAuth 配置文件：
```
{
# v3 puts model settings inside each actor.
"schema_version": "settings.json/v3",
"review": {
"mode": "full",
"execution": {
"executor": "auto",
"topology": "main-workers",
"actors": {
"teamlead": {
"seat": "main",
"llm": {
"auth": "oauth",
"provider": "openai",
"model": "gpt-5.5",
"effort": "medium",
"service_tier": "fast"
}
},
"lens": {
"seat": "worker",
"llm": {
"auth": "oauth",
"provider": "openai",
"model": "gpt-5.5",
"effort": "medium",
"service_tier": "fast"
}
},
"synthesize": {
"seat": "worker",
"llm": {
"auth": "oauth",
"provider": "openai",
"model": "gpt-5.5",
"effort": "xhigh",
"service_tier": "fast"
}
}
},
"deliberation": "controlled-lens-deliberation"
}
},
"reconstruct": {
"execution": {
"actors": {
"semantic_author": {
"llm": {
"auth": "oauth",
"provider": "openai",
"model": "gpt-5.5",
"effort": "high",
"service_tier": "fast"
}
},
"confirmation_provider": {
"llm": {
"auth": "oauth",
"provider": "openai",
"model": "gpt-5.5",
"effort": "medium",
"service_tier": "fast"
}
}
}
}
}
}
```
LLM 切换器轴线：
| auth | provider | runtime 路径 |
|---|---|---|
| `oauth` | `openai` | Codex worker（订阅） |
| `oauth` | `anthropic` | Claude Code worker（订阅） |
| `api_key` | `openai` | OpenAI API |
| `api_key` | `anthropic` | Anthropic API |
| `api_key` | `grok` | xAI/Grok OpenAI 风格的 API |
| `local` | `lmstudio` | LM Studio OpenAI 风格的 endpoint |
不支持的设置会在配置文件解析期间停止。
### provider·model 切换（推荐：`onto configure-provider`）
`settings.json`을 손으로 고치는 대신 `onto configure-provider`가 actor LLM 블록을
라우트 검증 후 기록합니다(units 등 다른 설정은 보존). 라우팅 불가능한 조합은 기록
전에 fail-loud 합니다.
```
# Codex (OpenAI) OAuth
onto configure-provider --provider openai --model gpt-5.5 --auth oauth \
--effort medium --service-tier fast
# Claude Code (Anthropic) OAuth
onto configure-provider --provider anthropic --model claude-opus-4-8 --auth oauth \
--effort high
```
- `--service-tier`는 `openai`+`oauth`(Codex) 경로 전용입니다 — anthropic에 주면
profile 해석 단계에서 거부됩니다.
- `--auth`를 주면 reconstruct actor 블록(`semantic_author`/`confirmation_provider`)도
함께 기록합니다. 생략하면 review actor만 기록하고 loader가 provider 기본 auth를 파생합니다.
- `--timeout-ms `는 각 actor `llm` 블록에 per-actor `timeout_ms`(양의 정수)를
함께 기록합니다 — codex/claude direct-call worker 호출 타임아웃(아래 [타임아웃](#타임아웃)
참고). api_key SDK 경로에는 적용되지 않습니다.
- `--project`는 프로젝트 seat(`.onto/settings.json`)에, 생략하면 사용자 seat
(`~/.onto/settings.json`)에 기록합니다.
- 지원 model id는 [`.onto/authority/supported-models.yaml`](.onto/authority/supported-models.yaml)가
authority입니다. 범용 seat은 `gpt-5.5`(openai)·`claude-opus-4-8`(anthropic)이고,
역할 전용으로 `review`에 `gpt-5.6-sol`·`claude-fable-5`, `semantic_map_synthesize`에
`gpt-5.6-luna`·`claude-sonnet-5`가 인증돼 있습니다. 현재 프로젝트에서 실제로
해석되는 seat은 `onto seats`로 확인하세요.
- 이 명령은 actor 블록만 기록합니다. `units[].llm.model`로 unit별 model을 고정해
두었다면(위 정적 프로필 예시가 그렇습니다) 같은 model로 바꾸거나 그 `model` 키를
지워 actor 값을 상속하게 하세요.
### 超时
| 경로 | 기본값 | 조절 knob (우선순위) |
|---|---|---|
| review unit worker (codex/claude) | 240s (짧은 응답 단계 180s, `issue_stance_matrix` 120s) | `units[].timeout_ms` |
| direct-call CLI worker (codex/claude) — reconstruct·inline review | 600s | actor `llm.timeout_ms` → 없으면 `ONTO_LLM_TIMEOUT_MS` |
| SDK direct call (`api_key`) | 120s | `ONTO_LLM_TIMEOUT_MS` (ms) |
`llm.timeout_ms`(ms)는 actor `llm` 블록에 넣는 per-actor 값으로, codex/claude CLI worker
경로(reconstruct의 `semantic_author`/`confirmation_provider`, inline review actor)의 호출
타임아웃을 그 값으로 고정합니다. 없으면 env `ONTO_LLM_TIMEOUT_MS`, 그것도 없으면 기본값을
씁니다(api_key SDK 경로에는 적용되지 않고 `ONTO_LLM_TIMEOUT_MS`만 반영). 이 knob은 review의
`units[].timeout_ms`(worker 프로세스 bound)와 구분되는 별개 계층입니다.
`ONTO_LLM_TIMEOUT_MS`(ms)는 direct-call/CLI-worker와 SDK 경로 기본값을 전역으로 덮어씁니다.
opus 같은 프론티어 모델의 긴 단일-turn authoring도 600s worker 기본값으로 완료되므로 지원
모델에는 override가 필요 없습니다. 특정 review unit이 오래 걸리면 그 unit의
`units[].timeout_ms`만 키우면 됩니다(모든 unit에 큰 값을 박을 필요 없음).
## 文档
| 文档 | 内容 |
|---|---|
| [reconstruct 契约注册表](https://github.com/kangminlee-maker/onto-mcp/blob/main/.onto/processes/reconstruct/reconstruct-contract-registry.yaml) | 活跃的重建产物/门控权威图（附带叙述性契约） |
| [docs/development.md](https://github.com/kangminlee-maker/onto-mcp/blob/main/docs/development.md) | 验证工具和开发工作流 |
| [docs/architecture/repo-layout.md](https://github.com/kangminlee-maker/onto-mcp/blob/main/docs/architecture/repo-layout.md) | 仓库布局 SSOT：文件夹角色和放置规则 |
| [docs/architecture/](https://github.com/kangminlee-maker/onto-mcp/tree/main/docs/architecture) | 架构说明 |
标签：DLL 劫持, MCP, TypeScript, 人工智能工具, 代码质量审查, 大语言模型, 安全插件, 暗色界面, 本体论, 自动化攻击