SPURS MCP Server

<div align="center">

Official Model Context Protocol Server for the US Department of Special Projects and Unified Response Services (US-SPURS)

Features • Quick Start • Architecture • Tools • API • Security

</div>

---

Overview

SPURS MCP Server is an enterprise-grade, self-evolving Model Context Protocol server that grows its capabilities automatically using AI. When a tool is requested that doesn't exist, the server discovers implementations from GitHub and Postman, generates new tools using AI, validates them in a secure sandbox, and permanently adds them to its registry.

┌─────────────────────────────────────────────────────────────┐
│  User Request: "I need a tool to analyze sentiment"         │
│                            │                                │
│                            ▼                                │
│  ┌─────────────────────────────────────────────────────┐   │
│  │  Tool exists? ─► YES ─► Execute immediately         │   │
│  │       │                                              │   │
│  │      NO                                              │   │
│  │       │                                              │   │
│  │       ▼                                              │   │
│  │  AUTO-EVOLUTION ENGINE                               │   │
│  │  1. Search GitHub + Postman for implementations     │   │
│  │  2. AI analyzes and generates tool code             │   │
│  │  3. Secure sandbox testing & validation             │   │
│  │  4. Register permanently in database                │   │
│  │  5. Execute and return result                       │   │
│  │                                                      │   │
│  │  ✓ Tool now available forever                       │   │
│  └─────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────┘

---

Features

Core Capabilities

Feature	Description
Self-Evolving Tools	Automatically discovers, generates, and registers new tools on-demand
Multi-AI Platform	Native support for OpenAI, Anthropic Claude, and Google Gemini with automatic failover
Full MCP Protocol	Complete implementation of MCP 2024-11-05 specification
Enterprise Security	Encrypted secrets, RBAC, sandboxed execution, audit logging
Real-time Streaming	WebSocket support for live AI response streaming
Production Web UI	Modern dashboard for tool management, monitoring, and AI playground

Auto-Evolution Engine

The server's unique capability to grow itself:

• GitHub Discovery - Searches MCP server repositories for tool implementations
• Postman Discovery - Finds API collections with relevant capabilities
• AI Code Generation - Uses LLMs to analyze and generate compatible tool code
• Secure Sandbox Testing - Validates generated tools in isolated environment
• Dynamic Registration - Hot-reloads new tools without server restart
• Creation Audit Trail - Full logging of how each tool was created

AI Provider Management

• Health Monitoring - Real-time status checks for each provider
• Automatic Failover - Seamlessly switches providers on failure
• Guided Setup - Step-by-step configuration for new users
• Usage Analytics - Track API usage and costs per provider

---

Quick Start

Prerequisites

• Node.js 18+ (required for native fetch API)
• PostgreSQL database (Neon-backed recommended)
• API keys for AI providers (OpenAI required, others optional)

Installation

# Clone the repository
git clone https://github.com/US-SPURS/spurs-mcp-server.git
cd spurs-mcp-server

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Edit .env with your configuration

# Initialize database
npm run db:push

# Start the server
npm start

MCP Client Configuration

Add to your Claude Desktop or MCP client configuration:

{
  "mcpServers": {
    "spurs": {
      "url": "http://localhost:5000",
      "headers": {
        "X-API-Key": "your-api-key"
      }
    }
  }
}

Verify Installation

# Health check
curl http://localhost:5000/health

# List available tools
curl -H "X-API-Key: demo-api-key" http://localhost:5000/mcp/tools

# Execute a tool
curl -X POST http://localhost:5000/mcp/tools/call \
  -H "X-API-Key: demo-api-key" \
  -H "Content-Type: application/json" \
  -d '{"name": "generate_uuid", "arguments": {"count": 3}}'

---

Architecture

