Feat/update basic quickstart template

[rholinshead]

Update the first of the init templates to make sure it works in full, including deployment to cloud. Will update the others in subsequent PRs

Changes:

• update to also init with a requirements.txt file so mcp-agent and openai are added as a requirement
• remove unused provider secrets (prevents prompting on deploy)
• some additional documentation / clarification; e.g. if using env variable you need to remove the empty secret string; and added a note for deploy step to specify the secret instead of env var

Summary by CodeRabbit

Release Notes

• New Features

  • Automatic requirements.txt generation during project initialization

• Documentation

  • Enhanced setup guide with API key configuration instructions
  • Added deployment workflow for running as a local or remote MCP server
  • Included MCP Inspector integration examples
  • Updated command examples with consistent package manager syntax

• Chores

  • Streamlined default provider configuration in template settings

[coderabbitai]

Walkthrough

The PR enhances the init command by adding automatic generation of a requirements.txt file during project initialization and substantially enriches template documentation with improved deployment instructions, setup steps, and configuration guidance.

Changes

Cohort / File(s)	Summary
Init command enhancement src/mcp_agent/cli/commands/init.py	Added _write_requirements() helper function with fallback behavior for creating requirements.txt; integrated into template initialization flows for basic and server templates to automatically generate requirements files.
Template documentation src/mcp_agent/data/templates/README_init.md	Expanded Quick Start section with API key setup instructions, environment variable guidance, and new requirements installation step; restructured deployment section to include local MCP server setup and added comprehensive remote server deployment workflow with MCP Inspector examples.
Template code updates src/mcp_agent/data/templates/basic_agent.py	Updated deployment command examples to use uv run prefix; added clarification comments about MCP server setup and configuration.
Template configuration files src/mcp_agent/data/templates/requirements.txt, src/mcp_agent/data/templates/secrets.yaml	Created new requirements.txt with mcp-agent and openai dependencies; reorganized secrets.yaml to comment out non-default provider blocks (anthropic, google, azure, bedrock) while preserving their configurations.

Sequence Diagram

sequenceDiagram
    participant User
    participant InitCmd as init command
    participant Templates as template engine
    participant FileSystem

    User->>InitCmd: Run init with template
    InitCmd->>Templates: Load template files
    Templates->>FileSystem: Copy README, code files
    
    alt Template requires requirements
        InitCmd->>InitCmd: Call _write_requirements()
        alt Write succeeds
            InitCmd->>FileSystem: Create requirements.txt
            FileSystem-->>InitCmd: Return filename
        else Cannot overwrite
            InitCmd-->>User: Print suggested content
            InitCmd->>InitCmd: Return None
        end
    end
    
    InitCmd-->>User: Report created files

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Mixed complexity across functional logic (new helper with error handling), template documentation enrichment, and configuration updates. The _write_requirements() function requires understanding of fallback behavior and integration points, while template changes involve content review across multiple files with varying scope.

Possibly related PRs

• PR merge init and quickstart #569: Modifies the same init command and template copying logic in src/mcp_agent/cli/commands/init.py, extending initialization workflows with quickstart and template-related functionality.

Suggested reviewers

• saqadri

Poem

🐰 A rabbit hops through templates bright,
Requirements bundled, secrets right!
README blooms with guidance clear,
Init commands, deployment near!
From local runs to clouds so high,
Configuration—perfected with a sigh! ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title "Feat/update basic quickstart template" accurately reflects the core intent of this pull request. The changeset modifies multiple related files that comprise the basic template initialization flow: the init.py command handler, the README template, the basic_agent.py template, the requirements.txt template, and the secrets.yaml configuration. The title correctly identifies that these changes represent an update to the template system. While the title is somewhat broad and doesn't specify particular improvements like requirements.txt generation or enhanced deployment documentation, it is sufficiently specific to distinguish this PR and communicate that templates are being updated to improve the initialization workflow.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.

✨ 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 feat/update-quickstart-templates

---

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

• X
• Mastodon
• Reddit
• LinkedIn

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

src/mcp_agent/data/templates/requirements.txt (1)

1-5: Consider version pinning for reproducibility.

The requirements file doesn't specify versions for dependencies. While this ensures users get the latest versions, it may lead to inconsistent behavior across different installations or over time as packages update.

Consider whether pinning versions (e.g., mcp-agent>=0.1.0) would improve the quickstart experience by ensuring consistent behavior.

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 205eae9 and fc06c31.

📒 Files selected for processing (5)

• src/mcp_agent/cli/commands/init.py (7 hunks)
• src/mcp_agent/data/templates/README_init.md (3 hunks)
• src/mcp_agent/data/templates/basic_agent.py (4 hunks)
• src/mcp_agent/data/templates/requirements.txt (1 hunks)
• src/mcp_agent/data/templates/secrets.yaml (2 hunks)

