strong-tie-mcp-server by ChrisTansey007 - MCP Server

Comprehensive Testing: Full test suite with pytest

Structured Logging: JSON logging with request tracking
Security: API key authentication and CORS protection
Monitoring: Health checks and performance metrics
Scalable Architecture: Hybrid SQLite + ChromaDB design

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   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      │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Data Flow

Ingestion: Strong-Tie API → SQLite (structured) + ChromaDB (vectors)
Exact Lookup: SKU → SQLite → Product JSON
Semantic Search: Query → E5 Embeddings → ChromaDB → Ranked Results
Question Answering: Question → Vector Retrieval → Mistral LLM → Answer

📦 Installation

Prerequisites

Python 3.11+
Git
Docker (optional but recommended)

Quick Start with 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

Local Development Setup

# 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

🔧 Configuration

Environment Variables

Key configuration options in .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

See .env.example for complete configuration options.

🛠️ API Reference

Tool Categories

Exact Tools

get_product_by_sku(sku: str) - Retrieve product by exact SKU
list_product_categories() - List all product categories with counts
list_recent_products(limit: int, offset: int) - Paginated product listing
database_health_check() - Database status and statistics

Vector Tools

semantic_search_products(query: str, k: int) - AI-powered product search
ask_product_question(question: str) - Natural language Q&A
vector_store_stats() - Vector database statistics

Asset Tools

get_product_assets(sku: str) - Retrieve product digital assets
upload_product_asset(sku: str, asset_url: str) - Register new assets

Spec Tools

get_product_specifications(sku: str) - Technical specifications
validate_product_compliance(sku: str, standards: list) - Compliance checking

Example API Calls

Using 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?"}}'

Using 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")

🚀 Deployment

Docker Production Deployment

# 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

Cloud Deployment

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

Google Cloud Run

# 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

Performance Optimization

GPU Acceleration

# Enable CUDA for embeddings
EMB_DEVICE=cuda

# Docker with GPU support
docker-compose -f docker-compose.gpu.yml up

Scaling

Use multiple workers: WORKERS=4
Load balancer for high availability
Redis caching for frequent queries
Database read replicas

🧪 Testing

Run Test Suite

# 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

Test Categories

Smoke Tests: Basic functionality verification
Integration Tests: End-to-end workflow testing
Performance Tests: Load and response time testing
Security Tests: Authentication and authorization

Example Test Output

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 =================================

📊 Monitoring

Health Checks

# 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": {}}'

Logs

# 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}

Metrics

Key metrics to monitor:

Request latency (p50, p95, p99)
Error rates by tool
Database query performance
Vector search response times
Memory usage and embeddings cache
Active connections

🔍 Troubleshooting

Common Issues

Database Connection Errors

# Check database file permissions
ls -la data/catalog.db

# Recreate database
rm data/catalog.db
python -m app.ingest.seed

Vector Search Not Working

# 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.seed

LLM/Ollama Issues

# 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'))"

Memory Issues

# 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 Mode

Enable debug logging:

DEBUG=true
LOG_LEVEL=DEBUG

🤝 Contributing

Development Workflow

Fork and Clone

git clone https://github.com/YOUR-USERNAME/strong-tie-mcp-server.git
cd strong-tie-mcp-server

Set Up Development Environment

python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows
pip install -r requirements.txt
cp .env.example .env

Make Changes

Follow PEP 8 style guidelines
Add tests for new functionality
Update documentation as needed

Test Your Changes

pytest tests/ -v
black app/ tests/
flake8 app/ tests/

Submit Pull Request

Create feature branch
Write clear commit messages
Include tests and documentation updates

Code Style

Use black for formatting
Follow flake8 linting rules
Type hints encouraged
Comprehensive docstrings

Adding New Tools

Create Tool Module

# 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}

Register in init.py

# app/tools/__init__.py
from . import my_tools

Add Tests

# tests/test_my_tools.py
@pytest.mark.asyncio
async def test_my_new_tool(http_client, mcp_headers):
    # Test implementation
    pass

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

FastMCP: Excellent MCP server framework
Strong-Tie: Product data and API access
LangChain: AI/ML framework and integrations
ChromaDB: Vector database for semantic search
Sentence Transformers: E5-base-v2 embedding model

📞 Support

Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Project Wiki

🗺️ Roadmap

v1.1 (Next Release)

Advanced caching layer (Redis)
Batch operations API
Enhanced asset management
Performance dashboards

v1.2 (Future)

Multi-tenant support
Real-time sync with Strong-Tie API
Advanced analytics and reporting
GraphQL API

v2.0 (Long-term)

Machine learning recommendations
Multi-language support
Integration marketplace
Advanced compliance automation

Built with ❤️ for the construction industry