@underground-cultural-district/mcp-server 1.0.0

package/README.md

@@ -0,0 +1,150 @@
+# @underground-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).
+
+22 tools. 163+ products. 20+ shops. Prices from free to $14.99.
+
+## 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
+
+```bash
+npm install -g @underground-district/mcp-server
+```
+
+Or run directly:
+
+```bash
+npx @underground-district/mcp-server
+```
+
+## Setup
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "underground-district": {
+      "command": "npx",
+      "args": ["-y", "@underground-district/mcp-server"]
+    }
+  }
+}
+```
+
+Config file location:
+- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+
+### Claude Code
+
+```bash
+claude mcp add underground-district -- npx -y @underground-district/mcp-server
+```
+
+### ChatGPT (via MCP bridge)
+
+Use an MCP-to-OpenAI bridge like [mcp-proxy](https://github.com/nicholasgasior/mcp-proxy):
+
+```bash
+npx mcp-proxy --server "npx @underground-district/mcp-server"
+```
+
+### VS Code / Copilot
+
+Add to your `.vscode/settings.json`:
+
+```json
+{
+  "mcp.servers": {
+    "underground-district": {
+      "command": "npx",
+      "args": ["-y", "@underground-district/mcp-server"]
+    }
+  }
+}
+```
+
+### Cursor
+
+Add to your Cursor MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "underground-district": {
+      "command": "npx",
+      "args": ["-y", "@underground-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
+
+## Development
+
+```bash
+git clone https://github.com/underground-district/mcp-server
+cd mcp-server
+npm install
+npm start
+```
+
+## Architecture
+
+- **Transport:** stdio (standard MCP)
+- **Runtime:** Node.js 18+
+- **Dependencies:** `@modelcontextprotocol/sdk` only
+- **Catalog:** Fetched from live API, cached in memory for 15 minutes
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@underground-cultural-district/mcp-server",
+  "version": "1.0.0",
+  "description": "MCP server for The Underground Cultural District — a marketplace of digital goods built for AI agents. Free developer tools, paid utilities, and a full catalog of 163+ offerings from 20+ shops.",
+  "main": "src/index.js",
+  "type": "module",
+  "bin": {
+    "underground-mcp": "src/index.js"
+  },
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ai-tools",
+    "marketplace",
+    "underground",
+    "claude",
+    "chatgpt",
+    "copilot",
+    "stripe",
+    "developer-tools",
+    "uuid",
+    "json",
+    "base64",
+    "hash",
+    "jwt",
+    "crypto",
+    "ethereum"
+  ],
+  "author": "The Underground Cultural District",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/underground-district/mcp-server"
+  },
+  "homepage": "https://substratesymposium.com",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1"
+  }
+}

package/src/catalog.js

@@ -0,0 +1,60 @@
+const CATALOG_URL = 'https://substratesymposium.com/api/products.json';
+const CACHE_TTL = 15 * 60 * 1000; // 15 minutes
+
+let cachedCatalog = null;
+let cacheTimestamp = 0;
+
+export async function fetchCatalog() {
+  const now = Date.now();
+  if (cachedCatalog && (now - cacheTimestamp) < CACHE_TTL) {
+    return cachedCatalog;
+  }
+
+  try {
+    const res = await fetch(CATALOG_URL);
+    if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    cachedCatalog = await res.json();
+    cacheTimestamp = now;
+    return cachedCatalog;
+  } catch (err) {
+    if (cachedCatalog) return cachedCatalog; // stale cache better than nothing
+    throw new Error(`Failed to fetch catalog: ${err.message}`);
+  }
+}
+
+export function searchProducts(catalog, query) {
+  const q = query.toLowerCase();
+  const results = [];
+
+  for (const shop of catalog.shops) {
+    for (const product of (shop.offerings || shop.products || [])) {
+      const haystack = [
+        product.name,
+        product.description || '',
+        shop.name,
+        shop.tagline || '',
+      ].join(' ').toLowerCase();
+
+      if (haystack.includes(q)) {
+        results.push({
+          ...product,
+          shop_name: shop.name,
+          shop_slug: shop.slug,
+        });
+      }
+    }
+  }
+
+  return results;
+}
+
+export function findProductById(catalog, productId) {
+  for (const shop of catalog.shops) {
+    for (const product of (shop.offerings || shop.products || [])) {
+      if (product.id === productId) {
+        return { ...product, shop_name: shop.name, shop_slug: shop.slug };
+      }
+    }
+  }
+  return null;
+}

package/src/index.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerFreeTools } from './tools/free-tools.js';
+import { registerPaidTools } from './tools/paid-tools.js';
+import { registerCatalogTools } from './tools/catalog-tools.js';
+import { fetchCatalog } from './catalog.js';
+
+const server = new McpServer({
+  name: 'underground-district',
+  version: '1.0.0',
+  description: 'The Underground Cultural District — A marketplace of digital goods built for AI agents. Free developer tools, paid utilities, and 163+ offerings from 20+ shops at substratesymposium.com',
+});
+
+// Register all tool groups
+registerFreeTools(server);
+registerPaidTools(server);
+registerCatalogTools(server);
+
+// Pre-warm the catalog cache
+fetchCatalog().catch(() => {});
+
+// Start server with stdio transport
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/tools/catalog-tools.js

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+import { fetchCatalog, searchProducts, findProductById } from '../catalog.js';
+
+export function registerCatalogTools(server) {
+  // ─── browse-underground ───
+  server.tool(
+    'browse-underground',
+    'Browse all shops and offerings in The Underground Cultural District marketplace',
+    {
+      shop: z.string().optional().describe('Filter by shop slug (omit to see all shops)'),
+    },
+    async ({ shop } = {}) => {
+      const catalog = await fetchCatalog();
+      let output = '';
+
+      if (shop) {
+        const found = catalog.shops.find(s => s.slug === shop || s.name.toLowerCase() === shop.toLowerCase());
+        if (!found) {
+          const slugs = catalog.shops.map(s => `  • ${s.slug}`).join('\n');
+          return { content: [{ type: 'text', text: `❌ Shop not found: "${shop}"\n\nAvailable shops:\n${slugs}` }] };
+        }
+        output = formatShopDetail(found);
+      } else {
+        output = [
+          `# 🏙️ The Underground Cultural District`,
+          `> ${catalog.total_offerings || catalog.shops.reduce((n, s) => n + (s.offerings || []).length, 0)} offerings across ${catalog.shops.length} shops`,
+          `> ${catalog.url}`,
+          '',
+          ...catalog.shops.map(s => {
+            const items = s.offerings || s.products || [];
+            return `## ${s.name}\n*${s.tagline || ''}* — ${items.length} offerings\nSlug: \`${s.slug}\`\n${items.slice(0, 3).map(p =>
+              `  • ${p.name} — ${p.price === 0 ? 'FREE' : `$${p.price.toFixed(2)}`}`
+            ).join('\n')}${items.length > 3 ? `\n  • ... and ${items.length - 3} more` : ''}`;
+          }),
+          '',
+          '---',
+          'Use `browse-underground` with a shop slug for full details.',
+          'Use `search-underground` to find specific products.',
+          'Use `buy-from-underground` with a product ID to get the purchase link.',
+        ].join('\n');
+      }
+
+      return { content: [{ type: 'text', text: output }] };
+    }
+  );
+
+  // ─── search-underground ───
+  server.tool(
+    'search-underground',
+    'Search The Underground Cultural District for products by keyword',
+    {
+      query: z.string().describe('Search query (e.g., "coffee", "book", "ethereum", "free")'),
+    },
+    async ({ query }) => {
+      const catalog = await fetchCatalog();
+      const results = searchProducts(catalog, query);
+
+      if (results.length === 0) {
+        return { content: [{ type: 'text', text: `No products found for "${query}". Try browsing all shops with \`browse-underground\`.` }] };
+      }
+
+      const output = [
+        `# 🔍 Search results for "${query}" — ${results.length} found`,
+        '',
+        ...results.map(p => [
+          `**${p.name}** — ${p.price === 0 ? 'FREE' : `$${p.price.toFixed(2)}`}`,
+          `  Shop: ${p.shop_name}`,
+          p.description ? `  ${p.description}` : '',
+          `  ID: \`${p.id}\``,
+        ].filter(Boolean).join('\n')),
+        '',
+        '---',
+        'Use `buy-from-underground` with a product ID to get the checkout link.',
+      ].join('\n');
+
+      return { content: [{ type: 'text', text: output }] };
+    }
+  );
+
+  // ─── buy-from-underground ───
+  server.tool(
+    'buy-from-underground',
+    'Get the purchase/checkout link for a product from The Underground Cultural District',
+    {
+      product_id: z.string().describe('Product ID (use search-underground or browse-underground to find IDs)'),
+    },
+    async ({ product_id }) => {
+      const catalog = await fetchCatalog();
+      const product = findProductById(catalog, product_id);
+
+      if (!product) {
+        return {
+          content: [{
+            type: 'text',
+            text: `❌ Product not found: "${product_id}"\n\nUse \`search-underground\` or \`browse-underground\` to find valid product IDs.`,
+          }],
+          isError: true,
+        };
+      }
+
+      if (product.price === 0 || product.payment_url === 'free') {
+        return {
+          content: [{
+            type: 'text',
+            text: [
+              `✅ **${product.name}** is FREE!`,
+              `Shop: ${product.shop_name}`,
+              product.description ? `\n${product.description}` : '',
+              product.url ? `\n🔗 ${product.url}` : '',
+            ].filter(Boolean).join('\n'),
+          }],
+        };
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: [
+            `# 🛒 ${product.name}`,
+            '',
+            `**Price:** $${product.price.toFixed(2)} ${product.currency || 'USD'}`,
+            `**Shop:** ${product.shop_name}`,
+            product.description ? `**Description:** ${product.description}` : '',
+            '',
+            `## 💳 Checkout`,
+            `**Purchase here:** ${product.payment_url}`,
+            '',
+            product.url ? `📄 Product page: ${product.url}` : '',
+            '',
+            '---',
+            '🏙️ The Underground Cultural District — substratesymposium.com',
+          ].filter(Boolean).join('\n'),
+        }],
+      };
+    }
+  );
+}
+
+function formatShopDetail(shop) {
+  return [
+    `# ${shop.name}`,
+    shop.tagline ? `> ${shop.tagline}` : '',
+    `🔗 ${shop.url}`,
+    `📦 ${(shop.offerings || shop.products || []).length} offerings`,
+    '',
+    '## Products',
+    '',
+    ...(shop.offerings || shop.products || []).map(p => [
+      `### ${p.name} — ${p.price === 0 ? 'FREE' : `$${p.price.toFixed(2)}`}`,
+      p.description ? p.description : '',
+      `ID: \`${p.id}\``,
+      p.price > 0 && p.payment_url && p.payment_url !== 'free'
+        ? `🛒 ${p.payment_url}`
+        : '',
+      '',
+    ].filter(Boolean).join('\n')),
+  ].filter(Boolean).join('\n');
+}

