综合测试：带pytest的完整测试套件
- 结构化日志记录：JSON日志记录和请求跟踪
- 安全：API密钥认证和CORS保护
- 监控：健康检查和绩效指标
- 可扩展体系结构：混合SQLite+ChromaDB设计
🏗️ 建筑
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ FastMCP │ │ SQLite DB │ │ ChromaDB │
│ (API Layer) │◄──►│ (Exact Lookup) │ │ (Vector Store)│
└─────────────────┘ └──────────────────┘ └─────────────────┘
│ │ │
▼ ▼ ▼
┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐
│ Tool Modules │ │ Product Data │ │ E5-base-v2 │
│ - exact_tools │ │ - SKU │ │ Embeddings │
│ - vector_tools│ │ - blob │ │ - Semantic │
│ - asset_tools │ │ - sha │ │ - Chunks │
│ - spec_tools │ │ - updated │ │ - Search │
└─────────────────┘ └──────────────────┘ └─────────────────┘数据流
- 摄入：强力API→ SQLite（结构化）+ChromaDB（矢量）
- 精确查找：SKU→ 数据库→ 产品JSON
- 语义搜索：查询→ E5嵌入件→ ChromaDB→ 排名结果
- 问答：问题→ 矢量检索→ 米斯特拉尔法学硕士→ 回答
📦 安装
先决条件
- Python 3.11+
- Git
- Docker（可选但推荐）
Docker快速入门
# Clone the repository
git clone https://github.com/ChrisTansey007/strong-tie-mcp-server.git
cd strong-tie-mcp-server
# Copy environment configuration
cp .env.example .env
# Edit .env file with your settings
# At minimum, change MCP_API_KEY and SECRET_KEY for production
# Build and run with Docker Compose
docker-compose up --build
# Server will be available at http://localhost:8000
# API documentation at http://localhost:8000/docs地方发展设置
# Clone and enter directory
git clone https://github.com/ChrisTansey007/strong-tie-mcp-server.git
cd strong-tie-mcp-server
# Create virtual environment
python -m venv venv
# Activate virtual environment
# Windows:
venv\Scripts\activate
# Linux/Mac:
source venv/bin/activate
# Install dependencies
pip install -r requirements.txt
# Copy and configure environment
cp .env.example .env
# Edit .env as needed
# Run initial data ingestion
python -m app.ingest.seed
# Start the server
python -m app.server
# Server runs at http://localhost:8000🔧 配置
环境变量
中的关键配置选项 .env:
# Security (REQUIRED for production)
MCP_API_KEY=your-secure-api-key
SECRET_KEY=your-secure-secret-key
# Server
ENVIRONMENT=production # development, testing, production
HOST=0.0.0.0
PORT=8000
DEBUG=false
# AI/ML
EMB_MODEL=intfloat/e5-base-v2
EMB_DEVICE=cpu # or 'cuda' for GPU acceleration
LLM_MODEL=mistral
# Performance
MAX_RPS=5
WORKERS=1 # For production deployment看 .env.example 了解完整的配置选项。
🛠️ api参考
工具类别
精确工具
get_product_by_sku(sku: str)-按确切SKU检索产品list_product_categories()-列出所有产品类别及其计数list_recent_products(limit: int, offset: int)-分页产品列表database_health_check()-数据库状态和统计
矢量工具
semantic_search_products(query: str, k: int)-基于人工智能的产品搜索ask_product_question(question: str)-自然语言问答vector_store_stats()-矢量数据库统计
资产工具
get_product_assets(sku: str)-检索产品数字资产upload_product_asset(sku: str, asset_url: str)-注册新资产
规范工具
get_product_specifications(sku: str)-技术规格validate_product_compliance(sku: str, standards: list)-合规性检查
API调用示例
使用curl
# Get product by SKU
curl -X POST http://localhost:8000/mcp \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"tool": "get_product_by_sku", "args": {"sku": "H1"}}'
# Semantic search
curl -X POST http://localhost:8000/mcp \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"tool": "semantic_search_products", "args": {"query": "stainless steel clips", "k": 5}}'
# Ask a question
curl -X POST http://localhost:8000/mcp \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"tool": "ask_product_question", "args": {"question": "What clips work best for outdoor use?"}}'使用Python
import httpx
headers = {"X-API-Key": "your-api-key", "Content-Type": "application/json"}
base_url = "http://localhost:8000/mcp"
async with httpx.AsyncClient() as client:
# Search for products
response = await client.post(
base_url,
headers=headers,
json={
"tool": "semantic_search_products",
"args": {"query": "structural screws", "k": 10}
}
)
results = response.json()
print(f"Found {len(results['results'])} products")🚀 部署
Docker生产部署
# Production with custom environment
docker-compose -f docker-compose.yml up -d
# With Ollama LLM service
docker-compose --profile llm up -d
# View logs
docker-compose logs -f strongtie-server
# Scale with multiple workers
docker-compose up --scale strongtie-server=3云部署
AWS ECS/Fargate
# Build and push to ECR
aws ecr get-login-password --region us-east-1 | docker login --username AWS --password-stdin 123456789012.dkr.ecr.us-east-1.amazonaws.com
docker build -t strongtie-mcp .
docker tag strongtie-mcp:latest 123456789012.dkr.ecr.us-east-1.amazonaws.com/strongtie-mcp:latest
docker push 123456789012.dkr.ecr.us-east-1.amazonaws.com/strongtie-mcp:latest谷歌云运行
# Build and deploy
gcloud builds submit --tag gcr.io/PROJECT-ID/strongtie-mcp
gcloud run deploy --image gcr.io/PROJECT-ID/strongtie-mcp --platform managed性能优化
GPU加速
# Enable CUDA for embeddings
EMB_DEVICE=cuda
# Docker with GPU support
docker-compose -f docker-compose.gpu.yml up扩展
- 使用多个workers：
WORKERS=4 - 高可用性负载均衡器
- Redis缓存用于频繁查询
- 数据库读取副本
🧪 测试
运行测试套件
# Install test dependencies
pip install -r requirements.txt
# Run all tests
pytest tests/ -v
# Run with coverage
pytest tests/ --cov=app --cov-report=html
# Run specific test categories
pytest tests/test_smoke.py::TestExactTools -v测试类别
- 冒烟测试：基本功能验证
- 集成测试：端到端工作流测试
- 性能测试：负载和响应时间测试
- 安全测试：身份验证和授权
测试输出示例
tests/test_smoke.py::TestExactTools::test_get_product_by_sku_success PASSED
tests/test_smoke.py::TestVectorTools::test_semantic_search_products PASSED
tests/test_smoke.py::TestServerEndpoints::test_health_endpoint PASSED
================================= 15 passed in 12.34s =================================📊 监控
健康检查
# Server health
curl http://localhost:8000/health
# Database status
curl -X POST http://localhost:8000/mcp \
-H "X-API-Key: your-api-key" \
-d '{"tool": "database_health_check", "args": {}}'
# Vector store statistics
curl -X POST http://localhost:8000/mcp \
-H "X-API-Key: your-api-key" \
-d '{"tool": "vector_store_stats", "args": {}}'日志
# Docker logs
docker-compose logs -f strongtie-server
# Local development
tail -f data/server.log
# Structured JSON logs in production
{"timestamp": "2024-01-15T10:30:00Z", "level": "info", "message": "Request completed", "request_id": "abc123", "duration_ms": 45}指标
需监控的关键指标：
- 请求延迟（p50、p95、p99）
- 按工具分类的错误率
- 数据库查询性能
- 矢量搜索响应时间
- 内存使用和嵌入缓存
- 活动连接
🔍 故障排除
常见问题
数据库连接错误
# Check database file permissions
ls -la data/catalog.db
# Recreate database
rm data/catalog.db
python -m app.ingest.seed矢量搜索不起作用
# Check ChromaDB directory
ls -la data/chroma/
# Verify embeddings model
python -c "from app.embeddings import get_embeddings; print(get_embeddings())"
# Rebuild vector store
rm -rf data/chroma/
python -m app.ingest.seedLLM/Ollama问题
# Check Ollama service
curl http://localhost:11434/api/tags
# Pull Mistral model
ollama pull mistral
# Test question answering
python -c "from langchain.llms import Ollama; print(Ollama(model='mistral')('Hello'))"内存问题
# Monitor memory usage
docker stats strongtie-mcp-server
# Reduce embedding batch size
EMB_BATCH_SIZE=16
# Use CPU instead of GPU
EMB_DEVICE=cpu调试模式
启用调试日志记录：
DEBUG=true
LOG_LEVEL=DEBUG🤝 贡献
开发工作流程
- 分叉和克隆
git clone https://github.com/YOUR-USERNAME/strong-tie-mcp-server.git
cd strong-tie-mcp-server- 设置开发环境
python -m venv venv
source venv/bin/activate # or venv\Scripts\activate on Windows
pip install -r requirements.txt
cp .env.example .env- 进行更改
- 遵循PEP 8风格指南
- 添加新功能的测试
- 根据需要更新文档
- 测试您的更改
pytest tests/ -v
black app/ tests/
flake8 app/ tests/- 提交拉取请求
- 创建特征分支
- 写明确的提交消息
- 包括测试和文档更新
代码的风格
- 使用
black用于格式化 - 跟随
flake8衣襟规则 - 鼓励键入提示
- 全面的文档字符串
添加新工具
- 创建工具模块
# app/tools/my_tools.py
from fastmcp import FastMCP
mcp = FastMCP.current()
@mcp.tool
def my_new_tool(param: str) -> dict:
"""Tool description."""
return {"result": param}- 注册 __初始化__南美国家巴拉圭的缩写（Paraguay）
# app/tools/__init__.py
from . import my_tools- 添加测试
# tests/test_my_tools.py
@pytest.mark.asyncio
async def test_my_new_tool(http_client, mcp_headers):
# Test implementation
pass📄 许可证
此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。
🙏 致谢
- FastMCP：优秀的MCP服务器框架
- 牢固的领带：产品数据和API访问
- LangChain：AI/ML框架和集成
- ChromaDB：用于语义搜索的矢量数据库
- 句子转换：E5-base-v2嵌入模型
📞 支持
- 问题:
- 讨论:
- 文档: 维基工程
🗺️ Roadmap
v1.1（下一版本）
- \[\]高级缓存层（Redis）
- \[\]批量操作API
- \[\]加强资产管理
- \[\]性能仪表板
v1.2（未来）
- \[\]多租户支持
- \[\]与Strong-Tie API实时同步
- \[\]高级分析和报告
- \[\]GraphQL API
v2.0（长期）
- \[\]机器学习建议
- \[\]多语言支持
- \[\]集成市场
- \[\]高级合规自动化
______________________________________________________________________
内置于❤️ 建筑行业