{"id":41481576,"url":"https://github.com/intertwine/vertex-mcp-chatbot","last_synced_at":"2026-01-23T17:20:37.681Z","repository":{"id":306917452,"uuid":"1027555983","full_name":"intertwine/vertex-mcp-chatbot","owner":"intertwine","description":"Vertex AI chatbot with MCP integration","archived":false,"fork":false,"pushed_at":"2025-10-30T13:19:40.000Z","size":835,"stargazers_count":3,"open_issues_count":1,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-10-30T15:24:15.610Z","etag":null,"topics":["chatbot","gcp","gemini","google-cloud","google-genai","llm","mcp-server","model-context-protocol","vertex-ai"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/intertwine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-28T07:29:33.000Z","updated_at":"2025-10-30T13:19:44.000Z","dependencies_parsed_at":"2025-10-04T20:23:27.348Z","dependency_job_id":"51c5fccd-d1d7-4680-8abe-68d8be0678bb","html_url":"https://github.com/intertwine/vertex-mcp-chatbot","commit_stats":null,"previous_names":["intertwine/vertex-mcp-chatbot"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/intertwine/vertex-mcp-chatbot","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intertwine%2Fvertex-mcp-chatbot","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intertwine%2Fvertex-mcp-chatbot/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intertwine%2Fvertex-mcp-chatbot/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intertwine%2Fvertex-mcp-chatbot/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/intertwine","download_url":"https://codeload.github.com/intertwine/vertex-mcp-chatbot/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/intertwine%2Fvertex-mcp-chatbot/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28696523,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T15:57:05.722Z","status":"ssl_error","status_checked_at":"2026-01-23T15:56:27.656Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","gcp","gemini","google-cloud","google-genai","llm","mcp-server","model-context-protocol","vertex-ai"],"created_at":"2026-01-23T17:20:37.148Z","updated_at":"2026-01-23T17:20:37.671Z","avatar_url":"https://github.com/intertwine.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Vertex MCP Chatbot\n\n[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-blue)](https://www.python.org)\n[![MCP](https://img.shields.io/badge/MCP-blue.svg)](https://modelcontextprotocol.io)\n[![Python SDK](https://img.shields.io/badge/Python%20SDK-green.svg)](https://github.com/modelcontextprotocol/python-sdk)\n[![Specification](https://img.shields.io/badge/specification-gray.svg)](https://spec.modelcontextprotocol.io/specification/)\n[![Documentation](https://img.shields.io/badge/documentation-purple.svg)](https://modelcontextprotocol.io)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nAn interactive command-line chatbot for Google Cloud Vertex AI, supporting both **Anthropic's Claude** and **Google Gemini** models. Choose your preferred AI provider with a simple flag. The chatbot features full MCP (Model Context Protocol) integration with Claude, allowing autonomous tool discovery and execution during conversations. Supports Vertex AI or direct Anthropic API access, with automatic tool calling, multi-turn conversations, and comprehensive error handling.\n\n## Features\n\n- 🤖 **Interactive Chat Interface**: Clean, intuitive terminal UI with rich formatting\n- 🔀 **Multi-Provider Support**: Choose between Claude (default) or Gemini with `--provider` flag\n- 🧠 **Claude via Vertex AI**: Anthropic's Claude Sonnet 4.5 through Google Cloud Vertex AI\n- 🌟 **Gemini Integration**: Google's Gemini 2.5 Flash available as alternative provider\n- 🔧 **Automatic Tool Calling** (Claude): Autonomous MCP tool discovery and execution during conversations\n- 📝 **Markdown Support**: Responses are rendered with proper markdown formatting\n- 💾 **Persistent History**: Conversation history saved between sessions on disk\n- 🎨 **Rich Terminal UI**: Colorful, well-formatted output using Rich library\n- 🔧 **Flexible Configuration**: Use Vertex AI (with GCP credentials) or direct Anthropic API\n- 🔌 **Full MCP Integration**: Load tools from `mcp_config.json` with automatic tool discovery and execution\n\n### MCP Features\n\nThe chatbot includes comprehensive MCP (Model Context Protocol) support:\n\n- ✅ **Tool Execution**: Claude automatically uses MCP tools during conversations\n- ✅ **Resource Access**: Read files, APIs, and other resources via URIs\n- ✅ **Prompt Templates**: Use pre-defined templates for common tasks\n- ✅ **Multiple Transports**: stdio, HTTP, and SSE protocols supported\n- ✅ **Multi-Server Support**: Connect to multiple MCP servers simultaneously\n- ✅ **Authentication**: OAuth 2.0, Basic Auth, and custom headers\n- ✅ **Reliability**: Automatic retry with exponential backoff\n- ✅ **Priority System**: Smart conflict resolution when servers offer similar tools\n\n## Quick Start\n\n```bash\n# 1. Clone and setup\ngit clone https://github.com/intertwine/vertex-mcp-chatbot.git\ncd vertex-mcp-chatbot\nmake setup            # Install dependencies and create .env\n\n# 2. Configure (edit .env file with your GCP project settings)\nnano .env             # or use your preferred editor\n\n# 3. Authenticate and run\nmake auth             # Authenticate with Google Cloud\nmake run              # Start the chatbot with quiet MCP logging!\n```\n\nFor all available commands, run:\n\n```bash\nmake help\n```\n\n## Prerequisites\n\n- Python 3.10 or higher\n- [uv](https://docs.astral.sh/uv/) package manager installed\n- Access to Google Cloud Vertex AI with Anthropic Claude enabled (MCP-capable regions)\n- Google Cloud CLI (`gcloud`) installed and authenticated\n\n## Installation\n\n1. Clone this repository:\n\n```bash\ngit clone https://github.com/intertwine/vertex-mcp-chatbot.git\ncd vertex-mcp-chatbot\n```\n\n1. Run the quick setup (installs dependencies and creates .env file):\n\n```bash\nmake setup\n```\n\n\u003e This runs `uv sync` and copies `.env.example` to `.env`\n\n1. Edit `.env` to override default project settings:\n\n```bash\nGOOGLE_CLOUD_PROJECT='your-gcp-project-id'\nGOOGLE_CLOUD_LOCATION='us-east1'\n```\n\n1. Authenticate with Google Cloud:\n\n```bash\nmake auth\n```\n\n\u003e This runs `gcloud auth application-default login`\n\n**Alternative manual setup:**\n\n```bash\n# Install dependencies manually\nuv sync\n\n# Copy environment file\ncp .env.example .env\n\n# Authenticate manually\ngcloud auth application-default login\n```\n\n## Usage\n\n### Basic Usage\n\nStart the chatbot with the default provider (Claude):\n\n```bash\nmake run\n```\n\n### Choosing Your AI Provider\n\n**Use Claude (default)**:\n\n```bash\nmake run              # Uses Claude Sonnet 4.5 (quiet MCP logging)\nmake run-claude       # Same as above (quiet MCP logging)\nmake run-opus         # Uses Claude Opus 4.1 (quiet MCP logging)\nmake run-haiku        # Uses Claude Haiku 4.5 (quiet MCP logging)\n```\n\n**Use Gemini**:\n\n```bash\nmake run-gemini       # Uses Gemini 2.5 Flash (quiet MCP logging)\nmake run-gemini-pro   # Uses Gemini 2.5 Pro (quiet MCP logging)\n```\n\n**With verbose logging**:\n\n```bash\nmake run-verbose      # Claude with INFO-level MCP logging\nmake run-debug        # Claude with DEBUG-level MCP logging\n```\n\n**Alternative (direct uv commands)**:\n\n```bash\nuv run main.py                    # Claude Sonnet 4.5 (default)\nuv run main.py --model claude-opus-4-1-20250805  # Claude Opus\nuv run main.py --model claude-haiku-4-5           # Claude Haiku 4.5\nuv run main.py --provider gemini  # Gemini 2.5 Flash\nuv run main.py --provider gemini --model gemini-2.5-pro  # Gemini 2.5 Pro\n\n# Logging control options\nuv run main.py --quiet-mcp        # Suppress MCP server info logging\nuv run main.py --log-level DEBUG  # Show detailed MCP debug information\nuv run main.py --log-level ERROR  # Only show errors from MCP operations\n```\n\n**Key Differences**:\n\n- **Claude**: Full MCP tool-calling support with autonomous tool discovery and execution\n- **Gemini**: Fast, efficient responses; MCP servers can be configured but tool calling is manual\n\nBoth providers offer the same intuitive terminal interface, markdown rendering, and persistent conversation history.\n\n### Configuring Claude via Vertex AI\n\nThe CLI automatically attempts to run Claude through Google Cloud Vertex AI using Application Default Credentials. To customise the behaviour, set any of the following environment variables before launching the REPL (they can be stored in `.env`):\n\n- `CLAUDE_VERTEX_ENABLED` – set to `false` to fall back to the public Anthropic API (requires `ANTHROPIC_API_KEY`)\n- `CLAUDE_VERTEX_PROJECT` – override the GCP project used for billing (`GOOGLE_CLOUD_PROJECT` is used otherwise)\n- `CLAUDE_VERTEX_LOCATION` – override the Vertex region (defaults to `GOOGLE_CLOUD_LOCATION` or `us-east1`)\n- `CLAUDE_VERTEX_BASE_URL` – fully override the Vertex endpoint if you need to point at a proxy\n- `CLAUDE_MODEL` – override the default Claude model (default: `claude-sonnet-4-5-20250929`)\n- `CLAUDE_API_VERSION` – override the Anthropic API version header (default: `2023-06-01`)\n\nSee [docs/claude-agent.md](docs/claude-agent.md) for an end-to-end walkthrough that covers authentication, MCP configuration, and troubleshooting tips when connecting Claude through Vertex AI, plus guidance on when to prefer the legacy Gemini provider.\n\n### MCP Configuration\n\nTo use MCP features, create an `mcp_config.json` file in the project root. See the [MCP User Guide](docs/mcp-guide.md) for detailed configuration instructions and examples.\n\n#### Example: Autonomous Tool Usage\n\nWhen you connect to an MCP server, Claude automatically sees available tools and can use them during conversations:\n\n```text\nYou \u003e /mcp connect filesystem\n✅ Connected to MCP server: filesystem\n\nYou \u003e Please list the files in the current directory\n\nClaude: The current directory contains the following files:\n  1. CODE_OF_CONDUCT.md (1.3 KB)\n  2. pyproject.toml (1.9 KB) - Python project configuration\n  3. README.md (24.6 KB) - Project documentation\n  4. main.py (1.7 KB) - Main Python script\n  ...\n```\n\nClaude automatically:\n\n- Discovered the `list_files` tool from the connected MCP server\n- Decided to call it with appropriate parameters\n- Received and processed the results\n- Formatted them into a helpful response\n\nNo explicit tool invocation needed - Claude autonomously chooses when and how to use tools!\n\n### Controlling MCP Logging\n\n**Note**: The default `make run` targets now use `--quiet-mcp` for cleaner output. Use `make run-verbose` or `make run-debug` if you need more detailed logging.\n\nThe chatbot provides options to control the verbosity of MCP server logging:\n\n**Suppress MCP logging (quiet mode):**\n\n```bash\nuv run main.py --quiet-mcp\n```\n\nThis suppresses all informational logging from MCP operations, showing only errors.\n\n**Adjust logging level:**\n\n```bash\nuv run main.py --log-level DEBUG    # Show detailed debug information\nuv run main.py --log-level INFO     # Show informational messages\nuv run main.py --log-level WARNING  # Default - show warnings and above\nuv run main.py --log-level ERROR    # Show only errors\nuv run main.py --log-level CRITICAL # Show only critical errors\n```\n\nThese options are useful when:\n\n- You want a cleaner output during tool execution (`--quiet-mcp`)\n- You're debugging MCP server connections (`--log-level DEBUG`)\n- You only care about errors (`--log-level ERROR`)\n\n### Scrollable Content\n\nWhen responses or content are too long for your terminal, the chatbot automatically switches to a scrollable view:\n\n**Navigation Controls:**\n\n- **↑/↓** or **j/k** - Scroll up/down line by line\n- **Home/g** - Jump to the top of the content\n- **End/G** - Jump to the bottom of the content\n- **q/Esc** - Exit scrollable view and return to chat\n\n**Features:**\n\n- Automatically detects when content exceeds terminal height\n- Works for:\n  - LLM responses\n  - `/history` command\n  - `/mcp tools` listings\n  - `/mcp resources` listings\n  - `/mcp prompts` listings\n- Preserves all markdown formatting and styling\n- Short content displays normally (no change in experience)\n\n### Available Commands\n\nWhile chatting, you can use these commands:\n\n- `/help` - Show available commands and tips\n- `/clear` - Clear the chat history and start fresh (resets the Claude session)\n- `/history` - Display the full conversation history with markdown rendering\n- `/system \u003cprompt\u003e` - Update the system instruction and restart the Claude agent\n- `/quit` - Exit the chatbot\n\n**MCP Commands** (when MCP is available):\n\n- `/mcp connect \u003cserver\u003e` - Connect to an MCP server from your config\n- `/mcp list` - Show configured servers and their connection status\n- `/mcp disconnect \u003cserver\u003e` - Disconnect from an MCP server\n- `/mcp tools` - Show available tools from all connected servers\n- `/mcp resources` - Show available resources from all connected servers\n- `/mcp prompts` - List available prompt templates from all connected servers\n- `/mcp prompt \u003cname\u003e` - Use a specific prompt template\n\n### MCP Tool Integration\n\nWhen MCP servers are connected, their tools become automatically available during conversations. Claude will intelligently use these tools when appropriate to help answer your questions or perform tasks. You don't need to use special syntax - just chat naturally and Claude will:\n\n- Recognize when a tool would be helpful\n- Execute the appropriate tool with the right parameters\n- Include the tool results in its response\n\nFor example, if you have a weather MCP server connected and ask \"What's the weather like?\", Claude will automatically use the weather tool to get current conditions.\n\n### MCP Resource Integration\n\nMCP resources are automatically read when you reference them by URI in your messages. This allows you to seamlessly include external data in your conversations with Claude:\n\n- **Automatic Detection**: When you include a resource URI in your message, it's automatically detected\n- **Transparent Reading**: The resource content is fetched and included in the context sent to Claude\n- **Multiple Resources**: You can reference multiple resources in a single message\n- **Standard URI Format**: Use standard URIs like `file:///path/to/data.json` or `http://example.com/api/data`\n\n**Example:**\n\n```text\nYou\u003e Can you analyze the data in file:///home/user/sales_report.csv?\n\n[The chatbot automatically reads the CSV file and includes its content in the prompt to Claude,\nwho can then analyze and discuss the data]\n```\n\n### MCP Prompt Templates\n\nMCP servers can provide prompt templates that help structure interactions for specific tasks. These templates make it easy to perform complex operations with consistent formatting:\n\n- **List Templates**: Use `/mcp prompts` to see all available templates\n- **Use a Template**: Use `/mcp prompt \u003ctemplate_name\u003e` to apply a template\n- **Interactive Arguments**: The chatbot will prompt you for any required template arguments\n- **Seamless Processing**: Filled templates are sent directly to Claude for processing\n\n**Example:**\n\n```text\nYou\u003e /mcp prompts\nAvailable prompts from code-analyzer:\n  - analyze_function: Analyze a function for complexity and suggest improvements\n  - review_pr: Review pull request changes and provide feedback\n  - explain_code: Explain how a piece of code works in simple terms\n\nYou\u003e /mcp prompt analyze_function\nEnter value for 'function_name': calculateTotalPrice\nEnter value for 'context': This function processes shopping cart items\n\n[The template is filled with your values and sent to Claude, who provides\na detailed analysis of the function based on the structured prompt]\n```\n\n### Example Session\n\n```text\n🚀 Starting Claude Agent REPL...\n✅ Ready!\n\nYou\u003e What is machine learning?\n\n╭─ Claude ─────────────────────────────────────────────╮\n│                                                      │\n│  Machine learning (ML) is a branch of artificial     │\n│  intelligence focused on building systems that can   │\n│  learn from data and improve their performance over  │\n│  time without being explicitly programmed for every  │\n│  scenario...                                         │\n│                                                      │\n╰──────────────────────────────────────────────────────╯\n\nYou\u003e /system You are a patient tutor for high-school students.\nSystem prompt updated.\n\nYou\u003e Explain overfitting in one paragraph.\n\n╭─ Claude ─────────────────────────────────────────────╮\n│                                                      │\n│  Overfitting happens when a model memorises the      │\n│  training data instead of learning the underlying    │\n│  patterns, so it performs well on the data it has    │\n│  seen but poorly on new examples. A simple way to    │\n│  picture it is a student who only studies past exam  │\n│  answers: they may ace the practice questions yet    │\n│  struggle when the real test words things slightly   │\n│  differently.                                        │\n│                                                      │\n╰──────────────────────────────────────────────────────╯\n\nYou\u003e /quit\n\n👋 Goodbye!\n```\n\n## MCP Configuration (docs/mcp-guide.md)\n\n### Basic Configuration\n\nCreate an `mcp_config.json` file in the project root:\n\n```json\n{\n  \"servers\": [\n    {\n      \"name\": \"filesystem\",\n      \"transport\": \"stdio\",\n      \"command\": [\"python\", \"examples/mcp-servers/filesystem_server.py\"]\n    },\n    {\n      \"name\": \"weather-api\",\n      \"transport\": \"http\",\n      \"url\": \"http://localhost:8080/mcp\",\n      \"auth\": {\n        \"type\": \"basic\",\n        \"username\": \"user\",\n        \"password\": \"pass\"\n      }\n    }\n  ]\n}\n```\n\n### Environment Variables\n\nThe MCP configuration supports environment variable substitution using `${VAR_NAME}` syntax. Variables are automatically loaded from your `.env` file:\n\n```bash\n# .env file\nAPI_KEY=your-secret-key\nOAUTH_CLIENT_SECRET=your-oauth-secret\n```\n\n```json\n{\n  \"servers\": [\n    {\n      \"name\": \"api-server\",\n      \"transport\": \"http\",\n      \"url\": \"https://api.example.com\",\n      \"headers\": {\n        \"Authorization\": \"Bearer ${API_KEY}\"\n      }\n    }\n  ]\n}\n```\n\nYou can also provide default values with `${VAR_NAME:-default}` syntax.\n\n### Advanced Configuration Options\n\n#### OAuth 2.0 Authentication\n\n```json\n{\n  \"name\": \"github-api\",\n  \"transport\": \"http\",\n  \"url\": \"https://api.github.com/mcp\",\n  \"auth\": {\n    \"type\": \"oauth\",\n    \"authorization_url\": \"https://github.com/login/oauth/authorize\",\n    \"token_url\": \"https://github.com/login/oauth/access_token\",\n    \"client_id\": \"your-client-id\",\n    \"client_secret\": \"${OAUTH_CLIENT_SECRET}\",\n    \"scope\": \"repo read:user\",\n    \"redirect_uri\": \"http://localhost:8080/callback\"\n  }\n}\n```\n\n#### Connection Retry Configuration\n\n```json\n{\n  \"name\": \"flaky-server\",\n  \"transport\": \"stdio\",\n  \"command\": [\"node\", \"server.js\"],\n  \"retry\": {\n    \"max_attempts\": 5,\n    \"initial_delay\": 1.0,\n    \"max_delay\": 30.0,\n    \"exponential_base\": 2.0,\n    \"jitter\": true\n  }\n}\n```\n\n#### Server Priority\n\nWhen multiple servers offer similar tools, use priority to control which server is preferred:\n\n```json\n{\n  \"servers\": [\n    {\n      \"name\": \"primary-calc\",\n      \"transport\": \"stdio\",\n      \"command\": [\"python\", \"calc_server.py\"],\n      \"priority\": 1\n    },\n    {\n      \"name\": \"backup-calc\",\n      \"transport\": \"http\",\n      \"url\": \"http://backup.example.com/mcp\",\n      \"priority\": 2\n    }\n  ]\n}\n```\n\n### Example MCP Servers\n\nThe project includes example MCP servers in `examples/mcp-servers/`:\n\n- **filesystem_server.py**: File operations (list, read, write)\n- **weather_server.py**: Weather data and forecasts\n\nSee [examples/README.md](examples/README.md) for detailed setup instructions.\n\n## Project Structure\n\n```text\nvertex-mcp-chatbot/\n├── main.py              # Entry point\n├── pyproject.toml       # Python project configuration and dependencies\n├── pytest.ini          # Pytest configuration\n├── scripts/\n│   ├── run_tests.py         # Custom test runner script\n│   └── run_example_tests.py # Example server test runner\n├── .env.example        # Example environment file\n├── .gitignore          # Git ignore rules\n├── README.md           # This file\n├── mcp_config.json.example # Example MCP server configuration\n├── docs/\n│   ├── claude-agent.md # Claude Agent SDK + Vertex AI walkthrough\n│   └── mcp-guide.md    # Comprehensive MCP user guide\n├── src/\n│   ├── __init__.py     # Package init\n│   ├── claude_agent_chatbot.py # Claude Agent REPL (default CLI)\n│   ├── claude_agent_client.py  # Claude SDK helper / session manager\n│   ├── claude_sdk_fallback.py  # Local stub used in tests when SDK is unavailable\n│   ├── config.py       # Configuration management for Claude + Gemini helpers\n│   ├── gemini_client.py # Legacy Gemini/Vertex AI client wrapper (still used in tests)\n│   ├── chatbot.py      # Legacy Gemini chatbot implementation\n│   ├── mcp_config.py   # MCP configuration handling\n│   └── mcp_manager.py  # MCP client management\n└── tests/\n    ├── __init__.py     # Test package init\n    ├── conftest.py     # Pytest fixtures and configuration\n    ├── test_config.py  # Configuration tests\n    ├── test_gemini_client.py # Gemini client tests\n    ├── test_chatbot.py # Legacy Gemini chatbot functionality tests\n    ├── test_claude_agent_chatbot.py # Claude REPL behaviour\n    ├── test_claude_agent_client.py # Claude client helper tests\n    ├── test_main.py    # Main entry point tests\n    ├── test_integration.py # Integration tests\n    ├── test_mcp_config.py # MCP configuration tests\n    ├── test_mcp_manager.py # MCP manager tests\n    ├── test_mcp_http_transport.py # HTTP/SSE transport tests\n    ├── test_mcp_multi_server.py # Multi-server coordination tests\n    ├── test_mcp_oauth.py # OAuth authentication tests\n    └── test_mcp_retry.py # Connection retry tests\n```\n\n## Configuration\n\nThe application uses the following configuration (can be modified in `src/config.py`):\n\n- **Project ID**: `your-gcp-project-id` (override in `.env` via `GOOGLE_CLOUD_PROJECT`)\n- **Location**: `your-gcp-location` (override in `.env` via `GOOGLE_CLOUD_LOCATION`)\n- **Default Claude Model**: `claude-4.5-sonnet` (change via `CLAUDE_MODEL`)\n- **Anthropic API Version**: `2025-02-19` (set `CLAUDE_API_VERSION` to override)\n- **Max History Length**: 10 conversation turns\n\n## Troubleshooting\n\n### \"Failed to start Claude Agent REPL\"\n\nMake sure you've:\n\n1. Authenticated with Google Cloud: `gcloud auth application-default login`\n2. Enabled the Vertex AI API and Anthropic publisher access for your project/region\n3. Granted the `Vertex AI User` role to the identity running the CLI\n4. Installed dependencies (`uv sync` or `pip install -e .`) so `google-auth` is available\n\n### \"Unable to refresh Google credentials\"\n\nCheck that:\n\n1. ADC credentials are active (`gcloud auth application-default login` or service account JSON)\n2. The `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values match your deployment\n3. The executing user/service account has billing enabled for the project\n4. You are targeting a region that exposes Claude through Vertex AI\n\n### Falling back to the public Anthropic API\n\nIf Vertex access is unavailable you can still run the REPL by setting `CLAUDE_VERTEX_ENABLED=false` and exporting `ANTHROPIC_API_KEY`. The helper automatically reconfigures the Claude SDK to use the public endpoint and keeps MCP tooling enabled.\n\n## Testing\n\nThis project includes a comprehensive test suite with 190+ tests covering all functionality, including example MCP servers.\n\n### Running Tests\n\n**Quick test run:**\n\n```bash\n# Install dev dependencies (includes pytest-cov for coverage)\nmake install-dev\n\n# Run all tests\nmake test\n```\n\n**Testing commands:**\n\n```bash\nmake test             # Run all tests with pytest\nmake test-v           # Run tests with verbose output\nmake test-cov         # Run tests with coverage report\nmake test-unit        # Run only unit tests\nmake test-int         # Run only integration tests\n```\n\n**Example MCP Server Tests:**\n\n```bash\nmake test-examples    # Run all example server tests\nmake test-examples-v  # Run with verbose output\nmake test-examples-cov # Run with coverage\nmake test-filesystem  # Run only filesystem server tests\nmake test-weather     # Run only weather server tests\nmake server-check     # Check server health\n```\n\n**Alternative (direct uv commands):**\n\n```bash\n# Run all tests\nuv run pytest tests/ -v\n\n# Using the custom test runner\nuv run python scripts/run_tests.py --verbose\nuv run python scripts/run_tests.py --coverage\nuv run python scripts/run_tests.py --unit\n\n# Example server tests\nuv run python scripts/run_example_tests.py --filesystem\nuv run python scripts/run_example_tests.py --weather\n```\n\n### Test Categories\n\n**Unit Tests:**\n\n- `test_config.py` - Configuration management (6 tests)\n- `test_claude_agent_client.py` - Claude Agent client helper (6 tests)\n- `test_claude_agent_chatbot.py` - Claude REPL commands and history (7 tests)\n- `test_gemini_client.py` - Gemini API client functionality (11 tests)\n- `test_chatbot.py` - Interactive chatbot features (23 tests)\n- `test_main.py` - Main entry point and CLI (8 tests)\n\n**MCP Framework Tests:**\n\n- `test_mcp_manager.py` - MCP client management (25+ tests)\n- `test_mcp_config.py` - MCP configuration handling (15+ tests)\n- `test_mcp_http_transport.py` - HTTP/SSE transport tests (20+ tests)\n- `test_mcp_multi_server.py` - Multi-server coordination (15+ tests)\n- `test_mcp_oauth.py` - OAuth authentication (20+ tests)\n- `test_mcp_retry.py` - Connection retry logic (10+ tests)\n\n**Example Server Tests:**\n\n- `test_filesystem_server.py` - Filesystem MCP server (44 tests)\n- `test_weather_server.py` - Weather MCP server (39 tests)\n\n**Integration Tests:**\n\n- `test_integration.py` - Full system integration scenarios\n\n### Test Coverage\n\nThe test suite covers:\n\n- ✅ **Configuration**: Environment variables, defaults, static methods\n- ✅ **Claude Agent**: Session lifecycle management, MCP registration, command handling\n- ✅ **Chatbot UI**: Commands, history, display formatting, input validation\n- ✅ **CLI Interface**: Argument parsing, exception handling, lifecycle management\n- ✅ **Integration**: End-to-end workflows, component interactions\n- ✅ **Error Handling**: Network failures, API errors, user interrupts\n\n### Test Features\n\n- **Comprehensive mocking** - No external API calls during testing\n- **No hanging tests** - Properly handles infinite loops and user input\n- **Fixtures and utilities** - Reusable test components in `conftest.py`\n- **Multiple test runners** - Standard pytest and custom runner with options\n- **CI/CD ready** - Configured for automated testing pipelines\n\n## Documentation\n\n- 📚 **[Documentation Index](docs/README.md)** - Complete documentation overview\n- 🤖 **[Claude Agent Guide](docs/claude-agent.md)** - Configure the Claude Agent SDK on Vertex AI\n- 📖 **[MCP User Guide](docs/mcp-guide.md)** - Comprehensive guide to using MCP features\n- ⚙️ **[MCP Configuration Reference](docs/mcp-config-reference.md)** - Detailed configuration options\n- 🔧 **[MCP API Reference](docs/mcp-api.md)** - Technical API documentation\n- 🔍 **[MCP Troubleshooting](docs/mcp-troubleshooting.md)** - Solutions to common problems\n- 🚀 **[Example MCP Servers](examples/README.md)** - Ready-to-use example servers\n- 🏗️ **[Implementation Details](plans/implement-mcp-client.md)** - Technical implementation notes\n\n## Development\n\nTo extend or modify the chatbot:\n\n### Architecture\n\n1. **`ClaudeAgentClient`** (`src/claude_agent_client.py`) - Creates Claude agents/sessions and sends messages\n2. **`ClaudeAgentChatbot`** (`src/claude_agent_chatbot.py`) - Terminal UI that wraps the Claude Agent SDK\n3. **`Config`** (`src/config.py`) - Centralised configuration management for Claude and Gemini helpers\n4. **`main.py`** - Entry point and CLI argument handling\n5. **Legacy Gemini modules** (`src/gemini_client.py`, `src/chatbot.py`) - Retained for backwards compatibility and tests\n\n### Adding New Features\n\n1. **New Commands**: Extend `ClaudeAgentChatbot.handle_command` for CLI additions\n2. **Model Parameters**: Modify settings in the `Config` class\n3. **API Features**: Add helpers to `ClaudeAgentClient` (or the fallback stub) for advanced SDK usage\n4. **UI Enhancements**: Update rendering helpers in `ClaudeAgentChatbot`\n\n### Development Workflow\n\n```bash\n# Set up development environment\nmake dev-setup        # Installs deps + pre-commit hooks\n\n# Run tests during development\nmake test             # Run all tests\nmake test-cov         # Run with coverage report\n\n# Code quality\nmake format           # Format code with black and isort\nmake lint             # Run flake8 linting\nmake pre-commit-run   # Run all pre-commit hooks\n\n# Dependency management\nmake add PKG=requests      # Add a new dependency\nmake add-dev PKG=pytest    # Add a dev dependency\nmake sync             # Sync dependencies from pyproject.toml\n\n# Clean up\nmake clean            # Remove Python cache files\nmake clean-all        # Remove cache + virtual environment\n```\n\n**Alternative (direct uv commands):**\n\n```bash\nuv sync --extra dev\nuv run pre-commit install\nuv run pytest tests/ -v --tb=short\nuv run black src/ tests/\nuv run isort src/ tests/\nuv run flake8 src/ tests/\n```\n\n### Writing Tests\n\nWhen adding new functionality:\n\n1. Add unit tests for individual methods/functions\n2. Add integration tests for feature workflows\n3. Use the fixtures in `tests/conftest.py` for common mocking\n4. Follow the existing test patterns and naming conventions\n5. Ensure tests don't make external API calls\n\n## Security Notes\n\n- Never commit your `.env` file or service account credentials\n- The `.gitignore` file is configured to exclude sensitive files\n- Store your service account JSON securely\n- Consider using Google Cloud Secret Manager for production deployments\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintertwine%2Fvertex-mcp-chatbot","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fintertwine%2Fvertex-mcp-chatbot","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fintertwine%2Fvertex-mcp-chatbot/lists"}