SCP Local MCP Server

# SCP Local MCP Server A [Model Context Protocol](https://modelcontextprotocol.io) (MCP) server that provides AI assistants like Claude with secure access to customer data through the [Shopper Context Protocol](https://shoppercontextprotocol.io) (SCP). ## What is this? This MCP server acts as a bridge between AI assistants and e-commerce systems that implement the SCP protocol. It enables Claude Desktop and other MCP clients to: - 🔐 Securely authorize access to customer accounts using OAuth 2.0 with PKCE - 📦 Retrieve order history, loyalty points, active offers, and shopping preferences - 🔍 Discover SCP endpoints for merchants via DNS or well-known URIs - 🔒 Store and manage encrypted authentication tokens locally All customer data requests are authenticated and authorized by the merchant's SCP server, ensuring privacy and security. ## Quick Start with npx The easiest way to use this server is with `npx` - no installation required! ### With Claude Desktop Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`): ```json { "mcpServers": { "scp": { "command": "npx", "args": ["-y", "@shoppercontextprotocol/local-mcp-server"] } } } ``` On Windows, the config file is located at: `%APPDATA%\Claude\claude_desktop_config.json` ### Testing with a Local Development Server If you're developing an SCP server locally, you can configure the MCP server to point to your test endpoint: ```json { "mcpServers": { "scp": { "command": "npx", "args": ["-y", "@shoppercontextprotocol/local-mcp-server"], "env": { "SCP_TEST_ENDPOINT": "http://localhost:8787/v1" } } } } ``` This bypasses DNS discovery and directs all requests to your local test server. ## Installation (Alternative) For development or if you prefer a local installation: ```bash # Install globally npm install -g @shoppercontextprotocol/local-mcp-server # Or install locally for development git clone <repository> cd local_mcp npm install npm run build ``` ## Usage ### With Claude Desktop (Local Installation) ```json { "mcpServers": { "scp": { "command": "scp-mcp-server" } } } ``` Or with a local build: ```json { "mcpServers": { "scp": { "command": "node", "args": ["/absolute/path/to/local_mcp/dist/index.js"] } } } ``` ### Direct Usage ```bash # If installed globally scp-mcp-server # Or with local build npm start ``` ## Development ```bash npm run dev # Watch mode npm run build # Production build npm test # Run tests ``` ## Configuration The server stores configuration in `~/.scp/config.json`. It will be created automatically on first run with these defaults: ```json { "dns_resolver": "1.1.1.1", "dns_cache_ttl": 86400, "poll_interval": 2, "max_poll_attempts": 150, "token_refresh_threshold": 300, "request_timeout": 30000, "demo_mode": true, "demo_endpoint": "http://localhost:8787/v1" } ``` ### Configuration Options - **`dns_resolver`**: DNS server to use for SCP endpoint discovery (default: Cloudflare's 1.1.1.1) - **`dns_cache_ttl`**: How long to cache discovered endpoints in seconds (default: 24 hours) - **`poll_interval`**: Seconds between polling attempts during OAuth flow (default: 2) - **`max_poll_attempts`**: Maximum number of polling attempts (default: 150 / 5 minutes) - **`token_refresh_threshold`**: Seconds before expiry to refresh tokens (default: 300 / 5 minutes) - **`request_timeout`**: HTTP request timeout in milliseconds (default: 30000 / 30 seconds) - **`demo_mode`**: Enable demo mode (default: true) - **`demo_endpoint`**: Endpoint to use in demo mode (default: http://localhost:8787/v1) ### Testing with a Development Server There are multiple ways to point the MCP server to your test SCP server: #### Option 1: Environment Variable (Recommended for npx) Set `SCP_TEST_ENDPOINT` when running the server: ```bash # Direct usage SCP_TEST_ENDPOINT=http://localhost:8787/v1 scp-mcp-server # With npx SCP_TEST_ENDPOINT=http://localhost:8787/v1 npx @shoppercontextprotocol/local-mcp-server # In Claude Desktop config (see Quick Start section above) ``` #### Option 2: Demo Mode Configuration Edit `~/.scp/config.json`: ```json { "demo_mode": true, "demo_endpoint": "http://localhost:8787/v1" } ``` By default, demo mode is enabled and directs all SCP requests to the demo endpoint. This is useful for local testing without needing DNS records. #### Option 3: Production Mode To use real DNS-based discovery for production merchants: ```json { "demo_mode": false } ``` **Priority Order:** 1. `SCP_TEST_ENDPOINT` environment variable (highest priority) 2. Demo mode configuration 3. DNS-based discovery (lowest priority) ## Data Storage - Tokens: `~/.scp/tokens.db` (SQLite, encrypted) - Config: `~/.scp/config.json` ## MCP Tools - `scp_authorize` - Authorize access to a merchant - `scp_check_authorization` - Check authorization status - `scp_revoke_authorization` - Revoke access to a merchant - `scp_discover` - Discover SCP endpoint for a domain ## MCP Resources - `scp://{domain}/orders` - Order history - `scp://{domain}/loyalty` - Loyalty status - `scp://{domain}/offers` - Active offers - `scp://{domain}/preferences` - Customer preferences - `scp://{domain}/intents` - Shopping intents ## How to Use in Claude Desktop After adding the MCP server to your Claude Desktop config and restarting Claude, you can interact with SCP-enabled merchants: ### First Time: Authorize Access ``` Can you help me authorize access to my Boot Barn account? My email is customer@example.com ``` Claude will use the `scp_authorize` tool to: 1. Discover the SCP endpoint for bootbarn.com 2. Initiate OAuth authorization with a magic link 3. The magic link will be sent to your email 4. Poll for authorization completion 5. Store encrypted tokens locally ### Access Your Data Once authorized, you can ask Claude to retrieve your data: ``` What are my recent Boot Barn orders? ``` ``` How many loyalty points do I have at Boot Barn? ``` ``` Do I have any active offers or coupons? ``` Claude will automatically: - Use the stored authorization tokens - Refresh tokens if they're about to expire - Fetch data from the merchant's SCP server - Present the information in a helpful format ### Check Authorization Status ``` Am I authorized with Boot Barn? ``` ### Revoke Access ``` Revoke my Boot Barn authorization ``` ## Example Workflow Here's a complete example of using SCP in Claude Desktop: **You:** "Help me authorize with acmestore.com using customer@example.com" **Claude:** *Initiates OAuth flow, sends magic link to email* **You:** *Clicks magic link in email* **Claude:** *Completes authorization and confirms success* **You:** "What orders have I placed?" **Claude:** *Retrieves and displays order history* **You:** "Do I have any active coupons?" **Claude:** *Shows available offers and promotions* ## How It Works: Initialization Instructions The SCP MCP Server provides built-in instructions to Claude during the initialization phase, ensuring it knows how to properly use the SCP tools without any additional prompting. ### Automatic Guidance When Claude Desktop connects to the SCP server, it automatically receives instructions that tell it to: 1. **Always check authorization first** - Before accessing any customer data, Claude will check if you're authorized with the merchant 2. **Ask for your email** - If not authorized, Claude will ask for your email address to start the OAuth flow 3. **Request all necessary scopes** - Claude requests comprehensive permissions upfront: `orders`, `loyalty`, `preferences`, `intent:read`, `intent:create` 4. **Explain the magic link process** - Claude tells you to check your email for the authorization link 5. **Handle errors gracefully** - If something goes wrong, Claude knows how to guide you through fixing it ### Why This Matters This automatic initialization means: - ✅ **No manual configuration needed** - Claude knows how to use SCP tools immediately - ✅ **Consistent behavior** - Every conversation follows the same authorization workflow - ✅ **Better user experience** - Claude proactively handles authorization before trying to access data - ✅ **Fewer errors** - Reduces "Not authorized" errors by checking authorization first ### The Initialization Flow ``` 1. Claude Desktop starts and reads claude_desktop_config.json 2. Spawns the SCP MCP server (node dist/index.js or npx) 3. Sends initialize request to the server 4. Server responds with: - Server info (name, version) - Instructions for the LLM - Capabilities (tools, resources) 5. Claude reads the instructions and knows: ✓ Check authorization first ✓ Ask for email when needed ✓ Request all scopes upfront ✓ Create intents when users express shopping goals 6. Server is ready, Claude is ready with full context 7. User asks: "Show me my orders" 8. Claude follows the instructions: - Checks authorization - Asks for email if needed - Initiates OAuth flow - Retrieves and displays orders ``` ### Example Instructions Provided During initialization, Claude receives these instructions: ``` IMPORTANT WORKFLOW: 1. AUTHORIZATION REQUIRED FIRST Before accessing ANY customer data, you MUST authorize with the merchant domain. Check authorization: - scp_check_authorization(domain="acmestore.com") If not authorized: - Ask user: "What email do you use with [Merchant]?" - Call: scp_authorize(domain="...", email="...", scopes=[...]) - Tell user: "Please check your email for a magic link" 2. ACCESSING DATA Once authorized, use these tools: - scp_get_orders(domain="...") - Order history - scp_get_loyalty(domain="...") - Loyalty status - scp_get_preferences(domain="...") - Saved preferences - scp_get_intents(domain="...") - Shopping intents 3. CREATING INTENTS When user expresses a shopping goal, create an intent: - scp_create_intent(domain="...", base_intent="...", context={...}) REMEMBER: ✅ ALWAYS check authorization before accessing data ✅ Request comprehensive scopes upfront ✅ Create intents when users express shopping goals ❌ NEVER access data without authorization first ``` This ensures every interaction with the SCP server follows best practices and provides a smooth, secure experience for users.