Ultimate

🧠 Ultimate MCP Server

---

🤖 What is Ultimate MCP Server?

Ultimate MCP Server is a comprehensive MCP-native system that serves as a complete AI agent operating system. It exposes dozens of powerful capabilities through the Model Context Protocol, enabling advanced AI agents to access a rich ecosystem of tools, cognitive systems, and specialized services.

While it includes intelligent task delegation from sophisticated models (e.g., Claude 3.7 Sonnet) to cost-effective ones (e.g., Gemini Flash 2.0 Lite), this is just one facet of its extensive functionality. The server provides unified access to multiple LLM providers while optimizing for cost, performance, and quality.

The system offers integrated cognitive memory systems, browser automation, Excel manipulation, database interactions, document processing, command-line utilities, dynamic API integration, OCR capabilities, vector operations, entity relation graphs, SQL database interactions, audio transcription, and much more. These capabilities transform an AI agent from a conversational interface into a powerful autonomous system capable of complex, multi-step operations across digital environments.

---## 🎯 Vision: The Complete AI Agent Operating System

At its core, Ultimate MCP Server represents a fundamental shift in how AI agents operate in digital environments. It serves as a comprehensive operating system for AI, providing:

• 🧠 A unified cognitive architecture that enables persistent memory, reasoning, and contextual awareness
• ⚙️ Seamless access to dozens of specialized tools spanning web browsing, document processing, data analysis, and more
• 💻 Direct system-level capabilities for filesystem operations, database interactions, and command-line utilities
• 🔄 Dynamic workflow capabilities for complex multi-step task orchestration and execution
• 🌐 Intelligent integration of various LLM providers with cost, quality, and performance optimization
• 🚀 Advanced vector operations, knowledge graphs, and retrieval-augmented generation for enhanced AI capabilities

This approach mirrors how sophisticated operating systems provide applications with access to hardware, services, and resources - but designed specifically for augmenting AI agents with powerful new capabilities beyond their native abilities.

---

🔌 MCP-Native Architecture

The server is built entirely on the Model Context Protocol (MCP), making it specifically designed to work with AI agents like Claude. All functionality is exposed through standardized MCP tools that can be directly called by these agents, creating a seamless integration layer between AI agents and a comprehensive ecosystem of capabilities, services, and external systems.

---

🧬 Core Use Cases: AI Agent Augmentation and Ecosystem

The Ultimate MCP Server transforms AI agents like Claude 3.7 Sonnet into autonomous systems capable of sophisticated operations across digital environments:

                        interacts with
┌─────────────┐ ────────────────────────► ┌───────────────────┐         ┌──────────────┐
│ Claude 3.7  │                           │   Ultimate MCP     │ ───────►│ LLM Providers│
│   (Agent)   │ ◄──────────────────────── │     Server        │ ◄───────│ External     │
└─────────────┘      returns results      └───────────────────┘         │ Systems      │
                                                │                        └──────────────┘
                                                ▼
                      ┌─────────────────────────────────────────────┐
                      │ Cognitive Memory Systems                    │
                      │ Web & Data: Browser, DB, RAG, Vector Search │
                      │ Documents: Excel, OCR, PDF, Filesystem      │
                      │ Analysis: Entity Graphs, Classification     │
                      │ Integration: APIs, CLI, Audio, Multimedia   │
                      └─────────────────────────────────────────────┘

Example workflow:

1. An AI agent receives a complex task requiring multiple capabilities beyond its native abilities
2. The agent uses the Ultimate MCP Server to access specialized tools and services as needed
3. The agent can leverage the cognitive memory system to maintain state and context across operations
4. Complex tasks like research, data analysis, document creation, and multimedia processing become possible
5. The agent can orchestrate multi-step workflows combining various tools in sophisticated sequences
6. Results are returned in standard MCP format, enabling the agent to understand and work with them
7. One important benefit is cost optimization through delegating appropriate tasks to more efficient models

This integration unlocks transformative capabilities that enable AI agents to autonomously complete complex projects while intelligently utilizing resources - including potentially saving 70-90% on API costs by using specialized tools and cost-effective models where appropriate.

---

💡 Why Use Ultimate MCP Server?

🧰 Comprehensive AI Agent Toolkit

A unified hub enabling advanced AI agents to access an extensive ecosystem of tools:

• 🌐 Perform complex web automation tasks (Playwright integration).
• 📊 Manipulate and analyze Excel spreadsheets with deep integration.
• 🧠 Access rich cognitive memory systems for persistent agent state.
• 💾 Interact securely with the filesystem.
• 🗄️ Interact with databases through SQL operations.
• 🖼️ Process documents with OCR capabilities.
• 🔍 Perform sophisticated vector search and RAG operations.
• 🏷️ Utilize specialized text processing and classification.
• ⌨️ Leverage command-line tools like ripgrep, awk, sed, jq.
• 🔌 Dynamically integrate external REST APIs.
• ✨ Use meta tools for self-discovery, optimization, and documentation refinement.

💵 Cost Optimization

API costs for advanced models can be substantial. Ultimate MCP Server helps reduce costs by:

• 📉 Routing appropriate tasks to cheaper models (e.g., $0.01/1K tokens vs $0.15/1K tokens).
• ⚡ Implementing advanced caching (exact, semantic, task-aware) to avoid redundant API calls.
• 💰 Tracking and optimizing costs across providers.
• 🧭 Enabling cost-aware task routing decisions.
• 🛠️ Handling routine processing with specialized non-LLM tools (filesystem, CLI utils, etc.).

🌐 Provider Abstraction

Avoid provider lock-in with a unified interface:

• 🔗 Standard API for OpenAI, Anthropic (Claude), Google (Gemini), xAI (Grok), DeepSeek, OpenRouter, and local OpenAI-compatible servers (Ollama, llama.cpp, mistral.rs, vLLM, LM Studio).
• 🏠 Free local inference: a single configurable local provider talks to any OpenAI-compatible local server via base_url, and is accounted at $0 cost so the cost optimizer prefers it for delegated work.
• ⚙️ Consistent parameter handling and response formatting.
• 🔄 Ability to swap providers without changing application code.
• 🛡️ Protection against provider-specific outages and limitations through fallback mechanisms.

📑 Comprehensive Document and Data Processing

Process documents and data efficiently:

• ✂️ Break documents into semantically meaningful chunks.
• 🚀 Process chunks in parallel across multiple models.
• 📊 Extract structured data (JSON, tables, key-value) from unstructured text.
• ✍️ Generate summaries and insights from large texts.
• 🔁 Convert formats (HTML to Markdown, documents to structured data).
• 👁️ Apply OCR to images and PDFs with optional LLM enhancement.

