Skip to content

Conversation

@jtcorbett
Copy link
Contributor

@jtcorbett jtcorbett commented Oct 23, 2025

TL;DR

Added new cloud-based example templates to the MCP Agent CLI initialization command.

How to test?

mcp init --template hello-world my-hello-world
mcp init --template mcp my-mcp-example
mcp init --template temporal my-temporal-workflow
mcp init --template chatgpt-app my-chatgpt-app

Summary by CodeRabbit

  • New Features
    • Added four new quickstart templates: hello-world, mcp, temporal, and chatgpt-app for faster project initialization.
    • Introduced ChatGPT app integration example with interactive coin-flip widget and React-based UI.
    • Enhanced example library with comprehensive workflow demonstrations including orchestration, evaluation-optimization, routing, and swarm patterns.
  • Documentation
    • Added setup guides and usage instructions for all new quickstart templates and advanced workflow examples.

Copy link
Contributor Author

jtcorbett commented Oct 23, 2025

This stack of pull requests is managed by Graphite. Learn more about stacking.

@jtcorbett jtcorbett mentioned this pull request Oct 23, 2025
@coderabbitai
Copy link

coderabbitai bot commented Oct 23, 2025

Caution

Review failed

The pull request is closed.

Walkthrough

This PR adds comprehensive example applications and templates to the MCP-Agent framework. Changes include: refactoring CLI example handling to use unified template mapping; four new cloud-deployable examples (hello-world, mcp, temporal, chatgpt-app); asyncio-based MCP server examples with client code; two use-case examples (financial-analyzer, researcher); and seven workflow pattern examples (deep-orchestrator, evaluator-optimizer, intent-classifier, orchestrator-worker, parallel, router, swarm).

Changes

