SDLC 最佳实践 MCP 服务器

一个自包含的模型上下文协议（MCP）服务器，使用本地嵌入提供SDLC文档的语义搜索和文档阅读功能。

架构概述

┌─────────────────────────────────────────────────────────────┐
│                     构建时间（Docker）                      │
├─────────────────────────────────────────────────────────────┤
│  docs/*.md → build_index.py → 嵌入 → sdlc_docs.db    │
│  • 按标题上下文分块文档                    │
│  • 生成768维向量（all-mpnet-base-v2）           │
│  • 存储在DuckDB中并附带元数据                           │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    运行时（容器）                       │
├─────────────────────────────────────────────────────────────┤
│  server.py (FastMCP) ← 标准输入 ← MCP 客户端 (Q CLI)          │
│  • pqsoft_search_docs: 语义向量搜索             │
│  • pqsoft_read_docs: 精确行范围读取           │
│  • pqsoft_recommend_docs: 基于内容的推荐   │
└─────────────────────────────────────────────────────────────┘

主要特性

🔍 语义搜索

• 本地嵌入: 不需要网络调用，完全自包含
• 上下文分块: 包含标题层次结构以获得更好的结果
• 重叠策略: 2行重叠防止信息丢失
• 余弦相似度: 向量比较的标准指标

📖 精确阅读

• 行范围访问: 从源文件中读取精确部分
• 安全加固: 防止路径遍历，仅限.md文件
• 元数据跟踪: 每个块的文件名和行号

🔒 安全性

• 只读数据库访问
• 防止路径遍历
• 文件类型限制（仅限.md）
• 隐藏文件阻止（无.env、.git等）

可用工具

pqsoft_search_docs(search_phrase: str, limit: int) -> list[dict]

在整个文档中进行语义搜索。

返回值:

[{
    'title': '测试策略',
    '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)
# 返回文件中的第1到第50行

pqsoft_recommend_docs(title: str) -> list[dict]

根据内容相似性获取相关文档。

开发与测试

1. 构建和测试

# 运行概念验证测试
./proof_test.sh

# 或手动构建
docker build -t best-practices-mcp .
# 或
podman build -t best-practices-mcp .

2. 测试搜索功能

# 使用Python MCP客户端
python3 mcp_search.py "测试策略"
python3 mcp_search.py "部署最佳实践"

# 使用读取测试脚本
python3 test_read.py "04-testing-strategies.md" 1 50

3. 使用Q CLI

添加到您的MCP配置（~/.aws/amazonq/mcp.json）：

{
  "mcpServers": {
    "sdlc-docs": {
      "command": "docker",
      "args": ["run", "--read-only", "-i", "best-practices-mcp"]
    }
  }
}

或对于Podman：

{
  "mcpServers": {
    "sdlc-docs": {
      "command": "podman",
      "args": ["run", "--read-only", "-i", "best-practices-mcp"]
    }
  }
}

添加您自己的文档

1. 将markdown文件放置在docs/目录下

   docs/
   ├── 编码标准.md
   ├── 部署/
   │   ├── kubernetes.md
   │   └── terraform.md
   └── 测试/
       └── 集成测试.md
   

2. 重新构建容器

   docker-compose up --build
   # 或
   podman-compose up --build
   

3. 文档自动索引

   • 创建带有标题上下文的块
   • 生成嵌入
   • 更新数据库

目录结构

├── Dockerfile                  # 多阶段构建，包括嵌入生成
├── docker-compose.yml          # 组合配置（Docker/Podman）
├── requirements.txt            # Python依赖项
├── build_index.py             # 索引脚本（构建时运行）
├── server.py                  # MCP服务器（运行时运行）
├── mcp_search.py              # 测试用Python MCP客户端
├── test_read.py               # pqsoft_read_docs测试脚本
├── docs/                      # 您的markdown文档
│   └── *.md
├── detect_container.sh        # 自动检测Docker/Podman
├── proof_test.sh             # 验证测试脚本
└── sdlc_docs.db              # 生成的向量数据库（在容器内）

容器运行时支持

所有脚本自动检测并使用Docker或Podman：

• proof_test.sh - 验证核心功能
• mcp_search.py - 自动检测运行时
• test_read.py - 自动检测运行时
• docker-compose.yml - 支持docker-compose和podman-compose

技术细节

嵌入模型

• 模型: sentence-transformers/all-mpnet-base-v2
• 维度: 768
• 为什么: 更高质量的嵌入以获得更好的语义搜索结果
• 许可证: Apache 2.0

数据库

• 引擎: DuckDB（嵌入式）
• 模式: id, title, filename, start_line, end_line, content, embedding
• 访问: 运行时只读
• 大小: 典型文档集约1-5MB

分块策略

• 大小: 每块约300字
• 重叠: 每块之间2行重叠
• 上下文: 每块前缀H1, H2, H3标题
• 为什么: 在精度和上下文保留之间取得平衡

性能

• 搜索延迟: 典型查询小于200毫秒
• 嵌入生成: 每次查询约50毫秒
• 相似度计算: 每块约1毫秒
• 内存: 约500MB（模型+运行时）

自定义

调整分块大小

编辑build_index.py:

chunks = chunk_text(content, chunk_size=400, overlap_lines=3)

更改嵌入模型

编辑build_index.py和server.py:

model = SentenceTransformer('sentence-transformers/all-MiniLM-L6-v2')
# 更新CREATE TABLE语句中的嵌入维度

修改搜索限制

默认是10个结果，最大50个。调整工具调用:

pqsoft_search_docs("查询", limit=20)

故障排除

容器无法启动

# 检查镜像是否成功构建
docker images | grep best-practices-mcp

# 查看构建日志
docker build -t best-practices-mcp . 2>&1 | less

搜索没有返回结果

# 验证数据库是否创建
docker run --rm best-practices-mcp ls -lh sdlc_docs.db

# 检查已索引块的数量
docker run --rm best-practices-mcp python -c "import duckdb; print(duckdb.connect('sdlc_docs.db').execute('SELECT COUNT(*) FROM documents').fetchone())"

路径遍历错误

• 确保路径相对于docs/目录
• 不要在路径中使用..
• 只有.md文件可访问

开发

运行测试

# 验证结构
python3 validate_structure.py

# 测试MCP协议
./proof_test.sh

# 测试搜索
python3 mcp_search.py "测试查询"

# 测试读取
python3 test_read.py "文件.md" 1 10

调试

# 进入正在运行的容器
docker exec -it <容器ID> /bin/bash

# 检查数据库
python3 -c "import duckdb; conn = duckdb.connect('sdlc_docs.db', read_only=True); print(conn.execute('SELECT COUNT(*) FROM documents').fetchone())"

# 查看已索引文件
python3 -c "import duckdb; conn = duckdb.connect('sdlc_docs.db', read_only=True); print(conn.execute('SELECT DISTINCT filename FROM documents').fetchall())"

许可

此项目按原样提供用于SDLC文档目的。

贡献

1. 将您的文档添加到docs/
2. 使用./proof_test.sh进行测试
3. 验证搜索是否有效：python3 mcp_search.py "您的主题"
4. 重新构建并部署

状态

✅ 生产就绪

• 所有测试通过
• 安全加固
• 兼容Docker/Podman
• 符合MCP协议
• 完整文档