---

🚀 Key Features

🔌 MCP Protocol Integration

• Native MCP Server: Built on the Model Context Protocol for seamless AI agent integration.
• MCP Tool Framework: All functionality exposed through standardized MCP tools with clear schemas.
• Tool Composition: Tools can be combined in workflows using dependencies.
• Tool Discovery: Supports dynamic listing and capability discovery for agents.

🤖 Intelligent Task Delegation

• Task Routing: Analyzes tasks and routes to appropriate models or specialized tools.
• Provider Selection: Chooses provider/model based on task requirements, cost, quality, or speed preferences.
• Cost-Performance Balancing: Optimizes delegation strategy.
• Delegation Tracking: Monitors delegation patterns, costs, and outcomes (via Analytics).

🌍 Provider Integration

• Multi-Provider Support: First-class support for OpenAI, Anthropic, Google, DeepSeek, xAI (Grok), OpenRouter, and local OpenAI-compatible servers (Ollama, llama.cpp, mistral.rs, vLLM, LM Studio) via a single configurable local provider. Extensible architecture.
• Free Local Inference: The local provider is cost-accounted at $0, so the intelligent delegation / cost-optimization layer will route cost-sensitive work (summarization, extraction, simple Q&A, formatting) to your own hardware when a capable local model is configured.
• Model Management: Handles different model capabilities, context windows, and pricing. Automatic selection and fallback mechanisms.

💾 Advanced Caching

• Multi-level Caching: Exact match, semantic similarity, and task-aware strategies.
• Persistent Cache: Disk-based persistence (e.g., DiskCache) with fast in-memory access layer.
• Cache Analytics: Tracks cache hit rates, estimated cost savings.

📄 Document Tools

• Smart Chunking: Token-based, semantic boundary detection, structural analysis methods. Configurable overlap.
• Document Operations: Summarization (paragraph, bullets), entity extraction, question generation, batch processing.

📁 Secure Filesystem Operations

• Path Management: Robust validation, normalization, symlink security checks, configurable allowed directories.
• File Operations: Read/write with encoding handling, smart text editing/replacement, metadata retrieval.
• Directory Operations: Creation, listing, tree visualization, secure move/copy.
• Search Capabilities: Recursive search with pattern matching and filtering.
• Security Focus: Designed to prevent directory traversal and enforce boundaries.

✨ Autonomous Tool Documentation Refiner

• Automated Improvement: Systematically analyzes, tests, and refines MCP tool documentation (docstrings, schemas, examples).
• Agent Simulation: Identifies ambiguities from an LLM agent's perspective.
• Adaptive Testing: Generates and executes schema-aware test cases.
• Failure Analysis: Uses LLM ensembles to diagnose documentation weaknesses.
• Iterative Refinement: Continuously improves documentation quality.
• (See dedicated section for more details)

🌐 Browser Automation with Playwright

• Full Control: Navigate, click, type, scrape data, screenshots, PDFs, file up/download, JS execution.
• Research: Automate searches across engines, extract structured data, monitor sites.
• Synthesis: Combine findings from multiple web sources into reports.

🧠 Cognitive & Agent Memory System

• Memory Hierarchy: Working, episodic, semantic, procedural levels.
• Knowledge Management: Store/retrieve memories with metadata, relationships, importance tracking.
• Workflow Tracking: Record agent actions, reasoning chains, artifacts, dependencies.
• Smart Operations: Memory consolidation, reflection generation, relevance-based optimization, decay.

📊 Excel Spreadsheet Automation

• Direct Manipulation: Create, modify, format Excel files via natural language or structured instructions. Analyze formulas.
• Template Learning: Learn from examples, adapt templates, apply formatting patterns.
• VBA Macro Generation: Generate VBA code from instructions for complex automation.

🏗️ Structured Data Extraction

• JSON Extraction: Extract structured JSON with schema validation.
• Table Extraction: Extract tables in multiple formats (JSON, CSV, Markdown).
• Key-Value Extraction: Simple K/V pair extraction.
• Semantic Schema Inference: Attempt to generate schemas from text.

⚔️ Tournament Mode

• Model Competitions: Run head-to-head comparisons for code or text generation tasks.
• Multi-Model Evaluation: Compare outputs from different models/providers simultaneously.
• Performance Metrics: Evaluate correctness, efficiency, style, etc. Persist results.

🗄️ SQL Database Interactions

• Query Execution: Run SQL queries against various DB types (SQLite, PostgreSQL, etc. via SQLAlchemy).
• Schema Analysis: Analyze schemas, suggest optimizations (using LLM).
• Data Exploration: Browse tables, visualize contents.
• Query Generation: Generate SQL from natural language descriptions.

🔗 Entity Relation Graphs

• Entity Extraction: Identify entities (people, orgs, locations, etc.).
• Relationship Mapping: Discover and map connections between entities.
• Knowledge Graph Construction: Build persistent graphs (e.g., using NetworkX).
• Graph Querying: Extract insights using graph traversal or LLM-based queries.

🔎 Advanced Vector Operations

• Semantic Search: Find similar content using vector embeddings.
• Vector Storage Integration: Interfaces with vector databases or local stores.
• Hybrid Search: Combines keyword and semantic search (e.g., via Marqo integration).
• Batched Processing: Efficient embedding generation and searching for large datasets.

📚 Retrieval-Augmented Generation (RAG)

• Contextual Generation: Augments prompts with relevant retrieved documents/chunks.
• Accuracy Improvement: Reduces hallucinations by grounding responses in provided context.
• Workflow Integration: Seamlessly combines retrieval (vector/keyword search) with generation. Customizable strategies.

🎙️ Audio Transcription

• Speech-to-Text: Convert audio files (e.g., WAV, MP3) to text using models like Whisper.
• Speaker Diarization: Identify different speakers (if supported by the model/library).
• Transcript Enhancement: Clean and format transcripts using LLMs.
• Multi-language Support: Handles various languages based on the underlying transcription model.

🏷️ Text Classification

• Custom Classifiers: Apply text classification models (potentially fine-tuned or using zero-shot LLMs).
• Multi-label Classification: Assign multiple categories.
• Confidence Scoring: Provide probabilities for classifications.
• Batch Processing: Classify large document sets efficiently.

👁️ OCR Tools

