TFModSearch MCP服务器

![Python 3.13+](https://www.python.org/downloads/) ![License: MIT](https://opensource.org/licenses/MIT)

A. 模型上下文协议（MCP） 该服务器使用混合搜索（关键字匹配、BM25和语义嵌入）为Terraform AWS模块文档提供智能搜索功能。

准备使用：包括一个预构建的搜索索引，其中嵌入了54个精心策划的Terraform AWS模块。立即安装并运行MCP服务器，无需构建索引！

🚀 特性

混合搜索引擎：结合关键字匹配（IDF加权）、BM25文本相关性、精确的模块名称匹配和语义相似性，以获得准确的结果
MCP集成：与Claude Desktop和其他MCP客户端无缝集成
快速高效：使用仅CPU推理的预构建搜索索引 BAAI/bge-base-en-v1.5 模型
准备使用：包括预置索引(model/tfmod_index.pkl)嵌入来自 BAAI/bge-base-en-v1.5 模型和策划的Terraform AWS模块文档
综合目录：访问从官方来源编译的具有丰富元数据的terraform aws模块文档
安全第一：用于安全文件操作的内置路径验证和访问控制
可配置权重：通过YAML配置或CLI参数微调搜索评分

- Claude代码CLI集成 - Claude桌面集成 -

用法

- 构建指数 - CLI搜索

MCP工具
配置
发展
测试
建筑

- 索引模块

贡献
许可证

📦 安装

快速安装（无需克隆）

使用此MCP服务器的最简单方法是 uvx -无需克隆存储库。

先安装uv （如果尚未安装）：

curl -LsSf https://astral.sh/uv/install.sh | sh

然后添加到您的MCP客户端配置中：

{
  "mcpServers": {
    "terraform-modules": {
      "command": "uvx",
      "args": ["git+https://github.com/SantyagoSeaman/aws-tf-modules-mcp-server"]
    }
  }
}

备注：如果出现“找不到命令”错误，请使用完整路径 uvx: ``bash # Find uvx location which uvx # Example output: /Users/username/.local/bin/uvx ` 然后在配置中使用完整路径： `json "command": "/Users/username/.local/bin/uvx" ``

先决条件

Python 3.13或更高版本
紫外线（推荐）或pip

本地安装（用于开发）

# Clone the repository
git clone https://github.com/SantyagoSeaman/aws-tf-modules-mcp-server.git
cd aws-tf-modules-mcp-server

# Create virtual environment and install dependencies
uv venv --python 3.13
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -r pyproject.toml

使用pip

# Clone the repository
git clone https://github.com/SantyagoSeaman/aws-tf-modules-mcp-server.git
cd aws-tf-modules-mcp-server

# Create virtual environment and install dependencies
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install -r pyproject.toml

整装待发：存储库包含一个预构建的搜索索引，因此您可以跳过索引构建步骤，在安装后立即运行MCP服务器！

🏃 快速开始

1.构建搜索索引（可选）

备注：此存储库包括一个预先构建的搜索索引，位于 model/tfmod_index.pkl 其中嵌入了54个精心策划的Terraform AWS模块。如果要使用包含的模块，可以跳过此步骤，直接继续测试或运行服务器。

要重建索引或使用其他模块创建新索引，请执行以下操作：

python src/tfmod_search_cli.py index \
  --docs_dir ./modules/terraform-aws-modules

备注：第一次运行将下载 BAAI/bge-base-en-v1.5 型号（约220MB）。

2.测试搜索（CLI）

使用命令行界面测试搜索功能：

python src/tfmod_search_cli.py search \
  --query "s3 bucket with kms encryption and versioning" \
  --top_k 5

Claude代码CLI集成

选项1：使用uvx（推荐-不需要克隆）

添加到您的克劳德代码设置(~/.claude/settings.json):

{
  "mcpServers": {
    "terraform-modules": {
      "command": "uvx",
      "args": ["git+https://github.com/SantyagoSeaman/aws-tf-modules-mcp-server"]
    }
  }
}

备注：如果 uvx 未找到，请使用完整路径（run which uvx 找到它）： ``json "command": "/Users/username/.local/bin/uvx" ``

选项2：使用本地安装

# Add the MCP server (replace with your actual path)
claude mcp add --transport stdio terraform-modules -- \
  /absolute/path/to/aws-tf-modules-mcp-server/.venv/bin/python \
  /absolute/path/to/aws-tf-modules-mcp-server/src/tfmod_mcp_server.py

# Verify the server was added
claude mcp list

或者手动添加到您的克劳德代码设置中(~/.claude/settings.json):

{
  "mcpServers": {
    "terraform-modules": {
      "command": "/absolute/path/to/aws-tf-modules-mcp-server/.venv/bin/python",
      "args": [
        "/absolute/path/to/aws-tf-modules-mcp-server/src/tfmod_mcp_server.py"
      ]
    }
  }
}

Claude桌面集成

添加到您的Claude Desktop配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

选项1：使用uvx（推荐-不需要克隆）

{
  "mcpServers": {
    "terraform-modules": {
      "command": "uvx",
      "args": ["git+https://github.com/SantyagoSeaman/aws-tf-modules-mcp-server"]
    }
  }
}

备注：如果 uvx 未找到，请使用完整路径（run which uvx 找到它）： ``json "command": "/Users/username/.local/bin/uvx" ``

选项2：使用本地安装

{
  "mcpServers": {
    "terraform-modules": {
      "command": "/absolute/path/to/aws-tf-modules-mcp-server/.venv/bin/python",
      "args": [
        "/absolute/path/to/aws-tf-modules-mcp-server/src/tfmod_mcp_server.py"
      ]
    }
  }
}

GitHub副本集成（VS代码）

在VS Code中将MCP服务器添加到GitHub Copilot（需要VS Code 1.99+）：

步骤1：创建 .vscode/mcp.json 在项目根目录中（或通过命令面板打开用户级配置：“MCP:打开用户配置”）：

选项1：使用uvx（推荐-不需要克隆）

{
  "servers": {
    "terraform-modules": {
      "type": "stdio",
      "command": "uvx",
      "args": ["git+https://github.com/SantyagoSeaman/aws-tf-modules-mcp-server"]
    }
  }
}

备注：如果 uvx 未找到，请使用完整路径（run which uvx 找到它）。

选项2：使用本地安装

{
  "servers": {
    "terraform-modules": {
      "type": "stdio",
      "command": "/absolute/path/to/aws-tf-modules-mcp-server/.venv/bin/python",
      "args": [
        "/absolute/path/to/aws-tf-modules-mcp-server/src/tfmod_mcp_server.py"
      ]
    }
  }
}

步骤2：单击出现在顶部的“开始”按钮 mcp.json 用于初始化服务器的文件。

步骤3：打开GitHub Copilot聊天，选择代理从弹出菜单中选择模式，然后单击工具图标以验证 terraform-modules 服务器及其工具可用。

通过命令面板进行替代设置:

打开命令选项板(Cmd+Shift+P 在macOS上/ Ctrl+Shift+P 在Windows/Linux上）
运行“MCP:添加服务器”
选择“stdio”作为服务器类型
进入 terraform-modules 作为服务器名称
输入Python路径作为命令
输入脚本路径作为参数

管理MCP服务器:

“MCP:列出服务器”--查看已安装的服务器和可用操作
“MCP:重置缓存工具”--如果工具未出现，则刷新工具发现
“MCP:显示输出”--调试服务器连接问题

有关更多详细信息，请参阅 VS代码MCP文档和 .

📖 用法

1.建立指数

备注：存储库包括一个预构建的索引——如果你想添加更多模块或自定义现有模块，你只需要构建一个新的索引。

根据模块文档构建或重建搜索索引：

python src/tfmod_search_cli.py index \
  --docs_dir ./modules/terraform-aws-modules \
  --index_path ./model/tfmod_bge_base_index.pkl

选项:

--docs_dir：包含Terraform模块标记文件的目录（必需）
--index_path：酸洗索引文件的输出路径（可选，默认为 ./model/tfmod_index.pkl)
--model：要使用的句子转换器模型（默认值： BAAI/bge-base-en-v1.5)

