星际迷航语录服务器

# 1. Set up API key (one-time)
cp .env.example .env
# Edit .env: QUOTES_MCP_API_KEY=your_actual_api_key

# 2. Start proxy (keep running while using Cursor)
npm run start:proxy

# 3. Test it works
curl -X POST "http://localhost:3001" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

# 4. Configure Cursor to use the proxy (see MCP Client Configuration section)

# If using git
git clone <repository-url>
cd mcp-quotes-server

# Or download and extract the files to a directory

npm install

# Copy the example environment file
cp .env.example .env

# Edit .env and replace YOUR_API_KEY with a valid API key
# The file should contain:
# QUOTES_MCP_API_KEY=your_actual_api_key_here

# Test the server
npm test

# Start the server (for testing)
npm start

claude mcp add quotes --transport http http://localhost:3001

[
  {
    "quote": "Live long and prosper.",
    "by": "Spock"
  },
  {
    "quote": "Beam me up, Scotty.",
    "by": "Captain James T. Kirk"
  }
]

{
  "quote": "Make it so.",
  "by": "Captain Jean-Luc Picard"
}

1. "Live long and prosper." - Spock

2. "Beam me up, Scotty." - Captain James T. Kirk

3. "Resistance is futile." - The Borg

4. "Make it so." - Captain Jean-Luc Picard

5. "I have been, and always shall be, your friend." - Spock

6. "Logic is the beginning of wisdom, not the end." - Spock

7. "It was … fun." - Captain James T. Kirk

8. "I don't believe in the no-win scenario." - Captain James T. Kirk

Input: "Spock" → Returns all 3 Spock quotes
Input: "spock" → Same result (case-insensitive)
Input: "Captain" → Returns quotes from both Kirk and Picard
Input: "Worf" → Returns "No quotes found" message

"Live long and prosper." - Spock

# Required for proxy to authenticate with remote server
QUOTES_MCP_API_KEY=your-actual-api-key

# Optional proxy configuration (defaults shown)
PROXY_PORT=3001
REMOTE_MCP_URL=https://quotes-mcp-server.YOUR-SUBDOMAIN.workers.dev

npm run start:proxy

🚀 MCP Proxy Server Started
================================
📍 Local URL:  http://localhost:3001
🌐 Remote URL: https://quotes-mcp-server.YOUR-SUBDOMAIN.workers.dev
🔑 API Key:    ✅ Configured
================================

# Run proxy tests (requires proxy to be running)
./test-proxy.sh

# Or test manually without API key:
curl -X POST "http://localhost:3001" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

Local Client → Proxy Server → Remote MCP Server
     ↑               ↓                ↓
     └─── Response ←─┴── + API Key ←──┘

# Initialize MCP session (no API key required)
curl -X POST "http://localhost:3001" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {"roots": {}, "sampling": {}},
      "clientInfo": {"name": "local-client", "version": "1.0.0"}
    },
    "id": 1
  }'

# Get random quote (no API key required)
curl -X POST "http://localhost:3001" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "random-quote-tool",
      "arguments": {}
    },
    "id": 2
  }'

curl "http://localhost:3001/proxy/health"

{
  "status": "healthy",
  "proxy": {
    "port": 3001,
    "remote_url": "https://quotes-mcp-server.YOUR-SUBDOMAIN.workers.dev",
    "api_key_configured": true,
    "uptime": 120.5
  }
}

📨 POST / - Proxying to remote MCP server
📤 200 OK - 45ms
📨 POST / - Proxying to remote MCP server  
📤 200 OK - 32ms

# Client requests must include:
mcp-session-id: 550e8400-e29b-41d4-a716-446655440000

# Server responses include:
mcp-session-id: 550e8400-e29b-41d4-a716-446655440000

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00.000Z", 
  "quotesLoaded": 8,
  "activeSessions": 2,
  "transport": "mcp-http"
}

{
  "name": "Star Trek Quotes MCP Server",
  "version": "1.0.0",
  "transport": "mcp-streamable-http",
  "totalQuotes": 8,
  "activeSessions": 2,
  "endpoints": {
    "POST /mcp": "MCP client requests and initialization",
    "GET /mcp": "MCP server-to-client notifications (SSE)",
    "DELETE /mcp": "MCP session termination"
  }
}

# 1. Install dependencies
npm install

# 2. Deploy to Cloudflare Workers
npx wrangler deploy

# 3. Validate deployment
npm run test:cloudflare

