SDLC最佳实践MCP服务器
两个模型上下文协议（MCP）服务器为SDLC文档提供搜索和文档读取功能：
- 本地MCP服务器 (
src_mcp/)-独立的本地嵌入和重新排序 - AWS知识库MCP服务器 (
aws_kb/)-使用AWS Bedrock和S3矢量的云原生
快速开始
本地MCP服务器（建议开发）
./run-local-mcp.sh- ✅ 零成本，本地运行
- ✅ 快速（\ list[dict]`
使用BM25+向量+重新排序对所有文档进行混合搜索。
退货：
[{
'title': 'Testing Strategies',
'filename': '04-testing-strategies.md',
'start_line': 125,
'end_line': 201,
'content': '...',
'similarity': 0.873
}, ...]pqsoft_read_docs(documentation_path: str, start_line: int, end_line: int) -> str
从文档文件中读取特定的行范围。
例子：
pqsoft_read_docs('04-testing-strategies.md', 1, 50)
# Returns lines 1-50 from the file开发与测试
本地MCP服务器
# Run the server
./run-local-mcp.sh
# Test search
cd src_mcp
python3 mcp_search.py "testing strategies"AWS知识库MCP服务器
# Deploy infrastructure (one-time setup)
cd aws_kb/scripts
./deploy_stack.sh
# Create vector bucket and index (one-time setup)
uv run create_vector_bucket.py
uv run create_vector_index.py
# Sync documents and run server
cd ../..
./run-awskb-mcp.sh看 aws_kb/README.md 和 aws_kb/QUICKSTART.md 有关AWS设置的详细说明。
2.测试搜索功能
# Local MCP
cd src_mcp
python3 mcp_search.py "testing strategies"
python3 mcp_search.py "deployment best practices"
# Using test script for reading
python3 test_read.py "04-testing-strategies.md" 1 503.与Q CLI一起使用
添加到MCP配置(~/.aws/amazonq/mcp.json):
本地MCP服务器：
{
"mcpServers": {
"sdlc-docs-local": {
"command": "/absolute/path/to/best-practices-mcp/run-local-mcp.sh"
}
}
}AWS知识库MCP服务器：
{
"mcpServers": {
"sdlc-docs-aws": {
"command": "/absolute/path/to/best-practices-mcp/run-awskb-mcp.sh",
"env": {
"AWS_PROFILE": "your-profile-name"
}
}
}
}替换 /absolute/path/to/best-practices-mcp/ 根据您的实际项目路径。
本地开发
先决条件
安装 紫外线:
curl -LsSf https://astral.sh/uv/install.sh | sh本地运行
本地MCP服务器：
./run-local-mcp.sh脚本会自动执行以下操作：
- 通过安装依赖项
uv sync - 递增更新索引（仅处理新/修改/删除的文件）
- 启动MCP服务器
AWS知识库MCP服务器：
./run-awskb-mcp.sh脚本会自动执行以下操作：
- 通过安装依赖项
uv sync - 如果更改，将文档同步到S3
- 启动MCP服务器
注： 文档文件更改时，两台服务器都会自动更新。本地服务器使用增量更新（仅处理更改的文件），而AWS服务器同步到S3。
添加您自己的文档
- 将标记文件放入
docs/目录
docs/
├── coding-standards.md
├── deployment/
│ ├── kubernetes.md
│ └── terraform.md
└── testing/
└── integration-tests.md- 重新启动MCP服务器
- 当地： ./run-local-mcp.sh （增量更新索引） - AWS： ./run-awskb-mcp.sh （自动同步到S3）
- 文档会自动编入索引
- 使用标题上下文创建的块 - 生成的嵌入 - 数据库/知识库已更新
目录结构
├── run-local-mcp.sh # Start local MCP server
├── run-awskb-mcp.sh # Start AWS KB MCP server
├── src_mcp/ # Local MCP implementation
│ ├── server.py # FastMCP server
│ ├── build_index.py # Index builder
│ ├── pyproject.toml # Dependencies
│ └── sdlc_docs.db # Vector database (generated)
├── aws_kb/ # AWS Knowledge Base implementation
│ ├── server.py # FastMCP server
│ ├── cloudformation/ # Infrastructure as code
│ ├── scripts/ # Deployment and sync scripts
│ ├── tests/ # Test scripts
│ ├── README.md # Detailed AWS setup guide
│ ├── QUICKSTART.md # Quick start guide
│ ├── IMPLEMENTATION.md # Implementation details
│ └── CODE_REVIEW.md # Code review and improvements
├── docs/ # Your markdown documentation
│ └── *.md
└── README.md # This file技术细节
本地MCP服务器
- 嵌入模型：句子转换器/全二分罗伯塔-v1（768昏暗）
- 数据库：DuckDB（嵌入式，运行时只读）
- 搜索：BM25+矢量+交叉编码器重新排序
- 尺寸：约1-5MB数据库，用于典型文档集
AWS知识库MCP服务器
- 嵌入模型：亚马逊泰坦嵌入v2（1024 dim）
- 向量存储：S3矢量（与传统数据库相比成本降低90%）
- 搜索：具有余弦相似度的矢量搜索
- 基础设施：CloudFormation管理，完全无服务器
分块策略
- 尺寸：每块约300个单词
- 重叠：块之间有2行
- 上下文：每个块前面都有H1、H2、H3标题
- 为什么：在精确性和上下文保留之间取得平衡
演出
- 搜索延迟：典型查询\&1 | less
### 搜索未返回任何结果
Verify database was created
docker run --rm best-practices-mcp ls -lh sdlc_docs.db
Check number of indexed chunks
docker run --rm best-practices-mcp python -c "import duckdb; print(duckdb.connect('sdlc_docs.db', read_only=True).execute('SELECT COUNT(*) FROM documents').fetchone())"
### 路径遍历错误
- 确保路径相对于docs/目录
- 不要使用 `..` 在路径
## 定制
### 调整块大小
编辑 `src_mcp/build_index.py`:
chunks = chunk_text(content, chunk_size=400, overlap_lines=3)
### 更改嵌入模型
编辑两者 `src_mcp/build_index.py` 和 `src_mcp/server.py`:
EMBEDDING_MODEL = 'sentence-transformers/all-MiniLM-L6-v2' EMBEDDING_DIM = 384 # Update to match model dimensions
Also update EMBEDDING_DIM in CREATE TABLE statement
### 修改搜索限制
默认值为10个结果，最多50个。在工具调用中调整：
pqsoft_search_docs("query", limit=20)
## 故障排除
### 本地MCP服务器
Check if database exists
ls -lh src_mcp/sdlc_docs.db
Force full rebuild (removes DB and rebuilds from scratch)
cd src_mcp && rm -f sdlc_docs.db sdlc_docs.db.wal && uv run python build_index.py
Check indexed documents
cd src_mcp && python3 -c "import duckdb; conn = duckdb.connect('sdlc_docs.db', read_only=True); print(conn.execute('SELECT DISTINCT filename FROM documents').fetchall())"
Check file metadata tracking
cd src_mcp && python3 -c "import duckdb; conn = duckdb.connect('sdlc_docs.db', read_only=True); print(conn.execute('SELECT filename, last_modified FROM file_metadata').fetchall())"
### AWS知识库MCP服务器
Check config
cat aws_kb/config.json
Manually sync docs
cd aws_kb && uv run python scripts/sync_docs.py
Check ingestion status
aws bedrock-agent list-ingestion-jobs --knowledge-base-id --data-source-id --region ap-southeast-2
看 `aws_kb/README.md` 了解AWS的详细故障排除。
## 比较：本地与AWS
|功能|本地（src_mcp）|AWS（AWS_kb）|
| ------------ | ----------------------------- | ------------------------------- |
|成本|0美元|~0.10-0.20美元/月|
|设置|2分钟|10分钟|
|延迟|\<200ms|~500ms|
|可扩展性|有限|无限|
|维护|增量更新|自动|
|依赖关系|句子转换器，DuckDB|仅限boto3|
|矢量存储|DuckDB|S3矢量|
|嵌入|全二分罗伯塔-v1 |泰坦|
|重新排名| ms marco MiniLM |在ap-southeast-2中不可用|
## 许可证
本项目按原样提供，用于SDLC文件编制。
## 测试
### 单元测试
使用以下命令运行单元测试 `uv`:
cd src_mcp uv run pytest tests/
测试要求首先构建数据库：
cd src_mcp uv run python build_index.py uv run pytest tests/
### 集成测试
测试搜索功能：
cd src_mcp uv run python mcp_search.py "testing strategies" uv run python test_read.py 04-testing-strategies.md 1 50
## 贡献
1. 将您的文档添加到 `docs/`
1. 运行单元测试： `cd src_mcp && uv run pytest tests/`
1. 使用本地服务器进行测试： `./run-local-mcp.sh`
1. 验证搜索是否有效
1. 承诺并推动
## 状态
✅ **生产就绪**
- 所有测试均已通过
- 加强安保
- 两种部署选项
- 符合MCP协议
- 完整记录现在我们列出了