Lumen MCP 服务器

关键词

本地向量检索代码语义检索增量索引嵌入向量本地向量数据库

使用说明（Markdown 格式）

项目概览

Lumen 是一个本地化的 MCP 服务器实现，旨在为大型语言模型（LLM）提供稳定的上下文服务。它通过 MCP 协议，向客户端暴露工具集合，包含代码语义搜索、索引状态查询等能力，并支持会话管理和进度通知。

主要功能点

  • MCP 服务端实现：通过 JSON-RPC 与 LLM 客户端通信，注册并暴露工具，处理请求与响应，并提供进度通知能力。
  • 资源与工具管理：实现了用于代码搜索的 semantic_search 工具，以及用于查询索引状态的 index_status 工具，并支持工具的调用、参数校验及结果格式化。
  • 增量索引与向量检索：内部集成 MerkleHash 风格的变更检测、分块切分、向量化嵌入与向量检索（KNN）等能力，支持增量索引、重新索引以及结果排序。
  • 本地嵌入模型支持：通过 embedder 接口对文本进行向量化，支持 Ollama 和 LM Studio 两种后端实现（可通过环境变量配置模型、后端、主机地址等）。
  • 进度通知与会话体验：在工具执行过程中提供 ProgressNotification，便于在 UI/LLM 端呈现处理进度，并提供 Claude Code 集成所需的 SessionStart/PreToolUse 机制。

安装与运行步骤

  • 先决条件
    • 安装本地 Embedding 服务：Ollama 或 LM Studio（本实现需要其中之一来生成文本向量）。
    • 安装并运行 Ollama（默认端口 http://localhost:11434）或 LM Studio，并确保可访问。
  • 构建与启动
    • 在项目根目录执行构建命令，生成本地可执行文件 lumen。
    • 以 stdio 传输启动 MCP 服务器，示例命令为 lumen stdio。启动后服务器通过标准输入输出与 MCP 客户端进行 JSON-RPC 通信。
  • 配置环境示例（运行时需设定）
    • LUMEN_EMBED_MODEL：指定嵌入模型名称，例如 all-minilm。
    • OLLAMA_HOST：Ollama 服务地址，如 http://localhost:11434。
    • LM_STUDIO_HOST：LM Studio 服务地址（如使用 LM Studio 时需要设置）。
    • XDG_DATA_HOME：用于存放本地索引数据库的目录（默认 ~/.local/share，建议使用临时目录做测试）。
  • 服务器地址与传输
    • 本实现默认通过 stdio 传输对接 MCP 客户端，后续可扩展支持其他传输协议（如 SSE、WebSocket）。

服务器配置（MCP 客户端需要的配置信息，JSON 格式）

{ "server_name": "lumen-mcp", "command": ["lumen"], "args": ["stdio"], "notes": "启动命令。该客户端配置仅用于 MCP 客户端接入服务器，实际运行时需在客户端以 JSON-RPC 方式连接。环境变量可选项包括：OLLAMA_HOST=http://localhost:11434、LUMEN_EMBED_MODEL=all-minilm、LUMEN_BACKEND=ollama、LM_STUDIO_HOST=http://localhost:1234。" }

  • 说明
    • server_name：MCP 服务器在客户端视角中的名称，便于日志与节点识别。
    • command/args：服务器启动命令及参数（本实现通过 lumen 的 stdio 模式启动）。
    • notes：简要说明与常用环境变量，供 MCP 客户端配置时参考。

基本使用方法

  • 首次接入
    • 启动 Ollama 或 LM Studio 服务，并确保网络可访问。
    • 启动 lumen server，使用 stdio 传输方式与 MCP 客户端建立连接。
    • 客户端通过 MCP 的 ListTools 接口获取服务器暴露的工具清单（包括 semantic_search 与 index_status），确认工具可以使用。
  • 典型工作流
    • 调用 semantic_search 工具进行代码检索，传入 query、path、limit、min_score 等参数，服务器返回分组后的结果及分数、代码片段等信息。
    • 调用 index_status 工具查看指定项目的索引状态，例如总文件数、已索引文件、总分块数、最后索引时间等。
    • 在需要时触发增量索引或强制重建索引，服务器会对变更的文件进行重新处理，并将新向量写入本地 SQLite/VECTOR 存储。
  • 进度与错误处理
    • 工具执行过程中会产生进度通知，便于 UI 显示进度条或告警信息。
    • 错误情形通过 MCP 错误响应返回，便于上层 LLM 客户端处理。

关键词

本地向量搜索, 代码语义检索, 增量索引, 嵌入向量, 本地向量数据库

分类

6

服务器信息

访问项目