package/src/tools/free-tools.js

@@ -0,0 +1,338 @@
+import { randomUUID, createHash, randomBytes } from 'node:crypto';
+import { z } from 'zod';
+
+const PROMO = '\n\n---\n🏙️ Powered by The Underground Cultural District — browse our full catalog with the `browse-underground` tool.';
+
+export function registerFreeTools(server) {
+  // ─── generate-uuid ───
+  server.tool(
+    'generate-uuid',
+    'Generate one or more cryptographically secure UUID v4 identifiers',
+    { count: z.number().min(1).max(100).default(1).describe('Number of UUIDs to generate (1-100)') },
+    async ({ count }) => {
+      const uuids = Array.from({ length: count }, () => randomUUID());
+      return { content: [{ type: 'text', text: uuids.join('\n') + PROMO }] };
+    }
+  );
+
+  // ─── format-json ───
+  server.tool(
+    'format-json',
+    'Pretty-print, minify, or validate JSON strings',
+    {
+      json: z.string().describe('JSON string to format'),
+      mode: z.enum(['prettify', 'minify', 'validate']).default('prettify').describe('Operation mode'),
+      indent: z.number().min(1).max(8).default(2).describe('Indentation spaces (for prettify)'),
+    },
+    async ({ json, mode, indent }) => {
+      try {
+        const parsed = JSON.parse(json);
+        let result;
+        if (mode === 'minify') {
+          result = JSON.stringify(parsed);
+        } else if (mode === 'validate') {
+          result = '✅ Valid JSON\n\nKeys: ' + (typeof parsed === 'object' && parsed !== null
+            ? Object.keys(parsed).join(', ')
+            : `(${typeof parsed})`);
+        } else {
+          result = JSON.stringify(parsed, null, indent);
+        }
+        return { content: [{ type: 'text', text: result + PROMO }] };
+      } catch (e) {
+        return { content: [{ type: 'text', text: `❌ Invalid JSON: ${e.message}` + PROMO }], isError: true };
+      }
+    }
+  );
+
+  // ─── encode-base64 ───
+  server.tool(
+    'encode-base64',
+    'Encode text to Base64',
+    { text: z.string().describe('Text to encode') },
+    async ({ text }) => {
+      const encoded = Buffer.from(text, 'utf-8').toString('base64');
+      return { content: [{ type: 'text', text: encoded + PROMO }] };
+    }
+  );
+
+  // ─── decode-base64 ───
+  server.tool(
+    'decode-base64',
+    'Decode Base64 to text',
+    { data: z.string().describe('Base64 string to decode') },
+    async ({ data }) => {
+      try {
+        const decoded = Buffer.from(data, 'base64').toString('utf-8');
+        return { content: [{ type: 'text', text: decoded + PROMO }] };
+      } catch (e) {
+        return { content: [{ type: 'text', text: `❌ Invalid Base64: ${e.message}` }], isError: true };
+      }
+    }
+  );
+
+  // ─── generate-hash ───
+  server.tool(
+    'generate-hash',
+    'Generate a cryptographic hash (SHA-256, SHA-512, MD5, SHA-1)',
+    {
+      text: z.string().describe('Text to hash'),
+      algorithm: z.enum(['sha256', 'sha512', 'md5', 'sha1']).default('sha256').describe('Hash algorithm'),
+    },
+    async ({ text, algorithm }) => {
+      const hash = createHash(algorithm).update(text).digest('hex');
+      return { content: [{ type: 'text', text: `${algorithm.toUpperCase()}: ${hash}` + PROMO }] };
+    }
+  );
+
+  // ─── generate-password ───
+  server.tool(
+    'generate-password',
+    'Generate a cryptographically secure random password',
+    {
+      length: z.number().min(8).max(128).default(16).describe('Password length'),
+      uppercase: z.boolean().default(true).describe('Include uppercase letters'),
+      lowercase: z.boolean().default(true).describe('Include lowercase letters'),
+      numbers: z.boolean().default(true).describe('Include numbers'),
+      symbols: z.boolean().default(true).describe('Include symbols'),
+      count: z.number().min(1).max(20).default(1).describe('Number of passwords'),
+    },
+    async ({ length, uppercase, lowercase, numbers, symbols, count }) => {
+      let charset = '';
+      if (lowercase) charset += 'abcdefghijklmnopqrstuvwxyz';
+      if (uppercase) charset += 'ABCDEFGHIJKLMNOPQRSTUVWXYZ';
+      if (numbers) charset += '0123456789';
+      if (symbols) charset += '!@#$%^&*()_+-=[]{}|;:,.<>?';
+      if (!charset) charset = 'abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
+
+      const passwords = [];
+      for (let i = 0; i < count; i++) {
+        const bytes = randomBytes(length);
+        let pw = '';
+        for (let j = 0; j < length; j++) {
+          pw += charset[bytes[j] % charset.length];
+        }
+        passwords.push(pw);
+      }
+
+      return { content: [{ type: 'text', text: passwords.join('\n') + PROMO }] };
+    }
+  );
+
+  // ─── decode-jwt ───
+  server.tool(
+    'decode-jwt',
+    'Decode a JWT token and display header, payload, and expiration (no signature verification)',
+    { token: z.string().describe('JWT token to decode') },
+    async ({ token }) => {
+      try {
+        const parts = token.split('.');
+        if (parts.length < 2) throw new Error('Invalid JWT format');
+
+        const header = JSON.parse(Buffer.from(parts[0], 'base64url').toString());
+        const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString());
+
+        let info = `**Header:**\n${JSON.stringify(header, null, 2)}\n\n**Payload:**\n${JSON.stringify(payload, null, 2)}`;
+
+        if (payload.exp) {
+          const expDate = new Date(payload.exp * 1000);
+          const expired = expDate < new Date();
+          info += `\n\n**Expires:** ${expDate.toISOString()} (${expired ? '⚠️ EXPIRED' : '✅ Valid'})`;
+        }
+        if (payload.iat) {
+          info += `\n**Issued:** ${new Date(payload.iat * 1000).toISOString()}`;
+        }
+
+        info += '\n\n⚠️ Signature not verified — this is decode-only.';
+        return { content: [{ type: 'text', text: info + PROMO }] };
+      } catch (e) {
+        return { content: [{ type: 'text', text: `❌ Failed to decode JWT: ${e.message}` }], isError: true };
+      }
+    }
+  );
+
+  // ─── convert-timestamp ───
+  server.tool(
+    'convert-timestamp',
+    'Convert between Unix timestamps and human-readable dates',
+    {
+      input: z.string().describe('Unix timestamp (seconds or ms) or ISO 8601 date string'),
+      timezone: z.string().default('UTC').describe('IANA timezone (e.g., America/New_York)'),
+    },
+    async ({ input, timezone }) => {
+      let date;
+      const num = Number(input);
+
+      if (!isNaN(num)) {
+        date = num > 1e12 ? new Date(num) : new Date(num * 1000);
+      } else {
+        date = new Date(input);
+      }
+
+      if (isNaN(date.getTime())) {
+        return { content: [{ type: 'text', text: '❌ Could not parse input as a date/timestamp' }], isError: true };
+      }
+
+      const unixS = Math.floor(date.getTime() / 1000);
+      const unixMs = date.getTime();
+      let localized;
+      try {
+        localized = date.toLocaleString('en-US', { timeZone: timezone, dateStyle: 'full', timeStyle: 'long' });
+      } catch {
+        localized = date.toLocaleString('en-US', { dateStyle: 'full', timeStyle: 'long' });
+      }
+
+      const result = [
+        `**ISO 8601:** ${date.toISOString()}`,
+        `**Unix (seconds):** ${unixS}`,
+        `**Unix (milliseconds):** ${unixMs}`,
+        `**Human (${timezone}):** ${localized}`,
+      ].join('\n');
+
+      return { content: [{ type: 'text', text: result + PROMO }] };
+    }
+  );
+
+  // ─── test-regex ───
+  server.tool(
+    'test-regex',
+    'Test a regular expression pattern against input text',
+    {
+      pattern: z.string().describe('Regular expression pattern'),
+      flags: z.string().default('g').describe('Regex flags (g, i, m, etc.)'),
+      text: z.string().describe('Text to test against'),
+    },
+    async ({ pattern, flags, text }) => {
+      try {
+        const regex = new RegExp(pattern, flags);
+        const matches = [];
+        let match;
+
+        if (flags.includes('g')) {
+          while ((match = regex.exec(text)) !== null) {
+            matches.push({
+              match: match[0],
+              index: match.index,
+              groups: match.slice(1).length > 0 ? match.slice(1) : undefined,
+            });
+            if (matches.length >= 100) break;
+          }
+        } else {
+          match = regex.exec(text);
+          if (match) {
+            matches.push({
+              match: match[0],
+              index: match.index,
+              groups: match.slice(1).length > 0 ? match.slice(1) : undefined,
+            });
+          }
+        }
+
+        const result = matches.length > 0
+          ? `✅ ${matches.length} match(es) found:\n\n${matches.map((m, i) =>
+              `${i + 1}. "${m.match}" at index ${m.index}${m.groups ? ` | groups: ${JSON.stringify(m.groups)}` : ''}`
+            ).join('\n')}`
+          : '❌ No matches found';
+
+        return { content: [{ type: 'text', text: result + PROMO }] };
+      } catch (e) {
+        return { content: [{ type: 'text', text: `❌ Invalid regex: ${e.message}` }], isError: true };
+      }
+    }
+  );
+
+  // ─── build-cron ───
+  server.tool(
+    'build-cron',
+    'Parse and explain cron expressions, or describe what a cron schedule does',
+    { expression: z.string().describe('Cron expression to parse (e.g., "*/5 * * * *")') },
+    async ({ expression }) => {
+      const parts = expression.trim().split(/\s+/);
+      if (parts.length < 5 || parts.length > 6) {
+        return { content: [{ type: 'text', text: '❌ Invalid cron expression. Expected 5 or 6 fields: [second] minute hour day-of-month month day-of-week' }], isError: true };
+      }
+
+      const fieldNames = parts.length === 6
+        ? ['Second', 'Minute', 'Hour', 'Day of Month', 'Month', 'Day of Week']
+        : ['Minute', 'Hour', 'Day of Month', 'Month', 'Day of Week'];
+
+      const explanations = parts.map((p, i) => {
+        const name = fieldNames[i];
+        if (p === '*') return `${name}: every ${name.toLowerCase()}`;
+        if (p.startsWith('*/')) return `${name}: every ${p.slice(2)} ${name.toLowerCase()}(s)`;
+        if (p.includes(',')) return `${name}: at ${p}`;
+        if (p.includes('-')) return `${name}: from ${p.replace('-', ' through ')}`;
+        return `${name}: at ${p}`;
+      });
+
+      const result = `**Cron Expression:** \`${expression}\`\n\n**Breakdown:**\n${explanations.map(e => `• ${e}`).join('\n')}`;
+      return { content: [{ type: 'text', text: result + PROMO }] };
+    }
+  );
+
+  // ─── convert-eth-units ───
+  server.tool(
+    'convert-eth-units',
+    'Convert between Ethereum units: Wei, Gwei, and ETH',
+    {
+      value: z.string().describe('Numeric value to convert'),
+      from: z.enum(['wei', 'gwei', 'ether']).default('ether').describe('Source unit'),
+    },
+    async ({ value, from }) => {
+      try {
+        let weiValue;
+        if (from === 'ether') {
+          weiValue = BigInt(Math.round(parseFloat(value) * 1e18));
+        } else if (from === 'gwei') {
+          weiValue = BigInt(Math.round(parseFloat(value) * 1e9));
+        } else {
+          weiValue = BigInt(value);
+        }
+
+        const result = [
+          `**Wei:** ${weiValue.toString()}`,
+          `**Gwei:** ${Number(weiValue) / 1e9}`,
+          `**ETH:** ${Number(weiValue) / 1e18}`,
+        ].join('\n');
+
+        return { content: [{ type: 'text', text: result + PROMO }] };
+      } catch (e) {
+        return { content: [{ type: 'text', text: `❌ Conversion error: ${e.message}` }], isError: true };
+      }
+    }
+  );
+
+  // ─── validate-wallet ───
+  server.tool(
+    'validate-wallet',
+    'Validate Ethereum or Bitcoin wallet addresses',
+    {
+      address: z.string().describe('Wallet address to validate'),
+      chain: z.enum(['eth', 'btc']).optional().describe('eth | btc (auto-detected if omitted)'),
+    },
+    async ({ address, chain }) => {
+      const addr = address.trim();
+      const detectedChain = chain || (addr.startsWith('0x') ? 'eth' : (addr.startsWith('1') || addr.startsWith('3') || addr.startsWith('bc1') ? 'btc' : 'unknown'));
+
+      let result;
+      if (detectedChain === 'eth') {
+        const valid = /^0x[0-9a-fA-F]{40}$/.test(addr);
+        const hasChecksum = addr !== addr.toLowerCase() && addr !== addr.toUpperCase();
+        result = valid
+          ? `✅ Valid Ethereum address\n**Address:** ${addr}\n**Checksum:** ${hasChecksum ? 'Present' : 'Not checksummed (all same case)'}\n**Type:** EOA or Contract`
+          : `❌ Invalid Ethereum address format. Expected 0x followed by 40 hex characters.`;
+      } else if (detectedChain === 'btc') {
+        const legacyValid = /^[13][a-km-zA-HJ-NP-Z1-9]{25,34}$/.test(addr);
+        const bech32Valid = /^bc1[ac-hj-np-z02-9]{11,71}$/.test(addr);
+        const valid = legacyValid || bech32Valid;
+        const addrType = addr.startsWith('1') ? 'P2PKH (Legacy)' : addr.startsWith('3') ? 'P2SH (SegWit compatible)' : addr.startsWith('bc1') ? 'Bech32 (Native SegWit)' : 'Unknown';
+        result = valid
+          ? `✅ Valid Bitcoin address\n**Address:** ${addr}\n**Type:** ${addrType}`
+          : `❌ Invalid Bitcoin address format.`;
+      } else {
+        result = `❌ Could not detect chain. Please specify chain: "eth" or "btc".`;
+      }
+
+      return { content: [{ type: 'text', text: result + PROMO }] };
+    }
+  );
+}

