跳转到内容
OntoSkills

MCP 运行时

OntoMCP 是 OntoSkills 的运行时层。它从托管本地主目录加载已编译的本体，并通过 stdio 上的模型上下文协议暴露它们。

安装

Terminal window
npx ontoskills install mcp
npx ontoskills install mcp --claude
npx ontoskills install mcp --cursor --project

这将在以下位置安装运行时二进制文件：

~/.ontoskills/bin/ontomcp

有关一条命令客户端引导，请参见 MCP 引导。

OntoMCP 加载什么

主要来源：

~/.ontoskills/ontologies/system/index.enabled.ttl

回退（按顺序）：

  1. ~/.ontoskills/ontologies/index.ttl
  2. 当前目录的 index.ttl
  3. */ontoskill.ttl 模式

覆盖本体根目录：

Terminal window
# 环境变量
ONTOMCP_ONTOLOGY_ROOT=~/.ontoskills/ontologies


# 或命令行标志
~/.ontoskills/bin/ontomcp --ontology-root ~/.ontoskills/ontologies

工具参考

OntoMCP 暴露 5 个工具 用于技能发现和推理。

search_skills

使用可选过滤器发现技能。

{
  "intent": "create_pdf",
  "requires_state": "oc:DocumentCreated",
  "yields_state": "oc:PdfGenerated",
  "skill_type": "executable",
  "limit": 25
}
参数类型描述
intentstring按已解决的意图过滤
requires_statestring按所需状态过滤（URI 或 oc:StateName）
yields_statestring按产出状态过滤（URI 或 oc:StateName）
skill_typestringexecutable 或 declarative
limitinteger最大结果数（1-100，默认 25）

示例响应：

{
  "skills": [
    {
      "id": "pdf",
      "qualified_id": "mareasw/office/pdf",
      "nature": "创建 PDF 文档的技能",
      "intents": ["create_pdf", "export_pdf"],
      "requires_state": ["oc:ContentReady"],
      "yields_state": ["oc:PdfGenerated"]
    }
  ],
  "total": 1
}

search_intents

搜索与自然语言查询语义匹配的意图。需要先导出嵌入。

{
  "query": "创建 pdf 文档",
  "top_k": 5
}
参数类型描述
querystring必需。 自然语言查询
top_kinteger返回结果数（默认 5）

示例响应：

{
  "query": "创建 pdf 文档",
  "matches": [
    {
      "intent": "create_pdf",
      "score": 0.92,
      "skills": ["mareasw/office/pdf", "mareasw/documents/pdf-generator"]
    }
  ]
}

注意： 需要先运行 ontoskills export-embeddings。如果嵌入不可用，工具会返回错误。

get_skill_context

获取技能的完整执行上下文，包括需求、转换、负载、依赖和知识节点。

{
  "skill_id": "pdf",
  "include_inherited_knowledge": true
}
参数类型描述
skill_idstring必需。 短 id（pdf）或限定 id（mareasw/office/pdf）
include_inherited_knowledgeboolean包含扩展技能的知识（默认 true）

示例响应：

{
  "id": "pdf",
  "qualified_id": "mareasw/office/pdf",
  "nature": "从内容创建 PDF 文档的技能",
  "genus": "DocumentGenerator",
  "differentia": "输出 PDF 格式",
  "intents": ["create_pdf", "export_pdf"],
  "requires_state": ["oc:ContentReady"],
  "yields_state": ["oc:PdfGenerated"],
  "handles_failure": ["oc:PdfGenerationFailed"],
  "requirements": [
    {"type": "Tool", "value": "wkhtmltopdf", "optional": false}
  ],
  "depends_on": ["content-processor"],
  "extends": ["document-base"],
  "execution_payload": {
    "executor": "shell",
    "code": "wkhtmltopdf $INPUT $OUTPUT.pdf",
    "timeout": 30000
  },
  "knowledge_nodes": [
    {
      "node_type": "PreFlightCheck",
      "directive_content": "验证 wkhtmltopdf 已安装",
      "applies_to_context": "PDF 生成之前",
      "has_rationale": "避免运行时失败",
      "severity_level": "HIGH"
    }
  ]
}

evaluate_execution_plan

评估意图或技能是否可以从当前状态执行。返回完整的执行计划和警告。

{
  "intent": "create_pdf",
  "current_states": ["oc:ContentReady", "oc:UserAuthenticated"],
  "max_depth": 10
}
参数类型描述
intentstring目标意图（使用 intent 或 skill_id）
skill_idstring目标技能（使用 intent 或 skill_id）
current_statesarray当前状态 URI 或紧凑值
max_depthinteger最大计划深度（1-10，默认 10）

示例响应：

{
  "executable": true,
  "plan": [
    {
      "skill_id": "content-processor",
      "step": 1,
      "satisfies": ["oc:ContentReady"]
    },
    {
      "skill_id": "pdf",
      "step": 2,
      "requires": ["oc:ContentReady"],
      "yields": ["oc:PdfGenerated"]
    }
  ],
  "missing_states": [],
  "warnings": []
}

当 executable: false：

{
  "executable": false,
  "plan": [],
  "missing_states": ["oc:ApiKeyConfigured"],
  "warnings": ["没有 API key 配置无法继续"]
}

query_epistemic_rules

使用引导过滤器查询规范化的知识节点。

{
  "skill_id": "pdf",
  "kind": "AntiPattern",
  "dimension": "SecurityGuardrail",
  "severity_level": "CRITICAL",
  "limit": 25
}
参数类型描述
skill_idstring按技能过滤
kindstring节点类型（Heuristic、AntiPattern、PreFlightCheck 等）
dimensionstring认识维度（NormativeRule、ResilienceTactic 等）
severity_levelstringCRITICAL、HIGH、MEDIUM、LOW
applies_to_contextstring上下文过滤器
include_inheritedboolean包含扩展技能（默认 true）
limitinteger最大结果数（1-100，默认 25）

本地开发

从仓库根目录：

Terminal window
# 使用本地本体运行
cargo run --manifest-path mcp/Cargo.toml -- --ontology-root ./ontoskills


# 运行测试
cargo test --manifest-path mcp/Cargo.toml


# 构建发布二进制
cargo build --release --manifest-path mcp/Cargo.toml

客户端指南

故障排除

”Ontology root not found”

确保已编译的 .ttl 文件存在：

Terminal window
ls ~/.ontoskills/ontologies/
# 应该显示：index.ttl、system/ 等


ls ~/.ontoskills/ontologies/system/
# 应该显示：index.enabled.ttl、embeddings/ 等

如果缺失，先编译技能：

Terminal window
ontoskills compile

“Embeddings not available”

search_intents 工具需要预计算的嵌入：

Terminal window
ontoskills export-embeddings

这会创建 ~/.ontoskills/ontologies/system/embeddings/。

“Server not initialized”

MCP 客户端必须在调用工具之前发送 initialize。合规客户端会自动处理。

连接静默断开

检查日志中的错误：

Terminal window
# 手动运行以查看 stderr
~/.ontoskills/bin/ontomcp --ontology-root ~/.ontoskills/ontologies

环境变量

变量描述默认值
ONTOMCP_ONTOLOGY_ROOT本体目录~/.ontoskills/ontologies