airbytehq · aaronsteers · Aug 6, 2025 · Aug 4, 2025 · Aug 4, 2025 · Aug 6, 2025
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -4,7 +4,12 @@ Thank you for your interest in contributing to the Builder MCP project! This gui
 
 ## Development Setup
 
-This project uses [uv](https://docs.astral.sh/uv/) for Python package management. Make sure you have uv installed:
+This project uses [uv](https://docs.astral.sh/uv/) for Python package management and follows modern Python development practices.
+
+### Prerequisites
+
+- Python 3.10+
+- [uv](https://docs.astral.sh/uv/) for package management
 
 ```bash
 # Install uv if you haven't already
@@ -14,55 +19,69 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 ### Quick Start
 
 1. **Clone the repository**:
+
    ```bash
    git clone https://github.com/airbytehq/connector-builder-mcp.git
    cd connector-builder-mcp
    ```
 
 2. **Install dependencies**:
+
    ```bash
    uv sync --all-extras
+   # Or:
+   poe sync
    ```
 
 3. **Verify the installation**:
+
    ```bash
    uv run connector-builder-mcp --help
    ```
 
-## Development Workflow
+### Using Poe Tasks
 
-We use [Poe the Poet](https://poethepoet.natn.io/) for task automation. Install it with:
+For convenience, install [Poe the Poet](https://poethepoet.natn.io/) task runner:
 
 ```bash
+# Install Poe
 uv tool install poethepoet
+
+# View all available commands
+poe --help
 ```
 
-### Available Tasks
+Available Poe commands:
 
 ```bash
-# Install/sync dependencies
-poe install        # or: uv sync --all-extras
-poe sync          # alias for install
+# Development
+poe install         # Install dependencies
+poe sync            # Alias for install
 
 # Code quality
-poe format        # Format code with ruff
-poe lint          # Lint code with ruff  
-poe lint-fix      # Lint and auto-fix issues
-poe typecheck     # Type check with mypy
+poe format          # Format code with ruff
+poe lint            # Lint code with ruff  
+poe lint-fix        # Lint and auto-fix issues
+poe typecheck       # Type check with mypy
+poe check           # Run all checks (lint + typecheck + test)
 
 # Testing
-poe test          # Run tests with verbose output
-poe test-fast     # Run tests, stop on first failure
+poe test            # Run tests with verbose output
+poe test-fast       # Run tests, stop on first failure
 
 # MCP server operations
-poe server        # Start the MCP server
-poe inspect       # Inspect available MCP tools
+poe mcp-serve-local # Serve with STDIO transport
+poe mcp-serve-http  # Serve over HTTP
+poe mcp-serve-sse   # Serve over SSE
+poe inspect         # Inspect available MCP tools
 
 # Combined workflows
-poe check         # Run lint + typecheck + test
+poe check           # Run lint + typecheck + test
 ```
 
-### Manual Commands (without Poe)
+You can see what any Poe task does by checking the `poe_tasks.toml` file at the root of the repo.
+
+## Manual Commands (without Poe)
 
 If you prefer to run commands directly with uv:
 
@@ -178,7 +197,7 @@ This project emphasizes **AI ownership** rather than AI assistance. When contrib
 
 We follow [Conventional Commits](https://www.conventionalcommits.org/):
 
-```
+```text
 feat: add new MCP tool for stream discovery
 fix: resolve manifest validation edge case
 docs: update contributing guidelines
@@ -191,18 +210,4 @@ test: add integration tests for connector builder
 - **Discussions**: Use GitHub Discussions for questions and ideas
 - **Code Review**: All changes require review before merging
 
-## Project Structure
-
-```
-connector-builder-mcp/
-├── connector_builder_mcp/  # Main package
-│   ├── server.py         # FastMCP server entry point
-│   ├── _connector_builder.py  # Connector building tools
-│   └── _util.py          # Shared utilities
-├── tests/                # Test suite
-├── poe_tasks.toml        # Task automation config
-├── pyproject.toml        # Project configuration
-└── CONTRIBUTING.md       # This file
-```
-
 Thank you for contributing to Builder MCP! 🚀
diff --git a/README.md b/README.md
@@ -1,49 +1,43 @@
 # connector-builder-mcp
 
-## Overview
-
-The `connector-builder-mcp` repository provides a Model Context Protocol (MCP) server implementation for Airbyte connector building operations. This repository will eventually codify relevant parts of the `builder-ai` functionality, with a focus on **AI ownership** rather than AI assist.
-
-### AI Ownership vs AI Assist
-
-This project emphasizes **end-to-end AI ownership**, including:
-
-- Autonomous connector building and testing
-- Automated PR creation and management
-- Complete workflow automation without human intervention
+*Helping robots build Airbyte connectors.*
 
-This differs from AI assist tools that merely help human developers - instead, this enables AI agents to fully own the connector development process from start to finish.
-
-## MCP Implementation
-
-The MCP server follows the established PyAirbyte pattern with:
+## Overview
 
-- Main server module that initializes FastMCP
-- Separate tool modules for different functional areas
-- Comprehensive connector building capabilities exposed as MCP tools
+A Model Context Protocol (MCP) server for Airbyte connector building operations, enabling **AI ownership** of the complete connector development lifecycle - from manifest validation to automated testing and PR creation.
 
-### Available Tools
+### Key Features
 
 - **Manifest Operations**: Validate and resolve connector manifests
 - **Stream Testing**: Test connector stream reading capabilities  
 - **Configuration Management**: Validate connector configurations
 - **Test Execution**: Run connector tests with proper limits and constraints
 
-## Getting Started
+## Quick Start
+
+**Prerequisites:**
 
-To use the Builder MCP server, you'll need Python 3.10+ and [uv](https://docs.astral.sh/uv/) for package management.
+- [uv](https://docs.astral.sh/uv/) for package management (`brew install uv`)
+- Python 3.10+ (`uv python install 3.10`)
 
-For detailed development setup and contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+If you are developing or testing locally, you will also want to install:
 
-## Installation
+- [PoeThePoet](https://poethepoet.natn.io) as a task manager (`uv tool install poethepoet`)
+
+*See the [Contributing Guide](CONTRIBUTING.md) or [Testing Guide](TESTING.md) for more information about working with the repo locally.*
+
+**Install:**
+
+The Poe `sync` and `install` commands are identical, giving a quick way to update your virtual environment or create one from scratch, if needed.
 
 ```bash
+# These are identical:
 uv sync --all-extras
+poe install
+poe sync
 ```
 
-## Manual Start
-
-Start the MCP server:
+**Run:**
 
 ```bash
 # You can use any of these to start the server manually:
@@ -53,28 +47,24 @@ poe mcp-serve-http
 poe mcp-serve-sse
 ```
 
-Or use with MCP clients by configuring the server in your MCP client configuration.
-
-### MCP Client Configuration
+## MCP Client Configuration
 
-To use the Builder MCP server with MCP clients like Claude Desktop, add the following configuration:
+To use with MCP clients like Claude Desktop, add the following configuration:
 
-#### Stable Version (Latest PyPI Release)
+### Stable Version (Latest PyPI Release)
 
 ```json
 {
   "mcpServers": {
     "connector-builder-mcp": {
       "command": "uvx",
-      "args": [
-        "connector-builder-mcp"
-      ]
+      "args": ["connector-builder-mcp"]
     }
   }
 }
 ```
 
-#### Development Version (Main Branch)
+### Development Version (Main Branch)
 
 ```json
 {
@@ -91,11 +81,7 @@ To use the Builder MCP server with MCP clients like Claude Desktop, add the foll
 }
 ```
 
-#### Repo Cloned Out Locally
-
-You can run from a locally cloned version of the repo using the below syntax.
-
-Remember to update the path to your actual repo location.
+### Local Development
 
 ```json
 {
@@ -113,6 +99,11 @@ Remember to update the path to your actual repo location.
 }
 ```
 
+## Contributing and Testing Guides
+
+- **[Contributing Guide](./CONTRIBUTING.md)** - Development setup, workflows, and contribution guidelines
+- **[Testing Guide](./TESTING.md)** - Comprehensive testing instructions and best practices
+
 ### Using Poe Tasks
 
 For convenience, you can use [Poe the Poet](https://poethepoet.natn.io/) task runner:
@@ -133,34 +124,3 @@ poe mcp-serve-sse   # Serve over SSE
 You can also run `poe --help` to see a full list of available Poe commands.
 
 If you ever want to see what a Poe task is doing (such as to run it directly or customize how it runs), check out the `poe_tasks.toml` file at the root of the repo.
-
-## Development
-
-This project uses [uv](https://docs.astral.sh/uv/) for package management and follows modern Python development practices.
-
-```bash
-# Install dependencies
-uv sync --all-extras
-
-# Run linting
-uv run ruff check .
-
-# Run formatting  
-uv run ruff format .
-
-# Run tests
-uv run pytest tests/ -v
-
-# Type checking
-uv run mypy connector_builder_mcp
-```
-
-Helping robots build Airbyte connectors.
-
-## Testing
-
-For comprehensive testing instructions, including FastMCP CLI tools and integration testing patterns, see the [Testing Guide](./TESTING.md).
-
-## Contributing
-
-See the [Contributing Guide](./CONTRIBUTING.md) for information on how to contribute.
diff --git a/TESTING.md b/TESTING.md
@@ -5,6 +5,7 @@ This guide provides comprehensive instructions for testing the Builder MCP serve
 ## Overview
 
 The Builder MCP server provides tools for Airbyte connector building operations. This guide covers:
+
 - Running the test suite
 - Manual testing with FastMCP CLI tools
 - Integration testing patterns
@@ -17,21 +18,26 @@ The Builder MCP server provides tools for Airbyte connector building operations.
 - [uv](https://docs.astral.sh/uv/) for package management
 - FastMCP 2.0 (installed automatically with dependencies)
 
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for detailed development setup instructions.
+
 ## Quick Start
 
 ### Install Dependencies
+
 ```bash
 poe sync
 # Equivalent to: uv sync --all-extras
 ```
 
 ### Run All Tests
+
 ```bash
 poe test
 # Equivalent to: uv run pytest tests/ -v
 ```
 
 ### Run Specific Test Categories
+
 ```bash
 # Run only integration tests
 uv run pytest tests/test_integration.py -v
@@ -65,12 +71,7 @@ poe inspect --help
 # Shows available options for the inspect command
 ```
 
-The inspection generates a comprehensive JSON report containing:
-- **Tools**: All available MCP tools with descriptions and input schemas
-- **Prompts**: Available prompt templates (currently 0)
-- **Resources**: Available resources (currently 0) 
-- **Templates**: Available templates (currently 0)
-- **Capabilities**: Server capabilities and features
+The inspection generates a comprehensive JSON report containing: **Tools**, **Prompts**, **Resources**, **Templates**, and **Capabilities**.
 
 #### Testing Specific Tools