2.CLI搜索（独立）

在不运行MCP服务器的情况下搜索模块：

# Search by functionality
python src/tfmod_search_cli.py search \
  --query "kubernetes cluster management" \
  --top_k 3

# Search by exact module name
python src/tfmod_search_cli.py search \
  --query "vpc" \
  --top_k 5

# Search with custom weights
python src/tfmod_search_cli.py search \
  --query "object storage" \
  --w_kw 2.5 \
  --w_exact 4.0 \
  --w_bm25 1.5 \
  --w_sem 1.0

# Search with optional query instruction for BGE models
python src/tfmod_search_cli.py search \
  --query "s3" \
  --query-instruction "Represent this sentence for searching relevant passages: "

🛠️ MCP工具

MCP服务器为Terraform模块发现和文档检索提供了三个工具：

`modules_list()`

在目录中列出所有可用的Terraform模块。

参数：无

退货：包含名称、路径、描述和关键字的完整模块列表。

示例:

{
  "modules": [
    {
      "module_name": "vpc",
      "path": "modules/terraform-aws-modules/vpc.md",
      "description": "Terraform module to create AWS VPC resources...",
      "keywords": ["vpc", "subnet", "networking", "aws"]
    }
  ],
  "count": 54
}

`search_modules(query: str)`

使用关键字、确切名称或自然语言查询搜索Terraform模块。

