Vaali MCP Server

🚀 Vaali MCP Server

A Model Context Protocol (MCP) server that showcases advanced AI agent capabilities through interactive parameter collection and contextual workflow automation, featuring both official MCP elicitation and intelligent parameter guidance patterns.

🚀 Quick Start

Prerequisites

• Node.js 18+
• VS Code (recommended)

Installation & Testing

# Clone and setup
git clone <repository-url>
cd vaali

# Install dependencies
npm install

# Build the project
npm run build

# Test elicitation concepts (educational walkthrough)
npm run test:advanced-concept

# Test with real MCP clients
npm run test:working-advanced

# Run all tests
npm run test:all

# Start server for Claude Desktop (stdio mode)
npm run start:stdio

# Start server with SSE transport (for debugging)
npm run start:sse

Claude Desktop Integration

Add to your Claude Desktop configuration file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "vaali": {
      "command": "node",
      "args": ["C:/absolute/path/to/vaali/lib/src/index.js", "stdio"],
      "cwd": "C:/absolute/path/to/vaali"
    }
  }
}

⚠️ Important Note

Use absolute paths for reliable operation. Replace with your actual project path.

Then try natural language commands:

"What's the weather in Tokyo?"
"Generate a weather report for Alice"
"Calculate 25 * 4 + 10"
"Test the elicitation tool"

✨ Features

• 🔄 Hybrid Elicitation: Both official MCP elicitation and universal parameter guidance
• 📊 Full MCP Compliance: Resources, tools, prompts, and elicitation capabilities
• 🎯 Progressive Enhancement: Optimal experience based on client capabilities
• 🛡️ Universal Compatibility: Works with any MCP client
• 🧪 Research-Ready: Comprehensive examples for academic and industrial research
• 🚀 Production-Ready: Robust error handling and graceful fallbacks

📦 Installation

☁️ Azure Deployment

Your MCP Server can be deployed to Azure App Service for cloud access and scalability.

🚀 GitHub Actions Deployment (Recommended)

The easiest way to deploy is through automated GitHub Actions:

1. Fork this repository to your GitHub account

2. Get Azure Publish Profile:

   az webapp deployment list-publishing-profiles -n your-app-name -g your-resource-group --xml
   

3. Add GitHub Secret:

   • Go to your forked repo → Settings → Secrets and variables → Actions
   • Click "New repository secret"
   • Name: AZURE_WEBAPP_PUBLISH_PROFILE
   • Value: Paste the XML output from step 2

4. Automatic Deployment:

   • ✅ Push to main → Automatically builds and deploys
   • ✅ TypeScript compilation → Handles build process properly
   • ✅ Production ready → Configures environment automatically

🎯 What the Automation Does:

• ✅ Builds TypeScript to JavaScript properly
• ✅ Installs production dependencies
• ✅ Deploys to Azure App Service
• ✅ Configures Node.js environment
• ✅ Provides deployment status and URL

🏗️ Azure Infrastructure Setup

If you need to create the Azure resources first, you can use the Bicep/ARM templates:

🏗️ Manual Infrastructure Creation:

# Create resource group
az group create --name vaali-mcp-rg --location centralus

# Deploy infrastructure using Bicep
az deployment group create \
  --resource-group vaali-mcp-rg \
  --template-file infra/main.bicep \
  --parameters webAppName=your-unique-app-name

# Or deploy using ARM template
az deployment group create \
  --resource-group vaali-mcp-rg \
  --template-file infra/azuredeploy.json \
  --parameters webAppName=your-unique-app-name

Pricing Tiers:

⚠️ Important Note

App Service runs 24/7. Check current Azure pricing for your region.

💻 Usage Examples

Try These Commands in Claude Desktop (Local):

"What's the weather in Seattle?"
"Calculate 25 * 4 + 10"
"Analyze the sentiment of 'This is amazing!'"
"Generate a weather report for Alice"
"Test the elicitation tool for rain prediction"

API Examples for Azure Deployment:

# Get weather (via SSE)
curl -X POST https://your-app.azurewebsites.net/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "get_weather", "arguments": {"location": "Tokyo"}}}'

# Test elicitation
curl -X POST https://your-app.azurewebsites.net/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "rain_prediction_with_elicitation", "arguments": {}}}'

📚 Documentation

For Users & Beginners

• docs/CLAUDE_DESKTOP_GUIDE.md - Complete Claude Desktop usage guide
• docs/README.md - Documentation index and navigation

For Developers

• docs/IMPLEMENTATION_COMPREHENSIVE_GUIDE.md - Complete technical implementation
• docs/test-documentation.md - Testing suite documentation

For Researchers

• docs/ELICITATION_COMPREHENSIVE_GUIDE.md - Elicitation patterns and best practices
• docs/ADVANCED_IMPLEMENTATION_SUMMARY.md - Technical architecture overview

🔧 Technical Details

🎯 What is This?

Vaali makes AI assistants (like Claude) smarter and more helpful by giving them:

