feat: add Markdown MCP docs generator (Docusaurus- and pdoc-compatible)

Introduces `scripts/generate_mcp_markdown.py` (exposed via `poe mcp-docs-md`)
which introspects the MCP server with `fastmcp inspect` and renders a small
set of Markdown files under `docs/mcp-generated/`:

- index.md — server overview + counts + TOC
- tools.md — one H2 per tool with a GFM parameters table and collapsible
  input/output JSON schemas
- resources.md — concrete resources and resource templates
- prompts.md — prompts and their arguments

Formatting is modeled on `mcpdocs-gen` (evaluated in PR #1013) but emitted
as plain CommonMark + GFM + YAML front-matter + `<details>` blocks, so the
pages render correctly in both Docusaurus and `pdoc` without MDX-only
components. Every tool/resource/prompt has a stable slug anchor for
deep-linking.

Author: devin-ai-integration[bot]

.gitignore

@@ -11,6 +11,9 @@ viztracer_report.json
 # Packaged docs
 docs/*.zip
 
+# Generated MCP server docs (regenerate via `poe mcp-docs-md`)
+docs/mcp-generated/
+
 # Misc
 .DS_Store
 

docs/CONTRIBUTING.md

@@ -143,3 +143,29 @@ poe mcp-serve-sse      # Server-Sent Events transport on localhost:8000
 
 poe mcp-inspect        # Show all available MCP tools and their schemas
 ```
+
+### Generating Markdown docs for the MCP Server
+
+The repo ships a small script that introspects the MCP server via
+`fastmcp inspect` and emits a Markdown documentation site under
+`docs/mcp-generated/` (git-ignored). The output is designed to be both
+Docusaurus-hostable and `pdoc`-compatible — plain CommonMark with YAML
+front-matter, no MDX-only components.
+
+```bash
+uv sync --group dev
+poe mcp-docs-md
+```
+
+Four files are produced:
+
+- `index.md` — server overview (name, version, instructions, counts)
+- `tools.md` — one section per tool with a parameters table and collapsible
+  input/output JSON schemas
+- `resources.md` — concrete resources + resource templates
+- `prompts.md` — prompts and their arguments
+
+Each tool/resource/prompt has a stable slug anchor (e.g.
+`tools.md#list_connectors`) so the pages can be deep-linked from Slack, issues,
+or other docs. Regenerate after any change to MCP tool signatures, descriptions,
+or schemas. The underlying script is at `scripts/generate_mcp_markdown.py`.

pyproject.toml

@@ -174,6 +174,7 @@ mcp-serve-http = { cmd = "python -c \"from airbyte.mcp.server import app; app.ru
 mcp-serve-sse = { cmd = "python -c \"from airbyte.mcp.server import app; app.run(transport='sse', host='127.0.0.1', port=8000)\"", help = "Start the MCP server with SSE transport" }
 mcp-inspect = { cmd = "fastmcp inspect airbyte/mcp/server.py:app", help = "Inspect MCP tools and resources (supports --tools, --health, etc.)" }
 mcp-tool-test = { cmd = "python -m fastmcp_extensions.utils.test_tool --app airbyte.mcp.server:app", help = "Test MCP tools directly with JSON arguments: poe mcp-tool-test <tool_name> '<json_args>'" }
+mcp-docs-md = { cmd = "python scripts/generate_mcp_markdown.py", help = "Generate Markdown docs for the MCP server into docs/mcp-generated/ (Docusaurus- and pdoc-compatible)" }
 
 # Claude Code MCP Testing Tasks
 [tool.poe.tasks.test-my-tools]