claud sesh

Author: mejango

docs/dev/v5/build/bendystraw.md

@@ -1,62 +1,46 @@
 ---
-sidebar_position: 4
+sidebar_position: 6
 ---
 
-# Subgraph
+# Subgraph (Legacy)
 
-The Juicebox subgraphs index events from the Juicebox contracts, and provide data to apps like [Crypto Fundraising & DAO Management](https://juicebox.money) and [Revnets](https://app.revnet.eth.sucks).  
+:::tip Recommended: Use Bendystraw
+For V5 protocol data, we recommend using [Bendystraw](/docs/dev/v5/build/bendystraw.md) - a modern GraphQL API with better performance, cross-chain support, and active maintenance.
+:::
 
-There are two subgraph versions: one for legacy contracts versions 1-3, and another for the current v5 contracts. Both maintain extensive, up-to-date data reflecting nearly every aspect of the contracts, including Projects (or Revents) and their balances/configurations, activity events like Payments and Redemptions, token holders, token balances and transfers, and much more.  
+The legacy Juicebox subgraphs index events from Juicebox contracts V1-V3. These are maintained for backwards compatibility with older projects.
 
-Both subgraphs are developed primarily by Peri (peri.eth, [@peri](https://twitter.com/peri)), and hosted by [Alchemy Subgraphs - By Satsuma](https://subgraph.satsuma-prod.com).  
+## Legacy Subgraph Access
 
----
-
-## Querying the subgraph  
-
-**URLs:**  
-Query URLs use this format:  
+**URL Format:**
 ```
 https://subgraph.satsuma-prod.com/<api-key>/juicebox/<name>/api
-```  
-
-If you don’t have your own Alchemy subgraphs API key, you can use the free dev key `bc505571c408`, which is restricted by a monthly query limit.  
-
-**For current (v5) contracts, Subgraph names follow their network name:**  
-- ethereum  
-- sepolia  
-- base  
-- base-sepolia  
-- arbitrum  
-- arbitrum-sepolia  
-- optimism  
-- optimism-sepolia  
-
-> **Note:** data from v1-v3 contracts are NOT available in the current (v5) subgraphs.  
-
-**For previous contracts (v1-v3), network names are suffixed with `-v3`. Only Ethereum networks are available:**  
-- ethereum-v3  
-- sepolia-v3  
-
----
+```
 
-## Query structure  
+**Free dev key:** `bc505571c408` (rate limited)
 
-Juicebox subgraphs accept standard graphql queries. More info [here](https://graphql.org/learn/).  
+**Available networks (V1-V3 only):**
+- `ethereum-v3`
+- `sepolia-v3`
 
-You can use Alchemy’s Playground to make sample queries to a specific subgraph, and explore the schema for queryable entities:  
+**Playground:**
 ```
 https://subgraph.satsuma-prod.com/juicebox/<network>/playground
-```  
-
-Schemas for each subgraph can also be found on Github.  
+```
 
----
+## V5 Data
 
-## Github  
+For V5 protocol data across all chains (Ethereum, Optimism, Arbitrum, Base), use [Bendystraw](/docs/dev/v5/build/bendystraw.md):
 
-- **Current v5:** [peripheralist/nana-subgraph: 🧃 Juicebox Subgraph implementation.](https://github.com/peripheralist/nana-subgraph)  
-- **Previous versions 1-3:** [jbx-protocol/juice-subgraph: 🧃 Juicebox Subgraph implementation.](https://github.com/jbx-protocol/juice-subgraph)  
+| Feature | Legacy Subgraph | Bendystraw |
+|---------|-----------------|------------|
+| Protocol versions | V1-V3 only | V5 |
+| Chains | Ethereum only | Ethereum, Optimism, Arbitrum, Base |
+| Cross-chain queries | No | Yes (Sucker Groups) |
+| SDK integration | Manual | `useBendystrawQuery` hook |
+| Maintenance | Minimal | Active |
 
-See the Readme in each repo for more information on development/contributing.
+## Source Code
 
+- **V1-V3 Subgraph:** [jbx-protocol/juice-subgraph](https://github.com/jbx-protocol/juice-subgraph)
+- **Bendystraw (V5):** [peripheralist/bendystraw](https://github.com/peripheralist/bendystraw)

docs/dev/v5/build/sdk.md

@@ -1,6 +1,6 @@
 # Juicebox Docs MCP Server
 
-An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that provides AI assistants with structured access to Juicebox documentation.
+An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that provides AI assistants with structured access to Juicebox documentation, SDK references, contract addresses, code examples, and integration patterns.
 
 ## Quick Start
 
@@ -18,6 +18,20 @@ curl -X POST https://docs.juicebox.money/api/mcp/search \
 curl -X POST https://docs.juicebox.money/api/mcp/get-doc \
   -H "Content-Type: application/json" \
   -d '{"path": "dev/v5/learn/overview.md"}'
+
+# Get contract addresses
+curl "https://docs.juicebox.money/api/mcp/contracts?contract=JBController"
+
+# Get SDK reference
+curl "https://docs.juicebox.money/api/mcp/sdk?package=juice-sdk-react&category=write"
+
+# Get integration patterns for revnets
+curl "https://docs.juicebox.money/api/mcp/patterns?projectType=revnet"
+
+# Search code examples
+curl -X POST https://docs.juicebox.money/api/mcp/search-code \
+  -H "Content-Type: application/json" \
+  -d '{"query": "pay", "language": "solidity", "limit": 5}'
 ```
 
 **JavaScript:**
@@ -42,29 +56,67 @@ npm run mcp:build-index
 
 ## API Endpoints
 
+### Documentation
+
 | Method | Endpoint | Description |
 |--------|----------|-------------|
 | `POST` | `/api/mcp/search` | Search docs (query, category, version, limit) |
 | `POST` | `/api/mcp/get-doc` | Get full document by path or title |
 | `GET` | `/api/mcp/list-docs?category=developer&version=v5` | List docs in category |
 | `GET` | `/api/mcp/structure` | Get documentation structure/stats |
 
-**Parameters:**
+### Code & Integration (New)
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| `POST` | `/api/mcp/search-code` | Search code examples by language/category |
+| `GET` | `/api/mcp/contracts` | Get contract addresses by name/chain |
+| `GET` | `/api/mcp/sdk` | Get SDK hook/utility reference |
+| `GET` | `/api/mcp/patterns` | Get integration patterns by project type |
+
+**Documentation Parameters:**
 - `query` (string, required for search): Search terms
 - `category`: `developer` | `user` | `dao` | `ecosystem` | `all`
 - `version`: `v3` | `v4` | `v5` | `all`
 - `limit` (number): Max results (default: 10)
 - `path` (string, required for get-doc): Document path or title
 
+**Code Search Parameters:**
+- `query` (string, required): Code search terms
+- `language`: `solidity` | `typescript` | `javascript` | `json` | `graphql` | `bash` | `all`
+- `category`: `contract` | `sdk-react` | `web3` | `api` | `config` | `cli` | `graphql` | `all`
+
+**Contract Address Parameters:**
+- `contract`: Contract name (e.g., `JBController`, `REVDeployer`)
+- `chainId`: `1` (mainnet) | `10` (optimism) | `8453` (base) | `42161` (arbitrum) | testnets | `all`
+- `category`: `core` | `revnet` | `hooks` | `suckers` | `omnichain` | `croptop` | `all`
+
+**SDK Reference Parameters:**
+- `package`: `juice-sdk-react` | `juice-sdk-core` | `revnet-sdk` | `all`
+- `hook`: Specific hook/utility name (e.g., `useJBProjectProvider`)
+- `category`: `context` | `read` | `write` | `omnichain` | `math` | `formatting` | `all`
+
+**Integration Patterns Parameters:**
+- `pattern`: Pattern ID (e.g., `pay-project`, `wagmi-setup`)
+- `category`: `setup` | `payments` | `calculations` | `data` | `deployment` | `omnichain` | `all`
+- `projectType`: `crowdfunding` | `revnet` | `dao-treasury` | `subscription`
+
 ## MCP Tools (Stdio Server)
 
 When using the local stdio MCP server:
 
+### Documentation Tools
 - `search_docs` - Search documentation by keyword or phrase
 - `get_doc` - Retrieve a specific documentation page
 - `list_docs_by_category` - List all docs in a category
 - `get_doc_structure` - Get the complete documentation structure
 
+### Code & Integration Tools (New)
+- `search_code_examples` - Search code examples from documentation
+- `get_contract_addresses` - Get contract addresses by name/chain
+- `get_sdk_reference` - Get SDK hooks and utilities reference
+- `get_integration_patterns` - Get integration patterns and templates
+
 ## Configuration
 
 ### Claude Desktop
@@ -87,10 +139,14 @@ Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)
 
 ## Features
 
-- **Semantic Search**: Fuzzy search across all documentation
-- **Category Filtering**: Filter by developer, user, dao, or ecosystem docs
+- **Semantic Search**: Fuzzy search across 1,600+ documentation pages
+- **Code Examples**: 8,000+ indexed code examples from docs (Solidity, TypeScript, GraphQL)
+- **SDK Reference**: juice-sdk-react hooks, juice-sdk-core utilities, revnet-sdk functions
+- **Contract Addresses**: All V5 contract addresses across 8 chains (mainnet + testnets)
+- **Integration Patterns**: Ready-to-use code patterns for common use cases
+- **Project Type Templates**: Patterns organized by project type (revnet, crowdfunding, DAO, subscription)
 - **Version Filtering**: Filter by protocol version (v3, v4, v5)
-- **Full Document Retrieval**: Get complete markdown content with metadata
+- **Category Filtering**: Filter by developer, user, dao, or ecosystem docs
 - **Always Up-to-Date**: Index automatically rebuilds when docs change
 
 ## Development

docs/dev/v5/build/subgraph.md

@@ -3,6 +3,11 @@
 /**
  * Standalone script to build the documentation index
  * Can be run independently or as part of the build process
+ *
+ * Enhanced to extract:
+ * - Code examples with language tags
+ * - Contract addresses
+ * - SDK usage patterns
  */
 
 import fs from "fs/promises";
@@ -16,10 +21,69 @@ const __dirname = path.dirname(__filename);
 const PROJECT_ROOT = path.resolve(__dirname, "../..");
 const DOCS_DIR = path.join(PROJECT_ROOT, "docs");
 const INDEX_FILE = path.join(__dirname, "docs-index.json");
+const CODE_EXAMPLES_FILE = path.join(__dirname, "code-examples-index.json");
+
+/**
+ * Extract code blocks from markdown content
+ * Returns array of { language, code, context } objects
+ */
+function extractCodeBlocks(content, docTitle, docPath) {
+  const codeBlocks = [];
+  // Match fenced code blocks with optional language
+  const codeRegex = /```(\w+)?\n([\s\S]*?)```/g;
+  let match;
+
+  while ((match = codeRegex.exec(content)) !== null) {
+    const language = match[1] || "text";
+    const code = match[2].trim();
+
+    // Skip very short code blocks (likely not useful examples)
+    if (code.length < 20) continue;
+
+    // Get surrounding context (heading before the code block)
+    const beforeCode = content.substring(0, match.index);
+    const headingMatch = beforeCode.match(/#{1,6}\s+(.+)$/m);
+    const context = headingMatch ? headingMatch[1].trim() : docTitle;
+
+    // Categorize the code example
+    let category = "general";
+    if (language === "solidity" || code.includes("contract ") || code.includes("function ")) {
+      category = "contract";
+    } else if (language === "typescript" || language === "javascript" || language === "ts" || language === "js") {
+      if (code.includes("useWrite") || code.includes("useRead") || code.includes("useJB")) {
+        category = "sdk-react";
+      } else if (code.includes("wagmi") || code.includes("viem")) {
+        category = "web3";
+      } else if (code.includes("fetch") || code.includes("axios") || code.includes("graphql")) {
+        category = "api";
+      } else {
+        category = "javascript";
+      }
+    } else if (language === "json") {
+      category = "config";
+    } else if (language === "bash" || language === "shell") {
+      category = "cli";
+    } else if (language === "graphql") {
+      category = "graphql";
+    }
+
+    codeBlocks.push({
+      language,
+      code,
+      context,
+      category,
+      docPath,
+      docTitle,
+    });
+  }
+
+  return codeBlocks;
+}
 
 async function buildIndex() {
   console.log("Building documentation index...");
   const docIndex = [];
+  const codeExamples = [];
 
   async function processDirectory(dir, basePath = "") {
     const entries = await fs.readdir(dir, { withFileTypes: true });
@@ -124,7 +188,12 @@ async function buildIndex() {
           else if (relativePath.startsWith("dev/v5/api/revnet/")) integratorRelevance = 6; // Revnet API
           else if (relativePath.startsWith("dev/v5/api/")) integratorRelevance = 3; // Other API lower priority
           else if (relativePath.startsWith("dev/v5/")) integratorRelevance = 5;
-          
+
+          // Extract code examples from the document
+          const docTitle = frontmatter.title || headings[0] || path.basename(entry.name, ".md");
+          const extractedCode = extractCodeBlocks(body, docTitle, relativePath);
+          codeExamples.push(...extractedCode);
+
           docIndex.push({
             path: relativePath,
             fullPath: fullPath,
@@ -148,26 +217,41 @@ async function buildIndex() {
   }
 
   await processDirectory(DOCS_DIR);
-  
-  // Save index
+
+  // Save documentation index
   await fs.writeFile(INDEX_FILE, JSON.stringify(docIndex, null, 2));
   console.log(`✓ Indexed ${docIndex.length} documents`);
   console.log(`✓ Index saved to ${INDEX_FILE}`);
-  
+
+  // Save code examples index
+  await fs.writeFile(CODE_EXAMPLES_FILE, JSON.stringify(codeExamples, null, 2));
+  console.log(`✓ Extracted ${codeExamples.length} code examples`);
+  console.log(`✓ Code examples saved to ${CODE_EXAMPLES_FILE}`);
+
   // Print summary
   const byCategory = {};
   const byVersion = {};
-  
+  const codeByCategory = {};
+  const codeByLanguage = {};
+
   for (const doc of docIndex) {
     byCategory[doc.category] = (byCategory[doc.category] || 0) + 1;
     if (doc.version) {
       byVersion[doc.version] = (byVersion[doc.version] || 0) + 1;
     }
   }
-  
-  console.log("\nSummary:");
+
+  for (const example of codeExamples) {
+    codeByCategory[example.category] = (codeByCategory[example.category] || 0) + 1;
+    codeByLanguage[example.language] = (codeByLanguage[example.language] || 0) + 1;
+  }
+
+  console.log("\nDocumentation Summary:");
   console.log("By category:", byCategory);
   console.log("By version:", byVersion);
+  console.log("\nCode Examples Summary:");
+  console.log("By category:", codeByCategory);
+  console.log("By language:", codeByLanguage);
 }
 
 buildIndex().catch(console.error);