搜索上下文MCP服务器
一个通用的MCP服务器，使用Gemini文件搜索对文档进行语义搜索。
它做什么：查询云中的Gemini FileSearchStores，并返回AI生成的答案和源引用。
它不做什么：索引文件、管理git仓库或运行工作流。索引是单独进行的（例如，通过文档仓库中的GitHub Actions或任何自定义管道）。
特性
- 🔍 使用Gemini File search API进行语义搜索
- 🤝 通过Gemini API动态发现存储（无需本地配置）
- 🧠 带有源引用的自然语言查询
- ⚡ 令牌高效响应（默认情况下约500-1000个令牌）
- 📊 双格式：Markdown（人类可读）和JSON（程序化）
- 🌐 通用：适用于您创建的任何Gemini FileSearchStores
______________________________________________________________________
建筑
Your indexing pipeline → Gemini FileSearchStores (cloud)
↓
search-context MCP server (local)
↓
Claude要点:
- MCP服务器 仅查询 基于云的FileSearchStores
- 是否 不 与git repos或本地文件交互
- 商店由以下人员创建和更新 你的 索引工作流程
- 服务器通过以下方式动态发现存储
client.file_search_stores.list()
______________________________________________________________________
快速开始
推荐： npx
npx -y github:ain3sh/search-context不需要克隆。始终使用GitHub上的最新版本。
来源
git clone https://github.com/ain3sh/search-context.git
cd search-context
npm install
npm run build
npm start______________________________________________________________________
配置
环境变量
GEMINI_API_KEY（必填）：您的Gemini API密钥LOG_LEVEL*（可选）*:debug,info，或error（默认值：info)
获取API密钥： https://aistudio.google.com/apikey
克劳德桌面
增添 ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"search-context": {
"command": "npx",
"args": ["-y", "github:ain3sh/search-context"],
"env": {
"GEMINI_API_KEY": "your_api_key_here"
}
}
}
}克劳德代码（项目级）
创建 .mcp.json 在项目根目录中：
{
"mcpServers": {
"search-context": {
"type": "stdio",
"command": "npx",
"args": ["-y", "github:ain3sh/search-context"],
"env": {
"GEMINI_API_KEY": "${GEMINI_API_KEY}"
}
}
}
}然后设置：
export GEMINI_API_KEY=your_api_key_here______________________________________________________________________
用法
发现商店
商店作为MCP资源公开。客户可以通过以下方式发现它们 resources/list.
服务器在启动时查询Gemini的API以查找所有可用的FileSearchStores，并将其公开为URI：
store://context
store://Factory-AI/factory
store://other-docs备注：店铺名称来自 displayName 您在创建FileSearchStore时设置的字段。
搜索文档
使用 search_context 带有自然语言查询的工具：
// Minimal query (common case)
search_context({
store: "context",
query: "How does File Search chunking work?"
})
// → ~500–1000 tokens, answer + citations
// With evidence chunks (for verification)
search_context({
store: "context",
query: "authentication flow setup",
include_chunks: true
})
// → ~2000–3000 tokens, answer + citations + chunk previews参数
store（字符串，必填）：MCP资源中的存储名称
例如 "context", "Factory-AI/factory"
query（字符串，必填）：自然语言查询include_chunks*（布尔值，可选）*：包括块预览（默认值：false)top_k*（数字，可选）*：检索块时include_chunks=true
违约： 3，最大值： 20
response_format*（字符串，可选）*:"markdown"或"json"（默认值："markdown")metadata_filter*（字符串，可选）*：使用高级过滤器 列表筛选器语法
响应格式
默认值(response_format="markdown", include_chunks=false):
# Search Results: context
**Query**: How does chunking work?
**Response**:
[Synthesized answer from semantic search]
---
**Sources** (2 files):
- ai.google.dev_gemini-api_docs_file-search.md
- CONTEXT_SEARCH_MCP_SPEC.md有大块(include_chunks=true):
[... same as above, plus ...]
---
## Retrieved Context Chunks
### [1] ai.google.dev_gemini-api_docs_file-search.md
Files are automatically chunked when imported into a file search store...
[truncated to 500 chars per chunk]
---JSON响应包括结构化 query, response, sources，可选 chunks[].
______________________________________________________________________
性能和成本
代币效率
优化响应以避免上下文垃圾邮件：
| 模式 | 代币（约） | 内容 |
|---|---|---|
默认值(include_chunks=false) | ~500–1000 | 综合答案+源引用 |
有大块(include_chunks=true) | ~2000–3000 | 答案+来源+500个字符块预览 |
保障措施：
- 块预览截断为500个字符
- 完整回复，最多25000个字符
- 将元数据缓存5分钟
成本模型（Gemini文件搜索）
对于MCP服务器 （查询）：
- 查询：免费；检索到的区块作为正常上下文令牌向您的Gemini API使用收费
用于索引 （由您的管道单独完成）：
- 索引：每1M代币约0.15美元（每个文件一次；仅在文件更改时重新运行）
- 存储：免费
月度估算示例 （如果使用每日索引工作流）：
- 100个文件（约150k个令牌）：每次同步约0.0225美元
- 每日同步，小变化： 约0.25美元至1美元/月
- 重度流失/积极开发： 约3至6美元/月
______________________________________________________________________
设置索引（与MCP服务器分开）
MCP服务器 仅查询 现有的Gemini文件搜索商店。您需要一个单独的过程来创建和更新这些存储。
选项1:GitHub操作工作流
如果你有一个文档存储库，你可以使用GitHub Actions自动索引。
示例：参见 ain3sh/docs 为了完整实施：
mirrors.json：要索引的存储库/目录的配置.github/scripts/sync.py：创建/更新FileSearchStores的脚本.github/workflows/sync.yml：每天运行并随变化而变化的工作流
关键步骤:
- 集
GEMINI_API_KEY作为存储库秘密 - 创建一个工作流，该工作流：
- 克隆/获取文档文件 - 使用Gemini文件搜索API创建/更新存储 - 设置a displayName 对于每个商店（这将成为MCP中的商店名称）
- 运行每日或文件更改
选项2：自定义管道
您可以从任何环境中进行索引：
from google import genai
client = genai.Client(api_key=os.getenv("GEMINI_API_KEY"))
# Create a store
store = client.file_search_stores.create(
display_name="my-docs" # This becomes store://my-docs in MCP
)
# Upload files
for file_path in doc_files:
client.file_search_stores.upload_file(
store_id=store.id,
path=file_path
)店铺命名
这 displayName 创建FileSearchStore时设置为其MCP资源URI：
# In your indexing script:
store = client.file_search_stores.create(display_name="context")
# In MCP:
search_context({ store: "context", query: "..." })______________________________________________________________________
发展
本地开发
# Install dependencies
npm install
# Build
npm run build
# Development mode (auto-reload)
npm run dev
# Run with API key
GEMINI_API_KEY=your_key npm start项目结构
search-context/
├── src/
│ └── index.ts # Main MCP server implementation
├── dist/
│ └── index.js # Compiled output (committed for npx)
├── package.json # Includes bin field for CLI
├── tsconfig.json
└── README.md快速本地测试
npm run build
timeout 5s GEMINI_API_KEY=your_key npx .MCP服务器寿命长；真正的测试最好通过MCP客户端（Claude Desktop、Claude Code等）进行。
______________________________________________________________________
故障排除
未找到商店
错误: Error: Store 'xyz' not found
检查:
- 商店位于Gemini（访问 谷歌人工智能工作室)
- 商店已上传文件
- 商店
displayName匹配您正在查询的内容 - 重新启动MCP服务器（启动时缓存存储列表）
API关键问题
症状: UNAUTHENTICATED, Invalid API key
检查:
GEMINI_API_KEY在environment/config中设置- 主要工作地点 https://aistudio.google.com/apikey
- 已启用文件搜索API访问
- 未超过配额（免费等级~1500 RPD）
无结果
症状: "No results found"
尝试:
- 更广泛或更精确的查询措辞
- 确认文件存在于商店中（检查Google AI Studio）
- 确认索引已成功完成
- 使用更接近文档措辞的术语
- 确保文件使用支持的格式（Markdown、文本、PDF等）
速率限制
错误: 429, RESOURCE_EXHAUSTED
- 自由层：~15转/分
- 等待60秒后重试
- 降低查询率
- 如果需要，升级到付费级别
客户端中未加载服务器
症状：MCP客户端未显示 search-context
检查:
npm run build无错误地完成
- MCP配置JSON有效
- 客户端日志（例如。
~/Library/Logs/Claude/mcp*.log)
npx可以访问GitHub
- 手动运行工作：
GEMINI_API_KEY=key npx -y github:ain3sh/search-context______________________________________________________________________
许可证
MIT许可证——见 LICENSE.