AI导哈

语义代码搜索服务器

DeepMatch MCP是一个基于向量嵌入的语义代码搜索服务器，支持通过自然语言查询代码库，适用于多仓库代码管理和开发效率提升。

  • by 657kbps
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 kuyermqi/deepmatch-mcp

使用说明

DeepMatch MCP

一种使用向量嵌入进行语义代码搜索的模型上下文协议（MCP）服务器。对代码库进行索引，并使用自然语言查询进行搜索。

特性

  • 语义代码搜索：按含义查找代码，而不仅仅是关键字
  • 多个嵌入提供程序：OpenAI、Ollama、Gemini、OpenAI兼容API
  • 实时文件监视：自动重新索引文件更改
  • 多存储库支持：同时索引多个目录
  • 智能过滤：尊重 .gitignore，跳过二进制文件和常用构建目录
  • MCP协议：适用于任何兼容MCP的客户端（Claude Desktop等）

建筑

┌─────────────────────────────────────────────────────────────────┐
│                        deepmatch-mcp                            │
├─────────────────────────────────────────────────────────────────┤
│  CLI Entrypoint (src/cli.ts)                                    │
│  - Parses config from CLI flags and environment variables       │
│  - Orchestrates startup: scan → index → watch → serve           │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │   Config    │  │  Providers  │  │     Vector Store        │  │
│  │  (Zod)      │  │ (Embedders) │  │      (Qdrant)           │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│                                                                 │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐  │
│  │  Scanner    │  │  Chunker    │  │     Index Manager       │  │
│  │ (Directory) │  │ (Line-based)│  │   (Batch Processing)    │  │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘  │
│                                                                 │
│  ┌─────────────┐  ┌───────────────────────────────────────────┐ │
│  │  Watcher    │  │              MCP Server                   │ │
│  │ (Chokidar)  │  │  (stdio transport, 'search' tool)         │ │
│  └─────────────┘  └───────────────────────────────────────────┘ │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

模块概述

模块 路径 描述
配置 src/config/ CLI/ENV解析与Zod验证
提供商 src/providers/ 嵌入提供商（OpenAI、Ollama、Gemini、OpenAI兼容）
商店 src/store/ Qdrant矢量数据库包装器
Chunker src/chunker/ 具有可配置限制的基于行的文本分块
扫描仪 src/scanner/ 支持.gitignore的目录遍历
索引器 src/indexer/ 批量嵌入和矢量追加业务编排
观察者 src/watcher/ 具有去抖动功能的文件更改检测
主控程序 src/mcp/ MCP stdio服务器 search 工具

安装

# Install dependencies
npm install

# Build
npm run build

用法

先决条件

  1. Qdrant -矢量数据库（默认值： http://localhost:6333)

    # Using Docker
docker run -p 6333:6333 qdrant/qdrant

  2. 嵌入提供者 -其中之一：

    • OpenAI API密钥
    • Ollama在当地跑步
    • Gemini API密钥
    • 任何与OpenAI兼容的API

CLI选项

npx deepmatch-mcp [options]

