使用说明

SDLC最佳实践MCP服务器

两个模型上下文协议（MCP）服务器为SDLC文档提供搜索和文档读取功能：

本地MCP服务器 (src_mcp/)-独立的本地嵌入和重新排序
AWS知识库MCP服务器 (aws_kb/)-使用AWS Bedrock和S3矢量的云原生

快速开始

本地MCP服务器（建议开发）

./run-local-mcp.sh

✅ 零成本，本地运行
✅ 快速（<200ms查询）
✅ 无需AWS帐户
✅ 混合搜索与重新排名

AWS知识库MCP服务器（生产）

./run-awskb-mcp.sh

✅ 可扩展、可管理的基础设施
✅ S3矢量（成本降低90%）
✅ 文档更改时自动同步
⚠️ 需要AWS帐户（约0.10-0.20美元/月）

体系结构比较

本地MCP服务器(`src_mcp/`)

┌─────────────────────────────────────────────────────────────┐
│                     Build Time                              │
├─────────────────────────────────────────────────────────────┤
│  docs/*.md → build_index.py → sdlc_docs.db                  │
│  • Chunks documents with heading context                    │
│  • Generates 768-dim vectors (all-distilroberta-v1)         │
│  • Creates BM25 full-text search index                      │
│  • Stores in DuckDB with metadata                           │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    Runtime (Query)                          │
├─────────────────────────────────────────────────────────────┤
│  Query → Hybrid Retrieval → Reranker → Results              │
│                                                             │
│  Stage 1: Parallel Retrieval                                │
│    • BM25 search (exact keywords) → top 30                  │
│    • Vector search (semantic) → top 30                      │
│                                                             │
│  Stage 2: Union + Deduplicate                               │
│    • Merge results by chunk ID                              │
│                                                             │
│  Stage 3: Cross-Encoder Reranking                           │
│    • ms-marco-MiniLM-L-6-v2 scores (query, doc) pairs       │
│    • Return top K by relevance                              │
└─────────────────────────────────────────────────────────────┘

AWS知识库MCP服务器(`aws_kb/`)

┌─────────────────────────────────────────────────────────────┐
│                   Infrastructure                            │
├─────────────────────────────────────────────────────────────┤
│  docs/*.md → S3 Bucket → Knowledge Base                     │
│  • Titan Embeddings v2 (1024-dim)                           │
│  • S3 Vectors for storage                                   │
│  • Fixed-size chunking (200 tokens)                         │
│  • Auto-ingestion on sync                                   │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                    Runtime (Query)                          │
├─────────────────────────────────────────────────────────────┤
│  Query → Knowledge Base Retrieve API → Results              │
│  • Vector search with cosine similarity                     │
│  • Reranking not available in ap-southeast-2                │
│  • Documents read directly from S3                          │
└─────────────────────────────────────────────────────────────┘

主要特点

🔍 混合搜索（本地）/矢量搜索（AWS）

本地：BM25+矢量+交叉编码器重新排序
亚马逊云服务：使用Titan嵌入进行矢量搜索
两者：自然语言查询的语义相似性

📖 精确读数

线路范围访问：从源文件中读取确切的部分
加强安保：路径遍历阻止，仅限.md文件
元数据跟踪：每个块的文件名和行号

🔒 安全

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

可用工具

`pqsoft_search_docs(search_phrase: str, limit: int) -> 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 50

3.与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标题
为什么：在精确性和上下文保留之间取得平衡

演出

搜索延迟：典型查询<200ms
嵌入生成：每次查询约50ms
相似度计算：每块约1ms
记忆：~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')
# Update embedding dimension in CREATE TABLE statement

修改搜索限制

默认值为10个结果，最多50个。在工具调用中调整：

pqsoft_search_docs("query", limit=20)

故障排除

容器无法启动

# Check if image built successfully
docker images | grep best-practices-mcp

# View build logs
docker build -t best-practices-mcp . 2>&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 <KB_ID> --data-source-id <DS_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

贡献

将您的文档添加到 docs/
运行单元测试： cd src_mcp && uv run pytest tests/
使用本地服务器进行测试： ./run-local-mcp.sh
验证搜索是否有效
承诺并推动

状态

✅ 生产就绪

所有测试均已通过
加强安保
两种部署选项
符合MCP协议
完整记录现在我们列出了

使用说明

SDLC最佳实践MCP服务器

快速开始

本地MCP服务器（建议开发）

AWS知识库MCP服务器（生产）

体系结构比较

本地MCP服务器(src_mcp/)

AWS知识库MCP服务器(aws_kb/)

主要特点

🔍 混合搜索（本地）/矢量搜索（AWS）

📖 精确读数

🔒 安全

可用工具

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

pqsoft_read_docs(documentation_path: str, start_line: int, end_line: int) -> str

开发与测试

本地MCP服务器

AWS知识库MCP服务器

2.测试搜索功能

3.与Q CLI一起使用

本地开发

先决条件

本地运行

添加您自己的文档

目录结构

技术细节

本地MCP服务器

AWS知识库MCP服务器

分块策略

演出

定制

调整块大小

更改嵌入模型

修改搜索限制

故障排除

容器无法启动

搜索未返回任何结果

路径遍历错误

定制

调整块大小

更改嵌入模型

修改搜索限制

故障排除

本地MCP服务器

AWS知识库MCP服务器

比较：本地与AWS

许可证

测试

单元测试

集成测试

贡献

状态

相关 MCP

Qdrant向量搜索MCP服务器

开发者辅助工具

Gemini API文档搜索服务

文档搜索服务器

文件内容读取器

文档搜索服务

本地MCP服务器(`src_mcp/`)

AWS知识库MCP服务器(`aws_kb/`)

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

`pqsoft_read_docs(documentation_path: str, start_line: int, end_line: int) -> str`