Semantica Search MCP

语义搜索MCP

🔍 Claude code的语义代码搜索 -使用带有AI嵌入的自然语言对代码库进行索引和搜索

______________________________________________________________________

为什么选择Semantica？

问题： 查找代码 grep 或者正则表达式速度慢，需要精确的语法，并且缺少语义关系。

解决方案： Semantica使用AI嵌入为您的代码库建立索引，实现自然语言搜索：

❌ Traditional: grep -r "def authenticate" app/
✅ Semantica: "Find authentication logic"
   → Returns auth functions, middleware, login flows across all files

实例：

• “数据库连接在哪里配置？”→ 返回数据库设置和连接代码
• “显示错误处理模式”→ 返回try/catch块、错误类、救援块
• “查找用户验证逻辑”→ 返回验证器、服务方法、模型验证

______________________________________________________________________

✨ 主要特点

🚀 生产准备就绪（第1-3阶段完成）

• ✅ 索引成功率100% -AST分割合并分块消除了错误
• ✅ 比本地快2倍 -OpenAI提供商的表现优于Ollama
• ✅ 自动重新索引 -Git挂钩保持索引新鲜（\

cd semantica-search-mcp npm install && npm run build

3. Configure Claude Code

Add to ~/.config/claude/claude_desktop_config.json (Linux)

Or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

{ "mcpServers": { "semantica-search": { "command": "/absolute/path/to/semantica-search-mcp/build/index.js" } } }

4. Index your first project

In Claude Code:

"Index the codebase at /path/to/your-project"

### 选项2：云设置（快速、可扩展）

**先决条件：** OpenAI API密钥

1. Install Semantica (same as Option 1, steps 2-3)

2. Set API key

export OPENAI_API_KEY="sk-..."

3. Create project config

In your project: .semantica/config.json

{ "embedding": { "provider": "openai", "model": "text-embedding-3-small", "dimensions": 1536, "batchSize": 128, "concurrency": 3, "openai": { "apiKey": "${OPENAI_API_KEY}", "timeout": 30000 } }, "vectordb": { "provider": "milvus", "collectionName": "my_project" } }

4. Index your project (same as Option 1)

______________________________________________________________________

## ⚙️ 配置指南

### 配置文件位置

`.semantica/config.json` 在项目根目录中

### 完整配置参考

{ "version": "1.0.0",

"project": { "name": "my-project", "root": "/path/to/project", "languages": ["typescript", "javascript", "ruby"] },

"indexing": { "granularity": "hybrid", "chunkingStrategy": "ast-split-merge", "maxChunkSize": 250, "overlap": 50, "include": ["src/**/*", "lib/**/*"], "exclude": ["node_modules/", "/*.test.*"], "languageConfig": { "typescript": { "extensions": [".ts", ".tsx"], "chunkTypes": ["function", "class", "interface", "type"] }, "ruby": { "extensions": [".rb"], "chunkTypes": ["def", "class", "module"] } } },

"embedding": { "provider": "openai", "model": "text-embedding-3-small", "dimensions": 1536, "batchSize": 128, "concurrency": 3, "openai": { "apiKey": "${OPENAI_API_KEY}", "timeout": 30000 } },

"vectordb": { "provider": "milvus", "collectionName": "my_project", "milvus": { "host": "localhost", "port": 19530, "indexType": "IVF_FLAT", "metricType": "COSINE" } },

"search": { "strategy": "hybrid", "maxResults": 10, "minScore": 0.5, "hybrid": { "vectorWeight": 0.7, "keywordWeight": 0.3 } } }

### 配置选项说明

#### `indexing` -要索引哪些文件

|选项|类型|描述|最佳实践|
| ------------------ | -------------------------------------- | -------------------------- | -------------------------------------- |
| `granularity` | `"hybrid"` | `"function"` | `"file"` |如何拆分代码|使用 `"hybrid"` （最佳平衡）|
| `chunkingStrategy` | `"ast-split-merge"` |分块算法|使用 `"ast-split-merge"` （100%成功）|
| `maxChunkSize` |number |每个块的最大令牌数|250（最适合嵌入）|
| `include` |string\[\]|要索引的全局模式| `["src/**/*", "app/**/*"]` |
| `exclude` |string\[\]|要跳过的全局模式| `["**/*.test.*", "node_modules/**"]` |
| `languageConfig` |object |语言特定设置|为每种语言定义|

**最佳实践：**