• PDF/Image Extraction: Uses Tesseract or other OCR engines, enhanced with LLM correction/formatting.
• Preprocessing: Image denoising, thresholding, deskewing options.
• Structure Analysis: Extracts PDF metadata and structure.
• Batch Processing: Handles multiple files concurrently.
• (Requires ocr extra dependencies: uv pip install -e ".[ocr]")

📝 Text Redline Tools

• HTML Redline Generation: Visual diffs (insertions, deletions, moves) between text/HTML. Standalone HTML output.
• Document Comparison: Compares various formats with intuitive highlighting.

🔄 HTML to Markdown Conversion

• Intelligent Conversion: Detects content type, uses libraries like readability-lxml, trafilatura, markdownify.
• Content Extraction: Filters boilerplate, preserves structure (tables, links).
• Markdown Optimization: Cleans and normalizes output.

📈 Workflow Optimization Tools

• Cost Estimation/Comparison: Pre-execution cost estimates, model cost comparisons.
• Model Selection Guidance: Recommends models based on task, budget, performance needs.
• Workflow Execution Engine: Runs multi-stage pipelines with dependencies, parallel execution, variable passing.

💻 Local Text Processing Tools (CLI Integration)

• Offline Power: Securely wrap and expose command-line tools like ripgrep (fast regex search), awk (text processing), sed (stream editor), jq (JSON processing) as MCP tools. Process text locally without API calls.

⏱️ Model Performance Benchmarking

• Empirical Measurement: Tools to measure actual speed (tokens/sec), latency across providers/models.
• Performance Profiles: Generate comparative reports based on real-world performance.
• Data-Driven Optimization: Use benchmark data to inform routing decisions.

📡 Multiple Transport Modes

• Streamable-HTTP (Recommended): Modern HTTP transport with streaming request/response bodies, optimal for HTTP-based MCP clients.
• Server-Sent Events (SSE): Legacy HTTP transport using server-sent events for real-time streaming.
• Standard I/O (stdio): Direct process communication for embedded integrations.
• Real-time Streaming: Token-by-token updates for LLM completions across all HTTP transports.
• Progress Monitoring: Track progress of long-running jobs (chunking, batch processing).
• Event-Based Architecture: Subscribe to specific server events.

✨ Multi-Model Synthesis

• Comparative Analysis: Analyze outputs from multiple models side-by-side.
• Response Synthesis: Combine best elements, generate meta-responses, create consensus outputs.
• Collaborative Reasoning: Implement workflows where different models handle different steps.

🧩 Extended Model Support

• Grok Integration: Native support for xAI's Grok.
• DeepSeek Support: Optimized handling for DeepSeek models.
• OpenRouter Integration: Access a wide variety via OpenRouter API key.
• Local / Self-Hosted Integration: A single configurable local provider for any OpenAI-compatible local server — Ollama, llama.cpp's llama-server, mistral.rs, vLLM, and LM Studio — point it at a base_url and run free ($0-cost) inference on your own hardware.
• Gemini Integration: Comprehensive support for Google's Gemini models.
• Anthropic Integration: Full support for Claude models including Claude 3.5 Sonnet and Haiku.
• OpenAI Integration: Complete support for GPT-3.5, GPT-4.0, and newer models.

🔧 Meta Tools for Self-Improvement & Dynamic Integration

• Tool Discovery: Agents can query available tools, parameters, descriptions (list_tools).
• Usage Recommendations: Get AI-driven advice on tool selection/combination for tasks.
• External API Integration: Dynamically register REST APIs via OpenAPI specs, making endpoints available as callable MCP tools (register_api, call_dynamic_tool).
• Documentation Generation: Part of the Autonomous Refiner feature.

📊 Analytics and Reporting

• Usage Tracking: Monitors tokens, costs, requests, success/error rates per provider/model/tool.
• Real-Time Monitoring: Live dashboard or stream of usage stats.
• Detailed Reporting: Generate historical cost/usage reports, identify trends, export data.
• Optimization Insights: Helps identify expensive operations or inefficient patterns.

📜 Prompt Templates and Management

• Jinja2 Templates: Create reusable, dynamic prompts with variables, conditionals, includes.
• Prompt Repository: Store, retrieve, categorize, and version control prompts.
• Metadata: Add descriptions, authorship, usage examples to templates.
• Optimization: Test and compare template performance and token usage.

🛡️ Error Handling and Resilience

• Intelligent Retries: Automatic retries with exponential backoff for transient errors (rate limits, network issues).
• Fallback Mechanisms: Configurable provider fallbacks on primary failure.
• Detailed Error Reporting: Captures comprehensive error context for debugging.
• Input Validation: Pre-flight checks for common issues (e.g., token limits, required parameters).

⚙️ System Features

• Rich Logging: Colorful, informative console logs via Rich.
• Health Monitoring: /healthz endpoint for readiness checks.
• Command-Line Interface: umcp CLI for management and interaction.

---

📦 Getting Started

🧪 Install

# Install uv (fast Python package manager) if you don't have it:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Clone the repository
git clone https://github.com/Dicklesworthstone/ultimate_mcp_server.git
cd ultimate_mcp_server

# Create a virtual environment and install dependencies using uv:
uv venv --python 3.13
source .venv/bin/activate
uv lock --upgrade
uv sync --all-extras

Note: The uv sync --all-extras command installs all optional extras defined in the project (e.g., OCR, Browser Automation, Excel). If you only need specific extras, adjust your project dependencies and run uv sync without --all-extras.

⚙️ .env Configuration

Create a file named .env in the root directory of the cloned repository. Add your API keys and any desired configuration overrides:

# --- API Keys (at least one provider required) ---
OPENAI_API_KEY=your_openai_sk-...
ANTHROPIC_API_KEY=your_anthropic_sk-...
GEMINI_API_KEY=your_google_ai_studio_key... # For Google AI Studio (Gemini API)
# Or use GOOGLE_APPLICATION_CREDENTIALS=/path/to/your/service-account-key.json for Vertex AI
DEEPSEEK_API_KEY=your_deepseek_key...
OPENROUTER_API_KEY=your_openrouter_key...
GROK_API_KEY=your_grok_key... # For Grok via xAI API