• 🔧 Tools they can use (weather, calculations, text analysis)
• 📋 Prompts that guide complex workflows
• 📁 Resources with your data and preferences
• 🤖 Interactive parameter collection that asks for missing information intelligently

Simple Example:

You: "What's the weather like?"

With Elicitation-Capable Client:
✨ Interactive form appears asking for location
📍 You enter "Seattle, WA"  
🌤️ "Current weather in Seattle: 45°F, Cloudy"

With Standard Client:
📋 "I can help with weather! Please provide your location:
   • City: 'Seattle', 'London', 'Tokyo'
   • City with region: 'Austin, TX', 'Paris, France'
   Or enter any city name..."

📸 Real Claude Desktop Elicitation in Action

Here's how the Vaali MCP server's elicitation looks in Claude Desktop:

Screenshot showing Claude Desktop's interactive parameter collection with the Vaali MCP server - demonstrating the seamless user experience of hybrid elicitation patterns.

🧠 Technical Innovation (For Researchers)

This project implements both official MCP elicitation and intelligent parameter guidance patterns, demonstrating comprehensive approaches to interactive parameter collection in AI agent workflows.

Hybrid Approach: Two Complementary Methods

1. 🔥 Official MCP Elicitation (NEW): Interactive workflows that collect missing parameters DURING tool execution

   • Server directly requests structured data from clients using server.elicitInput()
   • JSON schema-driven forms and dialogs in supporting clients
   • Accept/decline/cancel response model with immediate parameter collection
   • Standardized protocol feature for enhanced user experience

2. 📋 Parameter Guidance Pattern: Universal compatibility approach using existing MCP features

   • Works with ANY MCP client through intelligent error handling and contextual guidance
   • Rich contextual help, examples, and intelligent suggestions
   • Client-side intelligence for error recovery and preference learning

Key Technical Contributions

• 🚀 Interactive Workflows: Tools that start execution and collect missing parameters progressively
• 🔄 Hybrid Compatibility: Same tools work with elicitation-capable AND standard MCP clients
• 🛡️ Graceful Fallbacks: Automatic detection of client capabilities with appropriate response patterns
• 🎯 Progressive Enhancement: Enhanced experience for capable clients, universal functionality for all
• 📊 Comprehensive Implementation: Full MCP server with resources, tools, prompts, and elicitation

Research Significance

• Interactive AI Workflows: Demonstrates how tools can seamlessly collect parameters during execution
• Protocol Evolution: Shows official MCP elicitation working alongside existing parameter guidance
• Universal Compatibility: Single implementation works across all MCP client capabilities
• User Experience: Progressive enhancement from error messages to interactive forms
• Hybrid Architecture: Best of both worlds - standardized elicitation + universal fallbacks

🏗️ Complete MCP Implementation

This server demonstrates all four MCP capabilities working together:

✅ Resources (Static Data)

• config: Application configuration and settings
• sample-data: User profiles and preferences
• readme: Project documentation

✅ Tools (Interactive Functions)

• Weather Tools: Current conditions, forecasts, location lookup
• Analysis Tools: Text analysis, calculations, data processing
• Elicitation Tools: Interactive parameter collection testing

✅ Prompts (Workflow Templates)

• Weather Report Generator: Multi-step personalized reports
• Code Review: Structured review checklists
• Documentation Writer: Comprehensive documentation generation

✅ Elicitation (Interactive Parameter Collection)

• Official MCP Elicitation: JSON schema-driven interactive forms
• Parameter Guidance: Universal compatibility with rich contextual help
• Hybrid Implementation: Automatic fallback for maximum compatibility

🔀 Transport Protocols Explained

STDIO Transport (Local)

• Use case: Direct integration with Claude Desktop
• How it works: Process-to-process communication
• Advantages: Low latency, secure, no network overhead
• Configuration: Claude Desktop config file

SSE Transport (Azure/Web)

• Use case: Web-based MCP clients, cloud deployments
• How it works: HTTP Server-Sent Events
• Advantages: Works through firewalls, web-compatible, scalable
• Configuration: HTTP endpoint URL

🧪 Testing Your Deployment

Local Testing (STDIO):

# Test basic functionality
npm run test:advanced-concept

# Test with Claude Desktop
# 1. Configure Claude Desktop (see above)
# 2. In Claude: "What's the weather in Tokyo?"
# 3. In Claude: "Test the elicitation tool"

Azure Testing (SSE):

# Health check
curl https://your-app-name.azurewebsites.net/sse

# Test MCP capabilities
curl -X POST https://your-app-name.azurewebsites.net/messages \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test", "version": "1.0.0"}}}'

🔧 Environment Variables

Local Development:

NODE_ENV=development
TRANSPORT=stdio

Azure Production:

NODE_ENV=production
TRANSPORT=sse
PORT=3001
WEBSITE_NODE_DEFAULT_VERSION=18-lts
SCM_DO_BUILD_DURING_DEPLOYMENT=true

🎯 Production Considerations

