使用说明

项目简介

Semantic Tool 是一个微服务，旨在通过语义相似性动态发现和调用外部工具。它利用向量嵌入技术，允许用户使用自然语言查询来匹配并调用工具注册表中的相关工具。此外，它还能够管理和集成多个MCP服务器，将这些服务器提供的工具统一管理和暴露。

主要功能点

语义工具搜索: 通过文本描述的语义相似性查找相关工具。
工具调用 API: 通过 RESTful 接口直接调用已注册的工具。
MCP 服务器管理: 注册和列出可用的 MCP 服务器会话。

安装步骤

本地安装 (使用 'uv')

确保已安装 Python 3.13+ 和 'uv'。
克隆仓库到本地。
在仓库根目录下，使用 'uv run semantictool' 命令启动服务。

Docker 安装 (推荐)

确保已安装 Docker 和 Docker Compose。
克隆仓库到本地。
在仓库根目录下，使用 'docker compose up' 命令启动服务。

服务器配置

Semantic Tool 的配置通过 'CONFIG_LOCATION' 环境变量指定，默认为 'file:///config.yaml'。你可以通过修改 'config.yaml' 文件或设置环境变量来配置服务器。

以下是一个 'config.yaml' 示例，用于配置 Semantic Tool 可以管理的 MCP 服务器：

mcp_servers:
  timeserver: # 服务器名称，可以自定义
    command: uvx # MCP 服务器的启动命令
    args: ["mcp-timeserver"] # 启动命令的参数
  searxng: # 服务器名称，可以自定义
    command: uvx # MCP 服务器的启动命令
    args: ["mcp-searxng"] # 启动命令的参数
  wolframalpha: # 服务器名称，可以自定义
    command: uvx # MCP 服务器的启动命令
    args: ["mcp-wolfram-alpha"] # 启动命令的参数
    env: # 可选的环境变量配置
      WOLFRAM_API_KEY: "your_api_key" # 例如，Wolfram Alpha API 密钥

embedding:
  model_name: "all-MiniLM-L6-v2" # 向量嵌入模型名称
  dim: 384 # 向量维度

配置说明:

'mcp_servers': 定义 Semantic Tool 管理的 MCP 服务器列表。
- 每个服务器配置项下：
  - 'command': 指定启动 MCP 服务器进程的命令，例如 'uvx', 'python' 等。
  - 'args': 一个字符串列表，包含传递给启动命令的参数。这些参数会传递给 'command' 指定的程序，用于启动 MCP 服务器。
  - 'env' (可选): 一个字典，用于设置 MCP 服务器进程运行时的环境变量。

基本使用方法

Semantic Tool 提供了一系列 RESTful API 接口，用于工具和服务器的管理与调用。

API 概览:

工具端点 (Tools Endpoints):
- 'GET /api/v1/tools/list': 获取所有可用工具的列表。
- 'POST /api/v1/tools/call': 调用指定名称的工具，并传递参数。
- 'POST /api/v1/tools/semantic': 根据文本查询的语义相似性查找相关工具。
服务器端点 (Server Endpoints):
- 'GET /api/v1/servers/list': 获取所有已激活的服务器会话列表。

示例 API 请求 (使用 curl):

列出所有工具:

curl http://localhost:8000/api/v1/tools/list

调用工具 (假设有一个名为 'timeserver' 的工具):

curl -X POST -H "Content-Type: application/json" -d '{"name": "timeserver", "arguments": {}}' http://localhost:8000/api/v1/tools/call

语义搜索工具 (例如，搜索与 "current time" 相关的工具):

curl -X POST -H "Content-Type: application/json" -d '{"query": "current time", "quantity": 3}' http://localhost:8000/api/v1/tools/semantic

列出所有服务器:

curl http://localhost:8000/api/v1/servers/list

请根据实际部署情况修改 'localhost:8000' 为 Semantic Tool 服务器的地址和端口。

关键词