{ "include": ["src/**/*", "lib/**/*"], // Core code only "exclude": [ "node_modules/", // Dependencies "/*.test.*", // Tests "**/*.spec.*", // Specs "dist/", // Build output "coverage/" // Test coverage ] }

#### `embedding` -如何生成嵌入

|选项|类型|描述|最佳实践|
| ------------- | ------------------------ | ----------------- | -------------------------------------------------- |
| `provider` | `"ollama"` | `"openai"` |嵌入服务| Ollama：免费/本地，OpenAI：快速/云|
| `model` |string |型号名称| `"nomic-embed-text"` 或 `"text-embedding-3-small"` |
| `dimensions` |数字|矢量维度|768（Ollama）或1536（OpenAI）|
| `batchSize` |number |每批块数|64-128（平衡速度/内存）|
| `concurrency` |number |并行批次|3-5（基于提供商级别）|

**Ollama设置（本地，免费）：**

{ "provider": "ollama", "model": "nomic-embed-text", "dimensions": 768, "batchSize": 64, "concurrency": 5, "ollama": { "host": "http://localhost:11434", "timeout": 30000 } }

**OpenAI设置（云，快速）：**

{ "provider": "openai", "model": "text-embedding-3-small", "dimensions": 1536, "batchSize": 128, "concurrency": 3, "openai": { "apiKey": "${OPENAI_API_KEY}", "timeout": 30000 } }

#### `vectordb` -在哪里存储矢量

|选项|类型|描述|最佳实践|
| ---------------- | ------------ | --------------------- | --------------------------------- |
| `provider` | `"milvus"` |矢量数据库|使用 `"milvus"` （成熟、可扩展）|
| `collectionName` |string |集合/索引名称|每个项目唯一|
| `host` |string |数据库主机| `"localhost"` 对于本地|
| `port` |number |数据库端口|19530（Milvus默认值）|
| `indexType` | `"IVF_FLAT"` |索引算法| `"IVF_FLAT"` （平衡良好）|
| `metricType` | `"COSINE"` |距离度量| `"COSINE"` （最适合代码）|

#### `search` -如何搜索

|选项|类型|描述|最佳实践|
| --------------- | ---------- | --------------------- | ---------------------------- |
| `strategy` | `"hybrid"` |搜索算法|使用 `"hybrid"` （改善40%）|
| `maxResults` |number |要返回的结果|10-20（避免淹没）|
| `minScore` |number |相似度阈值|0.5-0.7（按项目调整）|
| `vectorWeight` |number |语义权重（0-1）|0.7（语义偏好）|
| `keywordWeight` |number |关键字权重（0-1）|0.3（补码）|

______________________________________________________________________

## 🎯 最佳实践

### 适用于小型项目（\
cd semantica-search-mcp
npm install
npm run build

开发流程

npm run watch          # Auto-rebuild on changes
npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report
npm run inspector     # MCP debugging

代码质量

• TypeScript：严格模式已启用
• 测试：80%以上的覆盖率目标
• 掉毛：自动格式化
• 建筑：可扩展性的提供者模式

______________________________________________________________________

📈 性能指标

索引性能（第2阶段→ 第3阶段）

搜索质量

______________________________________________________________________

🔒 安全与隐私

数据处理

Ollama（当地）：

• ✅ 100%本地处理
• ✅ 没有数据离开您的机器
• ✅ 完全隐私

OpenAI（云）：

• ⚠️ 发送到OpenAI API的代码块
• ⚠️ 仅嵌入（OpenAI无法搜索）
• ⚠️ 为API键使用环境变量（从不提交！）

API密钥管理

永远不要提交API密钥：

{
  "openai": {
    "apiKey": "${OPENAI_API_KEY}" // ✅ Environment variable
  }
}

不是这个：

{
  "openai": {
    "apiKey": "sk-proj-..." // ❌ NEVER hardcode!
  }
}

______________________________________________________________________

🎯 常见问题解答

Q： 索引需要多长时间？ A： 3s-15分钟，具体取决于尺寸。小项目（\<100个文件）：\<30s。大型项目（5K+文件）：10-15分钟。 这是一次性的 -增量更新小于10秒！

Q： OpenAI的价格是多少？ A： 初始指数为每个项目0.001-0.20美元。每日更新：\<0.10美元。大多数项目的成本比一杯咖啡还低！ ☕

Q： 我可以在Ollama和OpenAI之间切换吗？ A： 是的！只需更新配置并重新索引（维度更改需要清除旧索引）。

Q： 如果索引中断会发生什么？ A： 重新运行。这是一个一次性操作，为了简单起见，不需要检查点。

Q： 它离线工作吗？ A： 与Ollama合作：是（100%本地）。OpenAI:NO（需要互联网）。

Q： 这与Cursor或GitHub Copilot相比如何？ A： 光标在1-3分钟内索引~500-2K个文件（带缓存）。我们在12-13分钟内对所有文件（8K+）进行索引。考虑到覆盖范围，速度更完整，可比。

______________________________________________________________________

🚀 接下来是什么

完成✅

• 第一阶段：TypeScript/Ruby、Ollama、Milvus、AST分块
• 第2阶段：100%成功，自动重新索引，JavaScript，性能
• 第3.1阶段：OpenAI提供商、用户体验改进、测试

进行中🔄

• 第3.2阶段：Qdrant矢量数据库提供程序（更轻便的替代品）
• 第3.3阶段：专业文件
• 第3.4阶段：版本v2.1.0

未来🔮

• Python、Go、Java语言支持
• 嵌入缓存（重新索引速度提高50-70%）
• BM25关键字搜索
• Web仪表板UI

______________________________________________________________________

📄 许可证

私人（目前）

______________________________________________________________________

🙏 致谢

基于以下研究构建：

• cAST:AST感知代码块
• 光标代码索引
• 克劳德上下文MCP

______________________________________________________________________

问题或议题？ 检查 文档 或制造问题。

准备好开始了吗？ 跟随 快速开始 上面的向导！ 🚀