Skip to content

Commit 0a67c6d

Browse files
mejangomejango
committed
updated
1 parent d5f6f31 commit 0a67c6d

7 files changed

Lines changed: 437 additions & 32 deletions

File tree

‎api/mcp/[...path].js‎

Lines changed: 34 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -80,17 +80,48 @@ app.post(["/search", "/api/mcp/search"], async (req, res) => {
8080
if (!query) return res.status(400).json({ error: "query parameter is required" });
8181
if (docIndex.length === 0) return res.status(503).json({ error: "Index not available" });
8282

83+
// Detect query intent for building/integration queries
84+
const queryLower = query.toLowerCase();
85+
const isBuildingQuery = /\b(build|integrate|integration|deploy|launch|setup|configure|implement|develop|code|api|contract|hook|example|tutorial|how to|getting started)\b/i.test(query);
86+
const isV5Query = /\bv5\b/i.test(query) || queryLower.includes("v5");
87+
88+
// Auto-filter to v5 for building queries if version not specified
89+
let effectiveVersion = version;
90+
if (version === "all" && isBuildingQuery && !isV5Query) {
91+
effectiveVersion = "v5";
92+
}
93+
8394
let filteredIndex = docIndex;
8495
if (category !== "all") filteredIndex = filteredIndex.filter((d) => d.category === category);
85-
if (version !== "all") filteredIndex = filteredIndex.filter((d) => d.version === version);
96+
if (effectiveVersion !== "all") filteredIndex = filteredIndex.filter((d) => d.version === effectiveVersion);
8697

8798
const filteredFuse = new Fuse(filteredIndex, {
88-
keys: [{ name: "title", weight: 0.4 }, { name: "description", weight: 0.3 }, { name: "content", weight: 0.2 }, { name: "headings", weight: 0.1 }],
99+
keys: [
100+
{ name: "title", weight: 0.35 },
101+
{ name: "description", weight: 0.25 },
102+
{ name: "content", weight: 0.15 },
103+
{ name: "headings", weight: 0.1 },
104+
{ name: "tags", weight: 0.15 },
105+
],
89106
threshold: 0.4,
90107
includeScore: true,
108+
getFn: (obj, path) => {
109+
if (path === "tags") return obj.tags?.join(" ") || "";
110+
return Fuse.config.getFn(obj, path);
111+
},
91112
});
92113

93-
const results = filteredFuse.search(query, { limit: parseInt(limit) });
114+
let results = filteredFuse.search(query, { limit: parseInt(limit) * 2 });
115+
116+
// Re-rank by integrator relevance for building queries
117+
if (isBuildingQuery) {
118+
results = results.map(r => ({
119+
...r,
120+
score: r.score - (r.item.integratorRelevance || 0) * 0.1
121+
})).sort((a, b) => a.score - b.score).slice(0, parseInt(limit));
122+
} else {
123+
results = results.slice(0, parseInt(limit));
124+
}
94125
res.json({
95126
query,
96127
results: results.map((result) => ({

‎docs/dev/README.md‎

Lines changed: 12 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -13,14 +13,25 @@ Juicebox is a payment processor and capital formation engine for tokenized fundr
1313
Through scheduled rulesets, projects can adapt and evolve over time, adding structure, constraints, extensions, and incentives as needed. Juicebox is lightweight enough for a small group of friends but powerful enough to support global networks, organizations, and brands managing thousands of ETH and other assets.
1414

1515
These docs are here to help you navigate the protocol, whether you're...
16+
- Building a platform on Juicebox
17+
- Configuring a capital formation design using Juicebox
1618
- Auditing a Juicebox project
1719
- Designing your own Juicebox project
18-
- Developing extensions
20+
- Developing extensions usable by Juicebox projects
1921
- Learning Solidity and contract design
2022
- or, exploring the ecosystem for inspiration
2123

2224
... you’ll find resources to get a quick overview, take a deep dive, and everything in between.
2325

26+
---
27+
#### Directory
28+
29+
1. **[Learn](/docs/dev/v5/learn/overview.md)** - Step-by-step guidance on how the protocol works.
30+
2. **[Build](/docs/dev/v5/build/life-of-a-project.md)** - Guides to launch, configure, and extend a Juicebox project.
31+
3. **[API](/docs/dev/v5/api/core/README.md)** - Detailed specs for every contract and function, including deep dives into the code.
32+
4. **[Contract addresses](/docs/dev/v5/addresses.md)** - All contract addresses.
33+
5. **[MCP Server](/docs/dev/v5/build/mcp-server.md)** - Access documentation programmatically via MCP (Model Context Protocol).
34+
2435
---
2536

2637
#### Changes in Juicebox V5
@@ -51,14 +62,6 @@ These docs are here to help you navigate the protocol, whether you're...
5162

5263
- Added hooks that allow projects to bring their own functionality when they are paid, when token holders redeem, and when splits are paid out.
5364

54-
---
55-
#### Directory
56-
57-
1. **[Learn](/docs/dev/v5/learn/overview.md)** - Step-by-step guidance on how the protocol works.
58-
2. **[Build](/docs/dev/v5/build/life-of-a-project.md)** - Guides to launch, configure, and extend a Juicebox project.
59-
3. **[API](/docs/dev/v5/api/core/README.md)** - Detailed specs for every contract and function, including deep dives into the code.
60-
4. **[Contract addresses](/docs/dev/v5/addresses.md)** - All contract addresses.
61-
5. **[MCP Server](/docs/dev/v5/build/mcp-server.md)** - Access documentation programmatically via MCP (Model Context Protocol).
6265

6366
---
6467

‎docs/dev/v5/build/mcp-server.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
sidebar_position: 10
33
---
44

5-
# MCP Server for Documentation
5+
# MCP Server
66

77
The Juicebox documentation is available through an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server, making it easy for AI assistants and automated tools to search and retrieve documentation.
88

‎mcp-server/INTEGRATOR_TUNING.md‎

Lines changed: 198 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,198 @@
1+
# Fine-Tuning the MCP Server for Integrators
2+
3+
This document outlines the enhancements made to optimize the MCP server for integrators and developers building with Juicebox.
4+
5+
## Key Features
6+
7+
### 1. Automatic v5 Filtering for Building Queries
8+
9+
**Query Intent Detection**: The server automatically detects building/integration queries and filters to v5 documentation.
10+
11+
**Trigger Keywords:**
12+
- `build`, `integrate`, `integration`, `deploy`, `launch`
13+
- `setup`, `configure`, `implement`, `develop`
14+
- `code`, `api`, `contract`, `hook`
15+
- `example`, `tutorial`, `how to`, `getting started`
16+
17+
**Example:**
18+
```bash
19+
# Automatically filters to v5
20+
curl -X POST https://docs.juicebox.money/api/mcp/search \
21+
-d '{"query": "how to deploy a project"}'
22+
23+
# Explicitly requests v5
24+
curl -X POST https://docs.juicebox.money/api/mcp/search \
25+
-d '{"query": "deploy project", "version": "v5"}'
26+
```
27+
28+
### 2. Enhanced Metadata Extraction
29+
30+
Each document is now indexed with:
31+
- **Document Type**: `build`, `api`, `learn`, `example`
32+
- **Tags**: Automatic tagging based on content (e.g., `integration`, `hook`, `tutorial`)
33+
- **Integrator Relevance Score**: 0-10 scale prioritizing integrator-relevant content
34+
35+
**Relevance Scoring:**
36+
- `dev/v5/build/` → 10 (highest priority)
37+
- `dev/v5/build/examples/` → 9
38+
- `dev/v5/api/` → 8
39+
- `dev/v5/` → 5
40+
- Other docs → 0
41+
42+
### 3. Improved Search Ranking
43+
44+
**Search Weights:**
45+
- Title: 35% (was 40%)
46+
- Description: 25% (was 30%)
47+
- Content: 15% (was 20%)
48+
- Headings: 10% (unchanged)
49+
- **Tags: 15%** (new - boosts tagged content)
50+
51+
**Re-ranking for Building Queries:**
52+
- Results are re-ranked by `integratorRelevance` score
53+
- Build guides and examples are prioritized
54+
- API documentation gets higher ranking
55+
56+
### 4. Smart Query Routing
57+
58+
The server intelligently routes queries:
59+
60+
| Query Type | Auto-Filter | Priority Boost |
61+
|------------|-------------|----------------|
62+
| Building/Integration | v5 only | High (build guides, examples) |
63+
| API Reference | All versions | Medium (API docs) |
64+
| Concepts/Learning | All versions | Low (learn docs) |
65+
| General | All | None |
66+
67+
## Additional Fine-Tuning Suggestions
68+
69+
### 1. Add Code Example Extraction
70+
71+
Extract and index code blocks separately for better code search:
72+
73+
```javascript
74+
// Extract code blocks
75+
const codeBlocks = [];
76+
const codeRegex = /```[\s\S]*?```/g;
77+
// Index code separately with higher weight for code queries
78+
```
79+
80+
### 2. Add Contract Address Indexing
81+
82+
Create a separate index for contract addresses and deployment info:
83+
84+
```javascript
85+
// Special handling for addresses.md
86+
if (relativePath.includes("addresses")) {
87+
// Extract contract names and addresses
88+
// Make them searchable separately
89+
}
90+
```
91+
92+
### 3. Add Related Documents
93+
94+
Link related documents in the index:
95+
96+
```javascript
97+
// Extract "See also" links
98+
// Link related API docs, examples, and guides
99+
relatedDocs: extractRelatedLinks(content)
100+
```
101+
102+
### 4. Query Expansion
103+
104+
Expand common queries to include synonyms:
105+
106+
```javascript
107+
const queryExpansions = {
108+
"deploy": ["launch", "create", "setup"],
109+
"hook": ["extension", "custom", "plugin"],
110+
"ruleset": ["funding cycle", "configuration"],
111+
};
112+
```
113+
114+
### 5. Context-Aware Responses
115+
116+
Return contextual information with results:
117+
118+
```javascript
119+
// Include related concepts
120+
// Suggest next steps
121+
// Highlight code examples
122+
```
123+
124+
### 6. Version Comparison Tool
125+
126+
Add a tool to compare differences between versions:
127+
128+
```javascript
129+
{
130+
name: "compare_versions",
131+
description: "Compare documentation or features between v3, v4, and v5"
132+
}
133+
```
134+
135+
### 7. API Endpoint Discovery
136+
137+
Help integrators find the right API endpoints:
138+
139+
```javascript
140+
{
141+
name: "find_api_endpoint",
142+
description: "Find API endpoints for a specific task (e.g., 'deploy project', 'add hook')"
143+
}
144+
```
145+
146+
### 8. Code Snippet Extraction
147+
148+
Extract and index code snippets separately:
149+
150+
```javascript
151+
// Index code examples with language tags
152+
// Make them searchable with syntax highlighting context
153+
```
154+
155+
### 9. Common Patterns Library
156+
157+
Index common integration patterns:
158+
159+
```javascript
160+
// Tag common patterns: "multisig", "governance", "payments", etc.
161+
// Create pattern-based search
162+
```
163+
164+
### 10. Error Message Mapping
165+
166+
Map common errors to documentation:
167+
168+
```javascript
169+
// Index error messages and link to troubleshooting docs
170+
// Help integrators debug issues faster
171+
```
172+
173+
## Current Implementation
174+
175+
✅ **Implemented:**
176+
- Automatic v5 filtering for building queries
177+
- Enhanced metadata (docType, tags, integratorRelevance)
178+
- Improved search weights with tag support
179+
- Re-ranking for integrator-relevant content
180+
181+
🔄 **Recommended Next Steps:**
182+
1. Extract and index code blocks separately
183+
2. Add contract address special handling
184+
3. Implement query expansion
185+
4. Add related documents linking
186+
5. Create pattern-based search
187+
188+
## Testing
189+
190+
Test the improvements:
191+
192+
```bash
193+
# Building query (auto-filters to v5)
194+
curl -X POST https://docs.juicebox.money/api/mcp/search \
195+
-d '{"query": "how to deploy a project"}'
196+
197+
# Should return only v5 docs, prioritized by integrator relevance
198+
```

‎mcp-server/src/build-index.js‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,40 @@ async function buildIndex() {
5757
const versionMatch = relativePath.match(/v([345])/);
5858
const version = versionMatch ? `v${versionMatch[1]}` : null;
5959

60+
// Determine document type for better search relevance
61+
let docType = "general";
62+
let tags = [];
63+
64+
if (relativePath.includes("/build/")) {
65+
docType = "build";
66+
tags.push("integration", "development", "tutorial");
67+
}
68+
if (relativePath.includes("/api/")) {
69+
docType = "api";
70+
tags.push("reference", "contract", "interface");
71+
}
72+
if (relativePath.includes("/learn/")) {
73+
docType = "learn";
74+
tags.push("concept", "explanation");
75+
}
76+
if (relativePath.includes("/examples/")) {
77+
docType = "example";
78+
tags.push("code", "tutorial", "integration");
79+
}
80+
if (relativePath.includes("/hooks/")) {
81+
tags.push("hook", "extension", "custom");
82+
}
83+
if (relativePath.includes("addresses")) {
84+
tags.push("address", "deployment");
85+
}
86+
87+
// Boost priority for integrator-relevant content
88+
let integratorRelevance = 0;
89+
if (relativePath.startsWith("dev/v5/build/")) integratorRelevance = 10;
90+
else if (relativePath.startsWith("dev/v5/api/")) integratorRelevance = 8;
91+
else if (relativePath.startsWith("dev/v5/build/examples/")) integratorRelevance = 9;
92+
else if (relativePath.startsWith("dev/v5/")) integratorRelevance = 5;
93+
6094
docIndex.push({
6195
path: relativePath,
6296
fullPath: fullPath,
@@ -66,6 +100,9 @@ async function buildIndex() {
66100
headings: headings,
67101
category: category,
68102
version: version,
103+
docType: docType,
104+
tags: tags,
105+
integratorRelevance: integratorRelevance,
69106
sidebarPosition: frontmatter.sidebar_position || 999,
70107
url: `https://docs.juicebox.money/${relativePath.replace(/\.md$/, "")}`,
71108
});

0 commit comments

Comments
 (0)