mirror of synced 2025-12-19 18:14:56 -05:00

Files

Aaron ("AJ") Steers 3b879abd1f docs: Reorganize MCP server documentation (#68205 )

## What

Reorganizes the MCP (Model Context Protocol) server documentation to
clearly distinguish between multiple Airbyte MCP servers and makes all
MCP documentation discoverable through the sidebar.

Requested by AJ Steers (@aaronsteers) in [this Devin
session](https://app.devin.ai/sessions/7f61ccb7731f4009b19076fa2b5df36d).

**Problem**: The existing MCP documentation only covered one remote MCP
server (the Heroku-hosted "fast-coder" server), but there are actually
four MCP servers:
1. The new PyAirbyte MCP (local STDIO server) - the recommended option
2. The PyAirbyte Fast-Coder MCP (remote Heroku server) - for rapid code
generation
3. The Connector Builder MCP (in development)
4. The Embedded Operator MCP (existed but wasn't in the sidebar)

## How

- **Renamed** `docs/ai-agents/pyairbyte-mcp/` →
`docs/ai-agents/pyairbyte-fast-coder-mcp/` (the old remote server)
- **Created** new `docs/ai-agents/pyairbyte-mcp/README.md` with
documentation for the new local STDIO MCP server (copied from the
docstring in `airbyte/mcp/__init__.py` in the PyAirbyte repo)
- **Created** `docs/ai-agents/connector-builder-mcp/README.md` as a
stub/"coming soon" page
- **Updated** `docusaurus/sidebar-ai-agents.js` to:
  - Group all four MCP servers under a "MCP Servers" category
  - Add the previously hidden Embedded Operator MCP to the sidebar
- **Updated** `docs/ai-agents/README.md` to describe all four MCP
servers with clear distinctions
- **Fixed** typo: "embedded source" → "embedded search" in the
Fast-Coder MCP docs

## Review guide

1. **`docs/ai-agents/README.md`** - Verify the high-level descriptions
of each MCP server are clear and accurate
2. **`docs/ai-agents/pyairbyte-mcp/README.md`** - Review the setup
instructions for the new PyAirbyte MCP (local server). This content was
copied from the PyAirbyte repo docstring - please verify it's complete
and correct.
3. **`docs/ai-agents/pyairbyte-fast-coder-mcp/README.md`** - Verify the
renamed "Fast-Coder" MCP docs are still accurate
4. **`docusaurus/sidebar-ai-agents.js`** - Check that the sidebar
structure makes sense with all four MCP servers grouped together
5. **`docs/ai-agents/connector-builder-mcp/README.md`** - Confirm the
stub page is appropriate for the in-development server

**Key distinction to verify**: The new "PyAirbyte MCP" (local,
recommended) vs "PyAirbyte Fast-Coder MCP" (remote, for code generation)
are clearly differentiated in the docs.

## User Impact

**Positive:**
- Users can now discover all available Airbyte MCP servers in one place
- The new PyAirbyte MCP (local STDIO server) is documented and
positioned as the recommended option
- The Embedded Operator MCP is now visible in the documentation sidebar
- Clear guidance on which MCP server to use for different use cases

**Potential confusion:**
- Having two PyAirbyte-related MCP servers might initially confuse
users, but the docs clearly explain the differences

## Can this PR be safely reverted and rolled back?

- [x] YES 💚

This is purely documentation changes with no code or infrastructure
changes. Rolling back would just restore the previous documentation
structure.

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

2025-10-21 03:30:24 +00:00