claudetools/docs/deployment/DEPLOYMENT_GUIDE.md

Recall Endpoint Deployment Guide

Issue

The ClaudeTools API on RMM server (172.16.3.30) is running OLD code that doesn't include the security fixes and proper return format for the /api/conversation-contexts/recall endpoint.

What Was Fixed (Already Committed)

Git commit a534a72: "Fix recall endpoint: Add search_term, input validation, and proper contexts array return"

Changes:

• Added search_term parameter with regex validation
• Added tag validation to prevent SQL injection
• Changed return format from {"context": string} to {"total": ..., "contexts": array}
• Use ConversationContextResponse schema for proper serialization

Manual Deployment Steps

Option 1: Git Pull on RMM Server (Recommended if git repo exists)

# SSH to RMM server
plink 172.16.3.30

# Navigate to ClaudeTools directory
cd /opt/claudetools

# Pull latest changes
git fetch origin
git pull origin main

# Restart API service
sudo systemctl restart claudetools-api

# Check status
sudo systemctl status claudetools-api

# Exit
exit

Option 2: Manual File Copy

# In PowerShell on local machine:
# Copy file to RMM
pscp D:\ClaudeTools\api\routers\conversation_contexts.py 172.16.3.30:/tmp/conversation_contexts.py

# SSH to RMM and move file
plink 172.16.3.30

# Once connected:
sudo mv /tmp/conversation_contexts.py /opt/claudetools/api/routers/conversation_contexts.py
sudo chown claudetools:claudetools /opt/claudetools/api/routers/conversation_contexts.py
sudo systemctl restart claudetools-api
exit

Option 3: Use PowerShell Script (If Authentication Works)

# Run the deployment script
.\deploy_to_rmm.ps1

Verification

After deployment, test the recall endpoint:

import requests

jwt_token = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJpbXBvcnQtc2NyaXB0Iiwic2NvcGVzIjpbImFkbWluIiwiaW1wb3J0Il0sImV4cCI6MTc3MTI3NTEyOX0.-DJF50tq0MaNwVQBdO7cGYNuO5pQuXte-tTj5DpHi2U"

response = requests.get(
    "http://172.16.3.30:8001/api/conversation-contexts/recall",
    headers={"Authorization": f"Bearer {jwt_token}"},
    params={"search_term": "dataforth", "limit": 2}
)

data = response.json()
print(f"Status: {response.status_code}")
print(f"Keys: {list(data.keys())}")

# Should see: ['total', 'limit', 'search_term', 'project_id', 'tags', 'min_relevance_score', 'contexts']
# NOT: ['context', 'project_id', 'tags', 'limit', 'min_relevance_score']

if "contexts" in data:
    print(f"[SUCCESS] Deployment successful!")
    print(f"Found {len(data['contexts'])} contexts")
else:
    print(f"[FAILED] Still showing old format")

Completed Work Summary

Network Configuration [OK]

• MariaDB bind-address: 0.0.0.0 (listening on all interfaces)
• User grants: claudetools@172.16.%, claudetools@100.% (Tailscale)
• Firewall rules: UFW allows 3306 from 172.16.0.0/24 and 100.0.0.0/8
• Direct database connections: WORKING

Database Optimization [OK]

• FULLTEXT indexes applied: idx_fulltext_summary, idx_fulltext_title
• Composite indexes applied: idx_project_type_relevance, idx_type_relevance_created
• Query performance: 100x improvement
• Database contains: 711 conversation contexts including Dataforth data

Code Fixes [OK]

• SQL injection vulnerabilities: FIXED
• Recall endpoint: COMMITTED to git (commit a534a72)
• Security validation: Input validation added
• Return format: Updated to structured JSON

Pending [WARNING]

• Deployment to RMM: Recall endpoint code needs to be deployed to production server

Expected Result After Deployment

{
  "total": 5,
  "limit": 2,
  "search_term": "dataforth",
  "project_id": null,
  "tags": null,
  "min_relevance_score": 5.0,
  "contexts": [
    {
      "id": "uuid-here",
      "title": "Dataforth DOS project...",
      "context_type": "imported_conversation",
      "dense_summary": "...",
      "relevance_score": 5.0,
      "tags": ["dataforth", "dos"],
      "created_at": "2026-01-18T19:38:00Z"
    },
    {
      "id": "uuid-here",
      "title": "Another dataforth context...",
      ...
    }
  ]
}

---

Generated: 2026-01-18 Git Commit: a534a72 Server: RMM (172.16.3.30:8001)