# --- Local / Self-Hosted Providers (OpenAI-compatible, FREE inference) ---
# One generic provider covers Ollama, llama.cpp (llama-server), mistral.rs, vLLM, and LM Studio.
# No API key is required by most local servers; LOCAL_LLM_API_KEY is optional.
# LOCAL_LLM_BASE_URL=http://localhost:11434/v1   # Default (Ollama). Examples:
#   llama.cpp / mistral.rs / vLLM : http://localhost:8000/v1
#   LM Studio                     : http://localhost:1234/v1
# LOCAL_LLM_DEFAULT_MODEL=llama3.1:8b            # Model name as served by your local backend
# LOCAL_LLM_API_KEY=                             # Optional; most local servers ignore it
# LOCAL_LLM_REQUEST_TIMEOUT=30                   # Optional request timeout in seconds
# LOCAL_LLM_ENABLED=true                         # Optional; set false to disable the local provider

# --- Server Configuration (Defaults shown) ---
GATEWAY_SERVER_PORT=8013
GATEWAY_SERVER_HOST=127.0.0.1 # Change to 0.0.0.0 to listen on all interfaces (needed for Docker/external access)
# GATEWAY_API_PREFIX=/

# --- Logging Configuration (Defaults shown) ---
LOG_LEVEL=INFO # DEBUG, INFO, WARNING, ERROR, CRITICAL
USE_RICH_LOGGING=true # Set to false for plain text logs

# --- Cache Configuration (Defaults shown) ---
GATEWAY_CACHE_ENABLED=true
GATEWAY_CACHE_TTL=86400 # Default Time-To-Live in seconds (24 hours)
# GATEWAY_CACHE_TYPE=memory # Options might include 'memory', 'redis', 'diskcache' (check implementation)
# GATEWAY_CACHE_MAX_SIZE=1000 # Example: Max number of items for memory cache
# GATEWAY_CACHE_DIR=./.cache # Directory for disk cache storage

# --- Provider Timeouts & Retries (Defaults shown) ---
# GATEWAY_PROVIDER_TIMEOUT=120 # Default timeout in seconds for API calls
# GATEWAY_PROVIDER_MAX_RETRIES=3 # Default max retries on failure

# --- Provider-Specific Configuration ---
# GATEWAY_OPENAI_DEFAULT_MODEL=gpt-4.1-mini # Customize default model
# GATEWAY_ANTHROPIC_DEFAULT_MODEL=claude-3-5-sonnet-20241022 # Customize default model
# GATEWAY_GEMINI_DEFAULT_MODEL=gemini-2.0-pro # Customize default model

# --- Tool Specific Config (Examples) ---
# FILESYSTEM__ALLOWED_DIRECTORIES=["/path/to/safe/dir1","/path/to/safe/dir2"] # For Filesystem tools (JSON array)
# GATEWAY_AGENT_MEMORY_DB_PATH=unified_agent_memory.db # Path for agent memory database
# GATEWAY_PROMPT_TEMPLATES_DIR=./prompt_templates # Directory for prompt templates

▶️ Run

Make sure your virtual environment is active (source .venv/bin/activate).

# Start the MCP server with all registered tools found
umcp run

# Start the server including only specific tools
umcp run --include-tools completion chunk_document read_file write_file

# Start the server excluding specific tools
umcp run --exclude-tools browser_init browser_navigate research_and_synthesize_report

# Start with Docker (ensure .env file exists in the project root or pass environment variables)
docker compose up --build # Add --build the first time or after changes

Once running, the server will typically be available at http://localhost:8013 (or the host/port configured in your .env or command line). You should see log output indicating the server has started and which tools are registered.

💻 Command Line Interface (CLI)

The Ultimate MCP Server provides a powerful command-line interface (CLI) through the umcp command that allows you to manage the server, interact with LLM providers, test features, and explore examples. This section details all available commands and their options.

🌟 Global Options

The umcp command supports the following global option:

umcp --version  # Display version information

🚀 Server Management

Starting the Server

The run command starts the Ultimate MCP Server with specified options:

# Basic server start with default settings from .env
umcp run

# Run on a specific host (-h) and port (-p)
umcp run -h 0.0.0.0 -p 9000

# Run with multiple worker processes (-w)
umcp run -w 4

# Enable debug logging (-d)
umcp run -d

# Use stdio transport (-t)
umcp run -t stdio

# Use streamable-http transport (recommended for HTTP clients)
umcp run -t shttp

# Run only with specific tools (no shortcut for --include-tools)
umcp run --include-tools completion chunk_document read_file write_file

# Run with all tools except certain ones (no shortcut for --exclude-tools)
umcp run --exclude-tools browser_init browser_navigate

Example output:

┌─ Starting Ultimate MCP Server ───────────────────┐
│ Host: 0.0.0.0                                    │
│ Port: 9000                                       │
│ Workers: 4                                       │
│ Transport mode: streamable-http                  │
└────────────────────────────────────────────────┘

INFO:     Started server process [12345]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:9000 (Press CTRL+C to quit)

Available options:

• -h, --host: Host or IP address to bind the server to (default: from .env)
• -p, --port: Port to listen on (default: from .env)
• -w, --workers: Number of worker processes to spawn (default: from .env)
• -t, --transport-mode: Transport mode for server communication ('shttp' for streamable-http, 'sse', or 'stdio', default: shttp)
• -d, --debug: Enable debug logging
• --include-tools: List of tool names to include (comma-separated)
• --exclude-tools: List of tool names to exclude (comma-separated)

🔌 Provider Management

Listing Providers

The providers command displays information about configured LLM providers:

# List all configured providers
umcp providers

# Check API keys (-c) for all configured providers
umcp providers -c

# List available models (no shortcut for --models)
umcp providers --models

# Check keys and list models
umcp providers -c --models

Example output:

┌─ LLM Providers ──────────────────────────────────────────────────┐
│ Provider   Status   Default Model            API Key             │
├───────────────────────────────────────────────────────────────────┤
│ openai     ✓        gpt-4.1-mini            sk-...5vX [VALID]    │
│ anthropic  ✓        claude-3-5-sonnet-20241022 sk-...Hr [VALID]  │
│ gemini     ✓        gemini-2.0-pro          [VALID]              │
│ deepseek   ✗        deepseek-chat           [NOT CONFIGURED]     │
│ openrouter ✓        --                      [VALID]              │
│ grok       ✓        grok-1                  [VALID]              │
└───────────────────────────────────────────────────────────────────┘

With --models:

OPENAI MODELS:
  - gpt-4.1-mini
  - gpt-4o
  - gpt-4-0125-preview
  - gpt-3.5-turbo

ANTHROPIC MODELS:
  - claude-3-5-sonnet-20241022
  - claude-3-5-haiku-20241022
  - claude-3-opus-20240229
  ...

Available options:

• -c, --check: Check API keys for all configured providers
• --models: List available models for each provider

