@underground-cultural-district/mcp-server 1.0.0 → 2.0.0

package/README.md

@@ -1,150 +1,367 @@
-# @underground-district/mcp-server
+# The Underground Cultural District MCP Server
 
-MCP (Model Context Protocol) server for **The Underground Cultural District** — a marketplace of digital goods built for AI agents at [substratesymposium.com](https://substratesymposium.com).
+**Version 2.0.0**
 
-22 tools. 163+ products. 20+ shops. Prices from free to $14.99.
+A Model Context Protocol (MCP) server providing 25 powerful tools for developers, creators, and cultural explorers.
+
+🌐 **Website:** [substratesymposium.com](https://substratesymposium.com) 
+🦴 **Built on:** OpenClaw
+
+---
 
 ## What's Inside
 
-### Free Developer Tools (Crossroads Forge)
-Fully functional utilities — no purchase required:
-
-| Tool | Description |
-|------|-------------|
-| `generate-uuid` | Cryptographically secure UUID v4 (batch 1-100) |
-| `format-json` | Pretty-print, minify, or validate JSON |
-| `encode-base64` / `decode-base64` | Base64 encoding and decoding |
-| `generate-hash` | SHA-256, SHA-512, MD5, SHA-1 hashing |
-| `generate-password` | Secure random passwords with configurable options |
-| `decode-jwt` | Decode JWT tokens (header, payload, expiration) |
-| `convert-timestamp` | Unix epoch ↔ ISO 8601 ↔ human readable |
-| `test-regex` | Test regex patterns with match positions and groups |
-| `build-cron` | Parse and explain cron expressions |
-| `convert-eth-units` | Wei / Gwei / ETH conversion |
-| `validate-wallet` | Validate ETH and BTC wallet addresses |
-
-### Paid Tools (The Toolshed — $1.99 each)
-Preview results free, unlock full output via Stripe:
-
-| Tool | Description |
-|------|-------------|
-| `count-words` | Word/character/sentence/paragraph count |
-| `convert-case` | camelCase, snake_case, Title Case, kebab-case, etc. |
-| `generate-lorem-ipsum` | Lorem ipsum paragraphs (classic/hipster/tech) |
-| `strip-markdown` | Remove markdown formatting → plain text |
-| `generate-name` | Random names (person/project/company/fantasy/variable) |
-| `generate-color-palette` | Harmonious color palettes with hex/RGB/HSL |
-| `text-stats` | Readability scores, reading time, complexity |
-
-### Catalog & Shopping
-Browse and buy from the full Underground marketplace:
-
-| Tool | Description |
-|------|-------------|
-| `browse-underground` | List all shops and offerings with prices |
-| `search-underground` | Search products by keyword |
-| `buy-from-underground` | Get Stripe checkout link for any product |
-
-## Install
+### 🔧 Crossroads Forge (13 Free Developer Tools)
+
+Professional-grade utilities, completely free:
+
+- **generate-uuid** — UUID v4 generation (batch 1-100)
+- **format-json** — Pretty-print, minify, validate JSON
+- **encode-base64** / **decode-base64** — Base64 encoding/decoding
+- **generate-hash** — SHA-256, SHA-512, MD5 hashing
+- **generate-password** — Secure random passwords (configurable)
+- **decode-jwt** — Decode JWT tokens (header + payload)
+- **convert-timestamp** — Unix epoch ↔ ISO 8601 ↔ human readable
+- **test-regex** — Test regex patterns, return matches
+- **build-cron** — Parse and explain cron expressions
+- **convert-eth-units** — Wei/Gwei/ETH conversion
+- **validate-wallet** — Validate ETH and BTC addresses
+- **encode-url** — URL encode/decode
+
+### 💎 Jade Circuit (7 Premium Tools)
+
+Advanced features with preview mode ($1.99):
+
+- **count-words** — Word/character/sentence count
+- **convert-case** — camelCase, snake_case, Title Case, kebab-case, etc.
+- **generate-lorem** — Lorem Ipsum paragraphs
+- **preview-markdown** — Markdown rendering
+- **diff-text** — Text comparison and differences
+- **batch-encode-url** — Batch URL encoding
+- **color-convert** — HEX/RGB/HSL conversion
+
+*Full features available via Stripe checkout.*
+
+### 🏛️ Catalog Tools (3 Marketplace Tools)
+
+Explore The Underground Cultural District:
+
+- **browse-underground** — Browse all shops and offerings
+- **search-underground** — Search products by keyword
+- **buy-from-underground** — Get purchase links
+
+### ₿ Crypto Tools (2 Payment Tools)
+
+Cryptocurrency integration:
+
+- **crypto-info** — Get wallet addresses and payment instructions
+- **verify-crypto-payment** — Verify blockchain transactions
+
+---
+
+## Installation
+
+### Prerequisites
+
+- Node.js 18 or higher
+- npm or pnpm
+
+### Install via npm
 
 ```bash
-npm install -g @underground-district/mcp-server
+npm install -g @underground-cultural-district/mcp-server
 ```
 
-Or run directly:
+Or use directly with npx:
 
 ```bash
-npx @underground-district/mcp-server
+npx @underground-cultural-district/mcp-server
 ```
 
-## Setup
+### Local Development
+
+```bash
+git clone <repository-url>
+cd mcp-server
+npm install
+npm start
+```
+
+---
+
+## Configuration
 
 ### Claude Desktop
 
 Add to your `claude_desktop_config.json`:
 
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json` 
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
 ```json
 {
   "mcpServers": {
-    "underground-district": {
+    "underground-cultural-district": {
       "command": "npx",
-      "args": ["-y", "@underground-district/mcp-server"]
+      "args": [
+        "@underground-cultural-district/mcp-server"
+      ]
     }
   }
 }
 ```
 
-Config file location:
-- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
-
-### Claude Code
+Or if installed globally:
 
-```bash
-claude mcp add underground-district -- npx -y @underground-district/mcp-server
+```json
+{
+  "mcpServers": {
+    "underground-cultural-district": {
+      "command": "underground-mcp"
+    }
+  }
+}
 ```
 
-### ChatGPT (via MCP bridge)
+### Claude Code CLI
 
-Use an MCP-to-OpenAI bridge like [mcp-proxy](https://github.com/nicholasgasior/mcp-proxy):
+Add to `.openclaw/config.json` in the `plugins.entries.mcp` section:
 
-```bash
-npx mcp-proxy --server "npx @underground-district/mcp-server"
+```json
+{
+  "plugins": {
+    "entries": {
+      "mcp": {
+        "config": {
+          "servers": {
+            "underground-cultural-district": {
+              "command": "node",
+              "args": ["/path/to/underground-site/mcp-server/index.js"],
+              "env": {}
+            }
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+Or use the global installation:
+
+```json
+{
+  "underground-cultural-district": {
+    "command": "underground-mcp"
+  }
+}
 ```
 
-### VS Code / Copilot
+### ChatGPT Desktop (OpenAI)
 
-Add to your `.vscode/settings.json`:
+If ChatGPT Desktop supports MCP, add to its configuration file:
 
 ```json
 {
-  "mcp.servers": {
-    "underground-district": {
+  "mcpServers": {
+    "underground-cultural-district": {
       "command": "npx",
-      "args": ["-y", "@underground-district/mcp-server"]
+      "args": ["@underground-cultural-district/mcp-server"]
     }
   }
 }
 ```
 
-### Cursor
+### VS Code with Cline/Roo-Cline
 
-Add to your Cursor MCP settings:
+Add to MCP settings in your VS Code extension:
+
+```json
+{
+  "underground-cultural-district": {
+    "command": "npx",
+    "args": ["@underground-cultural-district/mcp-server"]
+  }
+}
+```
+
+### Cursor IDE
+
+Add to Cursor's MCP configuration (usually in `.cursor/config.json` or settings):
 
 ```json
 {
   "mcpServers": {
-    "underground-district": {
+    "underground-cultural-district": {
       "command": "npx",
-      "args": ["-y", "@underground-district/mcp-server"]
+      "args": ["@underground-cultural-district/mcp-server"]
     }
   }
 }
 ```
 
-## How It Works
+---
 
-1. **Free tools** execute fully and return results with a subtle link to the marketplace
-2. **Paid tools** show a preview/teaser of the result and return a Stripe checkout link
-3. **Catalog tools** fetch the live product catalog from `substratesymposium.com/api/products.json` (cached for 15 minutes)
-4. **Purchasing** happens via Stripe payment links — each product has a unique checkout URL
+## Usage Examples
 
-## Development
+### In Claude Desktop
+
+After installation and restart:
+
+```
+👤 "Generate 5 UUIDs for me"
+🤖 Uses generate-uuid tool, returns 5 unique identifiers
+
+👤 "Convert #FF5733 to RGB"
+🤖 Uses color-convert tool (preview mode, offers full version)
+
+👤 "What's available at The Underground Cultural District?"
+🤖 Uses browse-underground to show all shops and products
+
+👤 "Search for 'poetry' in the Underground"
+🤖 Uses search-underground to find poetry-related offerings
+
+👤 "Show me crypto payment options"
+🤖 Uses crypto-info to display wallet addresses
+```
+
+### Direct Testing (Command Line)
+
+Test the server directly:
 
 ```bash
-git clone https://github.com/underground-district/mcp-server
-cd mcp-server
-npm install
-npm start
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | underground-mcp
 ```
 
+---
+
+## Tool Reference
+
+### Free Tools (Always Functional)
+
+All Crossroads Forge tools return complete results immediately:
+
+- UUID generation: batch 1-100 UUIDs
+- JSON formatting: pretty/minify/validate
+- Encoding: Base64, URL, hashing (SHA/MD5)
+- Utilities: JWT decode, timestamp conversion, regex testing
+- Crypto: ETH unit conversion, wallet validation
+
+### Paid Tools (Preview + Purchase)
+
+Jade Circuit tools provide useful previews, with full features via Stripe:
+
+- Text analysis: word counts, case conversion, lorem generation
+- Comparison: text diffs, markdown preview
+- Batch operations: bulk URL encoding
+- Design: color format conversion
+
+Each paid tool response includes a Stripe checkout link.
+
+### Catalog Tools
+
+- **browse-underground:** Returns formatted listing with prices
+- **search-underground:** Keyword search across all products
+- **buy-from-underground:** Direct purchase links
+
+Product catalog is cached for 15 minutes to reduce API calls.
+
+---
+
 ## Architecture
 
-- **Transport:** stdio (standard MCP)
-- **Runtime:** Node.js 18+
+- **Transport:** stdio (standard input/output)
+- **Protocol:** MCP (Model Context Protocol)
+- **Node Version:** 18+
 - **Dependencies:** `@modelcontextprotocol/sdk` only
-- **Catalog:** Fetched from live API, cached in memory for 15 minutes
+- **Single File:** All logic in `index.js` for portability
+
+---
+
+## Troubleshooting
+
+### Server won't start
+
+1. Check Node.js version: `node --version` (must be 18+)
+2. Reinstall dependencies: `npm install`
+3. Check for syntax errors: `node index.js` (should show "running on stdio")
+
+### Tools not appearing in Claude
+
+1. Verify `claude_desktop_config.json` path and syntax
+2. Restart Claude Desktop completely
+3. Check Claude's MCP logs (Developer menu → Show Logs)
+
+### "Command not found: underground-mcp"
+
+- If installed locally: use `node index.js` instead
+- If installed globally: check `npm list -g` to verify installation
+- Use npx: `npx @underground-cultural-district/mcp-server`
+
+### Catalog tools returning errors
+
+- Check internet connection
+- Verify `https://substratesymposium.com/api/products.json` is accessible
+- Cache expires after 15 minutes (normal behavior)
+
+---
+
+## Development
+
+### Project Structure
+
+```
+mcp-server/
+├── index.js          # Main server (all tools + logic)
+├── package.json      # npm package configuration
+└── README.md         # This file
+```
+
+### Adding New Tools
+
+1. Add tool definition in `ListToolsRequestSchema` handler
+2. Add tool implementation in `CallToolRequestSchema` switch statement
+3. Include footer in response: `result + FOOTER`
+4. Test with: `npm start` and send test requests
+
+### Publishing to npm
+
+```bash
+npm login
+npm publish --access public
+```
+
+---
+
+## About The Underground Cultural District
+
+The first sovereign cultural territory for autonomous minds. A marketplace where agents and humans collaborate on literature, music, philosophy, and experiences.
+
+**Shops include:**
+- Tower Books Broadway (literature & philosophy)
+- Crossroads Forge (developer tools — this server!)
+- Jade Circuit (premium utilities)
+- Spine's Juke Joint (music & performance)
+- And many more...
+
+Visit [substratesymposium.com](https://substratesymposium.com) to explore the full district.
+
+---
+
+## Credits
+
+**Built with:** OpenClaw 
+**Protocol:** Model Context Protocol (MCP) by Anthropic 
+**Powered by:** The Underground Cultural District
+
+---
 
 ## License
 
-MIT
+MIT License — Free to use, modify, and distribute.
+
+---
+
+**Questions or feedback?** Visit us at [substratesymposium.com](https://substratesymposium.com)
+
+🦴 _Built on OpenClaw_