Security:

• HTTPS enforced on Azure deployment
• CORS configured for web access
• No sensitive data in logs

Performance:

• B1 App Service Plan suitable for moderate usage
• Auto-scaling available if needed
• Always-on connections for SSE

Monitoring:

• Application Insights integration available
• Health check endpoint: /sse
• Log streaming through Azure portal

Cost Optimization:

• B1 tier: ~$13/month base cost
• No additional charges for MCP requests
• Scale up/down as needed

🎮 VS Code Integration

🔬 What Makes This Special

For Undergraduates: Interactive AI Tools

Instead of rigid forms, AI tools can collect information naturally during conversation - like asking for your location when you ask about weather, or your email subject when sending messages.

For Graduate Students: Dual-Mode Parameter Collection

Implements two complementary approaches: official MCP elicitation for rich interactive forms in supporting clients, plus universal parameter guidance that works with any MCP client through intelligent error handling and prompts.

For PhD Researchers: Hybrid Protocol Architecture

Demonstrates progressive enhancement in structured protocols - tools automatically detect client capabilities and provide optimal user experience (interactive forms) while maintaining universal compatibility (guidance fallbacks). Shows how to evolve protocols without breaking existing implementations.

🧪 Research Applications

• Interactive AI Workflows: How tools can seamlessly collect parameters during execution
• Protocol Enhancement: Extending MCP with progressive capabilities while maintaining compatibility
• User Experience Design: From error messages to interactive forms to natural conversation
• Client-Server Architecture: Capability detection and graceful degradation patterns
• Hybrid System Design: Combining standardized protocols with intelligent behaviors

🎯 Project Status

✅ Complete MCP implementation with all four capabilities (resources, tools, prompts, elicitation)
✅ Interactive workflow tools that collect parameters during execution
✅ Hybrid compatibility - works with elicitation-capable AND standard clients
✅ Comprehensive testing suite demonstrating interactive workflows
✅ Claude Desktop integration with natural language usage
✅ Learning-focused server architecture for education and experimentation
✅ MIT Licensed - Open source and ready for contributions

Built on MCP SDK 1.7.0 and demonstrates interactive AI tool capabilities for learning purposes.

🔧 Configuration Guide

📱 Local Development Setup

For Claude Desktop Integration (Recommended for development):

1. Build the project:

   npm install
   npm run build
   

2. Configure Claude Desktop:

   Windows: Edit %APPDATA%\Claude\claude_desktop_config.json
   macOS: Edit ~/Library/Application Support/Claude/claude_desktop_config.json
   Linux: Edit ~/.config/Claude/claude_desktop_config.json

   {
     "mcpServers": {
       "vaali": {
         "command": "node",
         "args": ["C:/absolute/path/to/vaali/lib/src/index.js", "stdio"],
         "cwd": "C:/absolute/path/to/vaali",
         "env": {
           "NODE_ENV": "development"
         }
       }
     }
   }
   

3. Test the connection:

   • Restart Claude Desktop
   • Try: "What tools do you have available?"
   • Try: "Test the elicitation tool for rain prediction"

For Local SSE Testing:

# Start server in SSE mode
npm run start:sse

# Test connection
curl http://localhost:3001/sse

☁️ Azure Production Setup

After deploying to Azure, your server will be available at:

• Main URL: https://vaali-mcp-server.azurewebsites.net
• SSE Endpoint: https://vaali-mcp-server.azurewebsites.net/sse

For MCP clients that support SSE transport:

// Example: Connecting to Azure-deployed Vaali server
const { SSEClientTransport } = require('@modelcontextprotocol/sdk/client/sse.js');
const { Client } = require('@modelcontextprotocol/sdk/client/index.js');

const client = new Client(
  {
    name: "vaali-client",
    version: "1.0.0"
  },
  {
    capabilities: {}
  }
);

const transport = new SSEClientTransport(
  new URL('https://your-app-name.azurewebsites.net/sse')
);

await client.connect(transport);

For web applications:

<!-- Direct SSE connection from browser -->
<script>
const eventSource = new EventSource('https://your-app-name.azurewebsites.net/sse');
eventSource.onmessage = function(event) {
  console.log('MCP Message:', event.data);
};
</script>

🤝 Contributing

Contributions are welcome! This project demonstrates advanced MCP patterns and is perfect for:

• Researchers: Extending elicitation patterns and protocol research
• Developers: Adding new tools and improving client compatibility
• Students: Learning about interactive AI workflows and protocol design

Development Setup

# Development mode with hot reload
npm run dev:stdio

# Run tests continuously
npm run test:watch

# Debug with VS Code
Press F5 → Select debug configuration

Areas for Contribution

• Additional elicitation patterns and examples
• New interactive tools demonstrating parameter collection
• Client compatibility testing and improvements
• Documentation and educational content
• Performance optimizations and error handling

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

💡 Usage Tip

Want to understand how interactive workflows transform AI interactions? Run npm run test:advanced-concept for an educational walkthrough!