SDK, CLI & MCP Server Testing Guide

Step-by-step instructions to manually test the Precogs SDK, CLI, and MCP Server.

Prerequisites

1. API Key: Create one from the WebApp dashboard or via API
2. Backend Running: http://localhost:4500 (dev) or https://api.precogs.ai (prod)
3. Test Key Created: pk_live_819dda2aee34401083feaef9f587e514 (example)

---

📦 Published Packages

• precogs-sdk: https://pypi.org/project/precogs-sdk/
• precogs-cli: https://pypi.org/project/precogs-cli/

1. Python SDK Testing

Installation

cd /path/to/precogs-sdk
pip install -e .

Test Script

Create test_sdk.py:

#!/usr/bin/env python3
"""SDK Manual Test Script"""

import os
from precogs import PrecogsClient

# Set your API key
os.environ["PRECOGS_API_KEY"] = "pk_live_YOUR_KEY_HERE"

def test_sdk():
    print("=== Precogs SDK Test ===\n")
    
    # 1. Initialize client
    print("1. Initializing client...")
    client = PrecogsClient()
    print(f"   ✓ Client: {client}\n")
    
    # 2. List API keys
    print("2. Listing API keys...")
    try:
        keys = client.api_keys.list()
        print(f"   ✓ Found {len(keys)} keys\n")
    except Exception as e:
        print(f"   ✗ Error: {e}\n")
    
    # 3. List projects
    print("3. Listing projects...")
    try:
        projects = client.projects.list()
        print(f"   ✓ Found {len(projects)} projects")
        if projects:
            print(f"   First: {projects[0].get('name', 'N/A')}\n")
    except Exception as e:
        print(f"   ✗ Error: {e}\n")
    
    # 4. Get dashboard
    print("4. Getting dashboard...")
    try:
        overview = client.dashboard.get_overview()
        print(f"   ✓ Dashboard: {overview}\n")
    except Exception as e:
        print(f"   ✗ Error: {e}\n")
    
    # 5. List vulnerabilities
    print("5. Listing vulnerabilities...")
    try:
        vulns = client.vulnerabilities.list(limit=5)
        print(f"   ✓ Found {len(vulns)} vulnerabilities\n")
    except Exception as e:
        print(f"   ✗ Error: {e}\n")
    
    print("=== Test Complete ===")
    client.close()

if __name__ == "__main__":
    test_sdk()

Run Test

python test_sdk.py

Expected Output

=== Precogs SDK Test ===

1. Initializing client...
   ✓ Client: <PrecogsClient base_url='https://api.precogs.ai'>

2. Listing API keys...
   ✓ Found 1 keys

3. Listing projects...
   ✓ Found 5 projects
   First: my-repo

4. Getting dashboard...
   ✓ Dashboard: {'total': 42, 'critical': 2, ...}

5. Listing vulnerabilities...
   ✓ Found 5 vulnerabilities

=== Test Complete ===

---

2. CLI Testing

Installation

cd /path/to/precogs-cli
pip install -e .

Test Commands

# 1. Check version
precogs version
# Expected: Precogs CLI v0.1.0

# 2. Login with API key
precogs auth login --api-key pk_live_YOUR_KEY_HERE
# Expected: ✓ API key saved to ~/.precogs/config.json

# 3. Check auth status
precogs auth status
# Expected: ✓ Authenticated with key: pk_live_819dda2...e514

# 4. List projects
precogs projects list
# Expected: Table of projects with ID, Name, Provider, Branch, Last Scan

# 5. Get specific project
precogs projects get PROJECT_ID
# Expected: Panel with project details

# 6. Trigger code scan
precogs scan code PROJECT_ID --branch main
# Expected: ✓ Scan started: scan_xxx

# 7. List vulnerabilities
precogs vulns list --limit 10
# Expected: Table of vulnerabilities

# 8. Get vulnerability details
precogs vulns get VULN_ID
# Expected: Panel with vulnerability details