┌─────────────────────────────────────────────────────────────────────────────┐
│                           SPURS MCP SERVER                                   │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐                   │
│  │   WEB UI     │    │   REST API   │    │  WEBSOCKET   │                   │
│  │  Port 5000   │    │   /mcp/*     │    │    /ws       │                   │
│  └──────┬───────┘    └──────┬───────┘    └──────┬───────┘                   │
│         │                   │                   │                            │
│         └───────────────────┼───────────────────┘                            │
│                             ▼                                                │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                    SECURITY LAYER                                    │    │
│  │                                                                      │    │
│  │  • API Key Authentication      • Role-Based Access Control (RBAC)  │    │
│  │  • Rate Limiting (per key)     • Request Validation                 │    │
│  │  • Encrypted Secret Storage    • Audit Logging                      │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                             │                                                │
│                             ▼                                                │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                       TOOL ROUTER                                    │    │
│  │                                                                      │    │
│  │   Tool Request ──► Exists? ──► YES ──► Execute & Return             │    │
│  │                        │                                             │    │
│  │                       NO                                             │    │
│  │                        ▼                                             │    │
│  │        ┌───────────────────────────────────────┐                    │    │
│  │        │      AUTO-EVOLUTION ENGINE            │                    │    │
│  │        │                                       │                    │    │
│  │        │  Discovery ─► Analysis ─► Generation  │                    │    │
│  │        │      │                                │                    │    │
│  │        │      ▼                                │                    │    │
│  │        │  Testing ─► Validation ─► Registration│                    │    │
│  │        └───────────────────────────────────────┘                    │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                             │                                                │
│         ┌───────────────────┼───────────────────┐                           │
│         ▼                   ▼                   ▼                           │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────┐                     │
│  │  BUILT-IN   │    │  GENERATED  │    │     AI      │                     │
│  │   TOOLS     │    │    TOOLS    │    │  PROVIDERS  │                     │
│  │             │    │             │    │             │                     │
│  │  9 core     │    │  Unlimited  │    │  OpenAI     │                     │
│  │  utilities  │    │  AI-created │    │  Anthropic  │                     │
│  │             │    │  tools      │    │  Gemini     │                     │
│  └─────────────┘    └─────────────┘    └─────────────┘                     │
│                             │                                                │
│                             ▼                                                │
│  ┌─────────────────────────────────────────────────────────────────────┐    │
│  │                    POSTGRESQL DATABASE                               │    │
│  │                                                                      │    │
│  │  api_keys          │ provider_settings  │ activity_logs             │    │
│  │  generated_tools   │ chat_history       │ tool_creation_logs        │    │
│  │  server_config     │ audit_trail        │ user_roles                │    │
│  └─────────────────────────────────────────────────────────────────────┘    │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Project Structure

spurs-mcp-server/
├── index.js                    # Main server entry point
├── package.json                # Dependencies and scripts
│
├── public/                     # Web interface
│   ├── index.html              # Single-page application
│   ├── css/styles.css          # Production styling
│   └── js/app.js               # Frontend application
│
├── server/                     # Database layer
│   ├── db.js                   # Neon PostgreSQL connection
│   └── storage.js              # CRUD operations
│
├── shared/
│   └── schema.js               # Drizzle ORM schema
│
├── src/
│   ├── config/                 # Configuration management
│   │   └── index.js
│   │
│   ├── middleware/             # Express middleware
│   │   ├── auth.js             # API key validation + RBAC
│   │   └── errorHandler.js     # Error handling
│   │
│   ├── mcp/                    # MCP registries
│   │   ├── toolRegistry.js     # Tool management
│   │   ├── promptRegistry.js   # Prompt templates
│   │   └── resourceRegistry.js # Resource definitions
│   │
│   ├── providers/              # AI provider adapters
│   │   ├── index.js            # Provider manager
│   │   ├── openai.js           # OpenAI integration
│   │   ├── anthropic.js        # Anthropic integration
│   │   └── gemini.js           # Google Gemini integration
│   │
│   ├── evolution/              # Auto-evolution engine
│   │   ├── orchestrator.js     # Main coordination
│   │   ├── discovery/
│   │   │   ├── github.js       # GitHub repo search
│   │   │   └── postman.js      # Postman collection search
│   │   ├── generator.js        # AI code generation
│   │   ├── sandbox.js          # Secure testing environment
│   │   └── registry.js         # Dynamic tool registration
│   │
│   ├── routes/                 # API routes
│   │   ├── mcp.js              # MCP protocol endpoints
│   │   ├── settings.js         # Configuration API
│   │   └── health.js           # Health checks
│   │
│   ├── tools/                  # Built-in tools
│   │   └── index.js            # Tool implementations
│   │
│   ├── utils/
│   │   └── logger.js           # Winston logging
│   │
│   └── websocket/
│       └── handler.js          # WebSocket MCP transport
│
└── docs/                       # Documentation
    ├── API.md                  # API reference
    ├── SECURITY.md             # Security policies
    └── TOOLS.md                # Tool development guide

---

Tools

Built-in Tools

Tool	Category	Description	Status
ai_chat	AI	Chat with AI models (OpenAI, Anthropic, Gemini)	✅ Production
ai_summarize	AI	Summarize text using AI with configurable length	✅ Production
ai_providers	AI	List available AI providers and their status	✅ Production
web_search	Search	Search the web and return structured results	✅ Production
code_sandbox	Code	Execute code in secure isolated sandbox	✅ Production
generate_uuid	Utility	Generate one or more UUIDs	✅ Production
timestamp	Utility	Get current timestamp in various formats	✅ Production
json_format	Utility	Format, validate, and transform JSON	✅ Production
base64	Utility	Encode/decode base64 strings	✅ Production

Auto-Generated Tools

Tools created by the auto-evolution engine are stored in the database and loaded dynamically:

// Example: Auto-generated sentiment analysis tool
{
  name: "sentiment_analysis",
  description: "Analyze sentiment of text (positive, negative, neutral)",
  category: "ai",
  source: "github:user/mcp-sentiment-server",
  created_at: "2024-12-02T10:30:00Z",
  usage_count: 1547,
  status: "active"
}

Creating Custom Tools

Tools follow a standard schema:

{
  name: "my_tool",
  description: "What this tool does",
  inputSchema: {
    type: "object",
    properties: {
      param1: { type: "string", description: "First parameter" },
      param2: { type: "integer", description: "Second parameter", default: 10 }
    },
    required: ["param1"]
  },
  handler: async (args) => {
    // Tool implementation
    return { result: "success", data: args.param1 };
  }
}

---

API Reference

Authentication

All API requests require the X-API-Key header:

curl -H "X-API-Key: your-api-key" https://your-server.com/mcp/tools

MCP Endpoints

Method	Endpoint	Description
GET	/health	Server health check
GET	/mcp/capabilities	Server capabilities and protocol version
GET	/mcp/tools	List all available tools
POST	/mcp/tools/call	Execute a tool
GET	/mcp/prompts	List prompt templates
POST	/mcp/prompts/get	Render a prompt template
GET	/mcp/resources	List available resources
POST	/mcp/resources/read	Read a resource
POST	/mcp/sampling/create	Create AI completion

Settings API

Method	Endpoint	Description
GET	/api/settings/stats	Server statistics
GET	/api/settings/providers	List AI providers
POST	/api/settings/providers/:name/test	Test provider connection
PUT	/api/settings/providers/:name	Update provider config
GET	/api/settings/api-keys	List API keys
POST	/api/settings/api-keys	Create new API key
DELETE	/api/settings/api-keys/:id	Revoke API key
GET	/api/settings/activity	Activity logs
GET	/api/settings/audit/export	Export audit logs (JSON/CSV)

WebSocket

Connect to /ws for real-time MCP communication:

const ws = new WebSocket('wss://your-server.com/ws', {
  headers: { 'X-API-Key': 'your-api-key' }
});

ws.send(JSON.stringify({
  jsonrpc: '2.0',
  method: 'tools/call',
  params: { name: 'ai_chat', arguments: { message: 'Hello!' } },
  id: 1
}));

Example Requests

Execute a Tool:

curl -X POST https://your-server.com/mcp/tools/call \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "ai_chat",
    "arguments": {
      "message": "Explain quantum computing in simple terms",
      "provider": "openai"
    }
  }'

AI Completion:

curl -X POST https://your-server.com/mcp/sampling/create \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      {"role": "user", "content": "Write a haiku about technology"}
    ],
    "provider": "anthropic",
    "maxTokens": 100
  }'

---

Web Interface

Access the web UI at http://localhost:5000 with these pages:

Page	Description
Home	Welcome page with feature overview and quick start
Dashboard	Real-time monitoring, stats, and activity feed
Tools	Browse, search, and execute all tools with user-friendly forms
Resources	Access MCP server resources
AI Playground	Interactive chat with AI providers
Connections	Manage external service integrations
Add-ons	Third-party extensions marketplace
Activity Logs	View all API activity and audit trail
Settings	Configure providers, API keys, and server settings

---

Security

Authentication & Authorization

• API Key Authentication - Secure key validation on all protected routes
• Role-Based Access Control (RBAC) - Granular permissions per key
• Scoped Permissions - Limit keys to specific tools or operations

Secret Management

• Encrypted Storage - All secrets encrypted at rest using AES-256
• No Plain Text - API keys and provider secrets never stored in plain text
• Secure Headers - API keys only accepted in headers (never query params)

Code Execution Safety

• Isolated Sandbox - Generated tools run in VM-isolated environment
• Resource Limits - CPU, memory, and time limits enforced
• Security Scanning - All generated code scanned before registration
• No Arbitrary Execution - Only validated, sandboxed code can run

Audit & Compliance

• Complete Audit Trail - Every API action logged with timestamp and user
• Export Capabilities - Audit logs exportable as JSON or CSV
• Webhook Notifications - Real-time alerts for security events
• Data Retention Policies - Configurable log retention periods

Network Security

• TLS 1.3 - All connections encrypted in transit
• Rate Limiting - Per-key and global rate limits
• CORS Protection - Configurable allowed origins
• DDoS Protection - Built-in request throttling

---

Configuration

Environment Variables

# Server
PORT=5000
NODE_ENV=production

# Database
DATABASE_URL=postgresql://user:pass@host:5432/spurs_mcp

# AI Providers (via Replit Integrations or manual)
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...

# Discovery APIs
GITHUB_TOKEN=ghp_...
POSTMAN_API_KEY=...

# Security
ENCRYPTION_KEY=your-32-byte-encryption-key
JWT_SECRET=your-jwt-secret

# Rate Limiting
RATE_LIMIT_MAX=100
RATE_LIMIT_WINDOW_MS=60000

Provider Configuration

Configure AI providers via the Settings API or web interface:

{
  "openai": {
    "enabled": true,
    "model": "gpt-4o-mini",
    "maxTokens": 4096,
    "temperature": 0.7
  },
  "anthropic": {
    "enabled": true,
    "model": "claude-3-5-sonnet-20241022",
    "maxTokens": 4096
  },
  "gemini": {
    "enabled": false,
    "model": "gemini-pro"
  }
}

---

Database Schema

Core Tables

-- API Keys with encryption
api_keys (
  id UUID PRIMARY KEY,
  name VARCHAR(255),
  key_hash VARCHAR(255),      -- Hashed key for validation
  key_prefix VARCHAR(10),     -- First 8 chars for identification
  scopes JSONB,               -- Permissions array
  rate_limit INTEGER,
  expires_at TIMESTAMP,
  created_at TIMESTAMP,
  last_used_at TIMESTAMP
)

-- Generated Tools
generated_tools (
  id UUID PRIMARY KEY,
  name VARCHAR(255) UNIQUE,
  description TEXT,
  category VARCHAR(50),
  input_schema JSONB,
  handler_code TEXT,          -- Encrypted
  source_type VARCHAR(50),    -- github, postman, ai
  source_url TEXT,
  version INTEGER,
  status VARCHAR(20),         -- testing, active, disabled
  test_results JSONB,
  created_at TIMESTAMP,
  last_used_at TIMESTAMP,
  usage_count INTEGER
)

-- Tool Creation Logs
tool_creation_logs (
  id UUID PRIMARY KEY,
  tool_id UUID REFERENCES generated_tools(id),
  stage VARCHAR(50),          -- discovery, analysis, generation, testing, registration
  status VARCHAR(20),
  details JSONB,
  ai_prompt_used TEXT,
  ai_response TEXT,
  created_at TIMESTAMP
)

-- Activity Logs
activity_logs (
  id UUID PRIMARY KEY,
  action VARCHAR(100),
  api_key_id UUID,
  details JSONB,
  ip_address VARCHAR(45),
  user_agent TEXT,
  created_at TIMESTAMP
)

---

Monitoring & Observability

Health Checks

# Basic health
GET /health
→ { "status": "healthy", "uptime": 86400, "version": "1.0.0" }

# Detailed status
GET /health/detailed
→ {
    "status": "healthy",
    "database": "connected",
    "providers": {
      "openai": "healthy",
      "anthropic": "healthy",
      "gemini": "degraded"
    },
    "tools": { "builtin": 9, "generated": 47 },
    "memory": { "used": "256MB", "total": "512MB" }
  }

Metrics

• Request count and latency per endpoint
• Tool execution success/failure rates
• AI provider usage and costs
• Auto-evolution success rate
• Database connection pool status

Webhook Notifications

Configure webhooks for real-time alerts:

{
  "webhook_url": "https://your-service.com/webhook",
  "events": [
    "tool.created",
    "tool.failed",
    "provider.down",
    "security.alert"
  ]
}

---

Development

Running Locally

# Development mode with hot reload
npm run dev

# Run tests
npm test

# Lint code
npm run lint

# Push database changes
npm run db:push

Adding Built-in Tools

// src/tools/myTool.js
const { toolRegistry } = require('../mcp/toolRegistry');

toolRegistry.register({
  name: 'my_custom_tool',
  description: 'Does something useful',
  category: 'utility',
  inputSchema: {
    type: 'object',
    properties: {
      input: { type: 'string', description: 'Input value' }
    },
    required: ['input']
  },
  handler: async (args) => {
    return { result: args.input.toUpperCase() };
  }
});

---

Deployment

Replit Deployment

The server is configured for one-click deployment on Replit:

1. Fork the repository to your Replit account
2. Set environment variables in Secrets
3. Click "Run" to start the server
4. Use the provided URL for API access

Docker Deployment

# Build image
docker build -t spurs-mcp-server .

# Run container
docker run -d \
  -p 5000:5000 \
  -e DATABASE_URL=your-db-url \
  -e OPENAI_API_KEY=your-key \
  spurs-mcp-server

Production Checklist

• [ ] Set NODE_ENV=production
• [ ] Configure TLS/HTTPS termination
• [ ] Set strong encryption keys
• [ ] Configure rate limiting
• [ ] Enable audit logging
• [ ] Set up monitoring/alerts
• [ ] Configure backup strategy
• [ ] Review CORS settings

---

Support

Resource	Link
Documentation	docs/
API Reference	docs/API.md
Security Policy	SECURITY.md
Issue Tracker	Internal SPURS ticket system

Contact

• Organization: US Department of Special Projects and Unified Response Services (US-SPURS)
• Classification: OFFICIAL USE ONLY
• Director Authorization: Philip Allen Cotton Jr.

---

License

PROPRIETARY - US Department of Special Projects and Unified Response Services (US-SPURS)

This software is classified as OFFICIAL USE ONLY and is restricted to authorized personnel only. Unauthorized access, use, or distribution is prohibited.

---

<div align="center">

SPURS MCP Server - Self-Evolving AI Infrastructure

Always Prepared. Prepare Always.

</div>