SPURS MCP Server

SPURS MCP Server

Self-evolving MCP server that automatically discovers, generates, and registers new tools on demand using AI, enabling dynamic tool expansion without manual intervention.

Category
Visit Server

README

SPURS MCP Server

<div align="center">

SPURS MCP Server MCP Protocol License Status

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>

Recommended Servers

playwright-mcp

playwright-mcp

A Model Context Protocol server that enables LLMs to interact with web pages through structured accessibility snapshots without requiring vision models or screenshots.

Official
Featured
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

An AI-powered tool that generates modern UI components from natural language descriptions, integrating with popular IDEs to streamline UI development workflow.

Official
Featured
Local
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

Enables interaction with Audiense Insights accounts via the Model Context Protocol, facilitating the extraction and analysis of marketing insights and audience data including demographics, behavior, and influencer engagement.

Official
Featured
Local
TypeScript
VeyraX MCP

VeyraX MCP

Single MCP tool to connect all your favorite tools: Gmail, Calendar and 40 more.

Official
Featured
Local
graphlit-mcp-server

graphlit-mcp-server

The Model Context Protocol (MCP) Server enables integration between MCP clients and the Graphlit service. Ingest anything from Slack to Gmail to podcast feeds, in addition to web crawling, into a Graphlit project - and then retrieve relevant contents from the MCP client.

Official
Featured
TypeScript
Kagi MCP Server

Kagi MCP Server

An MCP server that integrates Kagi search capabilities with Claude AI, enabling Claude to perform real-time web searches when answering questions that require up-to-date information.

Official
Featured
Python
E2B

E2B

Using MCP to run code via e2b.

Official
Featured
Neon Database

Neon Database

MCP server for interacting with Neon Management API and databases

Official
Featured
Exa Search

Exa Search

A Model Context Protocol (MCP) server lets AI assistants like Claude use the Exa AI Search API for web searches. This setup allows AI models to get real-time web information in a safe and controlled way.

Official
Featured
Qdrant Server

Qdrant Server

This repository is an example of how to create a MCP server for Qdrant, a vector search engine.

Official
Featured