参数:

query （string）：自由文本搜索查询

退货：元数据和相关性得分排名前三的模块。

查询示例:

"vpc" -按确切名称查找VPC模块
"object storage with encryption" -自然语言搜索
"kubernetes cluster management" - 查找EKS模块
"serverless functions" -查找Lambda模块

`get_module(module_identifier: str)`

检索特定Terraform模块的完整文档。

参数:

module_identifier （string）：模块名称（例如。， "vpc")或相对路径（例如。， "modules/terraform-aws-modules/vpc.md")

退货：以标记文本的形式完成模块文档。

安全：仅包含以下文件 modules/ 目录是可访问的。绝对路径和路径遍历尝试被拒绝。

⚙️ 配置

搜索权重配置

创建 config.yaml 在项目根目录下的文件中自定义搜索评分权重：

# Optional query instruction for BGE models (improves short query retrieval)
# Set to null to disable (default), or use:
# query_instruction: "Represent this sentence for searching relevant passages: "
query_instruction: null

search_weights:
  w_kw: 1.0      # Keyword overlap weight (IDF-weighted)
  w_exact: 3.0   # Exact module name match boost
  w_bm25: 2.0    # BM25 text relevance weight
  w_sem: 3.0     # Semantic similarity weight

配置优先级 （从高到低）：

CLI参数(--w_kw, --w_exact, --query-instruction等等）
config.yaml 文件
内置默认值

模块文档格式

Terraform模块文档文件应该是Markdown，前面有YAML：

---
module_name: terraform-aws-vpc
keywords: [vpc, subnet, networking, aws]
---

# Terraform AWS VPC Module

Module description and documentation...

👩‍💻 发展

设置开发环境

# Clone the repository
git clone https://github.com/SantyagoSeaman/aws-tf-modules-mcp-server.git
cd aws-tf-modules-mcp-server

# Install with development dependencies
uv pip install -e ".[dev]"

# Install pre-commit hooks
pre-commit install

发展依赖性

该项目包括以下开发工具：

pytest：支持异步的测试框架
颈毛：快速Python linter和格式化程序
米皮：静态类型检查器
预承诺：Git挂钩提高代码质量

代码质量

# Run linter
ruff check src/ tests/

# Run formatter
ruff format src/ tests/

# Run type checker
mypy src/

# Run all checks (linter + formatter + type checker)
pre-commit run --all-files

🧪 测试

该项目包括涵盖所有主要功能的全面集成测试。

运行测试

# Run all tests
pytest tests/ -v

# Run specific test suite
pytest tests/integration/test_mcp_server.py -v           # MCP server tests (17 tests)
pytest tests/integration/test_parse_markdown.py -v       # Parsing tests (12 tests)
pytest tests/integration/test_cli_index.py -v            # CLI index tests (4 tests)
pytest tests/integration/test_model_comparison.py -v -s  # Model comparison tests (31 tests)

# Run with coverage
pytest tests/ --cov=src --cov-report=term-missing --cov-report=html

测试覆盖率

MCP 服务器 （17项测试）： search_modules 工具， get_module 资源、安全验证、集成工作流
Markdown解析 （12个测试）：YAML前体解析、描述提取、规范化
CLI索引构建 （4个测试）：索引创建、验证、搜索集成
模型比较 （31个测试）：嵌入模型性能与时序分析的比较

总计：64个集成测试

🏗️ 建筑

包含的内容

此存储库包括：

预构建搜索索引 (model/tfmod_index.pkl):

- 使用预计算嵌入的现成搜索索引 BAAI/bge-base-en-v1.5 模型 - 包含BM25语料库、语义向量和关键字IDF分数 - 包括54个精心策划的Terraform AWS模块 - 文件大小：~4.38 MB

整理好的模块文档 (modules/terraform-aws-modules/):

- 为54个Terraform AWS模块编译的文档，涵盖计算、存储、网络、数据库、安全等领域 - 来源于官方地形自动气象站模块项目 - 使用YAML前体元数据格式化为Markdown - 每个模块都包括全面的文档，包括最佳实践、用例和示例

索引模块

搜索索引包括跨多个服务类别的54个Terraform AWS模块。每个模块都有全面的描述、最佳实践、用例和集成示例。

计算和容器：

app-runner -容器化web应用程序部署
autoscaling -EC2自动扩展组
batch -AWS Batch用于批处理计算工作负载
ec2-instance -EC2虚拟机
ecs -弹性集装箱服务
eks -弹性Kubernetes服务
eks-pod-identity -EKS吊舱身份配置
lambda -无服务器功能

网络：

alb -应用程序负载平衡器
customer-gateway -VPN客户网关
elb -经典负载平衡器
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内存数据库
opensearch -OpenSearch搜索和分析
rds -关系数据库服务
rds-aurora -Aurora无服务器数据库
rds-proxy -用于连接池的RDS代理
redshift -Redshift数据仓库

安全和身份：

acm -AWS证书管理器
iam -身份和访问管理
key-pair -EC2密钥对
kms -密钥管理服务
secrets-manager -秘密经理
security-group -VPC安全组

监控和记录：

cloudwatch -CloudWatch日志和指标
datadog-forwarders -Datadog日志转发
managed-service-grafana -亚马逊管理Grafana
managed-service-prometheus -亚马逊管理普罗米修斯

应用程序集成：

apigateway-v2 -API网关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 -系统管理器参数存储

所有模块都包括详细的文档，包括：

模块元数据和版本信息
全面的功能描述
真实世界的用例
安全和运营最佳实践
集成示例和代码片段
AWS官方文档链接

组件

搜索库 (src/tfmod_search_lib.py)

- 混合评分的核心搜索引擎（关键字+BM25+语义） - 指标构建与管理 - 支持YAML前端的Markdown解析

CLI工具 (src/tfmod_search_cli.py)

- 索引构建和测试的命令行界面 - 两个子命令： index 和 search

MCP 服务器 (src/tfmod_mcp_server.py)

- 基于FastMCP的stdio服务器 - 公开搜索和检索工具 - 配置管理和日志记录

数据流

Documentation (.md files)
    ↓
CLI builds index (parse + embed + BM25)
    ↓
Pickled index file (.pkl)
    ↓
MCP server loads index
    ↓
Tools: search_modules, get_module, modules_list
    ↓
Claude Desktop / MCP Clients

搜索评分算法

混合搜索结合了四个具有可配置权重的信号：

关键字重叠 (w_kw)：IDF加权关键字匹配
精确匹配 (w_exact)：Boost用于精确匹配模块名称
BM25 (w_bm25)：统计文本相关性（Okapi BM25）
语义相似性 (w_sem)：神经嵌入的余弦相似性

在加权组合之前，所有分数都是最小最大归一化的。

嵌入模型比较

该项目支持多种嵌入模型。以下是基准测试结果比较 thenlper/gte-small 和 BAAI/bge-base-en-v1.5:

度量	低/低	BAAI/bge-base-en-v1.5
嵌入尺寸	384	768
模型大小	约67 MB	约220 MB
索引大小	约4.30毫巴	约4.38毫巴
索引构建时间	~4.2秒	~7.3秒
平均查询时间	约14毫秒	约35毫秒
成功率（前三名）	100%	100%

测试条件：跨越3个模块（s3 bucket、rds、ec2实例）的15个查询，每个模块有5种查询类型（1个单词、2个单词、短短语、中短语、长自然语言查询）。

关键发现:

两种模型在前三名结果中找到目标模块的成功率均为100%
gte-small 每次查询快2.5倍
bge-base-en-v1.5 为语义搜索提供更好的相似性分布（解决狭义聚类问题）
BGE v1.5支持可选的查询指令前缀，以改进短查询检索

预设模型: BAAI/bge-base-en-v1.5 默认情况下，使用较大的嵌入维度可以获得更好的检索质量。

🤝 贡献

欢迎投稿！请遵循以下指南：

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
进行更改
运行测试和代码质量检查
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

开发指南

遵循PEP 8风格指南（由 ruff)
向所有函数添加类型提示（由检查 mypy)
为新功能编写测试
根据需要更新文档
保持提交原子性和良好的描述

