feat: add basic MCP implementation for connector building

CONTRIBUTING.md

@@ -0,0 +1,208 @@
+# Contributing to Builder MCP
+
+Thank you for your interest in contributing to the Builder MCP project! This guide will help you get started with development and testing.
+
+## Development Setup
+
+This project uses [uv](https://docs.astral.sh/uv/) for Python package management. Make sure you have uv installed:
+
+```bash
+# Install uv if you haven't already
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Quick Start
+
+1. **Clone the repository**:
+   ```bash
+   git clone https://github.com/airbytehq/builder-mcp.git
+   cd builder-mcp
+   ```
+
+2. **Install dependencies**:
+   ```bash
+   uv sync --all-extras
+   ```
+
+3. **Verify the installation**:
+   ```bash
+   uv run builder-mcp --help
+   ```
+
+## Development Workflow
+
+We use [Poe the Poet](https://poethepoet.natn.io/) for task automation. Install it with:
+
+```bash
+uv tool install poethepoet
+```
+
+### Available Tasks
+
+```bash
+# Install/sync dependencies
+poe install        # or: uv sync --all-extras
+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
+
+# Testing
+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
+
+# Combined workflows
+poe check         # Run lint + typecheck + test
+```
+
+### Manual Commands (without Poe)
+
+If you prefer to run commands directly with uv:
+
+```bash
+# Development
+uv sync --all-extras                              # Install dependencies
+uv run ruff format .                              # Format code
+uv run ruff check .                               # Lint code
+uv run mypy builder_mcp                           # Type checking
+uv run pytest tests/ -v                          # Run tests
+
+# MCP server
+uv run builder-mcp                                # Start server
+uv run fastmcp inspect builder_mcp/server.py:app # Inspect tools
+```
+
+## Testing
+
+The project includes comprehensive tests covering:
+
+- **Server functionality**: MCP server initialization and tool registration
+- **Connector builder tools**: Manifest validation, stream testing, and resolution
+- **Utility functions**: Configuration filtering and validation
+
+Run the full test suite:
+
+```bash
+poe test
+# or
+uv run pytest tests/ -v
+```
+
+### Testing with Real Connectors
+
+To test with actual Airbyte connector manifests:
+
+1. Prepare a connector manifest (JSON format)
+2. Use the MCP tools through the server or test them directly
+3. Verify that validation, stream testing, and resolution work as expected
+
+## Code Style
+
+We use [Ruff](https://docs.astral.sh/ruff/) for both linting and formatting:
+
+- **Line length**: 100 characters
+- **Target Python version**: 3.10+
+- **Import sorting**: Automatic with ruff
+- **Type hints**: Required for all public functions
+
+Before submitting changes:
+
+```bash
+poe check  # Runs formatting, linting, type checking, and tests
+```
+
+## MCP Tool Development
+
+When adding new MCP tools:
+
+1. **Add the tool function** in the appropriate module (e.g., `builder_mcp/_connector_builder.py`)
+2. **Use proper type annotations** with Pydantic models for complex inputs/outputs
+3. **Register the tool** in the module's registration function
+4. **Add comprehensive tests** covering success and failure cases
+5. **Update documentation** if the tool adds new capabilities
+
+### Tool Function Pattern
+
+```python
+from typing import Annotated
+from pydantic import Field
+from fastmcp import FastMCP
+
+def my_new_tool(
+    param: Annotated[
+        str,
+        Field(description="Description of the parameter"),
+    ],
+) -> MyResultModel:
+    """Tool description for MCP clients.
+
+    Args:
+        param: Parameter description
+
+    Returns:
+        Result description
+    """
+    # Implementation here
+    pass
+
+def register_tools(app: FastMCP) -> None:
+    """Register all tools with the FastMCP app."""
+    app.tool()(my_new_tool)
+```
+
+## AI Ownership Focus
+
+This project emphasizes **AI ownership** rather than AI assistance. When contributing:
+
+- **Design for autonomy**: Tools should enable end-to-end AI control of connector building
+- **Comprehensive error handling**: AI agents need clear error messages and recovery paths  
+- **Structured outputs**: Use Pydantic models for consistent, parseable responses
+- **Testing workflows**: Include tools that support automated testing and validation
+
+## Submitting Changes
+
+1. **Create a feature branch**: `git checkout -b feature/your-feature-name`
+2. **Make your changes** following the code style guidelines
+3. **Run the full test suite**: `poe check`
+4. **Commit with clear messages**: Use conventional commit format
+5. **Push and create a pull request**
+
+### Commit Message Format
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+feat: add new MCP tool for stream discovery
+fix: resolve manifest validation edge case
+docs: update contributing guidelines
+test: add integration tests for connector builder
+```
+
+## Getting Help
+
+- **Issues**: Report bugs and request features via GitHub Issues
+- **Discussions**: Use GitHub Discussions for questions and ideas
+- **Code Review**: All changes require review before merging
+
+## Project Structure
+
+```
+builder-mcp/
+├── 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! 🚀

README.md

@@ -1,2 +1,87 @@
 # builder-mcp
+
+## Overview
+
+The `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
+
+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:
+- Main server module that initializes FastMCP
+- Separate tool modules for different functional areas
+- Comprehensive connector building capabilities exposed as MCP tools
+
+### Available Tools
+
+- **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
+
+To use the Builder MCP server, you'll need Python 3.10+ and [uv](https://docs.astral.sh/uv/) for package management.
+
+For detailed development setup and contribution guidelines, see [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## Installation
+
+```bash
+uv sync --all-extras
+```
+
+## Usage
+
+Start the MCP server:
+
+```bash
+uv run builder-mcp
+```
+
+Or use with MCP clients by configuring the server in your MCP client configuration.
+
+### Using Poe Tasks
+
+For convenience, you can use [Poe the Poet](https://poethepoet.natn.io/) task runner:
+
+```bash
+# Install Poe
+uv tool install poethepoet
+
+# Then use ergonomic commands
+poe install     # Install dependencies
+poe server      # Start MCP server
+poe test        # Run tests
+poe check       # Run all checks (lint + typecheck + test)
+```
+
+## 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 builder_mcp
+```
 Helping robots build Airbyte connectors.

builder_mcp/__init__.py

@@ -0,0 +1,13 @@
+"""Builder MCP - Model Context Protocol server for Airbyte connector building.
+
+This package provides MCP tools for autonomous AI ownership of connector building processes,
+including manifest validation, stream testing, and configuration management.
+
+The focus is on end-to-end AI ownership rather than AI assist, enabling AI agents to
+fully control the connector development workflow including testing and PR creation.
+"""
+
+from builder_mcp import server
+
+__all__ = ["server"]
+__version__ = "0.1.0"