POST /     - MCP protocol requests

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type

# MCP protocol request (requires API key)
curl -X POST https://quotes-mcp-server.YOUR-SUBDOMAIN.workers.dev \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2024-11-05"},"id":1}'

# Run ALL server implementations (79 total tests)
npm test

# Run all tests comprehensively
npm run test:all

# Run specific test suites by implementation
npm run test:core          # Local server implementations (64 tests)
npm run test:mcp           # MCP stdio server only (20 tests)
npm run test:http          # REST API server only (17 tests)
npm run test:mcp-http      # MCP HTTP server only (27 tests)
npm run test:cloudflare    # Cloudflare integration tests (15 tests) - requires .env
npm run test:cloudflare-quick  # Quick validation script (5 tests) - requires .env

# Development testing
npm run test:watch         # Run core tests in watch mode
npm run test:coverage      # Run core tests with coverage reporting

📊 Total Test Results:
   ✅ Core Tests: 64/64 passed (100%)
   ✅ Cloudflare Tests: 15/15 passed (100%)
   📈 Overall Success Rate: 79/79 (100%)

// Core quote operations used by all servers
export function searchQuotesByCharacter(quotesData, character)  // Character search with fuzzy matching
export function getRandomQuote(quotesData)                     // Random quote selection
export function formatQuoteAsText(quote)                       // Single quote formatting
export function formatQuotesAsText(quotesData)                 // Multi-quote numbered formatting
export function getAvailableCharacters(quotesData)             // Unique character extraction
export function searchQuotes(quotesData, query)                // General search functionality
export function validateQuoteData(quotesData)                  // Data structure validation
export function getQuoteStats(quotesData)                      // Collection statistics

// MCP resource and tool registration for all MCP servers
export function registerMcpResources(server, quotesData, serverType)  // Standard MCP resources
export function registerMcpTools(server, quotesData, serverType)      // Standard MCP tools  
export function getMcpServerMetadata(name, transport, quotesData, extras) // Server metadata

// HTTP endpoint handlers used by REST API
export function getApiInfo(quotesData, serverInfo)             // API information responses
export function getHealthCheck(quotesData, serverInfo)         // Health check responses
export function handleGetAllQuotes(quotesData)                 // GET /quotes logic
export function handleGetRandomQuote(quotesData)               // GET /quotes/random logic
export function handleGetQuotesByCharacter(quotesData, char)   // GET /quotes/character/:name logic
export function handleGetCharacters(quotesData)                // GET /characters logic
export function handleSearchQuotes(quotesData, query)          // GET /search logic
export function handle404NotFound()                            // Standard 404 responses
export function handleError(message, error)                    // Error response formatting

// Shared testing functions and data used across all test files
export const mockQuotesData                                    // Consistent test data
export function createTestHandlers(testQuotesData)             // Test handler factories
export function validateQuoteStructure(quote)                  // Quote validation
export function validateExpectedCharacters(characters)         // Character validation
export const characterSearchTests                              // Common test cases
export function validateResponseHeaders(response)              // Header validation
export function validateCORSHeaders(response)                  // CORS validation
export function validateDataIntegrity(data)                    // Data integrity checks

// Minimal MCP server for local client integration (Cursor IDE, Claude Code)
import { registerMcpResources, registerMcpTools } from './lib/mcp-resources.js';

const server = new McpServer({ name: 'quotes-server', version: '1.0.0' });
registerMcpResources(server, quotesData, 'Stdio');  // 3 MCP resources
registerMcpTools(server, quotesData, 'Stdio');      // 2 MCP tools

// Uses: StdioServerTransport for process communication
// Purpose: Local development, IDE integration
// Started with: npm start

// HTTP-based MCP server with session management
import { registerMcpResources, registerMcpTools, getMcpServerMetadata } from './lib/mcp-resources.js';

function createMcpServer() {
  const server = new McpServer({ name: 'quotes-server-http', version: '1.0.0' });
  registerMcpResources(server, quotesData, 'HTTP');  // Same 3 MCP resources
  registerMcpTools(server, quotesData, 'HTTP');      // Same 2 MCP tools
  return server;
}

// Uses: StreamableHTTPServerTransport + Express.js
// Features: Session management, SSE notifications, CORS
// Purpose: Remote MCP clients, web integration
// Started with: npm run start:mcp-http

