内容
# TFModSearch MCP 服务器
[](https://github.com/SantyagoSeaman/tfmodsearch/actions/workflows/ci.yml)
[](https://pypi.org/project/tfmodsearch/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
**模型上下文协议（MCP）** 服务器，提供使用混合搜索（关键词匹配、BM25 和语义嵌入）为 Terraform AWS 模块文档提供智能搜索功能。
**立即使用**：包含 54 个精选 Terraform AWS 模块的预建搜索索引。安装并立即运行 MCP 服务器 - 无需构建索引！
## 🤔 为什么选择 TFModSearch？
当 AI 助手编写 Terraform 时，它经常会猜测模块名称，发明不存在的变量，或使用过时的语法。TFModSearch 为您的助手提供了一个 **精选、版本化、离线知识库**，包含官方的 [`terraform-aws-modules`](https://github.com/terraform-aws-modules)，因此它可以：
- **从意图中查找正确的模块** - “我需要一个 Redis 缓存” 解析为 `elasticache`，而不是虚构的模块名称。
- **用真实输入/输出定位生成的代码** - 助手按需获取完整的、当前的模块文档（子模块、变量、输出、示例），而不是临时编造。
- **保持快速、私有和确定性** - 搜索在 CPU 上本地运行，针对预建索引。无需外部 API 调用，无速率限制，无网络往返。
将其视为一个始终可用的、可搜索的参考卡，适用于每个 terraform-aws-modules 模块 - 保持准确并随时可用。
## 🚀 功能
- **混合搜索引擎**：结合关键词匹配（IDF 加权）、BM25 文本相关性、精确模块名称匹配和语义相似性，以获得准确的结果
- **MCP 集成**：与 Claude Desktop 和其他 MCP 客户端无缝集成
- **快速高效**：使用 `intfloat/e5-small-v2` 模型的预建搜索索引，仅使用 CPU 推理
- **立即使用**：包含预建索引（`model/tfmod_e5_small_index.pkl`）和来自 `intfloat/e5-small-v2` 模型的嵌入，以及精选的 Terraform AWS 模块文档
- **全面的目录**：访问从官方来源编译的 terraform-aws-modules 文档，包含丰富的元数据
- **安全优先**：内置路径验证和访问控制，用于安全的 文件操作
- **可配置权重**：通过 YAML 配置或 CLI 参数微调搜索评分
## 📋 目录
- [为什么选择 TFModSearch？](#-为什么选择-tfmodsearch)
- [安装](#-安装)
- [插件安装（Claude Code / Codex）](#插件安装claude-code--codex--推荐)
- [快速安装（任何 MCP 客户端）](#快速安装任何-mcp-客户端)
- [快速入门](#-快速入门)
- [Claude Code CLI 集成](#claude-code-cli-集成)
- [Claude Desktop 集成](#claude-desktop-集成)
- [Codex CLI 集成](#codex-cli-集成)
- [GitHub Copilot 集成（VS Code）](#github-copilot-集成vs-code)
- [用法](#-用法)
- [构建索引](#1-构建索引)
- [CLI 搜索（独立）](#2-cli-搜索独立)
- [MCP 工具](#-mcp-工具)
- [配置](#️-配置)
- [开发](#-开发)
- [测试](#-测试)
- [架构](#-架构)
- [索引模块](#索引模块)
- [贡献](#-贡献)
- [许可证](#-许可证)
## 📦 安装
### 插件安装（Claude Code / Codex — 推荐）
插件会自动配置 MCP 服务器 **和** 添加工作流技能，使代理在编写 Terraform 之前搜索当前模块文档。
**Claude Code：**
```bash
/plugin marketplace add SantyagoSeaman/tfmodsearch
/plugin install tfmod-search@tfmodsearch
```
**Codex CLI：**
```bash
/plugin marketplace add SantyagoSeaman/tfmodsearch
/plugin install tfmod-search@tfmodsearch
```
两者都包含：
- **tfmod-search MCP 服务器**（通过 `uvx tfmodsearch` 运行 - 需要 [uv](https://github.com/astral-sh/uv)）
- **七种技能**：
- `aws-terraform-modules` - 自动调用编写 AWS Terraform 时：先搜索，然后从当前文档编写，固定版本
- `/tf-module <query>` - 即时模块查找，附带可粘贴的代码片段
- `/tf-stack <requirement>` - 用正确的输出→输入连接搭建多模块堆栈
- `tf-migrate` - 用覆盖模块替换手写的 `aws_*` 资源，逐个属性验证
- `tf-module-upgrade` - 审计固定的版本和变量用法与当前文档
- `tf-review` - 审查差异或 PR 的模块用法
- `tf-troubleshoot` - 诊断 Terraform 失败；附带预过滤脚本，可将任意大小的日志减少到仅诊断信息
- **两个子代理**（Claude Code）：`tf-log-analyst` 和 `tf-diff-reviewer` 在隔离的上下文中分析大型日志和差异，因此您的会话仅看到发现结果
### 快速安装（任何 MCP 客户端）
服务器位于 PyPI - 无需克隆存储库。
**首先安装 uv**（如果尚未安装）：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
然后将其添加到您的 MCP 客户端配置中：
```json
{
"mcpServers": {
"terraform-modules": {
"command": "uvx",
"args": ["tfmodsearch"]
}
}
}
```
> **提示**：在安装后运行 `uvx tfmodsearch --warmup` 一次 - 它会预下载嵌入模型（~130 MB）并验证服务器端到端，因此第一个真正的查询是瞬间的。
> **捆绑并准备就绪**：预建的搜索索引和所有 54 个模块文档 **包含在** 包中，因此 `uvx` 获取、安装并运行服务器，而无需克隆或重建。（`intfloat/e5-small-v2` 嵌入模型 - ~130 MB - 在第一次搜索时自动下载以编码您的查询，然后缓存后续查询。）
> **注意**：如果您遇到“命令未找到”错误，请使用 `uvx` 的完整路径：
> ```bash
> # 查找 uvx 位置
> which uvx
> # 示例输出：/Users/username/.local/bin/uvx
> ```
> 然后在您的配置中使用完整路径：
> ```json
> "command": "/Users/username/.local/bin/uvx"
> ```
### 先决条件
- Python 3.13 或更高版本
- [uv](https://github.com/astral-sh/uv)（推荐）或 pip
### 本地安装（用于开发）
```bash
# 克隆存储库
git clone https://github.com/SantyagoSeaman/tfmodsearch.git
cd tfmodsearch
# 创建虚拟环境并安装依赖项
uv venv --python 3.13
source .venv/bin/activate # 在 Windows 上：.venv\Scripts\activate
uv pip install -e .
```
### 使用 pip
```bash
# 克隆存储库
git clone https://github.com/SantyagoSeaman/tfmodsearch.git
cd tfmodsearch
# 创建虚拟环境并安装依赖项
python -m venv .venv
source .venv/bin/activate # 在 Windows 上：.venv\Scripts\activate
pip install -e .
```
**立即使用**：存储库包含预建的搜索索引，因此您可以在安装后跳过索引构建步骤并立即运行 MCP 服务器！
## 🏃 快速入门
### 1. 构建搜索索引（可选）
**注意**：此存储库包含预建的搜索索引 `model/tfmod_e5_small_index.pkl`，其中包含 54 个精选 Terraform AWS 模块的嵌入。您可以跳过此步骤，直接测试或运行服务器。
要重建索引或使用其他模块创建新索引：
```bash
python src/tfmod_search_cli.py index \
--docs_dir ./modules/terraform-aws-modules
```
**注意**：第一次运行将下载 `intfloat/e5-small-v2` 模型（~130MB）。
### 2. 测试搜索（CLI）
使用命令行界面测试搜索功能：
```bash
python src/tfmod_search_cli.py search \
--query "s3 bucket with kms encryption and versioning" \
--top_k 5
```
#### Claude Code CLI 集成
> **更喜欢 [插件安装](#插件安装claude-code--codex--推荐)** - 它在两个命令中配置服务器并添加工作流技能。
**选项 1：使用 uvx（无需克隆）**
```bash
claude mcp add terraform-modules -- uvx tfmodsearch
```
或将其添加到您的 Claude Code 设置（`~/.claude/settings.json`）：
```json
{
"mcpServers": {
"terraform-modules": {
"command": "uvx",
"args": ["tfmodsearch"]
}
}
}
```
> **注意**：如果找不到 `uvx`，请使用完整路径（运行 `which uvx` 查找）：
> ```json
> "command": "/Users/username/.local/bin/uvx"
> ```
**选项 2：使用本地安装**
```bash
# 添加 MCP 服务器（替换为实际路径）
claude mcp add --transport stdio terraform-modules -- \
/absolute/path/to/tfmodsearch/.venv/bin/python \
/absolute/path/to/tfmodsearch/src/tfmod_mcp_server.py
# 验证服务器已添加
claude mcp list
```
或手动添加到您的 Claude Code 设置（`~/.claude/settings.json`）：
```json
{
"mcpServers": {
"terraform-modules": {
"command": "/absolute/path/to/tfmodsearch/.venv/bin/python",
"args": [
"/absolute/path/to/tfmodsearch/src/tfmod_mcp_server.py"
]
}
}
}
```
#### Claude Desktop 集成
将其添加到您的 Claude Desktop 配置（macOS 上 `~/Library/Application Support/Claude/claude_desktop_config.json`）：
**选项 1：使用 uvx（推荐 - 无需克隆）**
```json
{
"mcpServers": {
"terraform-modules": {
"command": "uvx",
"args": ["tfmodsearch"]
}
}
}
```
> **注意**：如果找不到 `uvx`，请使用完整路径（运行 `which uvx` 查找）：
> ```json
> "command": "/Users/username/.local/bin/uvx"
> ```
**选项 2：使用本地安装**
```json
{
"mcpServers": {
"terraform-modules": {
"command": "/absolute/path/to/tfmodsearch/.venv/bin/python",
"args": [
"/absolute/path/to/tfmodsearch/src/tfmod_mcp_server.py"
]
}
}
}
```
#### Codex CLI 集成
> **更喜欢 [插件安装](#插件安装claude-code--codex--推荐)** - 它在两个命令中配置服务器并添加工作流技能。
对于手动设置，请全局注册服务器：
```bash
codex mcp add tfmod-search -- uvx tfmodsearch
```
或将其添加到 `~/.codex/config.toml`（全局）或 `.codex/config.toml`（每个项目）：
```toml
[mcp_servers.tfmod-search]
command = "uvx"
args = ["tfmodsearch"]
startup_timeout_sec = 30 # 默认 10s 太紧，而嵌入模型加载时
```
> **首次运行**：在之前执行 `uvx tfmodsearch --warmup` 一次 - 它会下载嵌入模型（~220 MB），因此服务器启动时间保持在超时范围内。
要提示 Codex（或任何代理）使用服务器，请在项目的 `AGENTS.md`（或 Claude Code 的 `CLAUDE.md`）中添加一行：
```markdown
编写使用 AWS 的 Terraform 之前，请调用 tfmod-search MCP 服务器：
search_modules 查找模块，然后 get_module 获取当前变量
名称和版本。不要从内存中编写模块块。
```
#### GitHub Copilot 集成（VS Code）
将 MCP 服务器添加到 GitHub Copilot in VS Code（需要 VS Code 1.99+）：
**步骤 1**：在项目根目录中创建 `.vscode/mcp.json`（或通过命令面板打开用户级配置：`MCP: Open User Configuration`）：
**选项 1：使用 uvx（推荐 - 无需克隆）**
```json
{
"servers": {
"terraform-modules": {
"type": "stdio",
"command": "uvx",
"args": ["tfmodsearch"]
}
}
}
```
> **注意**：如果找不到 `uvx`，请使用完整路径（运行 `which uvx` 查找）。
**选项 2：使用本地安装**
```json
{
"servers": {
"terraform-modules": {
"type": "stdio",
"command": "/absolute/path/to/tfmodsearch/.venv/bin/python",
"args": [
"/absolute/path/to/tfmodsearch/src/tfmod_mcp_server.py"
]
}
}
}
```
**步骤 2**：单击 `mcp.json` 文件顶部的“Start”按钮以初始化服务器。
**步骤 3**：打开 GitHub Copilot Chat，选择 **Agent** 模式从弹出菜单中，点击工具图标以验证 `terraform-modules` 服务器及其工具是否可用。
**替代设置方式**：
1. 打开命令面板（`Cmd+Shift+P` 在 macOS 上 / `Ctrl+Shift+P` 在 Windows/Linux 上）
2. 运行“MCP: 添加服务器”
3. 选择“stdio”作为服务器类型
4. 输入 `terraform-modules` 作为服务器名称
5. 输入 Python 路径作为命令
6. 输入脚本路径作为参数
**管理 MCP 服务器**：
- “MCP: 列出服务器” - 查看已安装的服务器和可用操作
- “MCP: 重置缓存工具” - 刷新工具发现，如果工具未显示
- “MCP: 显示输出” - 调试服务器连接问题
更多详细信息，请参阅 [VS Code MCP 文档](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) 和 [GitHub Copilot MCP 指南](https://docs.github.com/copilot/customizing-copilot/using-model-context-protocol/extending-copilot-chat-with-mcp)。## 📖 用法
### 1. 构建索引
**注意**：存储库包含预构建的索引 - 您只需在需要添加更多模块或自定义现有模块时构建新索引。
使用模块文档构建或重建搜索索引：
```bash
python src/tfmod_search_cli.py index \
--docs_dir ./modules/terraform-aws-modules \
--index_path ./model/tfmod_e5_small_index.pkl
```
**选项**：
- `--docs_dir`: 包含 Terraform 模块 Markdown 文件的目录（必需）
- `--index_path`: pickled 索引文件的输出路径（可选，默认为 `./model/tfmod_e5_small_index.pkl`）
- `--model`: 使用的句子转换器模型（默认：`intfloat/e5-small-v2`）
### 2. CLI 搜索（独立）
在不运行 MCP 服务器的情况下搜索模块：
```bash
# 按功能搜索
python src/tfmod_search_cli.py search \
--query "kubernetes cluster management" \
--top_k 3
# 按确切模块名称搜索
python src/tfmod_search_cli.py search \
--query "vpc" \
--top_k 5
# 使用自定义权重搜索
python src/tfmod_search_cli.py search \
--query "object storage with encryption" \
--w_kw 2.5 \
--w_exact 4.0 \
--w_bm25 1.5 \
--w_sem 1.0
# 使用 BGE 模型的查询指令
python src/tfmod_search_cli.py search \
--query "s3" --query-instruction "Represent this sentence for searching relevant passages: "
```
# query_instruction: "为搜索相关段落表示此句子： "
query_instruction: null
search_weights:
w_kw: 1.0 # 关键词重叠权重（IDF加权）
w_exact: 3.0 # 精确模块名称匹配提升
w_bm25: 2.0 # BM25 文本相关性权重
w_sem: 3.0 # 语义相似性权重
```
> 上面的值是存储库 `config.yaml`（与软件包捆绑）中附带的权重，因此它们是服务器开箱即用的默认设置。
**配置优先级**（从高到低）：
1. 命令行参数（`--w_kw`、`--w_exact`、`--query-instruction`等）
2. `config.yaml` 文件
3. 内置默认值
### 模块文档格式
Terraform 模块文档文件应为带有 YAML 前置信息的 Markdown：
```yaml
---
module_name: terraform-aws-vpc
keywords: [vpc, subnet, networking, aws]
---
# Terraform AWS VPC 模块
模块描述和文档...
```
## 👩💻 开发
### 设置开发环境
```bash
# 克隆存储库
git clone https://github.com/SantyagoSeaman/tfmodsearch.git
cd tfmodsearch
# 安装开发依赖项
uv pip install -e ".[dev]"
# 安装预提交钩子
pre-commit install
```
### 开发依赖项
该项目包含以下开发工具：
- **pytest**：具有异步支持的测试框架
- **ruff**：快速的 Python 静态代码检查和格式化工具
- **mypy**：静态类型检查器
- **pre-commit**：代码质量的 Git 钩子
### 代码质量
```bash
# 运行静态代码检查
ruff check src/ tests/
# 运行格式化工具
ruff format src/ tests/
# 运行类型检查器
mypy src/
# 运行所有检查（静态代码检查 + 格式化工具 + 类型检查器）
pre-commit run --all-files
```
## 🧪 测试
该项目包含涵盖所有主要功能的全面集成测试。
### 运行测试
```bash
# 运行所有测试
pytest tests/ -v
# 运行特定测试套件
pytest tests/integration/test_all_modules_searchable.py -v # 可搜索性，所有 54 个模块（169 个测试）
pytest tests/integration/test_model_comparison.py -v -s # 模型比较（31 个测试）
pytest tests/integration/test_mcp_server.py -v # MCP 服务器工具（38 个测试）
pytest tests/integration/test_parse_markdown.py -v # Markdown 解析（12 个测试）
pytest tests/integration/test_cli_index.py -v # CLI 索引构建（4 个测试）
# 运行测试并生成覆盖率报告
pytest tests/ --cov=src --cov-report=term-missing --cov-report=html
```
### 测试覆盖率
- **所有模块可搜索**（169 个测试）：验证所有 54 个模块均可通过关键词、精确名称和自然语言查询找到（目标在前 3 名），以及目录元数据和搜索质量检查
- **模型比较**（31 个测试）：嵌入模型性能比较，附带时间分析
- **MCP 服务器**（38 个测试）：`search_modules`、`get_module` 和 `modules_list` 工具，`top_k` 和 `sections` 参数，安全验证，集成工作流
- **端到端**（49 个测试）：针对启动的服务器进程的真实 MCP stdio 协议会话，轮胎有效载荷和入口点验证，`uvx` 打包服务器烟雾测试，插件清单/技能/代理合约，用于 Claude Code 和 Codex，技能脚本测试（Terraform 日志预过滤），通过 `claude` CLI 进行实时插件安装
- **Markdown 解析**（12 个测试）：YAML 前置信息解析，描述提取，规范化
- **CLI 索引构建**（4 个测试）：索引创建，验证，搜索集成
**总计**：318 个测试（集成 + 端到端）
## 🏗️ 架构
### 包含内容
该存储库包含：
- **预建搜索索引**（`model/tfmod_e5_small_index.pkl`）：
- 使用 `intfloat/e5-small-v2` 模型预计算嵌入的即用搜索索引
- 包含 BM25 语料库，语义向量和关键词 IDF 分数
- 包含 54 个精选的 Terraform AWS 模块
- 文件大小：~4.27 MB
- **精选模块文档**（`modules/terraform-aws-modules/`）：
- 54 个 Terraform AWS 模块的编译文档，涵盖计算，存储，网络，数据库，安全等
- 源自官方 [terraform-aws-modules](https://github.com/terraform-aws-modules) 项目
- 格式化为带有 YAML 前置信息元数据的 Markdown
- 每个模块都包含最佳实践，用例和示例的综合文档
### 索引模块
搜索索引包含 54 个 Terraform AWS 模块，涵盖多个服务类别。每个模块都用综合描述，最好实践，用例和集成示例进行文档记录。
**计算和容器：**
- `app-runner` - 容器化 Web 应用程序部署
- `autoscaling` - EC2 自动缩放组
- `batch` - 用于批处理计算工作负载的 AWS Batch
- `ec2-instance` - EC2 虚拟机
- `ecs` - 弹性容器服务
- `eks` - 弹性 Kubernetes 服务
- `eks-pod-identity` - EKS Pod 身份配置
- `lambda` - 无服务器函数
**网络：**
- `alb` - 应用程序负载均衡器
- `customer-gateway` - VPN 客户网关
- `elb` - 经典负载均衡器
- `transit-gateway` - 用于网络中心的 Transit Gateway
- `vpc` - 虚拟私有云
- `vpn-gateway` - VPN 网关和站点到站点 VPN
**存储：**
- `ebs-optimized` - EBS 优化验证
- `ecr` - 弹性容器注册表
- `efs` - 弹性文件系统
- `fsx` - FSx 文件系统（Lustre，ONTAP，OpenZFS，Windows）
- `s3-bucket` - S3 对象存储
**数据库：**
- `dms` - 数据库迁移服务
- `dynamodb-table` - DynamoDB NoSQL 数据库
- `elasticache` - ElastiCache（Redis，Memcached）
- `memory-db` - Redis 的 MemoryDB
- `opensearch` - OpenSearch 搜索和分析
- `rds` - 关系数据库服务
- `rds-aurora` - Aurora 无服务器数据库
- `rds-proxy` - 用于连接池的 RDS Proxy
- `redshift` - Redshift 数据仓库
**安全和身份：**
- `acm` - AWS 证书管理器
- `iam` - 身份和访问管理
- `key-pair` - EC2 密钥对
- `kms` - 密钥管理服务
- `secrets-manager` - 秘密管理器
- `security-group` - VPC 安全组
**监控和日志：**
- `cloudwatch` - CloudWatch 日志和指标
- `datadog-forwarders` - Datadog 日志转发
- `managed-service-grafana` - Amazon Managed Grafana
- `managed-service-prometheus` - Amazon Managed Prometheus
**应用程序集成：**
- `apigateway-v2` - API Gateway HTTP 和 WebSocket API
- `appsync` - GraphQL API 服务
- `eventbridge` - 事件驱动架构
- `msk-kafka-cluster` - Kafka 的托管流
- `sns` - 简单通知服务
- `sqs` - 简单队列服务
- `step-functions` - 无服务器工作流编排
**内容交付和网络安全：**
- `cloudfront` - CloudFront CDN
- `global-accelerator` - 用于性能的全局加速器
- `network-firewall` - AWS 网络防火墙
- `route53` - DNS 和域名管理
**开发工具和自动化：**
- `appconfig` - 应用程序配置管理
- `atlantis` - Terraform 拉取请求自动化
- `notify-slack` - Slack 通知集成
- `ssm-parameter` - 系统管理器参数存储
**大数据和分析：**
- `emr` - 弹性 MapReduce（Hadoop，Spark）用于大数据处理
所有模块都包含详细的文档，内容包括：
- 模块元数据和版本信息
- 综合功能描述
- 现实世界的用例
- 安全和操作最佳实践
- 集成示例和代码片段
- 指向官方 AWS 文档的链接
### 组件
1. **搜索库**（`src/tfmod_search_lib.py`）
- 具有混合评分（关键词 + BM25 + 语义）的核心搜索引擎
- 索引构建和管理
- 带有 YAML 前置信息支持的 Markdown 解析
2. **CLI 工具**（`src/tfmod_search_cli.py`）
- 用于索引构建和测试的命令行界面
- 两个子命令：`index` 和 `search`
3. **MCP 服务器**（`src/tfmod_mcp_server.py`）
- 基于 FastMCP 的 stdio 服务器
- 暴露搜索和检索工具
- 配置管理和日志记录
### 数据流
```
文档（.md 文件）
↓
CLI 构建索引（解析 + 嵌入 + BM25）
↓
索引文件（.pkl）
↓
MCP 服务器加载索引
↓
工具：search_modules，get_module，modules_list
↓
Claude Desktop / MCP 客户端
```
### 搜索评分算法
混合搜索结合四个信号，并具有可配置的权重：
1. **关键词重叠**（`w_kw`）：IDF 加权关键词匹配
2. **精确匹配**（`w_exact`）：精确模块名称匹配提升
3. **BM25**（`w_bm25`）：统计文本相关性（Okapi BM25）
4. **语义相似性**（`w_sem`）：神经嵌入的余弦相似性
所有分数在加权组合之前都会进行最小-最大归一化。
### 嵌入模型比较
该项目通过 `--model` 支持任何 sentence-transformers 模型。下表对 **完整目录** 的 5 个候选模型进行了基准测试：所有 54 个模块，每个模块查询 3 次（精确名称，关键词，自然语言）- 每个模型 162 个查询 - 使用 `config.yaml` 中的生产搜索权重。
| 模型 | 维度 | 大小 | 构建时间 | 平均查询时间 | 成功率（前 3 名） |
|---|---:|---:|---:|---:|---:|
| **`intfloat/e5-small-v2`** ⭐ *(默认，自 0.6.0)* | 384 | ~138 MB | ~4.1s | ~8 ms | **100.0%** |
| `BAAI/bge-base-en-v1.5` *(默认至 0.5.0)* | 768 | ~419 MB | ~7.5s | ~23 ms | 100.0% |
| `thenlper/gte-small` | 384 | ~65 MB | ~3.9s | ~8 ms | 98.8% |
| `BAAI/bge-small-en-v1.5` | 384 | ~129 MB | ~4.1s | ~8 ms | 98.8% |
| `sentence-transformers/all-MiniLM-L12-v2` | 384 | ~129 MB | ~3.0s | ~8 ms | 98.1% |
**为什么选择 `e5-small-v2`**：它是唯一一个与 `bge-base-en-v1.5` 的 100% 成功率相匹配的小型模型 - **体积减少约 3 倍**，**查询速度加快约 3 倍**，无需权重重新调整或查询/段落提示前缀（两者都尝试过；两者都没有在该语料库上产生影响）。`gte-small` 是最小的选项（~65 MB，~ 比旧默认设置小 6 倍），如果二进制大小比召回率的最后一个百分点更重要，则是一个合理的选择 - 请参阅 `tests/integration/test_model_comparison.py` 以获取存储库提交的，CI 运行的跨所有三个（`gte-small`，`bge-base-en-v1.5`，`e5-small-v2`）的比较。
要使用不同的模型，请使用 `--model <name>` 重新构建索引（参见 [构建索引](#1-building-the-index)），并在 `--index_path` / `config.yaml` 中指向新文件。
## 🤝 贡献
欢迎贡献！请遵循以下指南：
1. 分叉存储库
2. 创建一个功能分支（`git checkout -b feature/amazing-feature`）
3. 进行更改
4. 运行测试和代码质量检查
5. 提交更改（`git commit -m 'Add amazing feature'`）
6. 推送到分支（`git push origin feature/amazing-feature`）
7. 打开拉取请求
### 开发指南
- 遵循 PEP 8 样式指南（由 `ruff` 强制执行）
- 为所有函数添加类型提示（由 `mypy` 检查）
- 为新功能编写测试
- 根据需要更新文档
- 保持提交原子性和详细描述
## 📄 许可证
该项目根据 MIT 许可证许可 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
## 🙏 致谢
- 使用 [FastMCP](https://github.com/jlowin/fastmcp) - FastAPI 风格的 MCP 服务器框架
- 使用 [sentence-transformers](https://www.sbert.net/) 进行语义嵌入
- Terraform 模块文档来自 [terraform-aws-modules](https://github.com/terraform-aws-modules)
## 📞 支持
有关问题，问题或功能请求：
- 在 [GitHub Issues](https://github.com/SantyagoSeaman/tfmodsearch/issues) 上打开问题
- 检查现有问题以获取常见问题和解决方案
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器