语义代码搜索服务

MCP语义监视器

该项目提供了一个MCP服务器，该服务器监视代码存储库，使用Ollama嵌入对代码片段进行索引，并将其存储在Qdrant中以进行语义搜索。它利用Tree sitter解析代码结构，并利用Chokidar进行高效的文件监视。

特性

• 实时代码索引： 监视文件更改的指定存储库路径。
• 语义搜索： 使用Ollama将代码片段作为嵌入进行索引，并允许通过自然语言查询进行搜索。
• 代码解析： 利用Tree sitter对支持的编程语言进行结构化解析。
• Qdrant集成： 将嵌入和元数据存储在Qdrant矢量数据库中。
• MCP服务器： 通过模型上下文协议公开语义搜索和索引管理工具。

设置和安装

先决条件

• Node.js： 建议使用18或更高版本。
• npm或yarn： Node.js的包管理器。
• 问题： 正在运行的Qdrant实例。默认URL为 http://localhost:6333。如果使用身份验证，请确保它是可访问和配置的。
• 奥拉马： 必须安装并运行Ollama，并下载兼容的嵌入模型（默认值： nomic-embed-text).

步骤

1. 克隆存储库：

   复制

   git clone <repository-url>
   cd mcp-fs-server
   

2. 安装Node.js依赖关系：

   复制

   npm install
   # or
   yarn install
   

3. 下载WASM语法： 这个项目使用Tree sitter来解析代码。需要下载必要的WASM语法文件。

   复制

   npm run setup
   # or
   yarn setup
   

   此命令执行 node scripts/wasm-installer.js 它将所需的Tree sitter WASM文件下载到 ./wasm 目录。

4. 配置环境变量（可选）： 可以使用环境变量配置服务器。如果未设置，将使用默认值。请参阅 配置 详情请参阅第节。

运行服务器

1. 构建项目： 将TypeScript代码编译成JavaScript。

   复制

   npm run build
   # or
   yarn build
   

2. 启动服务器： 运行已编译的应用程序。

   复制

   npm start
   # or
   yarn start
   

   服务器将开始监听STDIN/STDOUT上的MCP请求。

3. 开发监视模式： 要在开发过程中文件更改时自动重新编译TypeScript：

   复制

   npm run watch
   # or
   yarn watch
   

用法

MCP服务器配置

此MCP服务器可以通过JSON配置与MCP兼容的客户端（如Claude Desktop）一起配置和使用。将服务器添加到MCP客户端配置中：

Claude桌面配置

添加到您的Claude桌面 claude_desktop_config.json 文件：

{
  "mcpServers": {
    "semantic-watcher": {
      "command": "node",
      "args": ["/path/to/mcp-fs-server/build/index.js"],
      "env": {
        "REPO_PATH": "/path/to/your/codebase",
        "QDRANT_URL": "http://localhost:6333",
        "QDRANT_COLLECTION": "my_codebase",
        "OLLAMA_MODEL": "nomic-embed-text",
        "LOG_LEVEL": "info"
      }
    }
  }
}

多环境示例

{
  "mcpServers": {
    "semantic-watcher-dev": {
      "command": "node",
      "args": ["/path/to/mcp-fs-server/build/index.js"],
      "env": {
        "REPO_PATH": "/path/to/dev/project",
        "QDRANT_COLLECTION": "dev_codebase",
        "OLLAMA_MODEL": "nomic-embed-text",
        "LOG_LEVEL": "debug"
      }
    },
    "semantic-watcher-prod": {
      "command": "node",
      "args": ["/path/to/mcp-fs-server/build/index.js"],
      "env": {
        "REPO_PATH": "/path/to/production/project",
        "QDRANT_URL": "https://qdrant.example.com",
        "QDRANT_API_KEY": "your-api-key-here",
        "QDRANT_COLLECTION": "prod_codebase",
        "OLLAMA_MODEL": "nomic-embed-text",
        "LOG_LEVEL": "warn"
      }
    }
  }
}

配置要求

1. 命令路径：使用构建的绝对路径 index.js 文件
2. 环境变量：在中设置所有必需的环境变量 env 章节
3. 存储库路径: REPO_PATH 必须指向要索引的代码库
4. 依赖项：确保Qdrant和Ollama正在运行且可访问

直接使用

服务器也可以直接作为MCP服务运行，通过STDIN/STDOUT进行通信。您可以通过发送MCP请求与它进行交互。使用此服务器的主要方式是调用它公开的工具。

工具

MCP语义观察程序公开了以下工具：

semantic_search

• 说明： 使用语义向量搜索搜索索引代码库。它查找语义上与自然语言查询相似的代码片段。
• 输入架构：
  • query （string，必填）：要搜索的自然语言查询。
  • limit （number，可选）：返回的最大结果数。默认值为5，最大值为20。
• 输出： 返回一个包含搜索结果的格式化字符串，包括文件路径、行号、分数和代码段。

refresh_index

• 说明： 手动触发对配置的存储库路径的完全重新扫描和重新索引(REPO_PATH).如果添加了新文件，或者您想确保索引是最新的，这很有用。
• 输入架构： 没有。
• 输出： 指示刷新过程已开始或完成的确认消息。

示例提示（MCP工具调用）

这些示例展示了如何使用MCP请求结构调用这些工具。

示例：语义搜索

要搜索与“如何初始化Qdrant客户端”相关的代码，最多可获得3个结果：

{
  "method": "call_tool",
  "params": {
    "name": "semantic_search",
    "arguments": {
      "query": "How is the Qdrant client initialized?",
      "limit": 3
    }
  }
}

示例：刷新索引

要手动触发存储库的重新扫描，请执行以下操作：

{
  "method": "call_tool",
  "params": {
    "name": "refresh_index",
    "arguments": {}
  }
}

配置

服务器的行为可以使用环境变量进行自定义：

贡献

看 贡献.md 了解如何为这个项目做出贡献的详细信息。

许可证

此项目根据MIT许可证获得许可-请参阅 许可证.md 文件以获取详细信息。