Skip to content

Commit 8f329e6

Browse files
dipsethdipseth
authored
feat: fix list_profiles bug and optimize response format (#22)
- Fix ProfileManager initialization to use proper server config - Optimize list_profiles response format for 90% token reduction - Add automated documentation updates during release - Resolve issue where list_profiles returned empty array This PR includes both the critical MCP tool fix and the automated documentation system that will ensure all docs stay synchronized with releases.
1 parent 1f546cf commit 8f329e6

File tree

14 files changed

+594
-61
lines changed

14 files changed

+594
-61
lines changed

‎.github/workflows/docs.yml‎

Lines changed: 26 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -109,9 +109,30 @@ jobs:
109109
- name: Create Pages directory structure
110110
run: |
111111
mkdir -p _site
112-
cp -r docs/generated/* _site/ 2>/dev/null || true
112+
113+
# Copy all documentation files
114+
cp -r docs/* _site/ 2>/dev/null || true
115+
116+
# Ensure API docs are properly placed
117+
if [ -d "docs/api" ]; then
118+
echo "✅ API documentation found, copying to _site/api/"
119+
cp -r docs/api _site/
120+
else
121+
echo "⚠️ API documentation not found at docs/api/"
122+
fi
123+
124+
# Copy generated docs if they exist
125+
if [ -d "docs/generated" ]; then
126+
echo "✅ Generated docs found, copying to _site/"
127+
cp -r docs/generated/* _site/ 2>/dev/null || true
128+
fi
129+
130+
# Copy README as index
113131
cp README.md _site/index.md 2>/dev/null || true
114132
133+
echo "📁 Site structure:"
134+
find _site -type f -name "*.html" | head -10
135+
115136
# Create a simple index.html if none exists
116137
if [ ! -f _site/index.html ]; then
117138
cat > _site/index.html << 'EOF'
@@ -136,10 +157,10 @@ jobs:
136157
<p>Production-ready Model Context Protocol server for Google Cloud Dataproc operations.</p>
137158
138159
<div class="nav">
139-
<a href="api-reference.html">📚 API Reference</a>
140-
<a href="quick-start.html">🚀 Quick Start</a>
141-
<a href="configuration-examples.html">⚙️ Configuration</a>
142-
<a href="security-guide.html">🔐 Security Guide</a>
160+
<a href="api/">📚 API Reference</a>
161+
<a href="QUICK_START.html">🚀 Quick Start</a>
162+
<a href="CONFIGURATION_EXAMPLES.html">⚙️ Configuration</a>
163+
<a href="security/">🔐 Security Guide</a>
143164
</div>
144165
145166
<h2>Features</h2>

‎.github/workflows/release.yml‎

Lines changed: 151 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -223,13 +223,163 @@ jobs:
223223
echo "ℹ️ **No release created** - No releasable changes detected." >> $GITHUB_STEP_SUMMARY
224224
fi
225225
226+
# ============================================================================
227+
# DOCUMENTATION UPDATE
228+
# ============================================================================
229+
update-documentation:
230+
name: 📚 Update Documentation
231+
runs-on: ubuntu-latest
232+
needs: semantic-release
233+
if: needs.semantic-release.outputs.released == 'true'
234+
timeout-minutes: 10
235+
permissions:
236+
contents: write
237+
pull-requests: write
238+
steps:
239+
- name: 📥 Checkout Repository
240+
uses: actions/checkout@v4
241+
with:
242+
fetch-depth: 0
243+
token: ${{ secrets.GITHUB_TOKEN }}
244+
245+
- name: 🟢 Setup Node.js
246+
uses: actions/setup-node@v4
247+
with:
248+
node-version: '20'
249+
cache: 'npm'
250+
registry-url: 'https://registry.npmjs.org'
251+
252+
- name: 📦 Install Dependencies
253+
run: npm ci --prefer-offline --no-audit
254+
255+
- name: 📝 Update README Version Badges
256+
run: |
257+
echo "📝 Updating README version badges..."
258+
NEW_VERSION="${{ needs.semantic-release.outputs.version }}"
259+
260+
# Update npm version badge
261+
sed -i "s|npm/v/@dipseth/dataproc-mcp-server\.svg|npm/v/@dipseth/dataproc-mcp-server.svg|g" README.md
262+
263+
# Update package references in README
264+
sed -i "s|@dipseth/dataproc-mcp-server@[0-9]\+\.[0-9]\+\.[0-9]\+|@dipseth/dataproc-mcp-server@$NEW_VERSION|g" README.md
265+
266+
# Update installation commands
267+
sed -i "s|npm install -g @dataproc/mcp-server|npm install -g @dipseth/dataproc-mcp-server@$NEW_VERSION|g" README.md
268+
269+
echo "✅ README version badges updated to v$NEW_VERSION"
270+
271+
- name: 📚 Update Documentation Links
272+
run: |
273+
echo "📚 Updating documentation links..."
274+
NEW_VERSION="${{ needs.semantic-release.outputs.version }}"
275+
276+
# Update package.json version references in docs
277+
find docs/ -name "*.md" -type f -exec sed -i "s|@dipseth/dataproc-mcp-server@[0-9]\+\.[0-9]\+\.[0-9]\+|@dipseth/dataproc-mcp-server@$NEW_VERSION|g" {} \;
278+
279+
# Update docs/index.md with latest version
280+
if [ -f "docs/index.md" ]; then
281+
sed -i "s|version: [0-9]\+\.[0-9]\+\.[0-9]\+|version: $NEW_VERSION|g" docs/index.md
282+
fi
283+
284+
echo "✅ Documentation links updated"
285+
286+
- name: 🔄 Regenerate Documentation
287+
run: |
288+
echo "🔄 Regenerating documentation..."
289+
290+
# Regenerate API documentation with new version
291+
npm run docs:generate
292+
293+
# Update GitHub Pages if needed
294+
if [ -f "docs/_config.yml" ]; then
295+
sed -i "s|version: [0-9]\+\.[0-9]\+\.[0-9]\+|version: ${{ needs.semantic-release.outputs.version }}|g" docs/_config.yml
296+
fi
297+
298+
echo "✅ Documentation regenerated"
299+
300+
- name: 📊 Update Package Metrics
301+
run: |
302+
echo "📊 Updating package metrics..."
303+
NEW_VERSION="${{ needs.semantic-release.outputs.version }}"
304+
305+
# Create or update package info file
306+
cat > docs/package-info.json << EOF
307+
{
308+
"name": "@dipseth/dataproc-mcp-server",
309+
"version": "$NEW_VERSION",
310+
"released": "$(date -u +%Y-%m-%dT%H:%M:%SZ)",
311+
"npmUrl": "https://www.npmjs.com/package/@dipseth/dataproc-mcp-server/v/$NEW_VERSION",
312+
"githubRelease": "https://github.com/${{ github.repository }}/releases/tag/v$NEW_VERSION",
313+
"installCommand": "npm install @dipseth/dataproc-mcp-server@$NEW_VERSION"
314+
}
315+
EOF
316+
317+
echo "✅ Package metrics updated"
318+
319+
- name: 🚀 Update NPM Documentation
320+
run: |
321+
echo "🚀 Updating NPM package documentation..."
322+
323+
# Ensure package.json has correct repository and homepage URLs
324+
npm pkg set homepage="https://dipseth.github.io/dataproc-mcp/"
325+
npm pkg set repository.url="git+https://github.com/${{ github.repository }}.git"
326+
npm pkg set bugs.url="https://github.com/${{ github.repository }}/issues"
327+
328+
# Update package keywords for better discoverability
329+
npm pkg set keywords='["mcp", "dataproc", "google-cloud", "model-context-protocol", "typescript", "nodejs"]'
330+
331+
echo "✅ NPM documentation metadata updated"
332+
333+
- name: 📝 Create Documentation Update Summary
334+
run: |
335+
echo "## 📚 Documentation Update Summary" >> $GITHUB_STEP_SUMMARY
336+
echo "" >> $GITHUB_STEP_SUMMARY
337+
echo "Updated documentation for version **v${{ needs.semantic-release.outputs.version }}**:" >> $GITHUB_STEP_SUMMARY
338+
echo "" >> $GITHUB_STEP_SUMMARY
339+
echo "### ✅ Updated Components" >> $GITHUB_STEP_SUMMARY
340+
echo "- 📝 README.md version badges and installation commands" >> $GITHUB_STEP_SUMMARY
341+
echo "- 📚 Documentation links and version references" >> $GITHUB_STEP_SUMMARY
342+
echo "- 🔄 Regenerated API documentation" >> $GITHUB_STEP_SUMMARY
343+
echo "- 📊 Package metrics and metadata" >> $GITHUB_STEP_SUMMARY
344+
echo "- 🚀 NPM package documentation" >> $GITHUB_STEP_SUMMARY
345+
echo "" >> $GITHUB_STEP_SUMMARY
346+
echo "### 🔗 Updated Links" >> $GITHUB_STEP_SUMMARY
347+
echo "- **NPM Package**: [v${{ needs.semantic-release.outputs.version }}](https://www.npmjs.com/package/@dipseth/dataproc-mcp-server/v/${{ needs.semantic-release.outputs.version }})" >> $GITHUB_STEP_SUMMARY
348+
echo "- **GitHub Pages**: [Documentation](https://dipseth.github.io/dataproc-mcp/)" >> $GITHUB_STEP_SUMMARY
349+
echo "- **Installation**: \`npm install @dipseth/dataproc-mcp-server@${{ needs.semantic-release.outputs.version }}\`" >> $GITHUB_STEP_SUMMARY
350+
351+
- name: 💾 Commit Documentation Updates
352+
run: |
353+
# Configure git
354+
git config --local user.email "[email protected]"
355+
git config --local user.name "GitHub Action"
356+
357+
# Check if there are changes to commit
358+
if git diff --quiet && git diff --staged --quiet; then
359+
echo "ℹ️ No documentation changes to commit"
360+
else
361+
echo "📝 Committing documentation updates..."
362+
git add .
363+
git commit -m "docs: update documentation for v${{ needs.semantic-release.outputs.version }}
364+
365+
- Update README version badges and installation commands
366+
- Update documentation links and version references
367+
- Regenerate API documentation
368+
- Update package metrics and NPM metadata
369+
370+
[skip ci]"
371+
372+
git push origin main
373+
echo "✅ Documentation updates committed and pushed"
374+
fi
375+
226376
# ============================================================================
227377
# POST-RELEASE VALIDATION
228378
# ============================================================================
229379
post-release-validation:
230380
name: ✅ Post-Release Validation
231381
runs-on: ubuntu-latest
232-
needs: semantic-release
382+
needs: [semantic-release, update-documentation]
233383
if: needs.semantic-release.outputs.released == 'true'
234384
timeout-minutes: 10
235385
steps:

‎README.md‎

Lines changed: 52 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -65,7 +65,7 @@ npx @dataproc/mcp-server
6565

6666
1. **Install the package:**
6767
```bash
68-
npm install -g @dataproc/mcp-server
68+
npm install -g @dipseth/dataproc-mcp-server@2.1.1
6969
```
7070

7171
2. **Run the setup:**
@@ -123,26 +123,52 @@ npx @dataproc/mcp-server
123123
- **Troubleshooting Guides** - Common issues and solutions
124124
- **IDE Integration** - TypeScript support
125125

126-
## 🛠️ Available Tools
127-
128-
| Tool | Description | Parameters Reduced |
129-
|------|-------------|-------------------|
130-
| `start_dataproc_cluster` | Create and start clusters | 80% |
131-
| `stop_dataproc_cluster` | Stop running clusters | 75% |
132-
| `delete_dataproc_cluster` | Delete clusters | 70% |
133-
| `list_dataproc_clusters` | List all clusters | 85% |
134-
| `get_dataproc_cluster` | Get cluster details | 75% |
135-
| `submit_dataproc_job` | Submit Spark/Hive jobs | 70% |
136-
| `get_dataproc_job` | Get job status | 80% |
137-
| `list_dataproc_jobs` | List all jobs | 85% |
138-
| `cancel_dataproc_job` | Cancel running jobs | 75% |
139-
| `get_dataproc_job_results` | Get job outputs | 70% |
140-
| `list_profiles` | List cluster profiles | 90% |
141-
| `get_profile` | Get profile details | 85% |
142-
| `validate_profile` | Validate configurations | 80% |
143-
| `get_cluster_metrics` | Get performance metrics | 75% |
144-
| `scale_dataproc_cluster` | Scale cluster nodes | 70% |
145-
| `update_cluster_labels` | Update cluster labels | 80% |
126+
## 🛠️ Complete MCP Tools Suite (21 Tools)
127+
128+
### 🚀 **Cluster Management (8 Tools)**
129+
| Tool | Description | Smart Defaults | Key Features |
130+
|------|-------------|----------------|--------------|
131+
| `start_dataproc_cluster` | Create and start new clusters | ✅ 80% fewer params | Profile-based, auto-config |
132+
| `create_cluster_from_yaml` | Create from YAML configuration | ✅ Project/region injection | Template-driven setup |
133+
| `create_cluster_from_profile` | Create using predefined profiles | ✅ 85% fewer params | 8 built-in profiles |
134+
| `list_clusters` | List all clusters with filtering | ✅ No params needed | Semantic queries, pagination |
135+
| `list_tracked_clusters` | List MCP-created clusters | ✅ Profile filtering | Creation tracking |
136+
| `get_cluster` | Get detailed cluster information | ✅ 75% fewer params | Semantic data extraction |
137+
| `delete_cluster` | Delete existing clusters | ✅ Project/region defaults | Safe deletion |
138+
| `get_zeppelin_url` | Get Zeppelin notebook URL | ✅ Auto-discovery | Web interface access |
139+
140+
### 💼 **Job Management (6 Tools)**
141+
| Tool | Description | Smart Defaults | Key Features |
142+
|------|-------------|----------------|--------------|
143+
| `submit_hive_query` | Submit Hive queries to clusters | ✅ 70% fewer params | Async support, timeouts |
144+
| `submit_dataproc_job` | Submit Spark/PySpark/Presto jobs | ✅ 75% fewer params | Multi-engine support |
145+
| `get_job_status` | Get job execution status | ✅ JobID only needed | Real-time monitoring |
146+
| `get_job_results` | Get job outputs and results | ✅ Auto-pagination | Result formatting |
147+
| `get_query_status` | Get Hive query status | ✅ Minimal params | Query tracking |
148+
| `get_query_results` | Get Hive query results | ✅ Smart pagination | Enhanced async support |
149+
150+
### 📋 **Configuration & Profiles (3 Tools)**
151+
| Tool | Description | Smart Defaults | Key Features |
152+
|------|-------------|----------------|--------------|
153+
| `list_profiles` | List available cluster profiles | ✅ Category filtering | 8 production profiles |
154+
| `get_profile` | Get detailed profile configuration | ✅ Profile ID only | Template access |
155+
| `query_cluster_data` | Query stored cluster data | ✅ Natural language | Semantic search |
156+
157+
### 📊 **Analytics & Insights (4 Tools)**
158+
| Tool | Description | Smart Defaults | Key Features |
159+
|------|-------------|----------------|--------------|
160+
| `check_active_jobs` | Quick status of all active jobs | ✅ No params needed | Multi-project view |
161+
| `get_cluster_insights` | Comprehensive cluster analytics | ✅ Auto-discovery | Machine types, components |
162+
| `get_job_analytics` | Job performance analytics | ✅ Success rates | Error patterns, metrics |
163+
| `query_knowledge` | Query comprehensive knowledge base | ✅ Natural language | Clusters, jobs, errors |
164+
165+
### 🎯 **Key Capabilities**
166+
- **🧠 Semantic Search**: Natural language queries with Qdrant integration
167+
- **⚡ Smart Defaults**: 60-80% parameter reduction through intelligent injection
168+
- **📊 Response Optimization**: 96% token reduction with full data preservation
169+
- **🔄 Async Support**: Non-blocking job submission and monitoring
170+
- **🏷️ Profile System**: 8 production-ready cluster templates
171+
- **📈 Analytics**: Comprehensive insights and performance tracking
146172

147173
## 📋 Configuration
148174

@@ -175,12 +201,12 @@ my-company-analytics-prod-1234:
175201

176202
## 📚 Documentation
177203

178-
- **[Quick Start Guide](https://dipseth.github.io/dataproc-mcp/QUICK_START)** - Get started in 5 minutes
179-
- **[Knowledge Base Semantic Search](https://dipseth.github.io/dataproc-mcp/KNOWLEDGE_BASE_SEMANTIC_SEARCH)** - Natural language queries and setup
204+
- **[Quick Start Guide](https://dipseth.github.io/dataproc-mcp/QUICK_START.html)** - Get started in 5 minutes
205+
- **[Knowledge Base Semantic Search](https://dipseth.github.io/dataproc-mcp/KNOWLEDGE_BASE_SEMANTIC_SEARCH.html)** - Natural language queries and setup
180206
- **[API Reference](https://dipseth.github.io/dataproc-mcp/api/)** - Complete tool documentation
181-
- **[Configuration Examples](https://dipseth.github.io/dataproc-mcp/CONFIGURATION_EXAMPLES)** - Real-world configurations
207+
- **[Configuration Examples](https://dipseth.github.io/dataproc-mcp/CONFIGURATION_EXAMPLES.html)** - Real-world configurations
182208
- **[Security Guide](https://dipseth.github.io/dataproc-mcp/security/)** - Best practices and compliance
183-
- **[Installation Guide](https://dipseth.github.io/dataproc-mcp/INSTALLATION_GUIDE)** - Detailed setup instructions
209+
- **[Installation Guide](https://dipseth.github.io/dataproc-mcp/INSTALLATION_GUIDE.html)** - Detailed setup instructions
184210

185211
## 🔧 MCP Client Integration
186212

@@ -304,6 +330,7 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
304330

305331
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol that makes this possible
306332
- [Google Cloud Dataproc](https://cloud.google.com/dataproc) - The service we're integrating with
333+
- [Qdrant](https://github.com/qdrant/qdrant) - High-performance vector database powering our semantic search and knowledge indexing
307334
- [TypeScript](https://www.typescriptlang.org/) - For type safety and developer experience
308335

309336
---

‎docs/CI_CD_GUIDE.md‎

Lines changed: 43 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -252,6 +252,9 @@ npm audit --audit-level moderate
252252
npm run docs:generate
253253
npm run docs:api
254254

255+
# Update documentation with current version
256+
npm run docs:update
257+
255258
# Test links
256259
npm run docs:test-links
257260

@@ -274,7 +277,46 @@ tar -tzf *.tgz
274277

275278
## 🚀 Enhanced Automatic Release Process
276279

277-
### ✨ **NEW: Automatic PR Merge Publishing**
280+
### ✨ **NEW: Automated Documentation Updates**
281+
282+
The release workflow now **automatically updates all documentation** when a new version is published:
283+
284+
#### **📚 What Gets Updated Automatically:**
285+
- ✅ **README.md** - Version badges and installation commands
286+
- ✅ **Documentation files** - All `.md` files with package references
287+
- ✅ **Configuration files** - `docs/_config.yml` and package metadata
288+
- ✅ **Package info** - Creates `docs/package-info.json` with release details
289+
- ✅ **NPM metadata** - Homepage, repository URLs, and keywords
290+
291+
#### **🔄 Documentation Update Flow:**
292+
```mermaid
293+
graph LR
294+
A[🚀 Semantic Release] --> B[📚 Update Documentation]
295+
B --> C[💾 Commit Changes]
296+
C --> D[✅ Post-Release Validation]
297+
```
298+
299+
#### **🛠️ Local Documentation Updates:**
300+
You can also update documentation locally:
301+
```bash
302+
# Update all documentation with current version
303+
npm run docs:update
304+
305+
# What it updates:
306+
# - README.md version badges and installation commands
307+
# - All documentation files with package references
308+
# - Configuration files and metadata
309+
# - Package information JSON file
310+
```
311+
312+
#### **📝 Documentation Update Script Features:**
313+
- **Smart version detection** - Reads current version from package.json
314+
- **Comprehensive updates** - Updates all references across the project
315+
- **Safe operations** - Only updates when changes are detected
316+
- **Detailed logging** - Shows exactly what was updated
317+
- **Git integration** - Commits changes with `[skip ci]` to prevent loops
318+
319+
### ✨ **Automatic PR Merge Publishing**
278320

279321
The CI/CD pipeline now **automatically publishes new versions when PRs are merged to main branch**. Here's how it works:
280322

0 commit comments

Comments
 (0)