# 9. Get AI fix suggestion
precogs vulns fix VULN_ID
# Expected: Panel with suggested code fix

# 10. View dashboard
precogs dashboard
# Expected: Security dashboard with severity counts

# 11. Logout
precogs auth logout
# Expected: ✓ Logged out. API key removed.

Quick Test Script

#!/bin/bash
# cli_test.sh

set -e
echo "=== Precogs CLI Test ==="

echo -e "\n1. Version"
precogs version

echo -e "\n2. Auth Login"
precogs auth login --api-key $PRECOGS_API_KEY

echo -e "\n3. Auth Status"
precogs auth status

echo -e "\n4. Projects List"
precogs projects list

echo -e "\n5. Dashboard"
precogs dashboard

echo -e "\n6. Vulnerabilities"
precogs vulns list --limit 5

echo -e "\n=== Test Complete ==="

---

3. MCP Server Testing

Installation

cd /path/to/precogs-mcp-server
npm install
npm run build

Manual Testing with Node

# Set environment variable
export PRECOGS_API_KEY="pk_live_YOUR_KEY_HERE"

# Run the server
node dist/index.js
# Expected: "Precogs MCP Server running on stdio"

Testing with Claude Desktop

1. Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "precogs": {
      "command": "node",
      "args": ["/path/to/precogs-mcp-server/dist/index.js"],
      "env": {
        "PRECOGS_API_KEY": "pk_live_YOUR_KEY_HERE"
      }
    }
  }
}

2. Restart Claude Desktop

3. Test Tools - Ask Claude:

   • "List my Precogs projects"
   • "Show security dashboard"
   • "Find critical vulnerabilities"
   • "Scan project PROJECT_ID for code issues"

Testing with MCP Inspector

# Install MCP Inspector
npm install -g @anthropic-ai/mcp-inspector

# Run inspector
PRECOGS_API_KEY=pk_live_xxx npx mcp-inspector node dist/index.js

Available MCP Tools

Tool	Description
precogs_list_projects	List all projects
precogs_get_project	Get project details
precogs_scan_code	Trigger SAST scan
precogs_scan_dependencies	Trigger SCA scan
precogs_scan_iac	Trigger IaC scan
precogs_get_scan_results	Get scan results
precogs_list_vulnerabilities	List vulnerabilities
precogs_get_vulnerability	Get vulnerability details
precogs_get_ai_fix	Get AI fix suggestion
precogs_dashboard	Get dashboard overview

---

Troubleshooting

Common Errors

Error	Cause	Fix
Invalid API key format	Key doesn't start with pk_	Check key format
Invalid or inactive API key	Key revoked or wrong	Create new key
Authentication required	Missing auth header	Set PRECOGS_API_KEY env var
ECONNREFUSED	Backend not running	Start API server
ModuleNotFoundError: No module named 'precogs'	SDK not installed	Run pip install -e .

Debug Mode

# SDK - Enable debug logging
PRECOGS_DEBUG=1 python test_sdk.py

# CLI - Verbose output
precogs --help  # Shows all commands

# MCP - Check stderr
node dist/index.js 2>&1 | head -20

---

Test Checklist

SDK

• Client initialization works
• API key from environment variable works
• api_keys.list() returns keys
• projects.list() returns projects
• scans.trigger_code_scan() starts scan
• vulnerabilities.list() returns vulnerabilities
• dashboard.get_overview() returns stats

CLI

• precogs version shows version
• precogs auth login saves key
• precogs auth status shows masked key
• precogs projects list shows table
• precogs scan code PROJECT_ID triggers scan
• precogs vulns list shows vulnerabilities
• precogs dashboard shows overview
• precogs auth logout clears key

MCP Server

• Server starts without errors
• precogs_list_projects works
• precogs_dashboard works
• precogs_scan_code triggers scan
• Claude Desktop integration works