Stacklok Toolhive MCP Server

关键词

文档检索向量检索本地模型嵌入服务器端 API

Markdown 格式使用说明

项目简介

  • 该仓库实现一个基于 MCP 协议的后端服务器，围绕 Stacklok Toolhive 文档构建知识上下文服务。核心能力包括：向 LLM 客户端提供文档检索、获取文档片段（chunk）、以及与外部功能的调用能力；同时集成了本地嵌入模型、向量检索、缓存的文档源同步等完整工作流。

主要功能点

  • MCP 服务端实现
    • 提供 MCP 工具（Tools），目前实现了 query_docs（文档检索/查询）和 get_chunk（按 Chunk ID 获取完整内容）两项核心能力。
    • 通过 FastMCP 框架暴露接口，支持 Streamable HTTP 传输，便于与 LLM 客户端进行 JSON-RPC 交互。
    • 错误与遥测处理：结合 McpError、OpenTelemetry 日志与可观测性输出。
  • 文档源同步与处理
    • 支持网站爬取与 GitHub 仓库中文档的抓取、解析和缓存。
    • 解析阶段使用 HTML Parser 与 Markdown Parser，提取主内容、标题、代码块、链接、元数据等信息。
    • Chunker 根据设置的 token/块策略将文本分块，便于嵌入与向量检索。
  • 本地嵌入与向量检索
    • 使用本地嵌入模型（fastembed）生成嵌入向量，存储在 SQLite + sqlite_vec 的向量表中。
    • 向量检索支持 semantic、keyword、hybrid 三种查询模式，以及基于 BM25 的关键词检索。
    • 提供 get_chunk、query_docs 的检索结果输出结构，包含分块信息、分数、元数据等。
  • 向量存储与元数据
    • 以 SQLite 数据库保存 chunks、向量、以及元数据；提供健康检查、数据库完整性校验、原子交换等实现。
  • 服务器管理与刷新
    • 支持后台刷新（RefreshOrchestrator），在服务器启动时自动初始化（如配置允许时）。
    • 提供启动/关闭的清理与调度逻辑，确保服务器与数据库之间的并发安全。
  • 可观测性与监控
    • 集成 OpenTelemetry 日志/追踪能力，支持日志/追踪端点地址配置，默认启用。
  • 配置与扩展
    • 通过 YAML 配置文件 sources.yaml 控制网站与 GitHub 的数据源，以及抓取参数、重试、并发等行为。
    • 配置加载、校验、环境变量覆盖等机制完善，确保在不同环境中可灵活使用。

安装步骤

  • 准备环境
    • 安装 Python 3.13+（或按项目实际要求的版本）。
    • 安装并配置 uv（项目示例中以「uv」作为任务/启动工具）。
  • 安装依赖与准备
    • 通过 uv（或等效工具）安装依赖，确保数据库、嵌入模型、以及向量检索所需库就绪。
  • 获取与配置
    • 将示例配置拷贝并修改为实际环境使用：sources.yaml（网站与 GitHub 来源、抓取参数等）。
    • 如需开启遥测，按环境变量配置 OTEL_ENABLED、OTEL_ENDPOINT、OTEL_SERVICE_NAME、OTEL_SERVICE_VERSION 等。
  • 启动 MCP 服务器
    • 运行命令：uv run python src/mcp_server.py
    • 服务器默认监听端口 8080，允许跨域和多传输协议（streamable-http）。
  • 运行后端服务的快速检查
    • 访问健康端点，检查服务是否正常启动。
    • 通过 MCP 客户端对 query_docs、get_chunk 等工具发起请求，验证 JSON-RPC 的响应结构。

服务器配置参考（MCP 客户端需要的最小信息） JSON 配置示例（仅为客户端参考，不需要额外代码） { "server_name": "toolhive-doc-mcp", "command": "uv", "args": ["run", "python", "src/mcp_server.py"], "host": "0.0.0.0", "port": 8080 } 配置注释与要点

  • server_name: MCP 服务器的名称，需与服务器实际用途一致，便于客户端管理与日后追踪。
  • command: 服务器启动命令的主程序（此处为 uv）。
  • args: 启动时传递给命令的参数集合，按仓库约定应包含启动 MCP 服务的子命令与入口脚本。
  • host/port: 服务器监听地址与端口，默认 0.0.0.0:8080，与代码中配置一致（port 由 config.mcp_port 控制，默认 8080）。
  • 备注：MCP 客户端通过该配置知道如何启动并连接到服务器；客户端本身不需要理解服务器内部实现细节。

基本使用方法

  • 启动服务器
    • 使用 MCP 客户端通过配置中的命令启动服务器（示例已给出）。
  • 发送请求请参考 MCP 协议
    • 通过客户端向服务器发送 JSON-RPC 请求，调用工具 query_docs 获取文档检索结果，或调用 get_chunk 获取指定 Chunk 的详细内容。
    • 请求参数包含 query、limit、query_type、min_score 等，响应返回结构包含检索结果、分数、元数据等。
  • 典型工作流程
    • 服务器启动后，客户端发送 JSON-RPC 请求调用 query_docs，携带查询文本与可选参数，服务器返回带分数的 Chunk 列表。
    • 客户端也可通过 get_chunk 按 Chunk ID 获取完整内容，便于在 LLM 的上下文中嵌入具体文本段落。
  • 常见运维操作
    • 监控日志与遥测端点，确保 OTLP 日志/追踪正常输出。
    • 如需更新文档源，调整 sources.yaml 并触发构建/同步流程，确保向量数据库与元数据保持一致。
    • 如遇数据库热更新，系统支持原子交换与回滚，确保服务不中断。

关键词 文档检索、向量检索、本地模型、嵌入、服务器端 API

category_id 5

服务器信息

访问项目