Options:
  --path <path>              Repository path to index (repeatable)
  --provider <provider>      Embedding provider: openai|ollama|gemini|openai-compatible
  --model <model>            Embedding model name
  --embedding-dim <dim>      Embedding dimension (auto-detected if not set)
  --batch-size <size>        Batch size for embeddings (default: 60)
  --max-files <count>        Maximum files to index (default: 50000)
  --qdrant-url <url>         Qdrant server URL (default: http://localhost:6333)
  --qdrant-key <key>         Qdrant API key
  --openai-key <key>         OpenAI API key
  --ollama-url <url>         Ollama server URL
  --gemini-key <key>         Gemini API key
  --openai-compat-base-url   OpenAI-compatible base URL
  --openai-compat-key        OpenAI-compatible API key

环境变量

所有CLI选项都可以通过环境变量设置：

变量 CLI标志
DEEPMATCH_PATHS --path
DEEPMATCH_PROVIDER --provider
DEEPMATCH_MODEL --model
DEEPMATCH_EMBEDDING_DIM --embedding-dim
DEEPMATCH_BATCH_SIZE --batch-size
DEEPMATCH_MAX_FILES --max-files
DEEPMATCH_QDRANT_URL --qdrant-url
DEEPMATCH_QDRANT_API_KEY --qdrant-key
DEEPMATCH_OPENAI_API_KEY --openai-key
DEEPMATCH_OLLAMA_URL --ollama-url
DEEPMATCH_GEMINI_API_KEY --gemini-key
DEEPMATCH_OPENAI_COMPAT_BASE_URL --openai-compat-base-url
DEEPMATCH_OPENAI_COMPAT_API_KEY --openai-compat-key

CLI标志优先于环境变量。

例子

使用OpenAI：

npx deepmatch-mcp \
  --path /path/to/your/repo \
  --provider openai \
  --openai-key sk-xxx

与Ollama：

npx deepmatch-mcp \
  --path /path/to/repo1 \
  --path /path/to/repo2 \
  --provider ollama \
  --ollama-url http://localhost:11434 \
  --model qwen3-embedding:0.6b

对于环境变量：

export DEEPMATCH_PATHS="/path/to/repo"
export DEEPMATCH_PROVIDER="openai"
export DEEPMATCH_OPENAI_API_KEY="sk-xxx"
npx deepmatch-mcp

MCP客户端配置

对于Claude Desktop，请在MCP设置中添加：

{
  "mcpServers": {
    "deepmatch": {
      "command": "npx",
      "args": ["deepmatch-mcp", "--path", "/path/to/repo", "--provider", "openai"],
      "env": {
        "DEEPMATCH_OPENAI_API_KEY": "sk-xxx"
      }
    }
  }
}

MCP工具

search

使用语义相似性搜索代码。

输入架构：

参数 类型 必填 说明
query string 是 自然语言搜索查询
limit number No 最大结果（1-50，默认值：10）
paths string[] 否 筛选到特定的存储库路径
minScore number No 最小相似性得分（0-1）

输出：

{
  "total_count": 5,
  "items": [
    {
      "filePath": "/repo/src/auth.ts",
      "repoPath": "/repo",
      "startLine": 10,
      "endLine": 25,
      "codeChunk": "function authenticate(token: string) {...}",
      "score": 0.92
    }
  ]
}

本地开发

设置

# Clone and install
git clone https://github.com/657KB/deepmatch-mcp
cd deep-match
npm install

开发工作流程

# Run tests (TDD)
npm test

# Run tests in watch mode
npx vitest

# Build TypeScript
npm run build

# Test the CLI
node dist/cli.js --help

项目结构

src/
├── cli.ts                 # Main entry point
├── config/
│   ├── schema.ts          # Zod schemas and defaults
│   ├── index.ts           # CLI/ENV parsing
│   └── config.test.ts
├── providers/
│   ├── types.ts           # IEmbedder interface
│   ├── embedders.ts       # Provider implementations
│   ├── index.ts
│   └── embedders.test.ts
├── store/
│   ├── types.ts           # IVectorStore interface
│   ├── qdrant.ts          # Qdrant implementation
│   ├── index.ts
│   └── qdrant.test.ts
├── chunker/
│   ├── extensions.ts      # Supported file extensions
│   ├── chunker.ts         # Line-based chunking
│   ├── index.ts
│   └── chunker.test.ts
├── scanner/
│   ├── scanner.ts         # Directory traversal
│   ├── index.ts
│   └── scanner.test.ts
├── indexer/
│   ├── index-manager.ts   # Batch indexing orchestration
│   ├── index.ts
│   └── index-manager.test.ts
├── watcher/
│   ├── file-watcher.ts    # Chokidar file watching
│   ├── index.ts
│   └── file-watcher.test.ts
└── mcp/
    ├── server.ts          # MCP server + search tool
    ├── index.ts
    └── server.test.ts

运行测试

# Run all tests
npm test

# Run specific test file
npx vitest src/chunker/chunker.test.ts

# Run with coverage
npx vitest --coverage

配置默认值（Roo代码对齐）

参数 默认值 说明
batchSize 60 嵌入批量大小
maxFiles 50000 可索引的最大文件数
chunkMin 50 最小块大小（字符）
chunkMax 1000 最大块大小（字符）
chunkMaxTolerance 1.15 最大尺寸的公差系数
chunkRebalanceMin 200 触发再平衡的最小剩余量
qdrantUrl http://localhost:6333 Qdrant服务器URL

文件筛选

支持的扩展

TypeScript、JavaScript、Python、Java、C/C++、C#、Go、Rust、Ruby、PHP、Swift、Kotlin、Scala、Lua、R、Perl、Shell、SQL、HTML、CSS、JSON、YAML、XML、Markdown、Vue、Svelte

排除目录

node_modules, dist, build, target, .git，隐藏目录， __pycache__, venv, .next, .nuxt, coverage, vendor, Pods, .gradle, .idea, .vscode

附加过滤器

  • 跳过大于1MB的文件
  • .gitignore 遵守规则（为嵌套目录堆叠）

许可证

麻省理工学院

相关 MCP