📄 许可证

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

🙏 致谢

建于快速MCP -FastAPI风格的MCP服务器框架
用途句子变换器用于语义嵌入
Terraform模块文档来自地形自动气象站模块

📞 支持

如有疑问、问题或功能请求：

打开一个问题
检查现有问题，找出常见问题和解决方案

______________________________________________________________________

Aws Tf Modules MCP Server

快速接入

详细介绍

TFModSearch MCP服务器

🚀 特性

📋 目录

📦 安装

快速安装（无需克隆）

先决条件

本地安装（用于开发）

使用pip

🏃 快速开始

1.构建搜索索引（可选）

2.测试搜索（CLI）

Claude代码CLI集成

Claude桌面集成

GitHub副本集成（VS代码）

📖 用法

1.建立指数

2.CLI搜索（独立）

🛠️ MCP工具

modules_list()

search_modules(query: str)

get_module(module_identifier: str)

⚙️ 配置

搜索权重配置

模块文档格式

👩‍💻 发展

设置开发环境

发展依赖性

代码质量

🧪 测试

运行测试

测试覆盖率

🏗️ 建筑

包含的内容

索引模块

组件

数据流

搜索评分算法

嵌入模型比较

🤝 贡献

开发指南

📄 许可证

🙏 致谢

📞 支持

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`modules_list()`

`search_modules(query: str)`

`get_module(module_identifier: str)`