Unicity Orchestrator

Unicity编排器

基于知识图的编排器，用于模型上下文协议（MCP）服务，具有高级工具发现和符号推理功能。

概述

Unicity Orchestrator是一个复杂的系统，通过以下组合管理和发现MCP工具：

• 知识图谱：工具、服务和数据类型之间的类型化关系
• 矢量嵌入：用于工具发现的语义相似性搜索
• 符号推理：用于智能工具选择的基于规则的推理
• 注册表集成：支持多个MCP清单注册表 *（开发中）*
• 链执行：具有依赖关系管理的多步工具执行 *（开发中——rmcp 0.14+）*

LLM交互模型

Unicity Orchestrator旨在操作 对大型语言模型的依赖最小 在规划和执行过程中。LLM只涉及两点：

1. 初始意图描述 LLM（或用户）提供任务的自然语言描述和可选的高级步骤。编排者确实如此 *不* 要求LLM命名工具或操作模式。
2. 后备援助 –只有在以下情况下，编排者才会要求LLM进行澄清或重新表述：

- 没有找到语义相关的工具， - 不存在有效的类型安全工具链， - 或者无法自动解决运行时错误。

所有核心决策均由以下人员内部处理：

• 语义检索 通过向量嵌入
• 类型标准化 JSON模式
• 知识图遍历 为了兼容性和链接
• 符号推理 用于基于规则的推理

这种设计确保了快速、可预测和经济高效的编排，同时保持LLM交互的有意性和最小化。

特性

核心能力

• 多注册表支持：GitHub、npm和自定义MCP注册表 *（开发中）*
• 工具发现：MCP服务的自动发现和索引
• 快速转发：通过智能冲突解决聚合来自所有MCP服务的提示
• 资源转发：通过自动发现聚合所有MCP服务的资源
• 语义搜索：按含义查找工具，而不仅仅是关键字
• 类型安全图：工具输入/输出之间的强制兼容性
• 符号规则：定义工具选择的自定义推理规则
• 规划：规划复杂的工具工作流程；LLM驱动每个步骤的执行

知识图谱特征

• 类型化边缘：DataFlow、语义相似性、顺序等。
• 图的遍历：找到数据转换的最佳工具链
• 使用模式：从历史工具使用中学习
• 备选建议：为同一任务找到等效工具

快速转发

编排器聚合来自所有配置的MCP服务的提示，并通过统一的界面呈现它们：

• 自动发现：在服务初始化过程中发现提示
• 冲突解决：当多个服务定义具有相同名称的提示时，编排器会创建命名空间别名（例如。， github-commit, gitlab-commit)
• 灵活的解决方案：提示可通过以下方式访问：

- 命名空间名称： github-commit - 原始提示名称： commit （决定第一场比赛） - 服务提示模式： github:commit 或 my-service:commit （消毒）

• 病例不敏感匹配：所有分辨率模式都适用，无论情况如何
• 参数验证：验证提示名称和参数以防止注入攻击

资源转发

编排器聚合来自所有配置的MCP服务的资源，并通过统一的接口呈现它们：

• 自动发现：在服务初始化过程中发现资源
• 基于URI的解析：资源通过其唯一URI进行访问（例如。， file:///path/to/file.txt, git://github.com/user/repo)
• 冲突解决：当多个服务使用相同的URI定义资源时，将使用第一个服务的版本
• 安全验证：验证资源URI以防止路径遍历和注入攻击
• 资源模板：支持参数化资源模板（例如。， git://{repo}/file/{path})

API和CLI

• REST API：用于工具查询和管理的HTTP端点
• CLI工具：用于管理和查询的命令行界面
• MCP协议：通过HTTP或stdio传输的完整MCP服务器

快速开始

Docker部署

Unicity Orchestrator可以与SurrealDB一起完全容器化运行。

使用Docker Compose

存储库包括 docker-compose.yml 在开发模式下启动编排器的文件：

• 内存模式（默认） --如果没有 SURREALDB_URL 如果提供，编排器会自动使用内存中的SurrealDB实例。
• 外部SurrealDB（可选） --要连接到真正的SurrealDB部署，请设置 SURREALDB_URL 以及相关的环境变量。

version: "3.9"