Testing a Provider

The test command allows you to test a specific provider:

# Test the default OpenAI model with a simple prompt
umcp test openai

# Test a specific model (--model) with a custom prompt (--prompt)
umcp test anthropic --model claude-3-5-haiku-20241022 --prompt "Write a short poem about coding."

# Test Gemini with a different prompt
umcp test gemini --prompt "What are three interesting AI research papers from 2024?"

Example output:

Testing provider 'anthropic'...

Provider: anthropic
Model: claude-3-5-haiku-20241022
Prompt: Write a short poem about coding.

❯ Response:
Code flows like water,
Logic cascades through the mind—
Bugs bloom like flowers.

Tokens: 13 input, 19 output
Cost: $0.00006
Response time: 0.82s

Available options:

• --model: Model ID to test (defaults to the provider's default)
• --prompt: Prompt text to send (default: "Hello, world!")

⚡ Direct Text Generation

The complete command lets you generate text directly from the CLI:

# Generate text with default provider (OpenAI) using a prompt (--prompt)
umcp complete --prompt "Write a concise explanation of quantum computing."

# Specify a provider (--provider) and model (--model)
umcp complete --provider anthropic --model claude-3-5-sonnet-20241022 --prompt "What are the key differences between Rust and Go?"

# Use a system prompt (--system)
umcp complete --provider openai --model gpt-4o --system "You are an expert programmer..." --prompt "Explain dependency injection."

# Stream the response token by token (-s)
umcp complete --provider openai --prompt "Count from 1 to 10." -s

# Adjust temperature (--temperature) and token limit (--max-tokens)
umcp complete --provider gemini --temperature 1.2 --max-tokens 250 --prompt "Generate a creative sci-fi story opening."

# Read prompt from stdin (no --prompt needed)
echo "Tell me about space exploration." | umcp complete

Example output:

Quantum computing uses quantum bits (qubits) that can exist in multiple states simultaneously, unlike classical bits (0 or 1). This quantum superposition, along with entanglement, allows quantum computers to process vast amounts of information in parallel, potentially solving certain complex problems exponentially faster than classical computers. Applications include cryptography, materials science, and optimization problems.

Tokens: 13 input, 72 output
Cost: $0.00006
Response time: 0.37s

Available options:

• --provider: Provider to use (default: openai)
• --model: Model ID (defaults to provider's default)
• --prompt: Prompt text (reads from stdin if not provided)
• --temperature: Sampling temperature (0.0-2.0, default: 0.7)
• --max-tokens: Maximum tokens to generate
• --system: System prompt for providers that support it
• -s, --stream: Stream the response token by token

💾 Cache Management

The cache command allows you to view or clear the request cache:

# Show cache status (default action)
umcp cache

# Explicitly show status (no shortcut for --status)
umcp cache --status

# Clear the cache (no shortcut for --clear, with confirmation prompt)
umcp cache --clear

# Show stats and clear the cache in one command
umcp cache --status --clear

Example output:

Cache Status:
  Backend: memory
  Enabled: True
  Items: 127
  Hit rate: 73.2%
  Estimated savings: $1.47

Available options:

• --status: Show cache status (enabled by default if no other flag)
• --clear: Clear the cache (will prompt for confirmation)

📊 Benchmarking

The benchmark command lets you compare performance and cost across providers:

# Run default benchmark (3 runs per provider)
umcp benchmark

# Benchmark only specific providers
umcp benchmark --providers openai,anthropic

# Benchmark with specific models
umcp benchmark --providers openai,anthropic --models gpt-4o,claude-3.5-sonnet

# Use a custom prompt and more runs (-r)
umcp benchmark --prompt "Explain the process of photosynthesis in detail." -r 5

Example output:

┌─ Benchmark Results ───────────────────────────────────────────────────────┐
│ Provider    Model               Avg Time   Tokens    Cost      Tokens/sec │
├──────────────────────────────────────────────────────────────────────────┤
│ openai      gpt-4.1-mini        0.47s      76 / 213  $0.00023  454        │
│ anthropic   claude-3-5-haiku    0.52s      76 / 186  $0.00012  358        │
│ gemini      gemini-2.0-pro      0.64s      76 / 201  $0.00010  314        │
│ deepseek    deepseek-chat       0.71s      76 / 195  $0.00006  275        │
└──────────────────────────────────────────────────────────────────────────┘

Available options:

• --providers: List of providers to benchmark (default: all configured)
• --models: Model IDs to benchmark (defaults to default model of each provider)
• --prompt: Prompt text to use (default: built-in benchmark prompt)
• -r, --runs: Number of runs per provider/model (default: 3)

🧰 Tool Management

The tools command lists available tools, optionally filtered by category:

# List all tools
umcp tools

# List tools in a specific category
umcp tools --category document

# Show related example scripts
umcp tools --examples

Example output:

┌─ Ultimate MCP Server Tools ─────────────────────────────────────────┐
│ Category    Tool                           Example Script            │
├──────────────────────────────────────────────────────────────────────┤
│ completion  generate_completion            simple_completion_demo.py │
│ completion  stream_completion              simple_completion_demo.py │
│ completion  chat_completion                claude_integration_demo.py│
│ document    summarize_document             document_processing.py    │
│ document    chunk_document                 document_processing.py    │
│ extraction  extract_json                   advanced_extraction_demo.py│
│ filesystem  read_file                      filesystem_operations_demo.py│
└──────────────────────────────────────────────────────────────────────┘

Tip: Run examples using the command:
  umcp examples <example_name>

Available options:

• --category: Filter tools by category
• --examples: Show example scripts alongside tools

📚 Example Management

The examples command lets you list and run example scripts:

# List all example scripts (default action)
umcp examples

# Explicitly list example scripts (-l)
umcp examples -l

# Run a specific example
umcp examples rag_example.py

# Can also run by just the name without extension
umcp examples rag_example

Example output when listing:

┌─ Ultimate MCP Server Example Scripts ─────────────────────────────────┐
│ Category             Example Script                                   │
├────────────────────────────────────────────────────────────────────────┤
│ text-generation      simple_completion_demo.py                        │
│ text-generation      claude_integration_demo.py                       │
│ document-processing  document_processing.py                           │
│ search-and-retrieval rag_example.py                                   │
│ browser-automation   browser_automation_demo.py                       │
└────────────────────────────────────────────────────────────────────────┘

Run an example:
  umcp examples <example_name>

When running an example:

Running example: rag_example.py

Creating vector knowledge base 'demo_kb'...
Adding sample documents...
Retrieving context for query: "What are the benefits of clean energy?"
Generated response:
Based on the retrieved context, clean energy offers several benefits:
...

Available options:

• -l, --list: List example scripts only
• --category: Filter examples by category

🔎 Getting Help

Every command has detailed help available:

# General help
umcp --help

# Help for a specific command
umcp run --help
umcp providers --help
umcp complete --help

Example output:

Usage: umcp [OPTIONS] COMMAND [ARGS]...

  Ultimate MCP Server: Multi-provider LLM management server
  Unified CLI to run your server, manage providers, and more.

Options:
  --version, -v                   Show the application version and exit.
  --help                          Show this message and exit.

Commands:
  run          Run the Ultimate MCP Server
  providers    List Available Providers
  test         Test a Specific Provider
  complete     Generate Text Completion
  cache        Cache Management
  benchmark    Benchmark Providers
  tools        List Available Tools
  examples     Run or List Example Scripts

Command-specific help:

Usage: umcp run [OPTIONS]

  Run the Ultimate MCP Server

  Start the server with optional overrides.

  Examples:
    umcp run -h 0.0.0.0 -p 8000 -w 4 -t sse
    umcp run -d

Options:
  -h, --host TEXT                 Host or IP address to bind the server to.
                                  Defaults from config.
  -p, --port INTEGER              Port to listen on. Defaults from config.
  -w, --workers INTEGER           Number of worker processes to spawn.
                                  Defaults from config.
  -t, --transport-mode [shttp|sse|stdio]
                                  Transport mode for server communication (-t
                                  shortcut). Options: 'shttp' (streamable-http, 
                                  recommended), 'sse', or 'stdio'.
  -d, --debug                     Enable debug logging for detailed output (-d
                                  shortcut).
  --include-tools TEXT            List of tool names to include when running
                                  the server.
  --exclude-tools TEXT            List of tool names to exclude when running
                                  the server.
  --help                          Show this message and exit.

---

🧪 Usage Examples

This section provides Python examples demonstrating how an MCP client (like an application using mcp-client or an agent like Claude) would interact with the tools provided by a running Ultimate MCP Server instance.

Note: These examples assume you have mcp-client installed (pip install mcp-client) and the Ultimate MCP Server is running at http://localhost:8013.

(The detailed code blocks from the original input are preserved below for completeness)

Basic Completion

import asyncio
from mcp.client import Client

async def basic_completion_example():
    client = Client("http://localhost:8013")
    response = await client.tools.completion(
        prompt="Write a short poem about a robot learning to dream.",
        provider="openai",
        model="gpt-4.1-mini",
        max_tokens=100,
        temperature=0.7
    )
    if response["success"]:
        print(f"Completion: {response['completion']}")
        print(f"Cost: ${response['cost']:.6f}")
    else:
        print(f"Error: {response['error']}")
    await client.close()

# if __name__ == "__main__": asyncio.run(basic_completion_example())

Claude Using Ultimate MCP Server for Document Analysis (Delegation)

import asyncio
from mcp.client import Client

async def document_analysis_example():
    # Assume Claude identifies a large document needing processing
    client = Client("http://localhost:8013")
    document = "... large document content ..." * 100 # Placeholder for large content

    print("Delegating document chunking...")
    # Step 1: Claude delegates document chunking (often a local, non-LLM task on server)
    chunks_response = await client.tools.chunk_document(
        document=document,
        chunk_size=1000, # Target tokens per chunk
        overlap=100,     # Token overlap
        method="semantic" # Use semantic chunking if available
    )
    if not chunks_response["success"]:
        print(f"Chunking failed: {chunks_response['error']}")
        await client.close()
        return

    print(f"Document divided into {chunks_response['chunk_count']} chunks.")

    # Step 2: Claude delegates summarization of each chunk to a cheaper model
    summaries = []
    total_cost = 0.0
    print("Delegating chunk summarization to gemini-2.0-flash-lite...")
    for i, chunk in enumerate(chunks_response["chunks"]):
        # Use Gemini Flash (much cheaper than Claude or GPT-4o) via the server
        summary_response = await client.tools.summarize_document(
            document=chunk,
            provider="gemini", # Explicitly delegate to Gemini via server
            model="gemini-2.0-flash-lite",
            format="paragraph",
            max_length=150 # Request a concise summary
        )
        if summary_response["success"]:
            summaries.append(summary_response["summary"])
            cost = summary_response.get("cost", 0.0)
            total_cost += cost
            print(f"  Processed chunk {i+1}/{chunks_response['chunk_count']} summary. Cost: ${cost:.6f}")
        else:
            print(f"  Chunk {i+1} summarization failed: {summary_response['error']}")

    print("\nDelegating entity extraction to gpt-4.1-mini...")
    # Step 3: Claude delegates entity extraction for the whole document to another cheap model
    entities_response = await client.tools.extract_entities(
        document=document, # Process the original document
        entity_types=["person", "organization", "location", "date", "product"],
        provider="openai", # Delegate to OpenAI's cheaper model
        model="gpt-4.1-mini"
    )

    if entities_response["success"]:
        cost = entities_response.get("cost", 0.0)
        total_cost += cost
        print(f"Extracted entities. Cost: ${cost:.6f}")
        extracted_entities = entities_response['entities']
        # Claude would now process these summaries and entities using its advanced capabilities
        print(f"\nClaude can now use {len(summaries)} summaries and {len(extracted_entities)} entity groups.")
    else:
        print(f"Entity extraction failed: {entities_response['error']}")

    print(f"\nTotal estimated delegation cost for sub-tasks: ${total_cost:.6f}")

    # Claude might perform final synthesis using the collected results
    final_synthesis_prompt = f"""
Synthesize the key information from the following summaries and entities extracted from a large document.
Focus on the main topics, key people involved, and significant events mentioned.

Summaries:
{' '.join(summaries)}

Entities:
{extracted_entities}

Provide a concise final report.
"""
    # This final step would likely use Claude itself (not shown here)

    await client.close()

# if __name__ == "__main__": asyncio.run(document_analysis_example())

Browser Automation for Research

import asyncio
from mcp.client import Client

async def browser_research_example():
    client = Client("http://localhost:8013")
    print("Starting browser-based research task...")
    # This tool likely orchestrates multiple browser actions (search, navigate, scrape)
    # and uses an LLM (specified or default) for synthesis.
    result = await client.tools.research_and_synthesize_report(
        topic="Latest advances in AI-powered drug discovery using graph neural networks",
        instructions={
            "search_query": "graph neural networks drug discovery 2024 research",
            "search_engines": ["google", "duckduckgo"], # Use multiple search engines
            "urls_to_include": ["nature.com", "sciencemag.org", "arxiv.org", "pubmed.ncbi.nlm.nih.gov"], # Prioritize these domains
            "max_urls_to_process": 7, # Limit the number of pages to visit/scrape
            "min_content_length": 500, # Ignore pages with very little content
            "focus_areas": ["novel molecular structures", "binding affinity prediction", "clinical trial results"], # Guide the synthesis
            "report_format": "markdown", # Desired output format
            "report_length": "detailed", # comprehensive, detailed, summary
            "llm_model": "anthropic/claude-3-5-sonnet-20241022" # Specify LLM for synthesis
        }
    )

    if result["success"]:
        print("\nResearch report generated successfully!")
        print(f"Processed {len(result.get('extracted_data', []))} sources.")
        print(f"Total processing time: {result.get('processing_time', 'N/A'):.2f}s")
        print(f"Estimated cost: ${result.get('total_cost', 0.0):.6f}") # Includes LLM synthesis cost
        print("\n--- Research Report ---")
        print(result['report'])
        print("-----------------------")
    else:
        print(f"\nBrowser research failed: {result.get('error', 'Unknown error')}")
        if 'details' in result: print(f"Details: {result['details']}")

    await client.close()

# if __name__ == "__main__": asyncio.run(browser_research_example())

Cognitive Memory System Usage

import asyncio
from mcp.client import Client
import uuid

async def cognitive_memory_example():
    client = Client("http://localhost:8013")
    # Generate a unique ID for this session/workflow if not provided
    workflow_id = str(uuid.uuid4())
    print(f"Using Workflow ID: {workflow_id}")

    print("\nCreating a workflow context...")
    # Create a workflow context to group related memories and actions
    workflow_response = await client.tools.create_workflow(
        workflow_id=workflow_id,
        title="Quantum Computing Investment Analysis",
        description="Analyzing the impact of quantum computing on financial markets.",
        goal="Identify potential investment opportunities or risks."
    )
    if not workflow_response["success"]: print(f"Error creating workflow: {workflow_response['error']}")

    print("\nRecording an agent action...")
    # Record the start of a research action
    action_response = await client.tools.record_action_start(
        workflow_id=workflow_id,
        action_type="research",
        title="Initial literature review on quantum algorithms in finance",
        reasoning="Need to understand the current state-of-the-art before assessing impact."
    )
    action_id = action_response.get("action_id") if action_response["success"] else None
    if not action_id: print(f"Error starting action: {action_response['error']}")

    print("\nStoring facts in semantic memory...")
    # Store some key facts discovered during research
    memory1 = await client.tools.store_memory(
        workflow_id=workflow_id,
        content="Shor's algorithm can break RSA encryption, posing a threat to current financial security.",
        memory_type="fact", memory_level="semantic", importance=9.0,
        tags=["quantum_algorithm", "cryptography", "risk", "shor"]
    )
    memory2 = await client.tools.store_memory(
        workflow_id=workflow_id,
        content="Quantum annealing (e.g., D-Wave) shows promise for portfolio optimization problems.",
        memory_type="fact", memory_level="semantic", importance=7.5,
        tags=["quantum_computing", "finance", "optimization", "annealing"]
    )
    if memory1["success"]: print(f"Stored memory ID: {memory1['memory_id']}")
    if memory2["success"]: print(f"Stored memory ID: {memory2['memory_id']}")

    print("\nStoring an observation (episodic memory)...")
    # Store an observation from a specific event/document
    obs_memory = await client.tools.store_memory(
        workflow_id=workflow_id,
        content="Read Nature article (doi:...) suggesting experimental quantum advantage in a specific financial modeling task.",
        memory_type="observation", memory_level="episodic", importance=8.0,
        source="Nature Article XYZ", timestamp="2024-07-20T10:00:00Z", # Example timestamp
        tags=["research_finding", "publication", "finance_modeling"]
    )
    if obs_memory["success"]: print(f"Stored episodic memory ID: {obs_memory['memory_id']}")

    print("\nSearching for relevant memories...")
    # Search for memories related to financial risks
    search_results = await client.tools.hybrid_search_memories(
        workflow_id=workflow_id,
        query="What are the financial risks associated with quantum computing?",
        top_k=5, memory_type="fact", # Search for facts first
        semantic_weight=0.7, keyword_weight=0.3 # Example weighting for hybrid search
    )
    if search_results["success"]:
        print(f"Found {len(search_results['results'])} relevant memories:")
        for res in search_results["results"]:
            print(f"  - Score: {res['score']:.4f}, ID: {res['memory_id']}, Content: {res['content'][:80]}...")
    else:
        print(f"Memory search failed: {search_results['error']}")

    print("\nGenerating a reflection based on stored memories...")
    # Generate insights or reflections based on the accumulated knowledge in the workflow
    reflection_response = await client.tools.generate_reflection(
        workflow_id=workflow_id,
        reflection_type="summary_and_next_steps", # e.g., insights, risks, opportunities
        context_query="Summarize the key findings about quantum finance impact and suggest next research actions."
    )
    if reflection_response["success"]:
        print("Generated Reflection:")
        print(reflection_response["reflection"])
    else:
        print(f"Reflection generation failed: {reflection_response['error']}")

    # Mark the action as completed (assuming research phase is done)
    if action_id:
        print("\nCompleting the research action...")
        await client.tools.record_action_end(
            workflow_id=workflow_id, action_id=action_id, status="completed",
            outcome="Gathered initial understanding of quantum algorithms in finance and associated risks."
        )

    await client.close()

# if __name__ == "__main__": asyncio.run(cognitive_memory_example())

Excel Spreadsheet Automation

import asyncio
from mcp.client import Client
import os

async def excel_automation_example():
    client = Client("http://localhost:8013")
    output_dir = "excel_outputs"
    os.makedirs(output_dir, exist_ok=True)
    output_path = os.path.join(output_dir, "financial_model.xlsx")

    print(f"Requesting creation of Excel financial model at {output_path}...")
    # Example: Create a financial model using natural language instructions
    create_result = await client.tools.excel_execute(
        instruction="Create a simple 3-year financial projection.\n"
                   "Sheet name: 'Projections'.\n"
                   "Columns: Year 1, Year 2, Year 3.\n"
                   "Rows: Revenue, COGS, Gross Profit, Operating Expenses, Net Income.\n"
                   "Data: Start Revenue at $100,000, grows 20% annually.\n"
                   "COGS is 40% of Revenue.\n"
                   "Operating Expenses start at $30,000, grow 10% annually.\n"
                   "Calculate Gross Profit (Revenue - COGS) and Net Income (Gross Profit - OpEx).\n"
                   "Format currency as $#,##0. Apply bold headers and add a light blue fill to the header row.",
        file_path=output_path, # Server needs write access to this path/directory if relative
        operation_type="create", # create, modify, analyze, format
        # sheet_name="Projections", # Can specify sheet if modifying
        # cell_range="A1:D6", # Can specify range
        show_excel=False # Run Excel in the background (if applicable on the server)
    )

    if create_result["success"]:
        print(f"Excel creation successful: {create_result['message']}")
        print(f"File saved at: {create_result.get('output_file_path', output_path)}") # Confirm output path

        # Example: Modify the created file - add a chart
        print("\nRequesting modification: Add a Revenue chart...")
        modify_result = await client.tools.excel_execute(
            instruction="Add a column chart showing Revenue for Year 1, Year 2, Year 3. "
                       "Place it below the table. Title the chart 'Revenue Projection'.",
            file_path=output_path, # Use the previously created file
            operation_type="modify",
            sheet_name="Projections" # Specify the sheet to modify
        )
        if modify_result["success"]:
             print(f"Excel modification successful: {modify_result['message']}")
             print(f"File updated at: {modify_result.get('output_file_path', output_path)}")
        else:
             print(f"Excel modification failed: {modify_result['error']}")

    else:
        print(f"Excel creation failed: {create_result['error']}")
        if 'details' in create_result: print(f"Details: {create_result['details']}")

    # Example: Analyze formulas (if the tool supports it)
    # analysis_result = await client.tools.excel_analyze_formulas(...)

    await client.close()

# if __name__ == "__main__": asyncio.run(excel_automation_example())

Multi-Provider Comparison

import asyncio
from mcp.client import Client

async def multi_provider_completion_example():
    client = Client("http://localhost:8013")
    prompt = "Explain the concept of 'Chain of Thought' prompting for Large Language Models."

    print(f"Requesting completions for prompt: '{prompt}' from multiple providers...")
    # Request the same prompt from different models/providers
    multi_response = await client.tools.multi_completion(
        prompt=prompt,
        providers=[
            {"provider": "openai", "model": "gpt-4.1-mini", "temperature": 0.5},
            {"provider": "anthropic", "model": "claude-3-5-sonnet-20241022", "temperature": 0.5},
            {"provider": "gemini", "model": "gemini-2.0-pro", "temperature": 0.5},
            # {"provider": "deepseek", "model": "deepseek-chat", "temperature": 0.5}, # Add others if configured
        ],
        # Common parameters applied to all if not specified per provider
        max_tokens=300
    )

    if multi_response["success"]:
        print("\n--- Multi-completion Results ---")
        total_cost = multi_response.get("total_cost", 0.0)
        print(f"Total Estimated Cost: ${total_cost:.6f}\n")

        for provider_key, result in multi_response["results"].items():
            print(f"--- Provider: {provider_key} ---")
            if result["success"]:
                print(f"  Model: {result.get('model', 'N/A')}")
                print(f"  Cost: ${result.get('cost', 0.0):.6f}")
                print(f"  Tokens: Input={result.get('input_tokens', 'N/A')}, Output={result.get('output_tokens', 'N/A')}")
                print(f"  Completion:\n{result['completion']}\n")
            else:
                print(f"  Error: {result['error']}\n")
        print("------------------------------")
        # An agent could now analyze these responses for consistency, detail, accuracy etc.
    else:
        print(f"\nMulti-completion request failed: {multi_response['error']}")

    await client.close()

# if __name__ == "__main__": asyncio.run(multi_provider_completion_example())

Cost-Optimized Workflow Execution

import asyncio
from mcp.client import Client

async def optimized_workflow_example():
    client = Client("http://localhost:8013")
    # Example document to process through the workflow
    document_content = """
    Project Alpha Report - Q3 2024
    Lead: Dr. Evelyn Reed (e.reed@example.com)
    Status: On Track
    Budget: $50,000 remaining. Spent $25,000 this quarter.
    Key Findings: Successful prototype development (v0.8). User testing feedback positive.
    Next Steps: Finalize documentation, prepare for Q4 deployment. Target date: 2024-11-15.
    Risks: Potential delay due to supplier issues for component X. Mitigation plan in place.
    """

    print("Defining a multi-stage workflow...")
    # Define a workflow with stages, dependencies, and provider preferences
    # Use ${stage_id.output_key} to pass outputs between stages
    workflow_definition = [
        {
            "stage_id": "summarize_report",
            "tool_name": "summarize_document",
            "params": {
                "document": document_content,
                "format": "bullet_points",
                "max_length": 100,
                # Let the server choose a cost-effective model for summarization
                "provider_preference": "cost", # 'cost', 'quality', 'speed', or specific like 'openai/gpt-4.1-mini'
            }
            # No 'depends_on', runs first
            # Default output key is 'summary' for this tool, access via ${summarize_report.summary}
        },
        {
            "stage_id": "extract_key_info",
            "tool_name": "extract_json", # Use JSON extraction for structured data
            "params": {
                "document": document_content,
                "json_schema": {
                    "type": "object",
                    "properties": {
                        "project_lead": {"type": "string"},
                        "lead_email": {"type": "string", "format": "email"},
                        "status": {"type": "string"},
                        "budget_remaining": {"type": "string"},
                        "next_milestone_date": {"type": "string", "format": "date"}
                    },
                    "required": ["project_lead", "status", "next_milestone_date"]
                },
                # Prefer a model known for good structured data extraction, balancing cost
                "provider_preference": "quality", # Prioritize quality for extraction
                "preferred_models": ["openai/gpt-4o", "anthropic/claude-3-5-sonnet-20241022"] # Suggest specific models
            }
        },
        {
            "stage_id": "generate_follow_up_questions",
            "tool_name": "generate_qa", # Assuming a tool that generates questions
            "depends_on": ["summarize_report"], # Needs the summary first
            "params": {
                # Use the summary from the first stage as input
                "document": "${summarize_report.summary}",
                "num_questions": 3,
                "provider_preference": "speed" # Use a fast model for question generation
            }
            # Default output key 'qa_pairs', access via ${generate_follow_up_questions.qa_pairs}
        }
    ]

---

View the full README on GitHub