diff --git a/CONTENT_GAPS_ANALYSIS.md b/CONTENT_GAPS_ANALYSIS.md index 2f5fb6b..68519d5 100644 --- a/CONTENT_GAPS_ANALYSIS.md +++ b/CONTENT_GAPS_ANALYSIS.md @@ -6,8 +6,8 @@ This document tracks structural and quality gaps that impact completeness and di | Metric | Value | |:-------|:------| -| Tutorial directories | 183 | -| Tutorials with exactly 8 numbered chapters | 180 | +| Tutorial directories | 185 | +| Tutorials with exactly 8 numbered chapters | 182 | | Tutorials with >8 numbered chapters | 3 | | Tutorials with 0 numbered chapters | 0 | | Tutorials with partial chapter coverage (1-7) | 0 | diff --git a/IMPORT_ROADMAP_TODO.md b/IMPORT_ROADMAP_TODO.md index 6816833..d30a427 100644 --- a/IMPORT_ROADMAP_TODO.md +++ b/IMPORT_ROADMAP_TODO.md @@ -69,6 +69,8 @@ This roadmap tracks the next highest-impact tutorial imports for `awesome-code-d | [`Fission-AI/OpenSpec`](https://github.com/Fission-AI/OpenSpec) | 23k+ | P1 | `pack-bv` | done | | [`sweepai/sweep`](https://github.com/sweepai/sweep) | 7k+ | P1 | `pack-bw` | done | | [`stagewise-io/stagewise`](https://github.com/stagewise-io/stagewise) | 6k+ | P1 | `pack-bw` | done | +| [`hangwin/mcp-chrome`](https://github.com/hangwin/mcp-chrome) | 10k+ | P1 | `pack-bx` | done | +| [`firecrawl/firecrawl-mcp-server`](https://github.com/firecrawl/firecrawl-mcp-server) | 5k+ | P1 | `pack-bx` | done | ## P2 (Strategic Extensions) diff --git a/README.md b/README.md index 8e72095..9ce6a34 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,8 @@ [![Awesome](https://awesome.re/badge.svg)](https://awesome.re) [![GitHub stars](https://img.shields.io/github/stars/johnxie/awesome-code-docs?style=social)](https://github.com/johnxie/awesome-code-docs) -[![Tutorials](https://img.shields.io/badge/tutorials-183-brightgreen.svg)](#-tutorial-catalog) -[![Content Hours](https://img.shields.io/badge/content-1960%2B%20hours-orange.svg)](#-tutorial-catalog) +[![Tutorials](https://img.shields.io/badge/tutorials-185-brightgreen.svg)](#-tutorial-catalog) +[![Content Hours](https://img.shields.io/badge/content-1980%2B%20hours-orange.svg)](#-tutorial-catalog) [![Last Updated](https://img.shields.io/github/last-commit/johnxie/awesome-code-docs?label=updated)](https://github.com/johnxie/awesome-code-docs/commits/main) [**Browse Tutorials**](#-tutorial-catalog) · [**A-Z Directory**](discoverability/tutorial-directory.md) · [**Learning Paths**](#-learning-paths) · [**Contributing**](#-contributing) · [**Community**](#-community) @@ -69,7 +69,7 @@ Use this quick-start map if you searched for a specific outcome. | build RAG systems | [LlamaIndex](tutorials/llamaindex-tutorial/) | [Haystack](tutorials/haystack-tutorial/) → [RAGFlow](tutorials/ragflow-tutorial/) | | run LLMs locally or at scale | [Ollama](tutorials/ollama-tutorial/) | [llama.cpp](tutorials/llama-cpp-tutorial/) → [vLLM](tutorials/vllm-tutorial/) → [LiteLLM](tutorials/litellm-tutorial/) | | build AI apps with TypeScript/Next.js | [Vercel AI SDK](tutorials/vercel-ai-tutorial/) | [CopilotKit](tutorials/copilotkit-tutorial/) → [LobeChat](tutorials/lobechat-ai-platform/) | -| build MCP tools and integrations | [MCP Python SDK](tutorials/mcp-python-sdk-tutorial/) | [FastMCP](tutorials/fastmcp-tutorial/) → [MCP Servers](tutorials/mcp-servers-tutorial/) → [MCP Quickstart Resources](tutorials/mcp-quickstart-resources-tutorial/) → [Create Python Server](tutorials/create-python-server-tutorial/) → [MCP Docs Repo](tutorials/mcp-docs-repo-tutorial/) → [Create TypeScript Server](tutorials/create-typescript-server-tutorial/) → [Awesome MCP Servers](tutorials/awesome-mcp-servers-tutorial/) → [Composio](tutorials/composio-tutorial/) → [Daytona](tutorials/daytona-tutorial/) → [GenAI Toolbox](tutorials/genai-toolbox-tutorial/) → [awslabs/mcp](tutorials/awslabs-mcp-tutorial/) → [MCP Inspector](tutorials/mcp-inspector-tutorial/) → [MCP Registry](tutorials/mcp-registry-tutorial/) → [MCP Specification](tutorials/mcp-specification-tutorial/) → [MCP TypeScript SDK](tutorials/mcp-typescript-sdk-tutorial/) → [MCP Go SDK](tutorials/mcp-go-sdk-tutorial/) → [MCP Rust SDK](tutorials/mcp-rust-sdk-tutorial/) → [MCP Java SDK](tutorials/mcp-java-sdk-tutorial/) → [MCP C# SDK](tutorials/mcp-csharp-sdk-tutorial/) → [MCP Swift SDK](tutorials/mcp-swift-sdk-tutorial/) → [MCP Kotlin SDK](tutorials/mcp-kotlin-sdk-tutorial/) → [MCP Ruby SDK](tutorials/mcp-ruby-sdk-tutorial/) → [MCP PHP SDK](tutorials/mcp-php-sdk-tutorial/) → [MCP Ext Apps](tutorials/mcp-ext-apps-tutorial/) → [MCPB](tutorials/mcpb-tutorial/) → [use-mcp](tutorials/use-mcp-tutorial/) → [MCP Use](tutorials/mcp-use-tutorial/) | +| build MCP tools and integrations | [MCP Python SDK](tutorials/mcp-python-sdk-tutorial/) | [FastMCP](tutorials/fastmcp-tutorial/) → [MCP Servers](tutorials/mcp-servers-tutorial/) → [MCP Quickstart Resources](tutorials/mcp-quickstart-resources-tutorial/) → [Create Python Server](tutorials/create-python-server-tutorial/) → [MCP Docs Repo](tutorials/mcp-docs-repo-tutorial/) → [Create TypeScript Server](tutorials/create-typescript-server-tutorial/) → [Awesome MCP Servers](tutorials/awesome-mcp-servers-tutorial/) → [Composio](tutorials/composio-tutorial/) → [Daytona](tutorials/daytona-tutorial/) → [GenAI Toolbox](tutorials/genai-toolbox-tutorial/) → [awslabs/mcp](tutorials/awslabs-mcp-tutorial/) → [MCP Inspector](tutorials/mcp-inspector-tutorial/) → [MCP Registry](tutorials/mcp-registry-tutorial/) → [MCP Specification](tutorials/mcp-specification-tutorial/) → [MCP TypeScript SDK](tutorials/mcp-typescript-sdk-tutorial/) → [MCP Go SDK](tutorials/mcp-go-sdk-tutorial/) → [MCP Rust SDK](tutorials/mcp-rust-sdk-tutorial/) → [MCP Java SDK](tutorials/mcp-java-sdk-tutorial/) → [MCP C# SDK](tutorials/mcp-csharp-sdk-tutorial/) → [MCP Swift SDK](tutorials/mcp-swift-sdk-tutorial/) → [MCP Kotlin SDK](tutorials/mcp-kotlin-sdk-tutorial/) → [MCP Ruby SDK](tutorials/mcp-ruby-sdk-tutorial/) → [MCP PHP SDK](tutorials/mcp-php-sdk-tutorial/) → [MCP Ext Apps](tutorials/mcp-ext-apps-tutorial/) → [MCPB](tutorials/mcpb-tutorial/) → [use-mcp](tutorials/use-mcp-tutorial/) → [MCP Use](tutorials/mcp-use-tutorial/) → [MCP Chrome](tutorials/mcp-chrome-tutorial/) → [Firecrawl MCP Server](tutorials/firecrawl-mcp-server-tutorial/) | --- @@ -103,7 +103,7 @@ This section tracks high-impact open-source vibe-coding and coding-agent ecosyst ``` ╔════════════════════════════════════════════════════════════╗ ║ 🤖 AI & AGENTS │ 🔧 DEV TOOLS │ 🗄️ DATA │ 🎤 SPEECH ║ - ║ 67+ tutorials │ 43 tutorials │ 14 tutorials │ 3 tutorials ║ + ║ 67+ tutorials │ 45 tutorials │ 14 tutorials │ 3 tutorials ║ ╚════════════════════════════════════════════════════════════╝ ``` @@ -255,6 +255,8 @@ AI coding assistants, build systems, and dev infrastructure. | **[MCPB](tutorials/mcpb-tutorial/)** | 1.7K+ | TypeScript/CLI | Official MCP bundle packaging format and CLI workflows for manifest authoring, packing, signing, and verification | | **[use-mcp](tutorials/use-mcp-tutorial/)** | 1.0K+ | TypeScript/React | Archived official React hook for MCP auth, connection lifecycle, and tool/resource/prompt client integration patterns | | **[MCP Use](tutorials/mcp-use-tutorial/)** | 9.1K+ | Python/TypeScript | Full-stack MCP agents, clients, servers, and inspector workflows across both runtimes | +| **[MCP Chrome](tutorials/mcp-chrome-tutorial/)** | 10.4K+ | TypeScript/Chrome Extension | Real-browser MCP automation with native messaging, network tooling, and semantic tab search | +| **[Firecrawl MCP Server](tutorials/firecrawl-mcp-server-tutorial/)** | 5.5K+ | TypeScript/Node | Official MCP web scraping/search server with retries, versioned endpoints, and multi-client integration paths | | **[OpenAI Python SDK](tutorials/openai-python-sdk-tutorial/)** | 29.8K+ | Python | GPT API, embeddings, assistants, batch processing | | **[tiktoken](tutorials/tiktoken-tutorial/)** | 17.1K+ | Python/Rust | Token counting, encoding, cost optimization | @@ -382,9 +384,9 @@ Continue ──→ Sweep ──→ OpenHands ──→ OpenCode ──→ Tabby > *"I want to build AI tool servers and extend Claude with custom capabilities"* ``` -MCP Python SDK ──→ FastMCP ──→ MCP Servers ──→ MCP Quickstart Resources ──→ Create Python Server ──→ MCP Docs Repo ──→ Create TypeScript Server ──→ Awesome MCP Servers ──→ Composio ──→ Daytona ──→ GenAI Toolbox ──→ awslabs/mcp ──→ MCP Inspector ──→ MCP Registry ──→ MCP Specification ──→ MCP TypeScript SDK ──→ MCP Go SDK ──→ MCP Rust SDK ──→ MCP Java SDK ──→ MCP C# SDK ──→ MCP Swift SDK ──→ MCP Kotlin SDK ──→ MCP Ruby SDK ──→ MCP PHP SDK ──→ MCP Ext Apps ──→ MCPB ──→ use-mcp ──→ MCP Use - (build (build servers (reference (multi-lang (python scaffold (archived docs (typescript scaffold (discovery and (tool + auth (sandbox (db-focused (aws server (debug + (publish + (protocol (client/server (go sdk + (rust rmcp + (java sdk + (csharp sdk + (swift sdk + (kmp core + (ruby server + (php server + (interactive ui + (bundle pack + (react hook + (full-stack - servers) fast) implementations) quickstart set) bootstrap path) migration map) bootstrap path) curation) runtime) infra) mcp control plane) ecosystem) transport tests) discovery ops) contract deep dive) sdk internals) conformance) task/oauth focus) spring modules) aspnet filters) lifecycle controls) transport model) client workflow) discovery model) host bridge model) sign verify) archived guidance) mcp workflows) +MCP Python SDK ──→ FastMCP ──→ MCP Servers ──→ MCP Quickstart Resources ──→ Create Python Server ──→ MCP Docs Repo ──→ Create TypeScript Server ──→ Awesome MCP Servers ──→ Composio ──→ Daytona ──→ GenAI Toolbox ──→ awslabs/mcp ──→ MCP Inspector ──→ MCP Registry ──→ MCP Specification ──→ MCP TypeScript SDK ──→ MCP Go SDK ──→ MCP Rust SDK ──→ MCP Java SDK ──→ MCP C# SDK ──→ MCP Swift SDK ──→ MCP Kotlin SDK ──→ MCP Ruby SDK ──→ MCP PHP SDK ──→ MCP Ext Apps ──→ MCPB ──→ use-mcp ──→ MCP Use ──→ MCP Chrome ──→ Firecrawl MCP Server + (build (build servers (reference (multi-lang (python scaffold (archived docs (typescript scaffold (discovery and (tool + auth (sandbox (db-focused (aws server (debug + (publish + (protocol (client/server (go sdk + (rust rmcp + (java sdk + (csharp sdk + (swift sdk + (kmp core + (ruby server + (php server + (interactive ui + (bundle pack + (react hook + (full-stack (chrome native + (web scrape + + servers) fast) implementations) quickstart set) bootstrap path) migration map) bootstrap path) curation) runtime) infra) mcp control plane) ecosystem) transport tests) discovery ops) contract deep dive) sdk internals) conformance) task/oauth focus) spring modules) aspnet filters) lifecycle controls) transport model) client workflow) discovery model) host bridge model) sign verify) archived guidance) mcp workflows) semantic tabs) search/crawl) ``` **Duration:** 100-135 hours | **Difficulty:** Intermediate to Advanced @@ -434,10 +436,10 @@ Dyad ──→ bolt.diy ──→ Stagewise ──→ Cline ──→ Roo Code ╔══════════════════════════════════════════════════════════╗ ║ COLLECTION OVERVIEW ║ ╠══════════════════════════════════════════════════════════╣ -║ 📦 Total Tutorials 183 ║ -║ 📝 Numbered Chapters 1,467 ║ -║ 📏 Tutorial Markdown 476,000+ lines ║ -║ ⏱️ Estimated Hours 1,960+ ║ +║ 📦 Total Tutorials 185 ║ +║ 📝 Numbered Chapters 1,483 ║ +║ 📏 Tutorial Markdown 477,000+ lines ║ +║ ⏱️ Estimated Hours 1,980+ ║ ║ ✅ Local Broken Links 0 ║ ║ 🧭 Structure Drift 0 (all root canonical) ║ ╚══════════════════════════════════════════════════════════╝ diff --git a/TUTORIAL_STRUCTURE.md b/TUTORIAL_STRUCTURE.md index b059ee4..0cf0018 100644 --- a/TUTORIAL_STRUCTURE.md +++ b/TUTORIAL_STRUCTURE.md @@ -17,7 +17,7 @@ tutorials// | Pattern | Count | |:--------|:------| -| `root_only` | 183 | +| `root_only` | 185 | | `docs_only` | 0 | | `index_only` | 0 | | `mixed` | 0 | diff --git a/categories/ai-ml-platforms.md b/categories/ai-ml-platforms.md index e3b3520..5a88759 100644 --- a/categories/ai-ml-platforms.md +++ b/categories/ai-ml-platforms.md @@ -4,7 +4,7 @@ ## Snapshot (February 12, 2026) -- repository-wide tutorials: **183** +- repository-wide tutorials: **185** - AI/agent + developer-tooling coverage: **largest cluster in the catalog** - canonical structure status: **all tracks publish full chapter sets** @@ -18,7 +18,7 @@ | Run spec-driven AI delivery workflows | [OpenSpec](../tutorials/openspec-tutorial/) | [Claude Task Master](../tutorials/claude-task-master-tutorial/) → [Codex CLI](../tutorials/codex-cli-tutorial/) | | Build RAG systems | [LlamaIndex](../tutorials/llamaindex-tutorial/) | [Haystack](../tutorials/haystack-tutorial/) → [RAGFlow](../tutorials/ragflow-tutorial/) | | Run LLMs in production | [Ollama](../tutorials/ollama-tutorial/) | [vLLM](../tutorials/vllm-tutorial/) → [LiteLLM](../tutorials/litellm-tutorial/) | -| Build MCP integrations | [MCP Python SDK](../tutorials/mcp-python-sdk-tutorial/) | [FastMCP](../tutorials/fastmcp-tutorial/) → [MCP Servers](../tutorials/mcp-servers-tutorial/) → [MCP Quickstart Resources](../tutorials/mcp-quickstart-resources-tutorial/) → [Create Python Server](../tutorials/create-python-server-tutorial/) → [MCP Docs Repo](../tutorials/mcp-docs-repo-tutorial/) → [Create TypeScript Server](../tutorials/create-typescript-server-tutorial/) → [Awesome MCP Servers](../tutorials/awesome-mcp-servers-tutorial/) → [Composio](../tutorials/composio-tutorial/) → [Daytona](../tutorials/daytona-tutorial/) → [GenAI Toolbox](../tutorials/genai-toolbox-tutorial/) → [awslabs/mcp](../tutorials/awslabs-mcp-tutorial/) → [MCP Inspector](../tutorials/mcp-inspector-tutorial/) → [MCP Registry](../tutorials/mcp-registry-tutorial/) → [MCP Specification](../tutorials/mcp-specification-tutorial/) → [MCP TypeScript SDK](../tutorials/mcp-typescript-sdk-tutorial/) → [MCP Go SDK](../tutorials/mcp-go-sdk-tutorial/) → [MCP Rust SDK](../tutorials/mcp-rust-sdk-tutorial/) → [MCP Java SDK](../tutorials/mcp-java-sdk-tutorial/) → [MCP C# SDK](../tutorials/mcp-csharp-sdk-tutorial/) → [MCP Swift SDK](../tutorials/mcp-swift-sdk-tutorial/) → [MCP Kotlin SDK](../tutorials/mcp-kotlin-sdk-tutorial/) → [MCP Ruby SDK](../tutorials/mcp-ruby-sdk-tutorial/) → [MCP PHP SDK](../tutorials/mcp-php-sdk-tutorial/) → [MCP Ext Apps](../tutorials/mcp-ext-apps-tutorial/) → [MCPB](../tutorials/mcpb-tutorial/) → [use-mcp](../tutorials/use-mcp-tutorial/) → [MCP Use](../tutorials/mcp-use-tutorial/) | +| Build MCP integrations | [MCP Python SDK](../tutorials/mcp-python-sdk-tutorial/) | [FastMCP](../tutorials/fastmcp-tutorial/) → [MCP Servers](../tutorials/mcp-servers-tutorial/) → [MCP Quickstart Resources](../tutorials/mcp-quickstart-resources-tutorial/) → [Create Python Server](../tutorials/create-python-server-tutorial/) → [MCP Docs Repo](../tutorials/mcp-docs-repo-tutorial/) → [Create TypeScript Server](../tutorials/create-typescript-server-tutorial/) → [Awesome MCP Servers](../tutorials/awesome-mcp-servers-tutorial/) → [Composio](../tutorials/composio-tutorial/) → [Daytona](../tutorials/daytona-tutorial/) → [GenAI Toolbox](../tutorials/genai-toolbox-tutorial/) → [awslabs/mcp](../tutorials/awslabs-mcp-tutorial/) → [MCP Inspector](../tutorials/mcp-inspector-tutorial/) → [MCP Registry](../tutorials/mcp-registry-tutorial/) → [MCP Specification](../tutorials/mcp-specification-tutorial/) → [MCP TypeScript SDK](../tutorials/mcp-typescript-sdk-tutorial/) → [MCP Go SDK](../tutorials/mcp-go-sdk-tutorial/) → [MCP Rust SDK](../tutorials/mcp-rust-sdk-tutorial/) → [MCP Java SDK](../tutorials/mcp-java-sdk-tutorial/) → [MCP C# SDK](../tutorials/mcp-csharp-sdk-tutorial/) → [MCP Swift SDK](../tutorials/mcp-swift-sdk-tutorial/) → [MCP Kotlin SDK](../tutorials/mcp-kotlin-sdk-tutorial/) → [MCP Ruby SDK](../tutorials/mcp-ruby-sdk-tutorial/) → [MCP PHP SDK](../tutorials/mcp-php-sdk-tutorial/) → [MCP Ext Apps](../tutorials/mcp-ext-apps-tutorial/) → [MCPB](../tutorials/mcpb-tutorial/) → [use-mcp](../tutorials/use-mcp-tutorial/) → [MCP Use](../tutorials/mcp-use-tutorial/) → [MCP Chrome](../tutorials/mcp-chrome-tutorial/) → [Firecrawl MCP Server](../tutorials/firecrawl-mcp-server-tutorial/) | ## Featured AI/ML Tutorial Tracks @@ -58,6 +58,8 @@ - [MCP Docs Repo](../tutorials/mcp-docs-repo-tutorial/) - [Create TypeScript Server](../tutorials/create-typescript-server-tutorial/) - [MCP Use](../tutorials/mcp-use-tutorial/) +- [MCP Chrome](../tutorials/mcp-chrome-tutorial/) +- [Firecrawl MCP Server](../tutorials/firecrawl-mcp-server-tutorial/) - [OpenAI Python SDK](../tutorials/openai-python-sdk-tutorial/) - [OpenAI Realtime Agents](../tutorials/openai-realtime-agents-tutorial/) diff --git a/discoverability/tutorial-directory.md b/discoverability/tutorial-directory.md index f05afa1..d374da7 100644 --- a/discoverability/tutorial-directory.md +++ b/discoverability/tutorial-directory.md @@ -2,7 +2,7 @@ This page is auto-generated from the tutorial index and is intended as a fast browse surface for contributors and search crawlers. -- Total tutorials: **183** +- Total tutorials: **185** - Source: `scripts/generate_discoverability_assets.py` ## A @@ -142,6 +142,8 @@ This page is auto-generated from the tutorial index and is intended as a fast br - Learn how to use `jlowin/fastmcp` to design, run, test, and deploy MCP servers and clients with practical transport, integration, auth, and operations patterns. - [Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents](https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/figma-context-mcp-tutorial/index.md) - Learn how to use `GLips/Figma-Context-MCP` (Framelink MCP for Figma) to give coding agents structured design context for higher-fidelity implementation. +- [Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients](https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/firecrawl-mcp-server-tutorial/index.md) + - Learn how to use `firecrawl/firecrawl-mcp-server` to add robust web scraping, crawling, search, and extraction capabilities to MCP-enabled coding and research agents. - [Firecrawl Tutorial: Building LLM-Ready Web Scraping and Data Extraction Systems](https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/firecrawl-tutorial/index.md) - Deep technical walkthrough. - [Fireproof Tutorial: Local-First Document Database for AI-Native Apps](https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/fireproof-tutorial/index.md) @@ -232,6 +234,8 @@ This page is auto-generated from the tutorial index and is intended as a fast br - A deep technical walkthrough of Microsoft AutoGen covering Building Multi-Agent AI Systems. - [Mastra Tutorial: TypeScript Framework for AI Agents and Workflows](https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/mastra-tutorial/index.md) - Learn how to build production AI applications with `mastra-ai/mastra`, including agents, workflows, memory, MCP tooling, and reliability operations. +- [MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP](https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/mcp-chrome-tutorial/index.md) + - Learn how to use `hangwin/mcp-chrome` to expose browser automation, content analysis, and semantic tab search tools to MCP clients. - [MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows](https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/mcp-csharp-sdk-tutorial/index.md) - Learn how to build and operate MCP clients and servers with `modelcontextprotocol/csharp-sdk`, including package choices, auth patterns, tasks, diagnostics, and versioning strategy. - [MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository](https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/mcp-docs-repo-tutorial/index.md) diff --git a/discoverability/tutorial-index.json b/discoverability/tutorial-index.json index 56aa43e..23d00be 100644 --- a/discoverability/tutorial-index.json +++ b/discoverability/tutorial-index.json @@ -1,6 +1,6 @@ { "project": "awesome-code-docs", - "tutorial_count": 183, + "tutorial_count": 185, "tutorials": [ { "file_url": "https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/activepieces-tutorial/index.md", @@ -1684,6 +1684,35 @@ "summary": "Learn how to use `GLips/Figma-Context-MCP` (Framelink MCP for Figma) to give coding agents structured design context for higher-fidelity implementation.", "title": "Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents" }, + { + "file_url": "https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/firecrawl-mcp-server-tutorial/index.md", + "index_path": "tutorials/firecrawl-mcp-server-tutorial/index.md", + "keywords": [ + "firecrawl", + "mcp", + "server", + "web", + "scraping", + "search", + "tools", + "clients", + "learn", + "use", + "add", + "robust", + "crawling", + "extraction", + "capabilities", + "enabled", + "coding", + "research" + ], + "path": "tutorials/firecrawl-mcp-server-tutorial", + "repo_url": "https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/firecrawl-mcp-server-tutorial", + "slug": "firecrawl-mcp-server-tutorial", + "summary": "Learn how to use `firecrawl/firecrawl-mcp-server` to add robust web scraping, crawling, search, and extraction capabilities to MCP-enabled coding and research agents.", + "title": "Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients" + }, { "file_url": "https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/firecrawl-tutorial/index.md", "index_path": "tutorials/firecrawl-tutorial/index.md", @@ -2560,6 +2589,35 @@ "summary": "Learn how to build production AI applications with `mastra-ai/mastra`, including agents, workflows, memory, MCP tooling, and reliability operations.", "title": "Mastra Tutorial: TypeScript Framework for AI Agents and Workflows" }, + { + "file_url": "https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/mcp-chrome-tutorial/index.md", + "index_path": "tutorials/mcp-chrome-tutorial/index.md", + "keywords": [ + "mcp", + "chrome", + "control", + "real", + "browser", + "through", + "learn", + "use", + "hangwin", + "expose", + "automation", + "content", + "analysis", + "semantic", + "tab", + "search", + "tools", + "clients" + ], + "path": "tutorials/mcp-chrome-tutorial", + "repo_url": "https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/mcp-chrome-tutorial", + "slug": "mcp-chrome-tutorial", + "summary": "Learn how to use `hangwin/mcp-chrome` to expose browser automation, content analysis, and semantic tab search tools to MCP clients.", + "title": "MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP" + }, { "file_url": "https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/mcp-csharp-sdk-tutorial/index.md", "index_path": "tutorials/mcp-csharp-sdk-tutorial/index.md", diff --git a/llms-full.txt b/llms-full.txt index 3c0a78f..c709e03 100644 --- a/llms-full.txt +++ b/llms-full.txt @@ -375,6 +375,12 @@ Main repository: - Summary: Learn how to use `GLips/Figma-Context-MCP` (Framelink MCP for Figma) to give coding agents structured design context for higher-fidelity implementation. - Keywords: figma, context, mcp, design, code, workflows, coding, agents, learn, use, glips, framelink, give, structured, higher, fidelity, implementation +## Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients +- Path: tutorials/firecrawl-mcp-server-tutorial +- Index: https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/firecrawl-mcp-server-tutorial/index.md +- Summary: Learn how to use `firecrawl/firecrawl-mcp-server` to add robust web scraping, crawling, search, and extraction capabilities to MCP-enabled coding and research agents. +- Keywords: firecrawl, mcp, server, web, scraping, search, tools, clients, learn, use, add, robust, crawling, extraction, capabilities, enabled, coding, research + ## Firecrawl Tutorial: Building LLM-Ready Web Scraping and Data Extraction Systems - Path: tutorials/firecrawl-tutorial - Index: https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/firecrawl-tutorial/index.md @@ -579,6 +585,12 @@ Main repository: - Summary: Learn how to build production AI applications with `mastra-ai/mastra`, including agents, workflows, memory, MCP tooling, and reliability operations. - Keywords: mastra, typescript, framework, agents, workflows, learn, build, production, applications, including, memory, mcp, tooling, reliability, operations +## MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP +- Path: tutorials/mcp-chrome-tutorial +- Index: https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/mcp-chrome-tutorial/index.md +- Summary: Learn how to use `hangwin/mcp-chrome` to expose browser automation, content analysis, and semantic tab search tools to MCP clients. +- Keywords: mcp, chrome, control, real, browser, through, learn, use, hangwin, expose, automation, content, analysis, semantic, tab, search, tools, clients + ## MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows - Path: tutorials/mcp-csharp-sdk-tutorial - Index: https://github.com/johnxie/awesome-code-docs/blob/main/tutorials/mcp-csharp-sdk-tutorial/index.md diff --git a/llms.txt b/llms.txt index 716c2e2..59b9fa8 100644 --- a/llms.txt +++ b/llms.txt @@ -76,6 +76,7 @@ - Fabric Tutorial: Open-Source Framework for Augmenting Humans with AI: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/fabric-tutorial - FastMCP Tutorial: Building and Operating MCP Servers with Pythonic Control: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/fastmcp-tutorial - Figma Context MCP Tutorial: Design-to-Code Workflows for Coding Agents: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/figma-context-mcp-tutorial +- Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/firecrawl-mcp-server-tutorial - Firecrawl Tutorial: Building LLM-Ready Web Scraping and Data Extraction Systems: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/firecrawl-tutorial - Fireproof Tutorial: Local-First Document Database for AI-Native Apps: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/fireproof-tutorial - Flowise LLM Orchestration: Deep Dive Tutorial: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/flowise-llm-orchestration @@ -110,6 +111,7 @@ - LocalAI Tutorial: Self-Hosted OpenAI Alternative: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/localai-tutorial - Logseq: Deep Dive Tutorial: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/logseq-knowledge-management - Mastra Tutorial: TypeScript Framework for AI Agents and Workflows: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/mastra-tutorial +- MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/mcp-chrome-tutorial - MCP C# SDK Tutorial: Production MCP in .NET with Hosting, ASP.NET Core, and Task Workflows: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/mcp-csharp-sdk-tutorial - MCP Docs Repo Tutorial: Navigating the Archived MCP Documentation Repository: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/mcp-docs-repo-tutorial - MCP Ext Apps Tutorial: Building Interactive MCP Apps and Hosts: https://github.com/johnxie/awesome-code-docs/tree/main/tutorials/mcp-ext-apps-tutorial diff --git a/tutorials/README.md b/tutorials/README.md index 8d08ad5..fb3e8a2 100644 --- a/tutorials/README.md +++ b/tutorials/README.md @@ -11,15 +11,15 @@ This file describes the structure of `tutorials/` and points to the authoritativ | Metric | Value | |:-------|:------| -| Tutorial directories | 183 | -| Tutorial markdown files | 1660 | -| Tutorial markdown lines | 476,790 | +| Tutorial directories | 185 | +| Tutorial markdown files | 1678 | +| Tutorial markdown lines | 477,603 | ## Content Structure Patterns | Pattern | Count | Description | |:--------|:------|:------------| -| Root chapter files | 183 | `index.md` + top-level `01-...md` to `08-...md` | +| Root chapter files | 185 | `index.md` + top-level `01-...md` to `08-...md` | | `docs/` chapter files | 0 | Deprecated and fully migrated | | Index-only roadmap | 0 | All catalog entries publish full chapter sets | | Mixed root + `docs/` | 0 | Legacy hybrid layout removed | diff --git a/tutorials/firecrawl-mcp-server-tutorial/01-getting-started-and-core-setup.md b/tutorials/firecrawl-mcp-server-tutorial/01-getting-started-and-core-setup.md new file mode 100644 index 0000000..8389800 --- /dev/null +++ b/tutorials/firecrawl-mcp-server-tutorial/01-getting-started-and-core-setup.md @@ -0,0 +1,39 @@ +--- +layout: default +title: "Chapter 1: Getting Started and Core Setup" +nav_order: 1 +parent: Firecrawl MCP Server Tutorial +--- + +# Chapter 1: Getting Started and Core Setup + +This chapter gets Firecrawl MCP running with minimum viable configuration. + +## Learning Goals + +- launch Firecrawl MCP with cloud credentials +- verify tool availability in your client +- capture initial connectivity checks + +## Quick Start Command + +```bash +env FIRECRAWL_API_KEY=fc-YOUR_API_KEY npx -y firecrawl-mcp +``` + +## First-Run Checklist + +1. API key is valid +2. client connects to server process +3. at least one scrape/search call succeeds +4. logs show no repeated auth or rate-limit failures + +## Source References + +- [README Installation](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md) + +## Summary + +You now have a working Firecrawl MCP baseline. + +Next: [Chapter 2: Architecture, Transports, and Versioning](02-architecture-transports-and-versioning.md) diff --git a/tutorials/firecrawl-mcp-server-tutorial/02-architecture-transports-and-versioning.md b/tutorials/firecrawl-mcp-server-tutorial/02-architecture-transports-and-versioning.md new file mode 100644 index 0000000..bdd443c --- /dev/null +++ b/tutorials/firecrawl-mcp-server-tutorial/02-architecture-transports-and-versioning.md @@ -0,0 +1,40 @@ +--- +layout: default +title: "Chapter 2: Architecture, Transports, and Versioning" +nav_order: 2 +parent: Firecrawl MCP Server Tutorial +--- + +# Chapter 2: Architecture, Transports, and Versioning + +Firecrawl MCP supports local transports and cloud-mode versioned endpoints, with V2 as the default modern path. + +## Learning Goals + +- understand transport mode implications +- map V1 vs V2 endpoint differences +- avoid migration mistakes in existing integrations + +## Endpoint Model Highlights + +| Mode | Notes | +|:-----|:------| +| local stdio/streamable | V2 behavior by default | +| cloud service mode | versioned V1 and V2 endpoint paths | + +## Versioning Guidance + +- V1 endpoints remain for backward compatibility. +- V2 is the current path for modern tool behavior and API support. +- migration requires endpoint and tool-surface awareness. + +## Source References + +- [Versioning Guide](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md) +- [README Transport Setup](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md) + +## Summary + +You now understand the transport and version boundaries that shape deployment architecture. + +Next: [Chapter 3: Tool Selection: Scrape, Map, Crawl, Search, Extract](03-tool-selection-scrape-map-crawl-search-extract.md) diff --git a/tutorials/firecrawl-mcp-server-tutorial/03-tool-selection-scrape-map-crawl-search-extract.md b/tutorials/firecrawl-mcp-server-tutorial/03-tool-selection-scrape-map-crawl-search-extract.md new file mode 100644 index 0000000..776ceb1 --- /dev/null +++ b/tutorials/firecrawl-mcp-server-tutorial/03-tool-selection-scrape-map-crawl-search-extract.md @@ -0,0 +1,37 @@ +--- +layout: default +title: "Chapter 3: Tool Selection: Scrape, Map, Crawl, Search, Extract" +nav_order: 3 +parent: Firecrawl MCP Server Tutorial +--- + +# Chapter 3: Tool Selection: Scrape, Map, Crawl, Search, Extract + +Effective Firecrawl usage depends on selecting the right tool for each information-retrieval task. + +## Learning Goals + +- choose tools based on known vs unknown URL scope +- combine tools for multi-step research tasks +- avoid over-crawling when simpler methods suffice + +## Tool Selection Matrix + +| Task Type | Preferred Tool | +|:----------|:---------------| +| single known URL | `scrape` | +| many known URLs | batch scrape variants | +| discover URLs on a domain | `map` | +| broad web discovery | `search` | +| large site traversal | `crawl` with strict limits | +| structured extraction | `extract` with schema guidance | + +## Source References + +- [README Tool Guide](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md) + +## Summary + +You now have a decision framework for tool selection that balances depth, cost, and speed. + +Next: [Chapter 4: Client Integrations: Cursor, Claude, Windsurf, VS Code](04-client-integrations-cursor-claude-windsurf-vscode.md) diff --git a/tutorials/firecrawl-mcp-server-tutorial/04-client-integrations-cursor-claude-windsurf-vscode.md b/tutorials/firecrawl-mcp-server-tutorial/04-client-integrations-cursor-claude-windsurf-vscode.md new file mode 100644 index 0000000..acb3748 --- /dev/null +++ b/tutorials/firecrawl-mcp-server-tutorial/04-client-integrations-cursor-claude-windsurf-vscode.md @@ -0,0 +1,35 @@ +--- +layout: default +title: "Chapter 4: Client Integrations: Cursor, Claude, Windsurf, VS Code" +nav_order: 4 +parent: Firecrawl MCP Server Tutorial +--- + +# Chapter 4: Client Integrations: Cursor, Claude, Windsurf, VS Code + +Firecrawl MCP is widely used because it can be configured across major coding-agent clients. + +## Learning Goals + +- configure Firecrawl MCP for major client ecosystems +- standardize environment key handling across clients +- reduce configuration drift between local and team setups + +## Integration Patterns + +| Client | Integration Style | +|:-------|:------------------| +| Cursor | MCP server JSON in settings | +| Claude Desktop | `claude_desktop_config.json` command block | +| Windsurf | model config MCP section | +| VS Code | `mcp.servers` or workspace `mcp.json` | + +## Source References + +- [README Client Config Sections](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md) + +## Summary + +You now have a cross-client setup model for consistent Firecrawl MCP usage. + +Next: [Chapter 5: Configuration, Retries, and Credit Monitoring](05-configuration-retries-and-credit-monitoring.md) diff --git a/tutorials/firecrawl-mcp-server-tutorial/05-configuration-retries-and-credit-monitoring.md b/tutorials/firecrawl-mcp-server-tutorial/05-configuration-retries-and-credit-monitoring.md new file mode 100644 index 0000000..ff483af --- /dev/null +++ b/tutorials/firecrawl-mcp-server-tutorial/05-configuration-retries-and-credit-monitoring.md @@ -0,0 +1,36 @@ +--- +layout: default +title: "Chapter 5: Configuration, Retries, and Credit Monitoring" +nav_order: 5 +parent: Firecrawl MCP Server Tutorial +--- + +# Chapter 5: Configuration, Retries, and Credit Monitoring + +Production reliability depends on proper retry controls and credit thresholds. + +## Learning Goals + +- configure retry behavior for rate-limited environments +- tune warning and critical thresholds for credits +- support cloud and self-hosted API endpoints cleanly + +## Key Environment Variables + +| Variable | Purpose | +|:---------|:--------| +| `FIRECRAWL_API_KEY` | authentication for cloud usage | +| `FIRECRAWL_API_URL` | custom endpoint for self-hosted deployments | +| `FIRECRAWL_RETRY_*` | retry/backoff behavior controls | +| `FIRECRAWL_CREDIT_*` | warning and critical credit thresholds | + +## Source References + +- [README Configuration](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md) +- [Changelog 1.2.4 and 1.2.0](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md) + +## Summary + +You now know which controls matter most for resilient Firecrawl MCP operations. + +Next: [Chapter 6: Batch Workflows, Deep Research, and API Evolution](06-batch-workflows-deep-research-and-api-evolution.md) diff --git a/tutorials/firecrawl-mcp-server-tutorial/06-batch-workflows-deep-research-and-api-evolution.md b/tutorials/firecrawl-mcp-server-tutorial/06-batch-workflows-deep-research-and-api-evolution.md new file mode 100644 index 0000000..c44fc6e --- /dev/null +++ b/tutorials/firecrawl-mcp-server-tutorial/06-batch-workflows-deep-research-and-api-evolution.md @@ -0,0 +1,34 @@ +--- +layout: default +title: "Chapter 6: Batch Workflows, Deep Research, and API Evolution" +nav_order: 6 +parent: Firecrawl MCP Server Tutorial +--- + +# Chapter 6: Batch Workflows, Deep Research, and API Evolution + +Firecrawl MCP has evolved from legacy V1 tooling to modern V2 behavior; teams need to plan around those differences. + +## Learning Goals + +- understand batch processing behavior and limits +- map V1-only capabilities versus V2 defaults +- plan endpoint migration without breaking clients + +## Evolution Highlights + +| Version | Notable Focus | +|:--------|:--------------| +| V1 | legacy endpoints plus deep-research/llmstxt oriented tools | +| V2 | modern API methods, improved extraction/search behavior | + +## Source References + +- [Versioning Guide](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md) +- [README Tool Guidance](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md) + +## Summary + +You now have a migration-aware perspective on batch and advanced Firecrawl MCP usage. + +Next: [Chapter 7: Reliability, Observability, and Failure Handling](07-reliability-observability-and-failure-handling.md) diff --git a/tutorials/firecrawl-mcp-server-tutorial/07-reliability-observability-and-failure-handling.md b/tutorials/firecrawl-mcp-server-tutorial/07-reliability-observability-and-failure-handling.md new file mode 100644 index 0000000..a405c66 --- /dev/null +++ b/tutorials/firecrawl-mcp-server-tutorial/07-reliability-observability-and-failure-handling.md @@ -0,0 +1,34 @@ +--- +layout: default +title: "Chapter 7: Reliability, Observability, and Failure Handling" +nav_order: 7 +parent: Firecrawl MCP Server Tutorial +--- + +# Chapter 7: Reliability, Observability, and Failure Handling + +This chapter turns error handling and operational controls into an explicit runbook. + +## Learning Goals + +- detect and handle rate-limit and transient failure patterns +- instrument enough logging to debug tool-call failures +- prevent runaway crawl workloads + +## Reliability Practices + +1. set retry values intentionally for your workload profile +2. cap crawl depth and scope per request +3. monitor credit thresholds and alert before service interruption +4. track client errors by transport and endpoint version + +## Source References + +- [README Rate Limiting and Configuration](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md) +- [Changelog](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md) + +## Summary + +You now have a reliability checklist for sustained Firecrawl MCP operations. + +Next: [Chapter 8: Security, Governance, and Contribution Workflow](08-security-governance-and-contribution-workflow.md) diff --git a/tutorials/firecrawl-mcp-server-tutorial/08-security-governance-and-contribution-workflow.md b/tutorials/firecrawl-mcp-server-tutorial/08-security-governance-and-contribution-workflow.md new file mode 100644 index 0000000..5dacf3e --- /dev/null +++ b/tutorials/firecrawl-mcp-server-tutorial/08-security-governance-and-contribution-workflow.md @@ -0,0 +1,36 @@ +--- +layout: default +title: "Chapter 8: Security, Governance, and Contribution Workflow" +nav_order: 8 +parent: Firecrawl MCP Server Tutorial +--- + +# Chapter 8: Security, Governance, and Contribution Workflow + +This chapter concludes with governance patterns for production use and contribution pathways. + +## Learning Goals + +- manage API keys and endpoint trust boundaries safely +- define governance around scraping behavior and data handling +- align contribution work with versioning and release rhythm + +## Governance Questions + +| Question | Why It Matters | +|:---------|:---------------| +| where are API keys stored and rotated? | prevents credential leakage | +| which domains are allowed for crawl/search jobs? | controls data and compliance risk | +| what release channel is approved for production clients? | avoids unplanned breaking changes | + +## Source References + +- [README](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md) +- [Versioning](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md) +- [Releases](https://github.com/firecrawl/firecrawl-mcp-server/releases) + +## Summary + +You now have an end-to-end model for adopting and operating Firecrawl MCP Server with strong governance. + +Next: combine this with [MCP Chrome](../mcp-chrome-tutorial/) and [MCP Inspector](../mcp-inspector-tutorial/) for full browsing-data toolchains. diff --git a/tutorials/firecrawl-mcp-server-tutorial/index.md b/tutorials/firecrawl-mcp-server-tutorial/index.md new file mode 100644 index 0000000..3ad82d6 --- /dev/null +++ b/tutorials/firecrawl-mcp-server-tutorial/index.md @@ -0,0 +1,84 @@ +--- +layout: default +title: "Firecrawl MCP Server Tutorial" +nav_order: 185 +has_children: true +format_version: v2 +--- + +# Firecrawl MCP Server Tutorial: Web Scraping and Search Tools for MCP Clients + +> Learn how to use `firecrawl/firecrawl-mcp-server` to add robust web scraping, crawling, search, and extraction capabilities to MCP-enabled coding and research agents. + +[![GitHub Repo](https://img.shields.io/badge/GitHub-firecrawl%2Ffirecrawl--mcp--server-black?logo=github)](https://github.com/firecrawl/firecrawl-mcp-server) +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/LICENSE) +[![NPM](https://img.shields.io/npm/v/firecrawl-mcp)](https://www.npmjs.com/package/firecrawl-mcp) +[![Latest Release](https://img.shields.io/github/v/release/firecrawl/firecrawl-mcp-server)](https://github.com/firecrawl/firecrawl-mcp-server/releases) + +## Why This Track Matters + +Firecrawl MCP Server gives AI agents production-grade web data access through a standard MCP interface. It supports scraping, crawl orchestration, search, extraction, retries, and deployment modes across popular MCP clients. + +This track focuses on: + +- setting up Firecrawl MCP for hosted and self-hosted environments +- selecting the right tool for scrape/map/crawl/search/extract tasks +- configuring reliability controls for retries and credit monitoring +- operating versioned endpoints and client integrations safely + +## Current Snapshot (Verified February 12, 2026) + +- repository: [`firecrawl/firecrawl-mcp-server`](https://github.com/firecrawl/firecrawl-mcp-server) +- stars: about **5.5k** +- latest release: [`v3.2.1`](https://github.com/firecrawl/firecrawl-mcp-server/releases/tag/v3.2.1) (**September 26, 2025**) +- recent activity: updated on **February 5, 2026** +- positioning: official Firecrawl MCP server for scraping, crawling, extraction, and search workflows + +## Mental Model + +```mermaid +flowchart LR + A[MCP client] --> B[Firecrawl MCP server] + B --> C[Tool routing layer] + C --> D[Firecrawl API cloud or self-hosted] + D --> E[Web data results] + E --> F[Agent reasoning and automation] +``` + +## Chapter Guide + +| Chapter | Key Question | Outcome | +|:--------|:-------------|:--------| +| [01 - Getting Started and Core Setup](01-getting-started-and-core-setup.md) | How do I run Firecrawl MCP quickly with API credentials? | Working integration baseline | +| [02 - Architecture, Transports, and Versioning](02-architecture-transports-and-versioning.md) | How do stdio, HTTP, and versioned endpoints affect behavior? | Cleaner deployment model | +| [03 - Tool Selection: Scrape, Map, Crawl, Search, Extract](03-tool-selection-scrape-map-crawl-search-extract.md) | Which tool should I use for each web data task? | Better tool choice | +| [04 - Client Integrations: Cursor, Claude, Windsurf, VS Code](04-client-integrations-cursor-claude-windsurf-vscode.md) | How do I connect Firecrawl MCP across major clients? | Reliable multi-client setup | +| [05 - Configuration, Retries, and Credit Monitoring](05-configuration-retries-and-credit-monitoring.md) | Which env vars and thresholds matter in production? | Better resilience | +| [06 - Batch Workflows, Deep Research, and API Evolution](06-batch-workflows-deep-research-and-api-evolution.md) | How do advanced tools and v1/v2 differences impact usage? | Safer migration planning | +| [07 - Reliability, Observability, and Failure Handling](07-reliability-observability-and-failure-handling.md) | How do we keep scraping workloads reliable over time? | Operational readiness | +| [08 - Security, Governance, and Contribution Workflow](08-security-governance-and-contribution-workflow.md) | How do teams run Firecrawl MCP responsibly at scale? | Long-term governance model | + +## What You Will Learn + +- how to integrate Firecrawl MCP in everyday coding/research agent loops +- how to choose and compose tools for web data acquisition tasks +- how to tune retry, credit, and environment settings for stability +- how to handle endpoint versioning and lifecycle governance + +## Source References + +- [Repository](https://github.com/firecrawl/firecrawl-mcp-server) +- [README](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/README.md) +- [Changelog](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/CHANGELOG.md) +- [Versioning Guide](https://github.com/firecrawl/firecrawl-mcp-server/blob/main/VERSIONING.md) + +## Related Tutorials + +- [Firecrawl Tutorial](../firecrawl-tutorial/) +- [MCP Servers Tutorial](../mcp-servers-tutorial/) +- [MCP Chrome Tutorial](../mcp-chrome-tutorial/) +- [MCP Use Tutorial](../mcp-use-tutorial/) + +--- + +Start with [Chapter 1: Getting Started and Core Setup](01-getting-started-and-core-setup.md). diff --git a/tutorials/mcp-chrome-tutorial/01-getting-started-and-native-bridge-setup.md b/tutorials/mcp-chrome-tutorial/01-getting-started-and-native-bridge-setup.md new file mode 100644 index 0000000..c71d80a --- /dev/null +++ b/tutorials/mcp-chrome-tutorial/01-getting-started-and-native-bridge-setup.md @@ -0,0 +1,46 @@ +--- +layout: default +title: "Chapter 1: Getting Started and Native Bridge Setup" +nav_order: 1 +parent: MCP Chrome Tutorial +--- + +# Chapter 1: Getting Started and Native Bridge Setup + +This chapter establishes a stable local setup across native bridge install, extension loading, and MCP client connection. + +## Learning Goals + +- install `mcp-chrome-bridge` globally +- load the Chrome extension and verify connection +- connect an MCP client using streamable HTTP or stdio + +## Baseline Install + +```bash +npm install -g mcp-chrome-bridge +``` + +If needed, run manual registration: + +```bash +mcp-chrome-bridge register +``` + +## Connection Checklist + +1. extension is loaded in `chrome://extensions/` +2. extension UI shows connected bridge status +3. MCP client can call at least one basic tool +4. browser tab listing returns expected windows/tabs + +## Source References + +- [README Quick Start](https://github.com/hangwin/mcp-chrome/blob/master/README.md) +- [Native Install Guide](https://github.com/hangwin/mcp-chrome/blob/master/app/native-server/install.md) + +## Summary + +You now have MCP Chrome installed and reachable from an MCP client. + +Next: [Chapter 2: Architecture and Component Boundaries](02-architecture-and-component-boundaries.md) diff --git a/tutorials/mcp-chrome-tutorial/02-architecture-and-component-boundaries.md b/tutorials/mcp-chrome-tutorial/02-architecture-and-component-boundaries.md new file mode 100644 index 0000000..c6ae87e --- /dev/null +++ b/tutorials/mcp-chrome-tutorial/02-architecture-and-component-boundaries.md @@ -0,0 +1,57 @@ +--- +layout: default +title: "Chapter 2: Architecture and Component Boundaries" +nav_order: 2 +parent: MCP Chrome Tutorial +--- + +# Chapter 2: Architecture and Component Boundaries + +MCP Chrome combines multiple layers: MCP protocol handling, native messaging, extension runtime, and AI vector processing. + +## Learning Goals + +- map each runtime layer and ownership boundary +- understand end-to-end tool call data flow +- identify where to add diagnostics and controls + +## Layered Architecture + +| Layer | Responsibility | +|:------|:---------------| +| MCP server | protocol transport and tool dispatch | +| native host | bridge communication with extension | +| extension background | executes Chrome API operations | +| content/offscreen workers | page interaction and AI processing | +| shared packages | tool schemas and common types | + +## Tool Call Flow + +```mermaid +sequenceDiagram + participant Client as MCP Client + participant MCP as MCP Server + participant Bridge as Native Messaging + participant Ext as Extension Background + participant Chrome as Chrome APIs + + Client->>MCP: tool call + MCP->>Bridge: native message + Bridge->>Ext: command payload + Ext->>Chrome: execute operation + Chrome-->>Ext: result + Ext-->>Bridge: response + Bridge-->>MCP: tool result + MCP-->>Client: final output +``` + +## Source References + +- [Architecture](https://github.com/hangwin/mcp-chrome/blob/master/docs/ARCHITECTURE.md) +- [Contributing Project Structure](https://github.com/hangwin/mcp-chrome/blob/master/docs/CONTRIBUTING.md) + +## Summary + +You now have a clear map of where browser actions, protocol logic, and AI processing live. + +Next: [Chapter 3: Tool Surface: Browser, Network, and Interaction](03-tool-surface-browser-network-and-interaction.md) diff --git a/tutorials/mcp-chrome-tutorial/03-tool-surface-browser-network-and-interaction.md b/tutorials/mcp-chrome-tutorial/03-tool-surface-browser-network-and-interaction.md new file mode 100644 index 0000000..b479d91 --- /dev/null +++ b/tutorials/mcp-chrome-tutorial/03-tool-surface-browser-network-and-interaction.md @@ -0,0 +1,43 @@ +--- +layout: default +title: "Chapter 3: Tool Surface: Browser, Network, and Interaction" +nav_order: 3 +parent: MCP Chrome Tutorial +--- + +# Chapter 3: Tool Surface: Browser, Network, and Interaction + +MCP Chrome exposes a broad tool API that spans tab management, page interaction, network capture, and data operations. + +## Learning Goals + +- choose the right tool family for each task +- avoid over-broad automation sequences +- design safer multi-step browser workflows + +## Tool Families + +| Family | Example Tools | +|:-------|:--------------| +| browser management | `get_windows_and_tabs`, `chrome_navigate`, `chrome_switch_tab` | +| network monitoring | capture start/stop, debugger start/stop, custom request | +| content analysis | `chrome_get_web_content`, `search_tabs_content`, interactive element discovery | +| interaction | click, fill/select, keyboard operations | +| data management | history and bookmark operations | + +## Selection Heuristics + +1. use content extraction before interaction when you need grounding +2. prefer explicit tab targeting in multi-tab sessions +3. gate destructive actions (close/delete) with confirmations in client prompts + +## Source References + +- [Tools Reference](https://github.com/hangwin/mcp-chrome/blob/master/docs/TOOLS.md) +- [README Tool Summary](https://github.com/hangwin/mcp-chrome/blob/master/README.md) + +## Summary + +You now understand how to map tasks to the right MCP Chrome tool group with lower failure risk. + +Next: [Chapter 4: Semantic Search and Vector Processing](04-semantic-search-and-vector-processing.md) diff --git a/tutorials/mcp-chrome-tutorial/04-semantic-search-and-vector-processing.md b/tutorials/mcp-chrome-tutorial/04-semantic-search-and-vector-processing.md new file mode 100644 index 0000000..a0e2597 --- /dev/null +++ b/tutorials/mcp-chrome-tutorial/04-semantic-search-and-vector-processing.md @@ -0,0 +1,45 @@ +--- +layout: default +title: "Chapter 4: Semantic Search and Vector Processing" +nav_order: 4 +parent: MCP Chrome Tutorial +--- + +# Chapter 4: Semantic Search and Vector Processing + +MCP Chrome includes a semantic engine for intelligent tab-content discovery, powered by embeddings and vector search. + +## Learning Goals + +- understand semantic index architecture at a high level +- identify performance-sensitive parts of the vector pipeline +- plan retrieval quality checks for real workflows + +## Semantic Pipeline + +```mermaid +flowchart LR + A[Tab content extraction] --> B[chunking] + B --> C[embedding generation] + C --> D[vector index] + D --> E[query embedding] + E --> F[similarity search] + F --> G[ranked context results] +``` + +## Performance Signals from Architecture Docs + +- WebAssembly SIMD is used for faster vector math operations. +- worker-based execution reduces UI blocking. +- vector database configuration controls recall, latency, and memory behavior. + +## Source References + +- [Architecture: AI Processing and Optimizations](https://github.com/hangwin/mcp-chrome/blob/master/docs/ARCHITECTURE.md) +- [Changelog](https://github.com/hangwin/mcp-chrome/blob/master/docs/CHANGELOG.md) + +## Summary + +You now have a functional mental model for how semantic tab search works and where tuning matters. + +Next: [Chapter 5: Transport Modes and Client Configuration](05-transport-modes-and-client-configuration.md) diff --git a/tutorials/mcp-chrome-tutorial/05-transport-modes-and-client-configuration.md b/tutorials/mcp-chrome-tutorial/05-transport-modes-and-client-configuration.md new file mode 100644 index 0000000..681ae87 --- /dev/null +++ b/tutorials/mcp-chrome-tutorial/05-transport-modes-and-client-configuration.md @@ -0,0 +1,47 @@ +--- +layout: default +title: "Chapter 5: Transport Modes and Client Configuration" +nav_order: 5 +parent: MCP Chrome Tutorial +--- + +# Chapter 5: Transport Modes and Client Configuration + +This chapter covers streamable HTTP and stdio transport choices for integrating MCP Chrome with clients. + +## Learning Goals + +- choose transport mode per client capabilities +- configure connection settings correctly +- reduce path and registration-related integration failures + +## Transport Comparison + +| Mode | Best For | +|:-----|:---------| +| streamable HTTP | modern MCP clients with HTTP transport support | +| stdio | clients that only support command-process integration | + +## Streamable HTTP Example + +```json +{ + "mcpServers": { + "chrome-mcp-server": { + "type": "streamableHttp", + "url": "http://127.0.0.1:12306/mcp" + } + } +} +``` + +## Source References + +- [README Transport Setup](https://github.com/hangwin/mcp-chrome/blob/master/README.md) +- [MCP CLI Config](https://github.com/hangwin/mcp-chrome/blob/master/docs/mcp-cli-config.md) + +## Summary + +You now know how to align MCP Chrome transport configuration with client constraints. + +Next: [Chapter 6: Visual Editor and Prompt Workflows](06-visual-editor-and-prompt-workflows.md) diff --git a/tutorials/mcp-chrome-tutorial/06-visual-editor-and-prompt-workflows.md b/tutorials/mcp-chrome-tutorial/06-visual-editor-and-prompt-workflows.md new file mode 100644 index 0000000..795f394 --- /dev/null +++ b/tutorials/mcp-chrome-tutorial/06-visual-editor-and-prompt-workflows.md @@ -0,0 +1,34 @@ +--- +layout: default +title: "Chapter 6: Visual Editor and Prompt Workflows" +nav_order: 6 +parent: MCP Chrome Tutorial +--- + +# Chapter 6: Visual Editor and Prompt Workflows + +MCP Chrome introduces visual workflows that help operators structure browser-automation prompts and reduce context loss. + +## Learning Goals + +- understand when visual workflows outperform raw prompt-only control +- use visual context to improve multi-step browser tasks +- combine visual and tool-driven execution safely + +## Workflow Pattern + +1. capture current browser state and intent +2. specify target UI state in visual editor +3. run tool sequence in small validated steps +4. inspect network/content outputs before proceeding + +## Source References + +- [Visual Editor Guide](https://github.com/hangwin/mcp-chrome/blob/master/docs/VisualEditor.md) +- [README Usage Examples](https://github.com/hangwin/mcp-chrome/blob/master/README.md) + +## Summary + +You now have a repeatable approach for combining visual planning and MCP tool execution. + +Next: [Chapter 7: Troubleshooting, Permissions, and Security](07-troubleshooting-permissions-and-security.md) diff --git a/tutorials/mcp-chrome-tutorial/07-troubleshooting-permissions-and-security.md b/tutorials/mcp-chrome-tutorial/07-troubleshooting-permissions-and-security.md new file mode 100644 index 0000000..e969eb2 --- /dev/null +++ b/tutorials/mcp-chrome-tutorial/07-troubleshooting-permissions-and-security.md @@ -0,0 +1,43 @@ +--- +layout: default +title: "Chapter 7: Troubleshooting, Permissions, and Security" +nav_order: 7 +parent: MCP Chrome Tutorial +--- + +# Chapter 7: Troubleshooting, Permissions, and Security + +Most MCP Chrome failures are installation or permission issues. This chapter turns those into a deterministic runbook. + +## Learning Goals + +- diagnose native host and registration failures quickly +- resolve platform-specific permission issues safely +- apply practical security boundaries in browser automation + +## Common Failure Classes + +| Class | Example | +|:------|:--------| +| registration failure | native host manifest missing or wrong path | +| permission error | execute permissions missing for bridge scripts | +| client transport mismatch | streamable HTTP config in stdio-only client | +| extension connectivity | native messaging host not detected | + +## Security Practices + +- treat browser automation tools as privileged operations +- keep extension permissions minimal and audited +- require human oversight for destructive or account-sensitive actions + +## Source References + +- [Troubleshooting](https://github.com/hangwin/mcp-chrome/blob/master/docs/TROUBLESHOOTING.md) +- [Native Install Guide](https://github.com/hangwin/mcp-chrome/blob/master/app/native-server/install.md) +- [Issue Template/Guide](https://github.com/hangwin/mcp-chrome/blob/master/docs/ISSUE.md) + +## Summary + +You now have a concrete troubleshooting and safety baseline for MCP Chrome operations. + +Next: [Chapter 8: Contribution, Release, and Runtime Operations](08-contribution-release-and-runtime-operations.md) diff --git a/tutorials/mcp-chrome-tutorial/08-contribution-release-and-runtime-operations.md b/tutorials/mcp-chrome-tutorial/08-contribution-release-and-runtime-operations.md new file mode 100644 index 0000000..8d926d2 --- /dev/null +++ b/tutorials/mcp-chrome-tutorial/08-contribution-release-and-runtime-operations.md @@ -0,0 +1,35 @@ +--- +layout: default +title: "Chapter 8: Contribution, Release, and Runtime Operations" +nav_order: 8 +parent: MCP Chrome Tutorial +--- + +# Chapter 8: Contribution, Release, and Runtime Operations + +This chapter closes with contribution mechanics and release-aware operations for teams maintaining MCP Chrome deployments. + +## Learning Goals + +- follow contribution standards and project structure conventions +- use changelog/release signals to plan safe upgrades +- define long-term operational ownership + +## Operations Checklist + +1. monitor release notes and changelog before upgrades +2. test native registration and key tools in staging +3. track client compatibility for transport and schema changes +4. document rollback path for bridge/runtime failures + +## Source References + +- [Contributing Guide](https://github.com/hangwin/mcp-chrome/blob/master/docs/CONTRIBUTING.md) +- [Changelog](https://github.com/hangwin/mcp-chrome/blob/master/docs/CHANGELOG.md) +- [Releases](https://github.com/hangwin/mcp-chrome/releases) + +## Summary + +You now have an end-to-end model for operating and evolving MCP Chrome in production workflows. + +Next: extend your MCP operations strategy with [MCP Inspector](../mcp-inspector-tutorial/) and [Firecrawl MCP Server](../firecrawl-mcp-server-tutorial/). diff --git a/tutorials/mcp-chrome-tutorial/index.md b/tutorials/mcp-chrome-tutorial/index.md new file mode 100644 index 0000000..bd7ca85 --- /dev/null +++ b/tutorials/mcp-chrome-tutorial/index.md @@ -0,0 +1,88 @@ +--- +layout: default +title: "MCP Chrome Tutorial" +nav_order: 184 +has_children: true +format_version: v2 +--- + +# MCP Chrome Tutorial: Control Your Real Chrome Browser Through MCP + +> Learn how to use `hangwin/mcp-chrome` to expose browser automation, content analysis, and semantic tab search tools to MCP clients. + +[![GitHub Repo](https://img.shields.io/badge/GitHub-hangwin%2Fmcp--chrome-black?logo=github)](https://github.com/hangwin/mcp-chrome) +[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/hangwin/mcp-chrome/blob/master/LICENSE) +[![Docs](https://img.shields.io/badge/docs-README%20%2B%20docs-blue)](https://github.com/hangwin/mcp-chrome/tree/master/docs) +[![Latest Release](https://img.shields.io/github/v/release/hangwin/mcp-chrome)](https://github.com/hangwin/mcp-chrome/releases) + +## Why This Track Matters + +MCP Chrome is a practical bridge between AI assistants and a user's real Chrome session. It avoids separate browser sandboxes and enables automation against active tabs, history, bookmarks, network events, and semantic content search. + +This track focuses on: + +- setting up native bridge and extension components correctly +- understanding streamable HTTP and stdio transport options +- using the 20+ tool surface safely and effectively +- operating troubleshooting, permissions, and release workflows + +## Current Snapshot (Verified February 12, 2026) + +- repository: [`hangwin/mcp-chrome`](https://github.com/hangwin/mcp-chrome) +- stars: about **10.4k** +- latest release: [`v1.0.0`](https://github.com/hangwin/mcp-chrome/releases/tag/v1.0.0) (**December 29, 2025**) +- recent activity: updated on **January 6, 2026** +- positioning: Chrome extension + native bridge MCP server for browser automation and semantic tab intelligence + +## Mental Model + +```mermaid +flowchart LR + A[MCP Client] --> B[Native MCP server] + B --> C[Native messaging bridge] + C --> D[Chrome extension background] + D --> E[Chrome APIs and content scripts] + D --> F[Semantic/vector search engine] +``` + +## Chapter Guide + +| Chapter | Key Question | Outcome | +|:--------|:-------------|:--------| +| [01 - Getting Started and Native Bridge Setup](01-getting-started-and-native-bridge-setup.md) | How do I install and connect MCP Chrome reliably? | Working local baseline | +| [02 - Architecture and Component Boundaries](02-architecture-and-component-boundaries.md) | How do native server, extension, and AI layers fit together? | Strong system model | +| [03 - Tool Surface: Browser, Network, and Interaction](03-tool-surface-browser-network-and-interaction.md) | What can the tool API do across tabs and pages? | Better tool selection | +| [04 - Semantic Search and Vector Processing](04-semantic-search-and-vector-processing.md) | How does semantic tab search work internally? | Higher signal retrieval | +| [05 - Transport Modes and Client Configuration](05-transport-modes-and-client-configuration.md) | When should I use streamable HTTP vs stdio? | Stable client integration | +| [06 - Visual Editor and Prompt Workflows](06-visual-editor-and-prompt-workflows.md) | How do visual workflows improve automation quality? | Faster iteration | +| [07 - Troubleshooting, Permissions, and Security](07-troubleshooting-permissions-and-security.md) | What usually breaks and how do we fix it safely? | Better operations | +| [08 - Contribution, Release, and Runtime Operations](08-contribution-release-and-runtime-operations.md) | How do teams maintain and extend MCP Chrome over time? | Long-term ownership | + +## What You Will Learn + +- how to install and register MCP Chrome for daily AI workflows +- how to map tool calls to browser-native capabilities safely +- how to configure transport and client wiring across environments +- how to handle security, troubleshooting, and release management + +## Source References + +- [Repository](https://github.com/hangwin/mcp-chrome) +- [README](https://github.com/hangwin/mcp-chrome/blob/master/README.md) +- [Architecture](https://github.com/hangwin/mcp-chrome/blob/master/docs/ARCHITECTURE.md) +- [Tools Reference](https://github.com/hangwin/mcp-chrome/blob/master/docs/TOOLS.md) +- [Troubleshooting](https://github.com/hangwin/mcp-chrome/blob/master/docs/TROUBLESHOOTING.md) +- [MCP CLI Config Guide](https://github.com/hangwin/mcp-chrome/blob/master/docs/mcp-cli-config.md) +- [Visual Editor](https://github.com/hangwin/mcp-chrome/blob/master/docs/VisualEditor.md) +- [Changelog](https://github.com/hangwin/mcp-chrome/blob/master/docs/CHANGELOG.md) + +## Related Tutorials + +- [Chrome DevTools MCP Tutorial](../chrome-devtools-mcp-tutorial/) +- [MCP Servers Tutorial](../mcp-servers-tutorial/) +- [MCP Inspector Tutorial](../mcp-inspector-tutorial/) +- [Firecrawl MCP Server Tutorial](../firecrawl-mcp-server-tutorial/) + +--- + +Start with [Chapter 1: Getting Started and Native Bridge Setup](01-getting-started-and-native-bridge-setup.md). diff --git a/tutorials/tutorial-manifest.json b/tutorials/tutorial-manifest.json index 2a5d38f..178a8cc 100644 --- a/tutorials/tutorial-manifest.json +++ b/tutorials/tutorial-manifest.json @@ -3,9 +3,9 @@ "docs_only": 0, "index_only": 0, "mixed": 0, - "root_only": 183 + "root_only": 185 }, - "tutorial_count": 183, + "tutorial_count": 185, "tutorials": [ { "chapter_numbers": [ @@ -1186,6 +1186,25 @@ "top_level_chapter_count": 8, "total_numbered_chapter_count": 8 }, + { + "chapter_numbers": [ + "01", + "02", + "03", + "04", + "05", + "06", + "07", + "08" + ], + "docs_chapter_count": 0, + "has_index": true, + "name": "firecrawl-mcp-server-tutorial", + "path": "tutorials/firecrawl-mcp-server-tutorial", + "structure": "root_only", + "top_level_chapter_count": 8, + "total_numbered_chapter_count": 8 + }, { "chapter_numbers": [ "01", @@ -1833,6 +1852,25 @@ "top_level_chapter_count": 8, "total_numbered_chapter_count": 8 }, + { + "chapter_numbers": [ + "01", + "02", + "03", + "04", + "05", + "06", + "07", + "08" + ], + "docs_chapter_count": 0, + "has_index": true, + "name": "mcp-chrome-tutorial", + "path": "tutorials/mcp-chrome-tutorial", + "structure": "root_only", + "top_level_chapter_count": 8, + "total_numbered_chapter_count": 8 + }, { "chapter_numbers": [ "01",