services:
  orchestrator:
    build: .
    environment:
      # Optional: If omitted, orchestrator runs with in-memory DB for development
      - SURREALDB_NAMESPACE=unicity
      - SURREALDB_DATABASE=orchestrator
      - SURREALDB_USERNAME=${SURREALDB_USERNAME:-root}
      - SURREALDB_PASSWORD=${SURREALDB_PASSWORD:-root}
      - MCP_BIND=0.0.0.0:3942
      - RUST_LOG=info,unicity_orchestrator=info
    ports:
      - "3942:3942"

使用以下命令启动系统：

docker compose up --build

默认情况下，这将与内存中的数据库一起运行。要将编排器指向SurrealDB实例，请设置 SURREALDB_URL:

SURREALDB_URL=ws://localhost:8000/rpc docker compose up

MCP服务器可在以下位置访问：

http://localhost:3942/mcp

直接使用Dockerfile

多阶段 Dockerfile 包括在内。要手动构建，请执行以下操作：

docker build -t unicity-orchestrator .

使用环境变量运行：

docker run --rm \
  -e SURREALDB_URL=ws://host.docker.internal:8000 \
  -e SURREALDB_NAMESPACE=unicity \
  -e SURREALDB_DATABASE=orchestrator \
  -e SURREALDB_USERNAME=root \
  -e SURREALDB_PASSWORD=root \
  -p 3942:3942 \
  unicity-orchestrator

默认情况下，容器通过以下入口点启动：

• 用途 内存SurrealDB 如果 SURREALDB_URL 未设置。
• 在以下情况下验证所需的数据库变量 SURREALDB_URL *是* 集。

服务器模式

Unicity Orchestrator提供多个服务器接口，每个接口都针对不同的用例设计：

公共REST API

在面向公共的端口上运行（默认值： 0.0.0.0:8080)并且仅暴露 只读 端点：

• GET /health
• POST /query --用户提供上下文的语义工具检索

此API对外公开是安全的，并且适用于面向用户的应用程序。

管理员REST API

在受限/管理员端口上运行（默认： 127.0.0.1:8081)并暴露 突变 端点：

• POST /discover --从配置的MCP服务中重新发现和索引工具

这些端点修改编排器状态，并且应该 不 公开曝光。 使用防火墙规则、Docker端口映射或专用网络绑定来限制访问。

MCP HTTP服务器

编排器还运行一个完整的 MCP兼容服务器 在其自己的端口上（默认值： 3942). 此端点为代理LLM和MCP客户端公开模型上下文协议：

http://localhost:3942/mcp

此服务器是基于LLM的工作流和工具执行的主要接口。

MCP标准服务器

用于本地开发或与期望 stdio MCP传输：

unicity-orchestrator mcp-stdio --db-url memory

当使用SurrealDB而不是内存中的数据库时，您可以通过环境变量或CLI标志向stdio服务器提供完整的数据库配置。例如：

SURREALDB_URL=ws://localhost:8000 \
SURREALDB_NAMESPACE=unicity \
SURREALDB_DATABASE=orchestrator \
SURREALDB_USERNAME=root \
SURREALDB_PASSWORD=root \
unicity-orchestrator mcp-stdio --db-url ws://localhost:8000

此模式通常用于本地MCP客户端工具，而不是生产部署。

端到端示例

此示例演示了工具编排的当前生命周期——从自然语言请求到工具发现、语义匹配、符号推理和执行。

1.用户/LLM请求

LLM（或用户）通过REST API或MCP协议发送查询：

{
  "query": "List open GitHub issues from this repository and group them by severity.",
  "context": {
    "repo_url": "https://github.com/example/project"
  }
}

2.语义检索

编排器为查询生成嵌入，并执行余弦相似性搜索（前32个结果，0.25阈值）。候选工具排名如下：

• github.list_issues — 0.91
• github.get_repo — 0.78
• json.structure_data — 0.72
• text.summarize — 0.68

低于阈值的工具将被丢弃。

3.符号推理

符号推理引擎将候选者加载到工作记忆中，并对规则应用正向/反向链接来调整置信度得分和排名选择。

编排器将排序后的工具选择返回给调用者：

[
  {
    "tool_name": "github.list_issues",
    "service_name": "github-mcp",
    "confidence": 0.91,
    "reasoning": "High semantic similarity to query; tool lists GitHub issues."
  }
]

4.执行

LLM（或调用客户端）选择一个工具并要求编排器执行它。编排器通过其rmcp客户端将调用路由到正确的子MCP服务：

{
  "tool_name": "github.list_issues",
  "service_name": "github-mcp",
  "arguments": {
    "repo": "example/project",
    "state": "open"
  }
}