// Traditional REST API using shared response handlers
import { 
  getApiInfo, getHealthCheck, handleGetAllQuotes, handleGetRandomQuote,
  handleGetQuotesByCharacter, handleGetCharacters, handleSearchQuotes,
  handle404NotFound, handleError 
} from './lib/rest-api-helpers.js';

// All endpoints are simple wrappers:
app.get('/quotes', (req, res) => {
  const result = handleGetAllQuotes(quotesData);
  res.json(result);
});

// Uses: Express.js framework
// Purpose: REST API consumers, web applications
// Started with: npm run start:http

// Global edge MCP server using DRY principles
import quotesData from './quotes.json';  // Single source of truth
import { 
  getRandomQuote, formatQuoteAsText, formatQuotesAsText, 
  searchQuotesByCharacter, getAvailableCharacters 
} from './lib/quote-functions.js';

// Lightweight HTTP handler using shared functions
export default {
  async fetch(request, env, ctx) {
    // Direct MCP protocol implementation
    // Uses shared functions for all quote operations
    // No duplicated data or logic
  }
}

// Uses: Cloudflare Workers Request/Response API
// Features: Global edge distribution, auto-scaling, DRY architecture
// Bundle size: 9.18 KiB (optimized)
// Started with: npx wrangler deploy

📁 quotes.json (Single Source of Truth)
     ↓
📦 lib/quote-functions.js (Core Logic)
     ↓
┌─── 📦 lib/mcp-resources.js ←── MCP Servers (stdio, HTTP)
│    📦 lib/rest-api-helpers.js ←── REST API Server
└─── 🌐 worker.js ←── Cloudflare Workers (Direct Import)

mcp-quotes-server/
├── 📦 lib/                              # Shared Libraries (Eliminates 400+ lines of duplication)
│   ├── quote-functions.js               #   🎯 Core: search, format, validate (8 functions)
│   ├── mcp-resources.js                 #   🔧 MCP: resources, tools, metadata (3 functions)  
│   ├── rest-api-helpers.js              #   🌐 REST: endpoint handlers (9 functions)
│   └── test-helpers.js                  #   🧪 Test: shared utilities (10+ functions)
│
├── 🚀 Server Implementations            # Thin wrappers around shared libraries
│   ├── server.js                        #   📡 MCP Stdio (44 lines)
│   ├── mcp-server-http.js               #   🌐 MCP HTTP (244 lines) 
│   ├── http-server.js                   #   📋 REST API (187 lines)
│   └── worker.js                        #   ☁️ Workers MCP DRY (269 lines, 9.18 KiB)
│
├── 📊 Data & Configuration
│   ├── quotes.json                      #   📚 Single source of truth (8 quotes)
│   ├── package.json                     #   📦 Dependencies & scripts
│   ├── package-lock.json                #   🔒 Locked dependency versions
│   └── wrangler.toml                    #   ☁️ Cloudflare Workers config
│
├── 🧪 Testing Suite (79 Tests Total)
│   ├── server.test.js                   #   📡 MCP Stdio tests (20 tests)
│   ├── http-server.test.js              #   📋 REST API tests (17 tests)
│   ├── mcp-server-http.test.js          #   🌐 MCP HTTP tests (27 tests)
│   ├── test-mcp-server.js               #   ☁️ Workers integration tests (15 tests)
│   ├── quick-test.sh                    #   ⚡ Fast validation script (5 tests)
│   └── manual-tests.md                  #   📖 Manual testing guide
│
└── 📖 Documentation
    ├── README.md                        #   📚 Complete documentation
    ├── CODE-DEDUPLICATION-SUMMARY.md   #   📊 Architecture benefits
    ├── WORKER-DEPLOYMENT.md            #   ☁️ Deployment guide
    └── TESTING.md                       #   🧪 Testing guide

# Server startup
npm start              # Start the MCP server (stdio transport)
npm run start:mcp-http # Start the MCP server (HTTP transport)  
npm run start:http     # Start the REST API server (HTTP)

# Testing
npm test               # Run all server implementations (79 tests)
npm run test:all       # Run all tests comprehensively
npm run test:core      # Run local implementations (64 tests)
npm run test:cloudflare     # Run Cloudflare integration tests (15 tests)
npm run test:cloudflare-quick # Quick validation (5 tests)

# Development testing
npm run test:watch     # Run core tests in watch mode
npm run test:coverage  # Run core tests with coverage

# Cloudflare Workers
npx wrangler deploy    # Deploy to Cloudflare Workers
npm run worker:dev     # Run Workers locally with Wrangler