🧰 Additional context used

🧠 Learnings (1)

📚 Learning: 2025-07-22T18:59:49.368Z

Learnt from: CR
PR: lastmile-ai/mcp-agent#0
File: examples/usecases/reliable_conversation/CLAUDE.md:0-0
Timestamp: 2025-07-22T18:59:49.368Z
Learning: Applies to examples/usecases/reliable_conversation/examples/reliable_conversation/src/**/*.py : Use mcp-agent's Agent abstraction for ALL LLM interactions, including quality evaluation, to ensure consistent tool access, logging, and error handling.

Applied to files:

• src/mcp_agent/data/templates/basic_agent.py

🧬 Code graph analysis (2)

src/mcp_agent/data/templates/basic_agent.py (1)

src/mcp_agent/workflows/factory.py (1)

• create_agent (49-50)

src/mcp_agent/cli/commands/init.py (1)

src/mcp_agent/cli/commands/config.py (1)

• _load_template (36-49)

🪛 LanguageTool

src/mcp_agent/data/templates/README_init.md

[uncategorized] ~63-~63: The official name of this software platform is spelled with a capital “H”.
Context: ...p-agent cloud account through Google or Github. Set up your mcp-agent cloud API Key a...

(GITHUB)

🔇 Additional comments (10)

src/mcp_agent/data/templates/basic_agent.py (3)

10-10: LGTM! Deployment command updated consistently.

The update to use uv run mcp-agent deploy is consistent with the deployment instructions throughout the template.

---

25-26: Server setup guidance is clear and helpful.

The comment properly guides users to uncomment the import when running as an MCP server, which aligns with the deployment documentation in the README.

---

142-143: Good UX consideration for server-only deployments.

The note about commenting out agent runs when only the server is needed improves the user experience by clarifying different usage modes.

src/mcp_agent/data/templates/secrets.yaml (2)

5-8: Excellent simplification for quickstart users.

Defaulting to OpenAI and providing clear guidance about environment variable usage makes the quickstart experience much smoother. The inline comment about removing the empty string to use env vars is particularly helpful.

---

10-25: Good UX: commenting out unused providers.

This prevents unnecessary prompting during deployment while keeping the provider configurations available as examples. This directly addresses the PR objective to "Remove unused provider secrets to prevent prompting on deploy."

src/mcp_agent/cli/commands/init.py (2)

78-96: LGTM! Consistent pattern with _write_readme.

The _write_requirements function follows the same pattern as _write_readme, providing proper fallback behavior when the file cannot be written. The implementation is clean and handles errors appropriately.

---

369-374: Requirements generation properly integrated.

The requirements.txt is now correctly generated for the basic template, with proper error handling and file tracking. This aligns with the PR objective to "Add initialization with a requirements.txt file."

src/mcp_agent/data/templates/README_init.md (3)

18-34: Excellent setup instructions.

The expanded Quick Start section now includes clear guidance about API keys, environment variables, requirements installation, and provider flexibility. This significantly improves the user experience.

---

41-53: Clear local server deployment instructions.

The step-by-step guidance for running as a local MCP server, including the MCP Inspector example, makes it easy for users to test their deployment locally before going to production.

---

55-90: Comprehensive remote deployment documentation.

The deployment workflow is now well-documented with specific commands, expected prompts, and clear explanations. This addresses the PR objective to add deployment clarification notes.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix capitalization: "GitHub" not "Github".

The official name of the platform is "GitHub" with a capital "H".

Apply this diff:

-to authenticate to mcp-agent cloud. You will be redirected to the login page, create an mcp-agent cloud account through Google or Github.
+to authenticate to mcp-agent cloud. You will be redirected to the login page, create an mcp-agent cloud account through Google or GitHub.

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	to authenticate to mcp-agent cloud. You will be redirected to the login page, create an mcp-agent cloud account through Google or Github.
	to authenticate to mcp-agent cloud. You will be redirected to the login page, create an mcp-agent cloud account through Google or GitHub.

🧰 Tools

🪛 LanguageTool

[uncategorized] ~63-~63: The official name of this software platform is spelled with a capital “H”.
Context: ...p-agent cloud account through Google or Github. Set up your mcp-agent cloud API Key a...

(GITHUB)

🤖 Prompt for AI Agents

In src/mcp_agent/data/templates/README_init.md around line 63, the word "Github"
is incorrectly capitalized; replace it with the correct "GitHub" everywhere in
that line (and similar occurrences if present) so the official product name is
used.