当前正在执行 每次通话使用一个工具LLM负责对多个工具调用进行排序——检查每个结果，决定下一步，并在工具之间传递参数。

注： 自动多步链执行（编排器执行计划的工具序列，并在它们之间传输输出）是与rmcp 0.14+一起开发的计划功能。今天，the plan_tools 端点可以建议一个多步骤的计划，但每个步骤的执行都是由调用者驱动的。

5.最终答复

执行的工具通过编排器返回其结果：

{
  "content": [
    {
      "type": "text",
      "text": "[{\"number\": 42, \"title\": \"Critical bug in auth\", \"labels\": [\"critical\"]}, ...]"
    }
  ]
}

然后，LLM可以使用相同的选择-然后执行流调用其他工具（例如，摘要器或格式化器），或直接处理结果。

安装

# Clone the repository
git clone 
cd unicity-orchestrator

# Build the project
cargo build --release

配置

MCP配置文件（MCP.json）

编排器需要 mcp.json 列出要加载的外部MCP服务的文件。 在Docker内部或直接从二进制文件运行时，编排器将尝试在工作目录中查找此文件(./mcp.json).

自动行为：

• 如果A mcp.json 在Docker构建期间，它存在于项目根目录中，它将自动包含在映像中。
• 如果没有 mcp.json 如果运行时存在，编排器将创建一个最小的默认文件：

{ "mcpServers": {} }

这确保了即使没有配置外部MCP服务，系统也能始终干净启动。 您可以随时向此文件添加服务并重新启动编排器。

创建 mcp.json 配置MCP服务的文件：

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

跑步

# Initialize the database
cargo run -- init --db-url memory

# Discover tools from configured services
cargo run -- discover-tools

# Start the API server
cargo run -- server --port 8080

# Query for tools
cargo run -- query "read a file from filesystem"

建筑

数据库层

• SurrealDB：具有图形功能的多模型数据库
• 模式：服务、工具、嵌入和关系的类型化表
• 查询：针对图遍历和相似性搜索进行了优化

知识图谱

• 节点：服务、工具、类型、概念、注册表
• 边缘：带置信度得分的类型化关系
• 遍历：具有类型检查和兼容性规则的BFS/DFS

嵌入引擎

• 模型：Qwen3 0.6B（1024维，通过embed_anything进行局部推理）
• 缓存：具有内容哈希重复数据消除功能的内存缓存
• 相似性：余弦相似度为0.25阈值

象征推理

• 规则：正向和反向链式推理
• 事实：带有类型化谓词的工作记忆
• 规划：实现目标的反向链接

API终点

健康检查

GET /health

退货：

{"status": "healthy", "timestamp": "2025-01-01T00:00:00Z"}

查询工具

POST /query
{
  "query": "read a json file",
  "context": {
    "file_path": "/path/to/file.json"
  }
}

发现工具

POST /discover

配置

数据库

SURREALDB_URL=ws://localhost:8000/rpc
SURREALDB_NAMESPACE=unicity
SURREALDB_DATABASE=orchestrator
SURREALDB_USERNAME=root
SURREALDB_PASSWORD=password

发展

项目结构

待办事项

添加符号规则

use unicity_orchestrator::knowledge_graph::symbolic::*;

let rule = SymbolicRule {
    id: "file_operation_chain".to_string(),
    name: "File Operation Chain".to_string(),
    description: "Chain file read with data processing".to_string(),
    antecedents: vec![
        SymbolicExpression::Fact(Fact {
            predicate: "tool_selected".to_string(),
            arguments: vec![
                SymbolicExpression::Variable("tool".to_string()),
                SymbolicExpression::Literal(LiteralValue::String("file_read".to_string()))
            ],
            confidence: Some(0.9),
        })
    ],
    consequents: vec![
        SymbolicExpression::Fact(Fact {
            predicate: "suggest_following_tool".to_string(),
            arguments: vec![
                SymbolicExpression::Variable("following_tool".to_string()),
                SymbolicExpression::Literal(LiteralValue::String("data_parse".to_string()))
            ],
            confidence: Some(0.8),
        })
    ],
    confidence: 0.85,
    priority: 100,
};

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

1. 克隆该仓库
2. 创建要素分支
3. 进行更改
4. 添加测试
5. 提交拉取请求

支持

有关问题和疑问，请使用GitHub问题跟踪器。