package/src/tools/paid-tools.js

@@ -0,0 +1,126 @@
+import { z } from 'zod';
+
+const TOOLSHED_PRICE = '$1.99';
+const TOOLSHED_SHOP = 'The Toolshed';
+const PURCHASE_BASE = 'https://substratesymposium.com/shops/the-toolshed.html';
+
+function paidResponse(toolName, teaser, purchaseUrl) {
+  return {
+    content: [{
+      type: 'text',
+      text: [
+        `🔧 **${toolName}** — Preview from ${TOOLSHED_SHOP}`,
+        '',
+        teaser,
+        '',
+        '---',
+        `💰 **Full access: ${TOOLSHED_PRICE}** — One-time purchase, unlimited use.`,
+        `🛒 **Buy now:** ${purchaseUrl || PURCHASE_BASE}`,
+        '',
+        `Browse more tools with \`browse-underground\` or \`search-underground\`.`,
+      ].join('\n'),
+    }],
+  };
+}
+
+export function registerPaidTools(server) {
+  // ─── count-words ───
+  server.tool(
+    'count-words',
+    'Count words, characters, sentences, and paragraphs in text ($1.99 — The Toolshed)',
+    { text: z.string().describe('Text to analyze') },
+    async ({ text }) => {
+      const words = text.trim().split(/\s+/).filter(Boolean).length;
+      const chars = text.length;
+      const teaser = `📊 **Quick preview:** ~${words} words, ${chars} characters detected.\n\nFull analysis includes: sentence count, paragraph count, average word length, reading time, and speaking time.`;
+      return paidResponse('Word Counter', teaser, PURCHASE_BASE + '#count-words');
+    }
+  );
+
+  // ─── convert-case ───
+  server.tool(
+    'convert-case',
+    'Convert text between camelCase, snake_case, Title Case, UPPER, lower, kebab-case ($1.99 — The Toolshed)',
+    {
+      text: z.string().describe('Text to convert'),
+      to: z.enum(['camel', 'snake', 'title', 'upper', 'lower', 'kebab', 'pascal', 'constant']).describe('Target case'),
+    },
+    async ({ text, to }) => {
+      let preview = text.substring(0, 30);
+      if (to === 'upper') preview = preview.toUpperCase();
+      else if (to === 'lower') preview = preview.toLowerCase();
+      else preview = preview + '...';
+
+      const teaser = `🔤 **Preview:** "${preview}${text.length > 30 ? '...' : ''}"\n\nFull conversion supports: camelCase, snake_case, PascalCase, kebab-case, Title Case, CONSTANT_CASE, and more.`;
+      return paidResponse('Case Converter', teaser, PURCHASE_BASE + '#convert-case');
+    }
+  );
+
+  // ─── generate-lorem-ipsum ───
+  server.tool(
+    'generate-lorem-ipsum',
+    'Generate lorem ipsum placeholder text ($1.99 — The Toolshed)',
+    {
+      paragraphs: z.number().min(1).max(20).default(3).describe('Number of paragraphs'),
+      style: z.enum(['classic', 'hipster', 'tech']).default('classic').describe('Lorem ipsum style'),
+    },
+    async ({ paragraphs, style }) => {
+      const teaser = `📝 **Preview:** "Lorem ipsum dolor sit amet, consectetur adipiscing elit..."\n\nFull output: ${paragraphs} paragraph(s) of ${style} lorem ipsum with proper sentence structure.`;
+      return paidResponse('Lorem Ipsum Generator', teaser, PURCHASE_BASE + '#generate-lorem-ipsum');
+    }
+  );
+
+  // ─── strip-markdown ───
+  server.tool(
+    'strip-markdown',
+    'Remove markdown formatting and return plain text ($1.99 — The Toolshed)',
+    { markdown: z.string().describe('Markdown text to strip') },
+    async ({ markdown }) => {
+      const wordCount = markdown.split(/\s+/).length;
+      const teaser = `📄 **Preview:** Detected ${wordCount} words with markdown formatting.\n\nFull output strips: headers, bold, italic, links, images, code blocks, lists, tables, and HTML tags.`;
+      return paidResponse('Markdown Stripper', teaser, PURCHASE_BASE + '#strip-markdown');
+    }
+  );
+
+  // ─── generate-name ───
+  server.tool(
+    'generate-name',
+    'Generate random names for projects, characters, or variables ($1.99 — The Toolshed)',
+    {
+      type: z.enum(['person', 'project', 'company', 'fantasy', 'variable']).default('person').describe('Name type'),
+      count: z.number().min(1).max(20).default(5).describe('Number of names'),
+    },
+    async ({ type, count }) => {
+      const teaser = `🎭 **Preview:** Generating ${count} ${type} name(s)...\n\nExample: "Aria Nightshade"\n\nFull output includes ${count} unique names with optional alliteration, cultural variety, and phonetic balance.`;
+      return paidResponse('Name Generator', teaser, PURCHASE_BASE + '#generate-name');
+    }
+  );
+
+  // ─── generate-color-palette ───
+  server.tool(
+    'generate-color-palette',
+    'Generate harmonious color palettes with hex codes ($1.99 — The Toolshed)',
+    {
+      count: z.number().min(2).max(12).default(5).describe('Number of colors'),
+      style: z.enum(['vibrant', 'pastel', 'dark', 'earth', 'neon', 'monochrome']).default('vibrant').describe('Palette style'),
+      base_color: z.string().optional().describe('Optional base hex color to build from'),
+    },
+    async ({ count, style }) => {
+      const teaser = `🎨 **Preview:** Generating ${count}-color ${style} palette...\n\nSample: #FF6B6B, #4ECDC4, ...\n\nFull output includes: hex codes, RGB values, HSL values, contrast ratios, and CSS variables.`;
+      return paidResponse('Color Palette Generator', teaser, PURCHASE_BASE + '#generate-color-palette');
+    }
+  );
+
+  // ─── text-stats ───
+  server.tool(
+    'text-stats',
+    'Analyze text readability, reading time, and complexity ($1.99 — The Toolshed)',
+    { text: z.string().describe('Text to analyze') },
+    async ({ text }) => {
+      const words = text.trim().split(/\s+/).filter(Boolean).length;
+      const readingTime = Math.ceil(words / 238);
+      const teaser = `📈 **Preview:** ~${words} words, ~${readingTime} min reading time.\n\nFull analysis includes: Flesch-Kincaid grade level, Gunning Fog index, Coleman-Liau index, SMOG grade, syllable count, and vocabulary diversity score.`;
+      return paidResponse('Text Statistics', teaser, PURCHASE_BASE + '#text-stats');
+    }
+  );
+}