Cohort / File(s) Change Summary
CLI Core Changes
docs/reference/cli.mdx, src/mcp_agent/cli/commands/init.py
Documentation updates to CLI reference table for four new quickstart templates (hello-world, mcp, temporal, chatgpt-app). Refactored init.py to consolidate example handling via a unified example_map that maps template names to destination directories and package-relative paths, replacing hard-coded EXAMPLE_ROOT and mixed repository/packaged example logic with consistent resources.files("mcp_agent.data") lookups.
Cloud Example: hello_world
src/mcp_agent/data/examples/cloud/hello_world/*
New simple cloud example with two tools (synchronous and asynchronous), configuration (asyncio, console logging), requirements (local mcp-agent[cli]), and README with setup/deployment instructions.
Cloud Example: mcp
src/mcp_agent/data/examples/cloud/mcp/*
Comprehensive MCP server example with workflows (BasicAgentWorkflow), tools (grade_story sync/async, sampling_demo, elicitation, notifications), prompt/resource providers, configuration (asyncio, fetch/filesystem servers, gpt-4o model), secrets template, requirements, and detailed README.
Cloud Example: temporal
src/mcp_agent/data/examples/cloud/temporal/*
Temporal-based cloud example with multiple workflows (BasicAgentWorkflow, PauseResumeWorkflow, SamplingWorkflow, ElicitationWorkflow, NotificationsWorkflow), a finder_tool, temporal_worker.py launcher, configuration with temporal settings, and README documentation.
Cloud Example: chatgpt_app — Backend
src/mcp_agent/data/examples/cloud/chatgpt_app/main.py, mcp_agent.config.yaml, requirements.txt, README.md
MCP server implementing a coin-flip widget rendered in ChatGPT via HTML/CSS/JS templates (inline and deployed variants), with tool/resource endpoints, widget metadata helpers, and Starlette-based local test server. Configuration for asyncio execution and secrets example included.
Cloud Example: chatgpt_app — Web Frontend
src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/*, package.json, tsconfig.json, public/index.html
React/TypeScript web client for coin-flip widget. Includes App component with theme/widget state management, interactive Coin component with 3D animations, custom hooks (useTheme, useWidgetState, useOpenAiGlobal), global types for OpenAI sandbox API, dev OpenAI mock setup, and styling (CSS animations for coin flips, theme switching).
Cloud Example: chatgpt_app — Web Config
src/mcp_agent/data/examples/cloud/chatgpt_app/web/.gitignore, README.md
Node/React project setup: gitignore for dependencies/build/env files, README with yarn setup/dev/build instructions.
MCP Agent Server Examples: asyncio — Main & Client
src/mcp_agent/data/examples/mcp_agent_server/asyncio/main.py, client.py
Asyncio server with BasicAgentWorkflow, sampling/elicitation/notification tools, token usage retrieval, and parallel LLM grading. Client demonstrates feature selection, workflow polling, tool execution, robust result parsing, and error handling with logging.
MCP Agent Server Examples: asyncio — Nested & Config
src/mcp_agent/data/examples/mcp_agent_server/asyncio/nested_sampling_server.py, nested_elicitation_server.py, mcp_agent.config.yaml, requirements.txt, short_story.md, logs/mcp-agent.jsonl
Nested MCP servers for sampling (haiku generation with progress) and elicitation (confirmation prompts via Pydantic schema). Configuration with asyncio, fetch/filesystem servers, gpt-4o model, and file-based logging. Includes sample short story and log artifacts.
Use Case: financial_analyzer
src/mcp_agent/data/examples/usecases/mcp_financial_analyzer/*
Complete stock analysis workflow with orchestrated multi-agent pipeline (data_collector, data_evaluator, analyst, report_writer), EvaluatorOptimizerLLM for quality control, output directory/report generation, and environment validation. Includes configuration with fetch/g-search/filesystem servers, sample report, secrets template, and README.
Use Case: researcher
src/mcp_agent/data/examples/usecases/mcp_researcher/*
Research workflow using Agent with Brave search, filesystem, containerized Python interpreter, and fetch tools. MCPConnectionManager wiring, OpenAI LLM augmentation, async context management, and Eutelsat investment report generation. Configuration includes Docker-based interpreter, brave/fetch/filesystem servers, o3-mini model.
Workflow: deep_orchestrator
src/mcp_agent/data/examples/workflows/workflow_deep_orchestrator/*
Deep Orchestrator with live Rich dashboard monitoring budget, memory, policy engine, agent cache, task queue, plan steps, and status. DeepOrchestratorMonitor class visualizing runtime state; complex grading task orchestration with result formatting and knowledge extraction. Config with OTEL tracing, gpt-4o model.
Workflow: evaluator_optimizer
src/mcp_agent/data/examples/workflows/workflow_evaluator_optimizer/*
Async tool demonstrating evaluator-optimizer pattern for cover letter generation with proofreader/fact_checker/style_enforcer agents and quality-gated refinement loop via EvaluatorOptimizerLLM.
Workflow: intent_classifier
src/mcp_agent/data/examples/workflows/workflow_intent_classifier/*
Intent classification demonstration with embedding-based and LLM-based classifiers for greeting/farewell intents using OpenAiIntentClassifier with shared context.
Workflow: orchestrator_worker
src/mcp_agent/data/examples/workflows/workflow_orchestrator_worker/*
Orchestrator for parallel multi-agent assignment grading (finder, writer, proofreader, fact_checker, style_enforcer) with result aggregation. Includes token usage tree display helpers and nested reports.
Workflow: parallel
src/mcp_agent/data/examples/workflows/workflow_parallel/*
ParallelLLM demonstrating fan-out (proofreader, fact_checker, style_enforcer) with fan-in aggregation (grader agent) using OpenAIAugmentedLLM.
Workflow: router
src/mcp_agent/data/examples/workflows/workflow_router/*
LLM-based routers (OpenAI, Anthropic) delegating requests to agents (finder, writer, reasoning), functions (print_to_console, print_hello_world), and filesystem server; demonstrates route_to_agent, route_to_function, route_to_server, and combined routing patterns.
Workflow: swarm
src/mcp_agent/data/examples/workflows/workflow_swarm/*
Airline customer-service swarm with nested agent hierarchy (Triage → Flight Modification/Lost Baggage → Flight Cancel/Change), utility functions for escalation/refunds/credits/baggage search, and policy documents (cancellation, change, lost_baggage). SwarmAgent configuration with context variables and human-input callbacks.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~55 minutes

Rationale: Large scope (100+ files across 11 distinct example categories) with heterogeneous types (Python logic, TypeScript/React, YAML configs, Markdown docs, CSS styling). While repetitive patterns reduce per-file complexity, the breadth demands multi-domain reasoning: init.py refactoring logic (medium); new web client implementation for chatgpt_app (medium); dense agent/workflow orchestration code across multiple examples (medium-to-high); and consistency checks across similar templates. The changes span CLI core, cloud deployment examples, framework patterns, and use-case demonstrations, each requiring contextual review.

Possibly related PRs

Suggested reviewers

  • saqadri
  • rholinshead
  • StreetLamb

Poem

🐰 A warren of examples springs to life,
Cloud, workflows, swarms—no need for strife!
ChatGPT coins flip, agents think,
Template maps unified, all in sync.
From orchestrators deep to routers keen,
The finest framework e'er seen!

✨ Finishing touches
  • 📝 Generate docstrings
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch 10-23-add_quickstart_examples

📜 Recent review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bd97817 and a1c14eb.

⛔ Files ignored due to path filters (1)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/yarn.lock is excluded by !**/yarn.lock, !**/*.lock
📒 Files selected for processing (102)
  • docs/reference/cli.mdx (1 hunks)
  • src/mcp_agent/cli/commands/init.py (4 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/README.md (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/main.py (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/.gitignore (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/README.md (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/package.json (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/public/index.html (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/components/App.css (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/components/App.tsx (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/components/Coin.css (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/components/Coin.tsx (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/index.css (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/index.tsx (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/utils/dev-openai-global.ts (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/utils/hooks/use-openai-global.ts (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/utils/hooks/use-theme.ts (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/utils/hooks/use-widget-state.ts (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/src/utils/types.ts (1 hunks)
  • src/mcp_agent/data/examples/cloud/chatgpt_app/web/tsconfig.json (1 hunks)
  • src/mcp_agent/data/examples/cloud/hello_world/README.md (1 hunks)
  • src/mcp_agent/data/examples/cloud/hello_world/main.py (1 hunks)
  • src/mcp_agent/data/examples/cloud/hello_world/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/cloud/hello_world/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/cloud/mcp/README.md (1 hunks)
  • src/mcp_agent/data/examples/cloud/mcp/main.py (1 hunks)
  • src/mcp_agent/data/examples/cloud/mcp/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/cloud/mcp/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/cloud/mcp/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/cloud/mcp/short_story.md (1 hunks)
  • src/mcp_agent/data/examples/cloud/temporal/README.md (1 hunks)
  • src/mcp_agent/data/examples/cloud/temporal/main.py (1 hunks)
  • src/mcp_agent/data/examples/cloud/temporal/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/cloud/temporal/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/cloud/temporal/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/cloud/temporal/temporal_worker.py (1 hunks)
  • src/mcp_agent/data/examples/mcp_agent_server/asyncio/README.md (1 hunks)
  • src/mcp_agent/data/examples/mcp_agent_server/asyncio/client.py (1 hunks)
  • src/mcp_agent/data/examples/mcp_agent_server/asyncio/logs/mcp-agent.jsonl (1 hunks)
  • src/mcp_agent/data/examples/mcp_agent_server/asyncio/main.py (1 hunks)
  • src/mcp_agent/data/examples/mcp_agent_server/asyncio/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/mcp_agent_server/asyncio/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/mcp_agent_server/asyncio/nested_elicitation_server.py (1 hunks)
  • src/mcp_agent/data/examples/mcp_agent_server/asyncio/nested_sampling_server.py (1 hunks)
  • src/mcp_agent/data/examples/mcp_agent_server/asyncio/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/mcp_agent_server/asyncio/short_story.md (1 hunks)
  • src/mcp_agent/data/examples/usecases/mcp_financial_analyzer/README.md (1 hunks)
  • src/mcp_agent/data/examples/usecases/mcp_financial_analyzer/main.py (1 hunks)
  • src/mcp_agent/data/examples/usecases/mcp_financial_analyzer/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/usecases/mcp_financial_analyzer/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/usecases/mcp_financial_analyzer/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/usecases/mcp_financial_analyzer/sample_report.md (1 hunks)
  • src/mcp_agent/data/examples/usecases/mcp_researcher/README.md (1 hunks)
  • src/mcp_agent/data/examples/usecases/mcp_researcher/main.py (1 hunks)
  • src/mcp_agent/data/examples/usecases/mcp_researcher/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/usecases/mcp_researcher/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/usecases/mcp_researcher/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_deep_orchestrator/README.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_deep_orchestrator/graded_report.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_deep_orchestrator/main.py (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_deep_orchestrator/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_deep_orchestrator/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_deep_orchestrator/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_deep_orchestrator/short_story.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_evaluator_optimizer/README.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_evaluator_optimizer/main.py (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_evaluator_optimizer/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_evaluator_optimizer/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_evaluator_optimizer/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_intent_classifier/README.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_intent_classifier/main.py (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_intent_classifier/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_intent_classifier/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_intent_classifier/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_orchestrator_worker/README.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_orchestrator_worker/graded_report.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_orchestrator_worker/main.py (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_orchestrator_worker/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_orchestrator_worker/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_orchestrator_worker/reports/graded_report.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_orchestrator_worker/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_orchestrator_worker/short_story.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_parallel/README.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_parallel/main.py (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_parallel/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_parallel/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_parallel/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_router/README.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_router/main.py (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_router/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_router/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_router/requirements.txt (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_swarm/README.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_swarm/main.py (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_swarm/mcp_agent.config.yaml (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_swarm/mcp_agent.secrets.yaml.example (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_swarm/policies/flight_cancellation_policy.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_swarm/policies/flight_change_policy.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_swarm/policies/lost_baggage_policy.md (1 hunks)
  • src/mcp_agent/data/examples/workflows/workflow_swarm/requirements.txt (1 hunks)

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@jtcorbett jtcorbett marked this pull request as ready for review October 23, 2025 13:43
@jtcorbett jtcorbett force-pushed the 10-22-merge_init_and_quickstart branch from 20288a3 to b52015f Compare October 23, 2025 13:48
@jtcorbett jtcorbett force-pushed the 10-23-add_quickstart_examples branch from d37a1f2 to 44fc459 Compare October 23, 2025 13:48
Copy link
Contributor Author

jtcorbett commented Oct 23, 2025

Merge activity

  • Oct 23, 2:38 PM UTC: A user started a stack merge that includes this pull request via Graphite.
  • Oct 23, 2:39 PM UTC: Graphite rebased this pull request as part of a merge.
  • Oct 23, 2:40 PM UTC: @jtcorbett merged this pull request with Graphite.

@jtcorbett jtcorbett changed the base branch from 10-22-merge_init_and_quickstart to graphite-base/577 October 23, 2025 14:38
@jtcorbett jtcorbett changed the base branch from graphite-base/577 to main October 23, 2025 14:38
@jtcorbett jtcorbett force-pushed the 10-23-add_quickstart_examples branch from 33e08d0 to a1c14eb Compare October 23, 2025 14:39
@jtcorbett jtcorbett merged commit 446de06 into main Oct 23, 2025
7 of 8 checks passed
@@ -0,0 +1,6 @@
# Core framework dependency
mcp-agent @ file://../../../ # Link to the local mcp-agent project root
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jtcorbett just checking, did you test all these quickstart examples -- mainly wondering about the paths for the schema requirements files being correct

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I tested them, but I did test them in the repo, so I should probably also test from the package as well to make sure they're loading right there

andrew-lastmile pushed a commit to andrew-lastmile/mcp-agent-fork that referenced this pull request Nov 4, 2025
### TL;DR

Added new cloud-based example templates to the MCP Agent CLI initialization command.

### How to test?

   ```
   mcp init --template hello-world my-hello-world
   mcp init --template mcp my-mcp-example
   mcp init --template temporal my-temporal-workflow
   mcp init --template chatgpt-app my-chatgpt-app
   ```
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants