From c8a24647900dcddcc83ff1f899a191dcd7082fcd Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Nov 2025 03:06:32 +0000 Subject: [PATCH 1/3] docs: add comprehensive deduplication analysis Added three detailed analysis documents identifying duplicate content across documentation: - DEDUPLICATION_AUDIT.md: Complete analysis with severity ratings and recommendations - DEDUP_QUICK_REFERENCE.md: At-a-glance summary and action items - DEDUP_FILE_REFERENCE.md: Exact file paths and line numbers for duplications Key findings: - ~4,000+ lines of duplicate content identified across 77 MDX files - 1,700-2,300 lines actionable cleanup (9-13% reduction) - 3 critical conflicts including JSON vs Markdown guidance - Prioritized action plan with time estimates Major issues: 1. Tool design guidance scattered across 3 files (2,485 lines) 2. Setup instructions duplicated in 3 files (250+ lines) 3. Security guidance fragmented across multiple files (500+ lines) --- DEDUPLICATION_AUDIT.md | 445 +++++++++++++++++++++++++++++++++++++++ DEDUP_FILE_REFERENCE.md | 391 ++++++++++++++++++++++++++++++++++ DEDUP_QUICK_REFERENCE.md | 139 ++++++++++++ 3 files changed, 975 insertions(+) create mode 100644 DEDUPLICATION_AUDIT.md create mode 100644 DEDUP_FILE_REFERENCE.md create mode 100644 DEDUP_QUICK_REFERENCE.md diff --git a/DEDUPLICATION_AUDIT.md b/DEDUPLICATION_AUDIT.md new file mode 100644 index 0000000..159ecdd --- /dev/null +++ b/DEDUPLICATION_AUDIT.md @@ -0,0 +1,445 @@ +# WebMCP Documentation Deduplication & Simplification Analysis + +## Executive Summary + +The WebMCP documentation contains **significant content duplication** across 77 MDX files (18,103 total lines). The most impactful issues are: + +1. **Tool Design Guidance** spread across 3 major files (best-practices.mdx, ai-frameworks/best-practices.mdx, concepts/tool-design.mdx) +2. **Security guidance** duplicated between root security.mdx and concepts/security.mdx +3. **Setup instructions** repeated in quickstart.mdx, development.mdx, and introduction.mdx +4. **AI Framework integration** scattered across 6+ files with overlapping content + +--- + +## Detailed Findings + +### TIER 1: CRITICAL DUPLICATIONS (High User Impact) + +#### 1. Tool Design Best Practices (3 Files, ~2,485 Lines) + +**Files Involved:** +- `/home/user/docs/best-practices.mdx` (1,480 lines) +- `/home/user/docs/ai-frameworks/best-practices.mdx` (540 lines) +- `/home/user/docs/concepts/tool-design.mdx` (465 lines) + +**Specific Overlaps:** + +1. **Naming Conventions** (Lines mentioned): + - best-practices.mdx: Lines 16-51 ("Tool Design Principles" → "Use Descriptive Names") + - concepts/tool-design.mdx: Lines 9-47 ("Naming Conventions") + - ai-frameworks/best-practices.mdx: Lines 297-311 ("Use clear naming conventions") + **Issue**: Identical guidance across three files. All explain `domain_verb_noun` pattern, same good/bad examples. + +2. **Descriptions and Clarity** (Lines): + - best-practices.mdx: Lines 53-93 ("Provide Detailed Descriptions") + - concepts/tool-design.mdx: Lines 49-77 ("Writing Clear Descriptions") + - ai-frameworks/best-practices.mdx: Lines 313-338 ("Write descriptive tool descriptions") + **Issue**: 80% overlap in examples and guidance. All use same "products_search" example. + +3. **Input Validation**: + - best-practices.mdx: Lines 147-215 ("Input Validation" section, ~70 lines) + - ai-frameworks/best-practices.mdx: Lines 182-233 ("Input Validation" section, ~50 lines) + - concepts/tool-design.mdx: Lines 80-177 ("Input Design" section, ~97 lines) + **Issue**: Same patterns shown with different emphasis. Zod vs JSON Schema explained in both. + +4. **Error Handling**: + - best-practices.mdx: Lines 365-435 ("Error Handling" section) + - ai-frameworks/best-practices.mdx: Lines 94-180 ("Error Handling" section) + - concepts/tool-design.mdx: Lines 360-400 ("Error Handling" section) + **Issue**: Identical error handling patterns, with overlapping code examples. + +5. **Response Formatting**: + - best-practices.mdx: Lines 249-330 ("Response Format" section, markdown vs JSON comparison) + - concepts/tool-design.mdx: Lines 179-272 ("Output Design" section) + **Issue**: Same comparison examples, identical guidance on markdown vs JSON. + +6. **Tool Annotations**: + - best-practices.mdx: Referenced within tool design + - concepts/tool-design.mdx: Lines 274-300 ("Tool Annotations" dedicated section) + - ai-frameworks/best-practices.mdx: Lines 340-368 ("Set appropriate tool annotations") + **Issue**: Same annotations (readOnlyHint, idempotentHint, destructiveHint) explained in all three. + +7. **Security in Tool Design**: + - best-practices.mdx: Lines 470-593 ("Security Best Practices" section) + - ai-frameworks/best-practices.mdx: Lines 372-456 ("Security" section) + **Issue**: Input validation, sanitization, and permission checking covered identically. + +8. **Testing**: + - best-practices.mdx: Lines 780-873 ("Testing & Quality Assurance") + - ai-frameworks/best-practices.mdx: Lines 459-520 ("Testing") + - concepts/tool-design.mdx: Lines 402-423 ("Testing Tools") + **Issue**: Same unit testing patterns, same test structure examples. + +**Severity**: HIGH - Users looking for tool design guidance will find the same content in 3 places, creating confusion about which is the "canonical" source. + +**Complexity**: Medium - Would require careful consolidation to merge into a single authoritative file while maintaining the existing reference structure for AI frameworks. + +**Recommended Action**: +- Keep `best-practices.mdx` as the canonical comprehensive guide +- Convert `concepts/tool-design.mdx` to focus on architectural patterns and design philosophy (less on implementation details) +- Reduce `ai-frameworks/best-practices.mdx` to framework-specific patterns only, reference the main best-practices guide for general guidance +- Estimated lines to remove: ~800-1000 lines + +--- + +#### 2. Setup & Installation Instructions (3 Files, ~250 Lines Duplicated) + +**Files Involved:** +- `/home/user/docs/introduction.mdx` (Lines 160-235) +- `/home/user/docs/quickstart.mdx` (Lines 18-92) +- `/home/user/docs/development.mdx` (Lines 11-33, 53-124) + +**Specific Overlaps:** + +1. **Installation Tab Examples** (3 frameworks): + - introduction.mdx: Lines 164-235 "Quick Example" section (React, Vanilla, Script Tag) + - quickstart.mdx: Lines 18-92 "Installation" section (React, Vanilla, Script Tag) + - development.mdx: Lines 15-33 "Quick Setup" (React, Vanilla, Script) + + **Issue**: Same code blocks repeated verbatim across files. React example `useWebMCP` hook with identical Zod schema. + +2. **Package Installation**: + - quickstart.mdx: Lines 22-24 (pnpm add commands) + - development.mdx: Lines 18-31 (same pnpm add commands) + - introduction.mdx: Embedded in code examples + **Issue**: Same dependency installation repeated in 2+ places. + +**Severity**: MEDIUM - Confusing for users following multiple guides; suggests the docs aren't unified. + +**Complexity**: Quick - Can consolidate by having quickstart reference development guide for setup, or vice versa. + +**Recommended Action**: +- Keep quickstart.mdx as the primary setup guide (most appropriate audience) +- Remove installation instructions from introduction.mdx (move to quickstart link) +- Have development.mdx reference quickstart for setup, focus on dev workflow +- Remove ~50 lines of duplicate code examples + +--- + +### TIER 2: SIGNIFICANT DUPLICATIONS (Medium User Impact) + +#### 3. Security Guidance (2 Files + Scattered Content) + +**Files Involved:** +- `/home/user/docs/security.mdx` (984 lines) - **ROOT LEVEL** +- `/home/user/docs/concepts/security.mdx` (partial, ~100 lines) - **CONCEPTS** +- `/home/user/docs/best-practices.mdx` Lines 470-593 ("Security Best Practices") + +**Specific Overlaps:** + +1. **Authentication & Authorization**: + - security.mdx: "Protecting User Sessions" section + - concepts/security.mdx: "Authentication & Authorization" section + - best-practices.mdx: Lines 472-499 ("Validate User Authentication") + **Issue**: Same auth patterns explained 3 times with different emphasis. + +2. **Input Validation & Sanitization**: + - security.mdx: "Standard Web Security" section + - best-practices.mdx: Lines 501-524 ("Sanitize Inputs") + - ai-frameworks/best-practices.mdx: Lines 401-420 ("Sanitize inputs") + **Issue**: Identical DOMPurify examples, same security patterns. + +3. **Rate Limiting**: + - security.mdx: "Rate Limit Tool Calls" section + - best-practices.mdx: Lines 526-559 ("Rate Limit Tool Calls") + - ai-frameworks/best-practices.mdx: Lines 422-456 ("Limit rate and scope") + **Issue**: Same implementation pattern shown 3 times. + +4. **Agent-Specific Threats**: + - security.mdx: Lines 52-350 (Prompt injection, tool misrepresentation, fingerprinting) + - best-practices.mdx: Lines 470-593 (Some overlap but less comprehensive) + **Issue**: Comprehensive agent-threat model in security.mdx not referenced from best-practices; some developers may miss critical guidance. + +**Severity**: MEDIUM - Critical security content scattered; developers might miss important threat models if they only read best-practices. + +**Complexity**: Medium - These files have different purposes (root security is comprehensive, concepts is architectural). Need careful refactoring. + +**Recommended Action**: +- `security.mdx` (root): Keep as primary, comprehensive security reference +- `concepts/security.mdx`: Repurpose for architectural security model (auth flow diagrams, etc.) +- `best-practices.mdx`: Reference security guide, include only implementation-specific examples +- Add cross-links in critical sections +- Estimated lines to remove: ~200-300 lines + +--- + +#### 4. AI Framework Integration (6 Files, Scattered Across Directory) + +**Files Involved:** +- `/home/user/docs/connecting-agents.mdx` (Lines 79-88, "Frontend AI Frameworks") +- `/home/user/docs/ai-frameworks/index.mdx` (128 lines, HUB file) +- `/home/user/docs/ai-frameworks/setup.mdx` (partial content overlap) +- `/home/user/docs/ai-frameworks/assistant-ui.mdx` (337 lines) +- `/home/user/docs/ai-frameworks/ag-ui.mdx` (385 lines) +- `/home/user/docs/ai-frameworks/best-practices.mdx` (540 lines) +- `/home/user/docs/ai-frameworks/custom-runtime.mdx` (450 lines) + +**Specific Overlaps:** + +1. **Setup Instructions**: + - ai-frameworks/setup.mdx: Package installation, client configuration + - assistant-ui.mdx: Includes setup steps + - ag-ui.mdx: Includes setup steps + **Issue**: Setup repeated in 2+ framework files instead of centralized. + +2. **Architecture Explanation**: + - index.mdx: "How Frontend Tool Calling Works" (Steps 1-5 + diagram) + - setup.mdx: Same architecture explanation + - assistant-ui.mdx: Repeats architecture before framework-specific content + **Issue**: Same sequence diagram shown multiple times. + +3. **MCP Client Integration**: + - setup.mdx: Client provider setup + - assistant-ui.mdx: Lines 50-150 (setup code) + - ag-ui.mdx: Lines 100-200 (setup code) + **Issue**: Nearly identical "useClient" or provider patterns shown 3 times. + +4. **Error Handling**: + - ai-frameworks/best-practices.mdx: Lines 94-180 + - assistant-ui.mdx: Error handling section + - ag-ui.mdx: Error handling section + **Issue**: Framework-agnostic error patterns duplicated in framework-specific files. + +**Severity**: MEDIUM - Navigation complexity. Users don't know which file to read first. Setup repeated across files. + +**Complexity**: Medium-High - Architecture requires careful reorganization without breaking navigation. + +**Recommended Action**: +- Strengthen `ai-frameworks/index.mdx` as the unified hub (it's currently weak) +- Consolidate setup steps into `ai-frameworks/setup.mdx` (not individual framework files) +- In framework-specific files (assistant-ui, ag-ui), reference setup.mdx and focus ONLY on framework-specific API +- Remove duplicated error handling patterns; reference best-practices.mdx +- Estimated lines to remove: ~300-500 lines + +--- + +### TIER 3: MINOR DUPLICATIONS (Low-Medium User Impact) + +#### 5. Tool Registration Concepts + +**Files Involved:** +- `/home/user/docs/concepts/tool-registration.mdx` (dedicated file) +- `/home/user/docs/packages/react-webmcp.mdx` (has `useWebMCP` detailed API) +- `/home/user/docs/quickstart.mdx` (setup section) +- `/home/user/docs/best-practices.mdx` (references but doesn't detail) + +**Issue**: Multiple files explain "registerTool()" vs "useWebMCP()" in similar ways. Tool registration details scattered. + +**Severity**: LOW-MEDIUM - Understanding concept requires reading multiple files, but they're complementary rather than identical. + +**Complexity**: Low-Medium - Could consolidate into a single reference file. + +--- + +#### 6. Conditional/Dynamic Tool Registration + +**Files Involved:** +- `/home/user/docs/advanced.mdx` Lines 7-84 ("Dynamic Tool Registration") +- `/home/user/docs/security.mdx` Lines 559-616 ("Conditional Registration") +- `/home/user/docs/best-practices.mdx` Lines 875-914 ("Tool Organization") + +**Issue**: Conditional tool registration shown in 3 different contexts. Same patterns repeated. + +**Severity**: LOW - Not critical for most developers, but scattered guidance. + +--- + +#### 7. Markdown Response Formatting + +**Files Involved:** +- `/home/user/docs/best-practices.mdx` Lines 251-330 ("Response Format" → "Use Markdown") +- `/home/user/docs/concepts/tool-design.mdx` Lines 180-216 ("Output Design" → "Return Structured Data") + +**Specific Issue**: +- best-practices.mdx specifically recommends markdown over JSON +- tool-design.mdx shows structured JSON as good pattern +- **CONFLICTING GUIDANCE** - both marked as good patterns + +**Severity**: MEDIUM - **CONFLICTING GUIDANCE IS CRITICAL** - developers don't know which approach to use. + +**Recommended Action**: +- Audit these approaches with team +- Document one canonical approach +- Reference from other files with rationale +- Estimated impact: Both files need review, potential 30-50 line changes + +--- + +### TIER 4: ORGANIZATIONAL ISSUES (Not Direct Duplication) + +#### 8. Extension Documentation Fragmentation + +**Files Involved:** +- `/home/user/docs/extension/index.mdx` (512 lines) +- `/home/user/docs/extension/agents.mdx` (416 lines) +- `/home/user/docs/extension/managing-userscripts.mdx` (566 lines) +- References scattered in troubleshooting, quickstart, connecting-agents + +**Issue**: Extension documentation is comprehensive but scattered. Users must navigate multiple pages to understand full functionality. + +**Note**: Not duplication, but navigation could be improved. + +--- + +#### 9. Packages Documentation Parallel Structure + +**Files Involved:** +- `/home/user/docs/packages/global.mdx` (739 lines) +- `/home/user/docs/packages/react-webmcp.mdx` (325 lines) +- `/home/user/docs/packages/transports.mdx` (460 lines) +- `/home/user/docs/packages/smart-dom-reader.mdx` (572 lines) +- `/home/user/docs/packages/extension-tools.mdx` (451 lines) +- `/home/user/docs/packages/webmcp-ts-sdk.mdx` (partial content) + +**Issue**: Each package has its own documentation, but some patterns (imports, configuration) repeated in each. + +**Note**: This is expected for package documentation; likely not a problem. + +--- + +### TIER 5: COMPLEXITY & VERBOSITY ISSUES + +#### 10. best-practices.mdx Size & Scope + +**File**: `/home/user/docs/best-practices.mdx` (1,480 lines) + +**Structure Issues**: +- Covers: Tool Design, Input Validation, Response Format, Error Handling, Security, Performance, Testing, Tool Organization, Framework Integration, Documentation, Monitoring, Version Management +- **This is too much for one page** - covers ~12 distinct topics +- Some readers will miss critical sections due to length +- Could be split into focused sub-pages or better organized + +**Recommended Action**: +- Consider splitting into two files: + 1. Best Practices for Tool Developers (naming, design, validation, response format) + 2. Best Practices for Tool Deployment (security, performance, testing, versioning) +- Or create a "Best Practices Hub" with sub-pages (like ai-frameworks model) + +**Complexity**: Medium - Would require restructuring and new navigation + +--- + +#### 11. security.mdx Depth vs Breadth + +**File**: `/home/user/docs/security.mdx` (984 lines) + +**Structure Issues**: +- Very comprehensive (good) but very long +- Covers agent-specific threats, prompt injection, standard web security, compliance +- Some readers may not finish due to length +- Difficult to find specific pattern (e.g., "how do I rate limit?") + +**Recommended Action**: +- Add better internal navigation (table of contents anchors) +- Consider progressive disclosure (expandable sections for advanced topics) +- Cross-link related content in best-practices.mdx + +**Complexity**: Low - Don't need to change content, just improve navigation + +--- + +#### 12. Verbose Code Examples + +**Issue**: Some files have 5-10 nearly identical code examples (React vs Vanilla JS vs Script Tag) scattered throughout the docs. + +**Files Affected**: introduction.mdx, quickstart.mdx, development.mdx, and others + +**Suggested Pattern**: Use reusable snippets for common patterns or create "code pattern library" to avoid repetition + +--- + +## Summary Table + +| Issue | Files Affected | Lines Duplicated | Severity | Complexity | Est. Cleanup | +|-------|---|---|---|---|---| +| Tool Design Guidance (3 files) | best-practices, ai-frameworks/best-practices, concepts/tool-design | ~2,485 | HIGH | Medium | 800-1,000 lines | +| Setup Instructions | introduction, quickstart, development | ~250 | MEDIUM | Quick | 100-150 lines | +| Security Guidance (scattered) | security, concepts/security, best-practices | ~500 | MEDIUM | Medium | 200-300 lines | +| AI Framework Integration | 6 files across ai-frameworks/ | ~300-500 | MEDIUM | Medium-High | 300-500 lines | +| Conflicting Markdown Guidance | best-practices, concepts/tool-design | ~100 | MEDIUM | Quick | 50-100 lines | +| Tool Registration Concepts | 4 files scattered | ~150-200 | LOW-MEDIUM | Low-Medium | 100-150 lines | +| Conditional Registration | advanced, security, best-practices | ~100 | LOW | Low | 50-100 lines | +| **TOTAL** | **~20 files** | **~4,000+ lines** | - | - | **~1,700-2,300 lines** | + +--- + +## Recommendations by Priority + +### Phase 1: CRITICAL (Immediate - Highest ROI) + +1. **Consolidate Tool Design Guidance** (1,000+ duplicate lines) + - Merge concepts into authoritative best-practices.mdx + - Repurpose tool-design.mdx for architectural patterns + - Reduce ai-frameworks/best-practices to framework-specific only + +2. **Resolve Markdown vs JSON Conflict** (Critical decision) + - Audit with team: is markdown really better than structured JSON? + - Document canonical approach + - Update conflicting files to align + +### Phase 2: HIGH (Week 1-2) + +3. **Consolidate Setup Instructions** + - Reference approach: quickstart → development → introduction + - Remove duplicate code examples + +4. **Centralize AI Framework Documentation** + - Create proper hub structure + - Move setup to single location + - Keep only framework-specific content in individual files + +### Phase 3: MEDIUM (Week 2-3) + +5. **Improve Security Documentation Structure** + - Add table of contents and anchors + - Cross-link with best-practices + - Consider progressive disclosure for advanced topics + +6. **Reorganize best-practices.mdx** + - Consider splitting into two files if >2,000 lines + - Add better internal navigation + - Use expandable sections for advanced topics + +### Phase 4: LOW (Nice to have) + +7. **Consolidate Tool Registration Concepts** + - Single authoritative reference file + - Cross-link from multiple entry points + +--- + +## Specific File-by-File Actions + +### Files to Modify (In Priority Order) + +1. **best-practices.mdx** → Extract tool naming, descriptions, input validation sections to new "Tool Design Reference" or consolidate with concepts/tool-design +2. **ai-frameworks/best-practices.mdx** → Reduce to framework-specific patterns only; reference main best-practices guide +3. **concepts/tool-design.mdx** → Refocus on design philosophy; reduce implementation details +4. **introduction.mdx** → Remove setup examples; reference quickstart.mdx +5. **development.mdx** → Remove duplicate setup; reference quickstart; focus on dev workflow +6. **security.mdx** → Add TOC and anchors; improve navigation +7. **ai-frameworks/setup.mdx** → Consolidate all framework setup here +8. **assistant-ui.mdx** & **ag-ui.mdx** → Remove setup instructions; reference ai-frameworks/setup.mdx + +### Files to Keep As-Is + +- concepts/security.mdx (architectural focus, not duplicate) +- concepts/tool-registration.mdx (dedicated reference) +- packages/* (expected to have parallel structure) +- extension/* (specialized domain, not duplicated) + +--- + +## Estimated Impact + +**Total Lines of Documentation**: 18,103 +**Estimated Duplicate Content**: ~4,000+ lines +**Estimated Reducible Content**: ~1,700-2,300 lines (without losing information) +**Percentage Reduction**: 9-13% of total documentation + +**User Experience Impact**: +- Faster navigation (fewer pages to read for single topic) +- Reduced confusion (single source of truth for each topic) +- Clearer progression from beginner to advanced +- Resolved conflicting guidance + diff --git a/DEDUP_FILE_REFERENCE.md b/DEDUP_FILE_REFERENCE.md new file mode 100644 index 0000000..e592711 --- /dev/null +++ b/DEDUP_FILE_REFERENCE.md @@ -0,0 +1,391 @@ +# Deduplication: Complete File Reference & Line Numbers + +## Critical Duplications + +### 1. Tool Design Guidance (2,485 Total Lines) + +#### A. Naming Conventions +- **File 1**: `/home/user/docs/best-practices.mdx` Lines 16-51 (36 lines) + - Section: "Tool Design Principles" → "Use Descriptive Names" + - Contains: `domain_verb_noun` pattern, good/bad examples + +- **File 2**: `/home/user/docs/concepts/tool-design.mdx` Lines 9-47 (39 lines) + - Section: "Naming Conventions" + - Contains: IDENTICAL pattern and examples + +- **File 3**: `/home/user/docs/ai-frameworks/best-practices.mdx` Lines 297-311 (15 lines) + - Section: "Use clear naming conventions" + - Contains: Same pattern, repeated examples + +**Action**: Keep best-practices (most canonical); reference from others + +--- + +#### B. Detailed Descriptions / Clarity +- **File 1**: `/home/user/docs/best-practices.mdx` Lines 53-93 (41 lines) + - Section: "Provide Detailed Descriptions" + - Uses "products_search" example extensively + +- **File 2**: `/home/user/docs/concepts/tool-design.mdx` Lines 49-77 (29 lines) + - Section: "Writing Clear Descriptions" + - Uses SAME "products_search" example + +- **File 3**: `/home/user/docs/ai-frameworks/best-practices.mdx` Lines 313-338 (26 lines) + - Section: "Write descriptive tool descriptions" + - Same content, different emphasis + +**Overlap**: ~80% identical guidance +**Action**: Consolidate into single source; reference from others + +--- + +#### C. Input Validation +- **File 1**: `/home/user/docs/best-practices.mdx` Lines 147-215 (69 lines) + - Uses Zod schema examples + - Covers business logic validation + +- **File 2**: `/home/user/docs/concepts/tool-design.mdx` Lines 80-177 (98 lines) + - "Input Design" section + - Uses JSON Schema AND Zod examples + +- **File 3**: `/home/user/docs/ai-frameworks/best-practices.mdx` Lines 182-233 (52 lines) + - "Validate inputs with Zod" + - Same patterns, Zod focused + +**Overlap**: ~70% similar patterns +**Action**: Keep best-practices as primary; tool-design for pattern theory + +--- + +#### D. Error Handling +- **File 1**: `/home/user/docs/best-practices.mdx` Lines 365-435 (71 lines) + - Section: "Error Handling" + - Covers graceful errors, business logic errors + +- **File 2**: `/home/user/docs/concepts/tool-design.mdx` Lines 360-400 (41 lines) + - Section: "Error Handling" + - Almost IDENTICAL examples and patterns + +- **File 3**: `/home/user/docs/ai-frameworks/best-practices.mdx` Lines 94-180 (87 lines) + - "Handle errors gracefully" + - Same patterns shown + +**Overlap**: ~85% identical +**Action**: Consolidate; keep one canonical version + +--- + +#### E. Response Formatting +- **File 1**: `/home/user/docs/best-practices.mdx` Lines 249-330 (82 lines) + - Section: "Response Format" + - "Use Markdown Instead of JSON" recommendation + - Shows markdown vs JSON comparison + +- **File 2**: `/home/user/docs/concepts/tool-design.mdx` Lines 179-216 (38 lines) + - Section: "Output Design" + - "Return Structured Data" (implies JSON) + - **CONFLICTS with File 1** + +**Critical Issue**: CONFLICTING GUIDANCE! +- best-practices says: Markdown better for AI +- tool-design says: Structured JSON better + +**Action**: RESOLVE CONFLICT - which approach is actually recommended? Update both files to agree + +--- + +#### F. Tool Annotations +- **File 1**: `/home/user/docs/best-practices.mdx` Referenced within multiple sections +- **File 2**: `/home/user/docs/concepts/tool-design.mdx` Lines 274-300 (27 lines) + - Dedicated section on annotations + - Explains: readOnlyHint, idempotentHint, destructiveHint + +- **File 3**: `/home/user/docs/ai-frameworks/best-practices.mdx` Lines 340-368 (29 lines) + - "Set appropriate tool annotations" + - SAME annotations, same examples + +**Action**: Keep tool-design as reference; reference from others + +--- + +#### G. Testing +- **File 1**: `/home/user/docs/best-practices.mdx` Lines 780-873 (94 lines) + - Section: "Testing & Quality Assurance" + - Unit testing, E2E testing patterns + +- **File 2**: `/home/user/docs/concepts/tool-design.mdx` Lines 402-423 (22 lines) + - Section: "Testing Tools" + - Same patterns, more concise + +- **File 3**: `/home/user/docs/ai-frameworks/best-practices.mdx` Lines 459-520 (62 lines) + - Section: "Testing" + - Same test structure examples + +**Action**: best-practices is most comprehensive; reference from others + +--- + +### 2. Setup & Installation (250+ Lines Duplicate) + +#### A. Introduction Quick Example (React/Vanilla/Script Tag) +- **File**: `/home/user/docs/introduction.mdx` Lines 164-235 (72 lines) + - Section: "Quick Example" + - Three tabs: React, Vanilla JS, Script Tag + - React example: useWebMCP hook with Zod schema + - Vanilla JS: navigator.modelContext.registerTool() + - Script Tag: CDN-based example + +**Content Summary**: +```tsx +// React Tab (Lines 168-188) +import '@mcp-b/global'; +import { useWebMCP } from '@mcp-b/react-webmcp'; +import { z } from 'zod'; + +function ProductPage({ productId }) { + useWebMCP({ + name: 'add_to_cart', + description: 'Add this product to shopping cart', + inputSchema: { quantity: z.number().min(1).default(1) }, + handler: async ({ quantity }) => { ... } + }); +} +``` + +--- + +#### B. Quickstart Installation & Examples +- **File**: `/home/user/docs/quickstart.mdx` Lines 18-92 (75 lines) + - Section: "Installation" + code examples + - IDENTICAL React/Vanilla/Script Tag tabs + - Same useWebMCP example code + +**Critical Finding**: Lines 26-91 are nearly VERBATIM copy of introduction.mdx Lines 164-235 + +--- + +#### C. Development Quick Setup +- **File**: `/home/user/docs/development.mdx` Lines 11-33 + 53-124 (94 lines total) + - Section: "Quick Setup" + "Development Workflow" + - Same React example with useWebMCP + - Same Vanilla JS examples + +**Critical Finding**: Contains SAME setup code as quickstart.mdx Lines 22-24 + +--- + +**Action**: +- Keep quickstart.mdx as primary (best organization for beginners) +- Remove code examples from introduction.mdx (add link to quickstart instead) +- development.mdx references quickstart for setup +- Estimated removal: 100-150 lines + +--- + +### 3. Security Guidance (500+ Lines Scattered) + +#### A. Authentication & Authorization +- **File 1**: `/home/user/docs/security.mdx` Lines 9-75 + - Section: "Protecting User Sessions" + - Shows auth flow diagram, best practices + +- **File 2**: `/home/user/docs/concepts/security.mdx` Lines 9-76 + - Section: "Authentication & Authorization" + - Same flow diagram, similar patterns + +- **File 3**: `/home/user/docs/best-practices.mdx` Lines 472-499 + - Section: "Validate User Authentication" + - Abbreviated version of same pattern + +**Overlap**: ~70% +**Action**: security.mdx is primary; concepts/security is architectural; remove from best-practices + +--- + +#### B. Input Validation & Sanitization +- **File 1**: `/home/user/docs/security.mdx` Lines 798-910 + - Section: "Standard Web Security" + - Shows DOMPurify example, escapeHtml pattern + +- **File 2**: `/home/user/docs/best-practices.mdx` Lines 501-524 + - Section: "Sanitize Inputs" + - IDENTICAL DOMPurify example code + +- **File 3**: `/home/user/docs/ai-frameworks/best-practices.mdx` Lines 401-420 + - "Sanitize inputs" section + - Same pattern, abbreviated + +**Overlap**: ~90% identical +**Action**: Remove from best-practices; reference security.mdx + +--- + +#### C. Rate Limiting +- **File 1**: `/home/user/docs/security.mdx` Lines 526-559 + - Section: "Rate Limit Tool Calls" + - Shows limiter implementation + +- **File 2**: `/home/user/docs/best-practices.mdx` Lines 526-559 + - **EXACT SAME LINES** - copy/paste duplication + - Section: "Rate Limit Tool Calls" + +- **File 3**: `/home/user/docs/ai-frameworks/best-practices.mdx` Lines 422-456 + - Shows rate limiter pattern (different implementation) + +**Overlap**: 100% for Files 1 & 2 +**Action**: REMOVE from best-practices; keep security.mdx as primary + +--- + +#### D. Agent-Specific Threats (Prompt Injection) +- **File 1**: `/home/user/docs/security.mdx` Lines 52-350 + - Comprehensive section on: + - Prompt injection risks (lines 54-170) + - Sensitive data exposure (lines 70-180) + - Other prompt injection mitigations (lines 180-242) + - Tool misrepresentation (lines 246-349) + - Privacy/fingerprinting (lines 351-459) + +- **File 2**: `/home/user/docs/best-practices.mdx` Lines 470-593 + - "Security Best Practices" + - Less comprehensive coverage of same topics + +**Critical Issue**: security.mdx has much more detailed threat model that some developers may miss + +**Action**: Ensure best-practices cross-links to security.mdx for detailed guidance + +--- + +### 4. AI Framework Integration (6 Files, 300-500 Lines) + +#### A. Architecture Explanation +- **File 1**: `/home/user/docs/ai-frameworks/index.mdx` Lines 11-49 + - Section: "How Frontend Tool Calling Works" + - Steps 1-5 + sequence diagram + +- **File 2**: `/home/user/docs/connecting-agents.mdx` Lines 79-88 + - Similar architecture explanation + - References ai-frameworks/index (good cross-link) + +- **File 3**: `/home/user/docs/ai-frameworks/assistant-ui.mdx` (partial) + - Repeats architecture before framework content + +**Action**: index.mdx is primary; strengthen it as hub; remove repetition from others + +--- + +#### B. Setup Instructions +- **File 1**: `/home/user/docs/ai-frameworks/setup.mdx` (dedicated setup page) + - Package installation + - Client configuration + +- **File 2**: `/home/user/docs/ai-frameworks/assistant-ui.mdx` Lines 1-60 + - Includes setup steps (should reference setup.mdx) + +- **File 3**: `/home/user/docs/ai-frameworks/ag-ui.mdx` Lines 1-60 + - Also includes setup steps + +**Action**: Move all setup to dedicated setup.mdx; framework files reference it + +--- + +#### C. MCP Client Integration +- **File 1**: `/home/user/docs/ai-frameworks/setup.mdx` + - Shows provider setup with `McpClientProvider` + +- **File 2**: `/home/user/docs/ai-frameworks/assistant-ui.mdx` Lines 50-150 + - Nearly identical provider setup code + +- **File 3**: `/home/user/docs/ai-frameworks/ag-ui.mdx` Lines 100-200 + - Same pattern shown again + +**Overlap**: ~80% code duplication +**Action**: Consolidate in setup.mdx; reference from framework files + +--- + +### 5. Tool Registration (Scattered, 150-200 Lines) + +#### A. registerTool() vs useWebMCP() +- **File 1**: `/home/user/docs/concepts/tool-registration.mdx` (dedicated file) + - Section: "The Simple Way: registerTool()" + - Explains lifecycle, best practices + +- **File 2**: `/home/user/docs/packages/react-webmcp.mdx` Lines 43-120 + - "useWebMCP" detailed API reference + - Includes type definitions, advanced usage + +- **File 3**: `/home/user/docs/quickstart.mdx` Lines 55-73 + - Brief tool registration example + +- **File 4**: `/home/user/docs/best-practices.mdx` (scattered references) + - Mentions patterns but doesn't detail + +**Note**: These are somewhat complementary rather than true duplicates, but could be consolidated better + +--- + +### 6. Conditional Tool Registration (100 Lines) + +#### A. Dynamic Tools Based on State +- **File 1**: `/home/user/docs/advanced.mdx` Lines 7-84 + - Section: "Dynamic Tool Registration" + - Shows user role-based registration + - Shows page-specific tools + - Shows component lifecycle scoping + +- **File 2**: `/home/user/docs/security.mdx` Lines 559-616 + - Section: "Conditional Registration" + - Shows admin-only tools example + +- **File 3**: `/home/user/docs/best-practices.mdx` Lines 875-914 + - Section: "Tool Organization" → "Reference Related Tools" + +**Overlap**: ~40% - similar patterns shown in different contexts + +**Action**: advanced.mdx is best reference; mention in security.mdx + +--- + +## Minor/Organizational Issues + +### Navigation Issues (Not Direct Duplication) + +1. **Extension Documentation** (`/home/user/docs/extension/`) + - index.mdx (512 lines) + agents.mdx (416 lines) + managing-userscripts.mdx (566 lines) + - Not duplicate, but fragmented - users must read multiple pages + +2. **Tool Design Scattered** + - concepts/tool-design.mdx talks design patterns + - best-practices.mdx talks implementation + - Both should be clearly linked in hierarchy + +3. **Security Model vs Best Practices** + - concepts/security.mdx = architectural model + - security.mdx = implementation best practices + - Should be clearly related + +--- + +## Summary by Severity + +### CRITICAL (Immediate Resolution Needed) +1. ✅ **Resolve JSON vs Markdown conflict** (best-practices vs tool-design) +2. ✅ **Consolidate tool naming guidance** (3 identical sections) +3. ✅ **Remove rate limiting duplication** (100% copy/paste in files 1 & 2) + +### HIGH (Week 1) +4. **Merge tool design patterns** (tool-design + best-practices) +5. **Deduplicate setup instructions** (introduction/quickstart/development) +6. **Consolidate AI framework setup** (6 files with overlapping content) + +### MEDIUM (Week 1-2) +7. Improve security navigation (add TOC) +8. Restructure best-practices.mdx (too large) +9. Fix tool registration cross-links + +### LOW (Nice to Have) +10. Improve extension documentation navigation +11. Use code snippet patterns for duplicates +12. Create "decision tree" for users + diff --git a/DEDUP_QUICK_REFERENCE.md b/DEDUP_QUICK_REFERENCE.md new file mode 100644 index 0000000..faa701c --- /dev/null +++ b/DEDUP_QUICK_REFERENCE.md @@ -0,0 +1,139 @@ +# Quick Reference: Documentation Deduplication Roadmap + +## Key Findings at a Glance + +- **Total Docs**: 77 MDX files, 18,103 lines +- **Duplicate Content**: ~4,000+ lines +- **Actionable Cleanup**: ~1,700-2,300 lines +- **Potential Reduction**: 9-13% of total docs + +## The 3 Biggest Problems + +### 1. Tool Design Guidance Spread Across 3 Files (2,485 lines) +**Files**: best-practices.mdx (1,480) | ai-frameworks/best-practices.mdx (540) | concepts/tool-design.mdx (465) + +**Issues**: +- Naming conventions explained identically in all 3 +- Same "products_search" examples repeated +- Identical error handling patterns shown multiple times +- Conflicting guidance on JSON vs Markdown responses + +**What to Do**: Consolidate into best-practices.mdx; reduce others to framework-specific content only +**Est. Impact**: Remove 800-1,000 lines + +### 2. Setup Instructions Duplicated in 3 Files (250+ lines) +**Files**: introduction.mdx | quickstart.mdx | development.mdx + +**Issues**: +- Same React/Vanilla/Script Tag examples repeated verbatim +- Same npm install commands in multiple places +- Confusing for users (which guide do I follow?) + +**What to Do**: Keep quickstart.mdx as primary; remove from introduction.mdx; development.mdx references it +**Est. Impact**: Remove 100-150 lines + +### 3. Security Guidance Scattered (500+ lines) +**Files**: security.mdx (984) | concepts/security.mdx (100) | best-practices.mdx (124) + +**Issues**: +- Rate limiting shown 3 different ways +- Input validation/sanitization duplicated +- Auth patterns explained multiple times +- Developers may miss critical threat models + +**What to Do**: security.mdx is primary; reference from best-practices; refactor concepts/security +**Est. Impact**: Remove 200-300 lines + +--- + +## Action Items (Ranked by Impact) + +### TIER 1: Do First (Week 1) +1. **Resolve JSON vs Markdown Conflict** (best-practices vs tool-design) + - Which is actually correct/preferred? + - Update both files to align + - Est: 2-4 hours + +2. **Consolidate Tool Design Guidance** + - Keep best-practices.mdx as canonical + - Extract implementation details; refocus tool-design.mdx on philosophy + - Reduce ai-frameworks/best-practices to framework-specific only + - Est: 4-6 hours + +### TIER 2: Do Second (Week 1-2) +3. **Deduplicate Setup Instructions** + - Keep quickstart.mdx primary + - Remove from introduction.mdx + - Have development.mdx reference it + - Est: 2-3 hours + +4. **Improve AI Framework Structure** + - Strengthen ai-frameworks/index.mdx as hub + - Move all setup to ai-frameworks/setup.mdx + - Remove setup from assistant-ui.mdx, ag-ui.mdx + - Est: 4-6 hours + +### TIER 3: Do Third (Week 2) +5. **Improve Security Navigation** + - Add table of contents to security.mdx + - Add anchors for quick navigation + - Cross-link with best-practices + - Est: 2-3 hours + +6. **Consider Restructuring best-practices.mdx** + - Currently 1,480 lines covering 12 topics + - Consider splitting into two files (Dev vs Deployment) + - Or create hub with sub-pages + - Est: 4-8 hours (depends on scope) + +### TIER 4: Nice to Have +7. **Consolidate Tool Registration Concepts** (Est: 2-3 hours) +8. **Use Code Snippet Patterns** for duplicate examples (Est: 3-4 hours) + +--- + +## Files Needing Changes (Priority Order) + +| File | Action | Est. Lines Removed | Priority | +|------|--------|-------------------|----------| +| best-practices.mdx | Consolidate tool design | 300-400 | HIGH | +| ai-frameworks/best-practices.mdx | Reduce to framework-specific only | 200-250 | HIGH | +| concepts/tool-design.mdx | Refocus on philosophy, remove implementation | 200-250 | HIGH | +| introduction.mdx | Remove setup examples | 50-75 | MEDIUM | +| development.mdx | Reference quickstart, remove setup | 50-100 | MEDIUM | +| security.mdx | Improve navigation (add TOC) | 0 | MEDIUM | +| ai-frameworks/assistant-ui.mdx | Remove setup instructions | 50-75 | MEDIUM | +| ai-frameworks/ag-ui.mdx | Remove setup instructions | 50-75 | MEDIUM | + +--- + +## Navigation & UX Improvements + +1. **Add cross-links**: Best-practices → Security.mdx for detailed patterns +2. **Create "Quick Reference" cards** in key files linking to detailed docs +3. **Improve table of contents** in long files (security.mdx, best-practices.mdx) +4. **Use consistent terminology** across all files +5. **Create decision tree** for users: "When should I read which file?" + +--- + +## Metrics to Track + +- **Before**: 18,103 lines | 77 files | ~4,000 duplicate lines +- **After**: ~17,000-17,400 lines | 75-77 files | Consolidated content +- **User Experience**: + - Faster time to find information (fewer duplicate results) + - Clearer progression from beginner → advanced + - Resolved conflicts (single source of truth) + - Better navigation structure + +--- + +## Detailed Analysis Available + +See `DEDUPLICATION_AUDIT.md` for: +- Exact file line numbers and ranges +- Code examples of duplications +- Detailed recommendations per file +- Specific sections to consolidate + From c9e42b9de328348a81143ea6903532b6eab56962 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Nov 2025 03:15:47 +0000 Subject: [PATCH 2/3] docs: add documentation structure analysis and reorganization plan Added comprehensive analysis for separating conceptual vs procedural content: - DOCUMENTATION_ANALYSIS_REPORT.md: Detailed file-by-file breakdown with line numbers - DOCUMENTATION_ACTION_CHECKLIST.md: Step-by-step implementation checklist Key findings: - why-webmcp.mdx (100% conceptual) incorrectly placed in Documentation tab - 3 missing Concepts pages: agent-threat-model, tool-routing, tool-composition - Documentation tab has 30-40% conceptual content that should link to Concepts - Detailed migration plan with 10-12 hour implementation estimate Proposed structure: - Documentation tab: Pure action-oriented "how to" guides - Concepts tab: Theory, architecture, and design philosophy - Cross-links between tabs for seamless navigation --- DOCUMENTATION_ACTION_CHECKLIST.md | 237 ++++++++++++++ DOCUMENTATION_ANALYSIS_REPORT.md | 498 ++++++++++++++++++++++++++++++ 2 files changed, 735 insertions(+) create mode 100644 DOCUMENTATION_ACTION_CHECKLIST.md create mode 100644 DOCUMENTATION_ANALYSIS_REPORT.md diff --git a/DOCUMENTATION_ACTION_CHECKLIST.md b/DOCUMENTATION_ACTION_CHECKLIST.md new file mode 100644 index 0000000..a9fae26 --- /dev/null +++ b/DOCUMENTATION_ACTION_CHECKLIST.md @@ -0,0 +1,237 @@ +# WebMCP Documentation Reorganization: Action Checklist + +## QUICK SUMMARY FOR DECISION-MAKERS + +**Main Finding**: The Documentation tab contains 100% conceptual content in `why-webmcp.mdx` that should be in the Concepts tab. Additionally, three major architectural concepts are embedded in procedural pages and should be extracted to dedicated Concepts pages. + +**Time to Implement**: ~8-12 hours total + +--- + +## PHASE 1: CRITICAL FIXES (1-2 hours) + +### ☐ Move why-webmcp.mdx to Concepts Tab +- **What**: Move entire file to `concepts/alternatives.mdx` +- **Why**: 100% conceptual content (design philosophy, alternatives comparison) +- **Files to change**: docs.json, introduction.mdx +- **Time**: 1 hour +- **Impact**: Fixes major tab confusion, improves navigation + +### ☐ Update docs.json Navigation +```json +// Remove from Documentation tab -> Guides: +"why-webmcp" + +// Add to Concepts tab -> NEW GROUP "Design & Philosophy": +{ + "group": "Design & Philosophy", + "pages": [ + "concepts/overview", + "concepts/alternatives" + ] +} +``` + +### ☐ Update introduction.mdx +- Remove link to `/why-webmcp` +- Add link to `/concepts/alternatives` in relevant sections +- Lines affected: 31, 293-295 + +--- + +## PHASE 2: DOCUMENTATION IMPROVEMENTS (3-4 hours) + +### ☐ Update Documentation Pages with Concept Links + +#### connecting-agents.mdx +- Add link to concepts/architecture near line 35 (Browser Agents section) +- Add link to concepts/extension near line 143 +- Condense "What are local MCP clients?" (lines 198-206) to 1-2 sentences + link + +#### best-practices.mdx +- Add "See Also" section at end +- Link to concepts/tool-design.mdx +- Link to concepts/performance.mdx +- Link to concepts/security.mdx + +#### advanced.mdx +- Add callout box before "Multi-Tab Tool Collection" (line 382) saying: + "For architectural overview, see [Concepts: Tool Routing](/concepts/tool-routing)" +- Add callout before "Cross-Site Tool Composition" (line 652) saying: + "For detailed architecture, see [Concepts: Tool Composition](/concepts/tool-composition)" + +#### security.mdx +- Add callout after "Why WebMCP Security is Different" (line 30) saying: + "For deep dive into threat models, see [Concepts: Agent Threat Model](/concepts/agent-threat-model)" + +--- + +## PHASE 3: CREATE MISSING CONCEPTS PAGES (5-6 hours) + +### ☐ Create concepts/agent-threat-model.mdx (NEW) +- **Source material**: documentation/security.mdx lines 11-180 +- **Size**: 150-200 lines +- **Content sections**: + - Prompt Injection: The "Lethal Trifecta" + - Tool Misrepresentation Risks + - Privacy: User Fingerprinting via Over-Parameterization +- **Time to create**: 2-3 hours +- **Frontmatter**: + ```yaml + title: 'Agent-Specific Security Threats' + description: 'Unique security challenges in multi-agent environments. Threat modeling, prompt injection risks, and WebMCP-specific defenses.' + icon: 'triangle-exclamation' + ``` + +### ☐ Create concepts/tool-routing.mdx (NEW) +- **Source material**: documentation/advanced.mdx lines 382-436 +- **Size**: 100-150 lines +- **Content sections**: + - Multi-Tab Tool Collection Overview + - How Tool Collection Works (with mermaid diagram) + - Tool Routing Mechanism + - Design Implications +- **Time to create**: 1-2 hours +- **Frontmatter**: + ```yaml + title: 'Tool Routing & Multi-Tab Collection' + description: 'How MCP-B extension collects and routes tool calls across multiple browser tabs simultaneously.' + icon: 'network-wired' + ``` + +### ☐ Create concepts/tool-composition.mdx (NEW) +- **Source material**: documentation/advanced.mdx lines 652-710 +- **Size**: 100-150 lines +- **Content sections**: + - Cross-Site Tool Composition Overview + - How Cross-Site Calls Work (with sequence diagram) + - Security Isolation Between Sites + - Common Composition Patterns +- **Time to create**: 1-2 hours +- **Frontmatter**: + ```yaml + title: 'Cross-Site Tool Composition' + description: 'Composing tools from multiple websites into complex workflows. Architecture, patterns, and security considerations.' + icon: 'link' + ``` + +### ☐ Update docs.json to Add New Concepts Pages +```json +{ + "group": "Architecture & Patterns", + "pages": [ + "concepts/architecture", + "concepts/tool-routing", + "concepts/tool-composition", + "concepts/mcp-ui-integration" + ] +} +``` + +--- + +## PHASE 4: OPTIONAL POLISH (2-3 hours) + +### ☐ Consider Renaming Tabs for Clarity +- **Option 1**: "Documentation" → "How-To Guides" +- **Option 2**: "Concepts" → "Concepts & Philosophy" +- Pros: More descriptive +- Cons: Breaking change to URL structure + +### ☐ Add Tab Purpose Descriptions +Add to top of each tab in navigation (mintlify supports this): +``` +Documentation: Step-by-step guides and procedural instructions for building and deploying WebMCP tools +Concepts: Theoretical foundations, architectural patterns, and design decisions behind WebMCP +``` + +### ☐ Add Cross-References at Bottom of Pages +- Add "Learn more: [Read the theory behind this guide](/concepts/page-name)" callouts +- Add "Get started: [Implement this pattern](/guide-name)" callouts in Concepts pages + +### ☐ Consider Splitting best-practices.mdx +- Current: 1481 lines (very long) +- Option: Split into: + - best-practices-tool-design.mdx + - best-practices-security.mdx + - best-practices-performance.mdx +- Note: Only if page length becomes unwieldy (recommend <1200 lines) + +--- + +## VERIFICATION CHECKLIST + +After completing above, verify: + +- ☐ No procedural/action-oriented content in Concepts tab +- ☐ No 100% conceptual content in Documentation tab +- ☐ All architectural patterns (tool routing, composition, threat models) have dedicated Concepts pages +- ☐ Cross-references exist between related Documentation and Concepts pages +- ☐ docs.json navigation structure updated and consistent +- ☐ All internal links still work (test after file moves) +- ☐ Each Concepts page links to relevant Documentation page (if exists) +- ☐ Each Documentation page links to related Concepts pages (if exists) + +--- + +## LINE-BY-LINE MIGRATION SPECIFICS + +### why-webmcp.mdx → concepts/alternatives.mdx + +**Files to modify**: +1. `/home/user/docs/why-webmcp.mdx` → `/home/user/docs/concepts/alternatives.mdx` +2. `/home/user/docs/introduction.mdx` (update links) +3. `/home/user/docs/docs.json` (update navigation) + +**Frontmatter change**: +```yaml +# BEFORE +--- +title: 'Why WebMCP?' +description: 'Understand why WebMCP provides a better approach...' +icon: 'lightbulb' +--- + +# AFTER +--- +title: 'WebMCP vs Alternatives' +description: 'Comparison of WebMCP with browser automation, remote MCP, computer use, and other approaches. When to use WebMCP vs alternatives.' +icon: 'columns-3' +--- +``` + +--- + +## ESTIMATED EFFORT BREAKDOWN + +| Phase | Task | Hours | Priority | +|-------|------|-------|----------| +| 1 | Move why-webmcp.mdx | 1 | CRITICAL | +| 1 | Update docs.json | 0.5 | CRITICAL | +| 2 | Add concept links to Doc pages | 3 | HIGH | +| 3 | Create agent-threat-model.mdx | 2.5 | HIGH | +| 3 | Create tool-routing.mdx | 1.5 | HIGH | +| 3 | Create tool-composition.mdx | 1.5 | HIGH | +| 3 | Update docs.json for new pages | 0.5 | HIGH | +| 4 | Polish/renaming/cross-refs | 2 | MEDIUM | +| 4 | Test all links | 1 | MEDIUM | +| **TOTAL** | | **13.5 hours** | | + +**Recommended approach**: +- Do Phases 1-3 (9 hours) in one work session +- Do Phase 4 (4.5 hours) in follow-up session after community feedback + +--- + +## SUCCESS CRITERIA (Final Review) + +Page through documentation and verify users experience: + +1. **Getting started?** → Introduction → Quickstart → Examples (all procedural) +2. **Want to build?** → Guides section (all procedural) +3. **Want to understand WHY?** → Concepts section (all conceptual) +4. **Need architectural details?** → New concepts pages cover tool routing, composition, threats +5. **Cross-references exist?** → Documentation → Concepts and vice versa + +✅ If all above check out, reorganization is complete! + diff --git a/DOCUMENTATION_ANALYSIS_REPORT.md b/DOCUMENTATION_ANALYSIS_REPORT.md new file mode 100644 index 0000000..1c9a278 --- /dev/null +++ b/DOCUMENTATION_ANALYSIS_REPORT.md @@ -0,0 +1,498 @@ +# WebMCP Documentation Structure Analysis Report + +## EXECUTIVE SUMMARY + +The WebMCP documentation has significant conceptual content currently placed in the Documentation tab that should be moved to or linked from the Concepts tab. The main issue is that **why-webmcp.mdx is entirely conceptual** (design philosophy, alternatives comparison) but located in the Documentation tab's "Guides" group. Additionally, several procedural pages contain substantial theoretical sections explaining architectural patterns and threat models. + +**Current State**: +- Documentation tab (10 pages): Mix of ~60% procedural, 40% conceptual +- Concepts tab (11 pages): Pure conceptual content, well-organized + +**Recommended Action**: Restructure Documentation to be purely action-oriented with strategic links to Concepts for deeper understanding. + +--- + +## DETAILED FILE-BY-FILE ANALYSIS + +### DOCUMENTATION TAB PAGES + +--- + +## 1. introduction.mdx (308 lines) + +**Classification**: Entry point - Mixed (70% procedural, 30% conceptual) + +**Conceptual Sections**: +- **Lines 11-29**: "The Problem" + "Design Philosophy" - Philosophical framework explaining WebMCP's core principles (human-in-the-loop, AI augments vs. replaces) +- **Lines 35-46**: "What WebMCP Is NOT" - Boundary setting (headless browsing, autonomous agents, backend services, UI replacement) +- **Lines 113-128**: "How It Works" steps - High-level architectural flow +- **Lines 262-279**: "Understanding the Standards" - Relationship between WebMCP and MCP specification + +**Overlap with Concepts**: +- Design philosophy duplicates concepts/overview.mdx (lines 18-24) +- Standards explanation overlaps with concepts/overview.mdx (lines 26-54) + +**Assessment**: This is appropriate for an introduction. Keep most conceptual content here since it's the entry point, but could link to concepts/overview.mdx for deeper dives. + +**Recommendation**: +- ✅ KEEP: Quick example and quick navigation to next steps +- ✅ KEEP: Design philosophy intro (brief) +- ↔️ LINK: "Design Philosophy" → concepts/overview +- ↔️ LINK: "Understanding the Standards" → concepts/overview +- ✅ KEEP: Key terms reference to glossary + +--- + +## 2. quickstart.mdx (292 lines) + +**Classification**: Procedural guide - 85% action-oriented + +**Conceptual Sections**: +- **Lines 94-109**: "Building Interactive Apps with MCP-UI + WebMCP" - Brief explanation of bidirectional communication and three-part system +- **Lines 215-262**: "Best Practices" accordion group - Explanations of WHY practices matter (context engineering, lifecycle management, security principles) + +**Assessment**: Mostly action-oriented and appropriate for Documentation tab. The "Best Practices" section has explanatory text that duplicates concepts/tool-design.mdx content. + +**Recommendation**: +- ✅ KEEP: Installation and basic setup examples +- ✅ KEEP: Real-world example +- ✅ KEEP: Testing section +- ✅ KEEP: Best Practices (but consider linking detailed patterns to concepts/tool-design.mdx for deeper understanding) +- ↔️ LINK: "Best Practices" → concepts/tool-design.mdx for design pattern rationale + +--- + +## 3. examples.mdx (214 lines) + +**Classification**: Reference/resource guide - 95% procedural + +**Conceptual Sections**: +- **Lines 19-30**: Brief explanations of why webmcp.sh example "stands out" +- **Lines 74-79**: "Why MCP-UI + WebMCP?" - Brief conceptual summary + +**Assessment**: This is appropriately action-oriented reference material. Minimal conceptual content. + +**Recommendation**: +- ✅ KEEP: Keep as-is. This is reference material showing working implementations. + +--- + +## 4. why-webmcp.mdx (351 lines) + +**🚨 CRITICAL ISSUE: WRONG TAB** + +**Classification**: Purely conceptual - 100% theoretical/comparative + +**Content Breakdown**: +- **Lines 7-43**: Browser automation inefficiency (conceptual analysis) +- **Lines 51-71**: Why Remote MCP doesn't solve browser problems (comparison) +- **Lines 77-147**: WebMCP approach vs. UI navigation (comparison matrix, architectural discussion) +- **Lines 149-184**: Context engineering philosophy and UI design for LLMs +- **Lines 186-232**: Architectural advantages of browser location +- **Lines 234-246**: Philosophy statement ("Admission, not prediction") +- **Lines 248-300**: Comprehensive alternatives comparison with decision criteria +- **Lines 302-312**: When NOT to use WebMCP (scope boundaries) + +**Assessment**: +- This entire page is theoretical comparison and design philosophy +- Does NOT provide procedural guidance ("how to" content) +- Explains "why WebMCP was designed this way" and "when to use WebMCP vs alternatives" +- Currently in Documentation "Guides" group but is fundamentally conceptual + +**Problem**: +- User looking for "how to build WebMCP tools" will find this +- Should be in Concepts tab for users wanting to understand design decisions +- Misplaces comparison/decision-making content in "how-to" section + +**Recommendation**: +- ⚠️ **MOVE to Concepts tab** as `concepts/alternatives.mdx` or `concepts/why-webmcp.mdx` +- Create new group in Concepts: "Design & Philosophy" or "Decision Making" +- Replace Documentation link with brief comparison in introduction.mdx + link to full Concepts page +- Or keep slim version in Documentation focused only on "Quick Comparison" with link to full Concepts page + +**Specific Suggested Reorganization**: +``` +Documentation tab - Guides group: +- Remove why-webmcp.mdx or replace with "Why Use WebMCP?" (one-page quick guide) + +Concepts tab - New "Design & Philosophy" group: +- Add concepts/alternatives.mdx (expanded why-webmcp.mdx) +- Add concepts/design-philosophy.mdx +- Keep existing concepts/overview.mdx here +``` + +--- + +## 5. connecting-agents.mdx (600 lines) + +**Classification**: Procedural guide - 70% procedural, 30% conceptual + +**Conceptual Sections** (Should be shortened or linked): +- **Lines 33-77**: "Browser Agents" - Explains WHAT browser agents are (conceptual) before WHEN to use them + - Could move explanation to concepts page + - Procedural content (lines 61-77) is good to keep + +- **Lines 79-139**: "Frontend AI Frameworks" - Brief conceptual intro (lines 79-87) then procedural + +- **Lines 141-180**: "MCP-B Extension" - Conceptual explanation (what it is) mixed with procedural + +- **Lines 196-354**: "Local MCP Clients" - Extensive explanation of what they are (lines 198-206) before procedures + +**Assessment**: +- Good procedural guide for connecting agents +- But wastes space on conceptual explanations of "what is X" before showing "how to use X" +- Could be streamlined with links to Concepts pages + +**Recommendation**: +- ✅ KEEP: All procedural sections (quick setup, configuration, examples) +- ✅ KEEP: Comparison matrix (line 409-418) - decision-making tool +- ✅ KEEP: Security considerations (lines 420-454) - important for users +- ↔️ LINK: "What are browser agents?" → concepts/architecture.mdx or new concepts page +- ↔️ LINK: "What is MCP-B Extension?" → concepts/extension.mdx or architecture +- ↔️ CONDENSE: Explanations of "what is X" can be 1-2 sentences with links + +--- + +## 6. best-practices.mdx (1481 lines) + +**Classification**: Procedural best practices guide - 80% procedural + +**Content Breakdown**: +- Lines 7-15: Intro explaining website owner context +- **Lines 15-94**: Tool Design Principles (procedural with explanations) +- Lines 147-262: Input validation (procedural) +- Lines 249-323: Response format (procedural with markdown explanation) +- Lines 365-435: Error handling (procedural) +- Lines 470-559: Security best practices (procedural with explanations) +- Lines 595-743: Performance optimization (procedural) +- Lines 780-873: Testing & QA (procedural) +- Lines 875-987: Tool organization (procedural) +- Lines 995-1125: Framework integration (procedural) +- Lines 1126-1220: Documentation (procedural) +- Lines 1221-1304: Monitoring & analytics (procedural) +- Lines 1305-1367: Version management (procedural) + +**Conceptual Overlap**: +- Tool naming, descriptions, schemas overlap with concepts/tool-design.mdx +- Performance optimization overlaps with concepts/performance.mdx +- Security explanations overlap with concepts/security.mdx + +**Assessment**: +- This is a solid, comprehensive "best practices" guide for developers +- Procedurally focused with good "good vs bad" examples +- Overlap with Concepts pages is expected (different levels of detail) +- This is appropriate for Documentation tab + +**Recommendation**: +- ✅ KEEP: Keep in Documentation tab as comprehensive procedural guide +- ↔️ LINK: Add "For deeper context" links to relevant Concepts pages + - Tool naming/design → concepts/tool-design.mdx + - Performance guidance → concepts/performance.mdx + - Security patterns → concepts/security.mdx +- 📝 CONSIDER: This is very long (1481 lines). Could be split or summarized with links to specific sections. + +--- + +## 7. development.mdx (317 lines) + +**Classification**: Procedural development guide - 95% procedural + +**Content**: +- Lines 7-124: Setup and workflow (procedural) +- Lines 126-145: Hot reload support (brief explanation + procedural) +- Lines 147-186: Debugging tools (procedural with explanations) +- Lines 234-280: Environment configuration and troubleshooting (procedural) + +**Assessment**: Appropriate procedural guide for local development workflow. + +**Recommendation**: +- ✅ KEEP: Keep in Documentation tab as-is +- No changes needed + +--- + +## 8. advanced.mdx (908 lines) + +**Classification**: Advanced patterns guide - 65% procedural, 35% conceptual + +**Conceptual Sections** (explanations of patterns before/alongside examples): +- **Lines 7-84**: "Dynamic Tool Registration" - Mostly procedural examples, appropriate + +- **Lines 86-151**: "Context Engineering Patterns" + - Lines 86-92: Conceptual explanation of what context engineering is and why it matters + - Lines 94-151: Procedural pattern examples + - **ISSUE**: The concept of context engineering (lines 86-92) explains a mental model that could be in Concepts + +- **Lines 243-264**: State synchronization - Procedural with examples + +- **Lines 382-588**: "Multi-Tab Tool Collection" + - **Lines 382-390**: Architectural explanation of how tool collection works + - **Lines 391-436**: Tool routing explanation and diagrams (CONCEPTUAL ARCHITECTURE) + - **Lines 460-588**: Design implications (architectural thinking) + - **ISSUE**: This section is 40% architectural explanation. Should reference concepts/architecture.mdx + +- **Lines 652-832**: "Cross-Site Tool Composition" + - **Lines 652-710**: Architectural explanation of how cross-site calls work (CONCEPTUAL) + - **Lines 712-762**: Example patterns (procedural) + - **Lines 764-832**: Best practices (procedural) + - **ISSUE**: Lines 652-710 explain architectural concepts that should be in Concepts + +**Assessment**: +- Strong procedural patterns guide for advanced use cases +- But contains embedded architectural concepts mixed with examples +- The "Multi-Tab Tool Collection" and "Cross-Site Tool Composition" sections have significant conceptual content + +**Recommendation**: +- ✅ KEEP: All procedural examples (how to implement patterns) +- ✅ KEEP: Error handling and performance sections +- ↔️ EXTRACT: "Multi-Tab Tool Collection" architecture section → New Concepts page or expand concepts/architecture.mdx +- ↔️ EXTRACT: "Cross-Site Tool Composition" architectural explanation → New Concepts page +- ↔️ LINK: Context engineering concept → New concepts page on "Tool Design Philosophy" or explain inline concepts/tool-design.mdx +- 📝 SUGGESTION: Create `concepts/tool-routing-and-composition.mdx` page with: + - Multi-tab tool collection architecture + - Cross-site tool composition patterns + - Tool routing and security isolation + - Reference the advanced.mdx examples + +--- + +## 9. building-mcp-ui-apps.mdx (392 lines) + +**Classification**: Procedural guide - 85% procedural, 15% conceptual + +**Conceptual Sections**: +- **Lines 7-16**: "What You're Building" - Explains three-component system and bidirectional interaction +- **Lines 20-38**: Navigation guide with references to architecture (conceptual intro) + +**Assessment**: +- Appropriate amount of conceptual framing for procedural guide +- Correctly links to concepts/mcp-ui-integration.mdx for architecture +- Good balance of "what you're building" + "how to build it" + +**Recommendation**: +- ✅ KEEP: Keep as-is +- ✅ GOOD: Existing link to concepts/mcp-ui-integration.mdx is perfect + +--- + +## 10. security.mdx (985 lines) + +**Classification**: Security guide - 60% procedural, 40% conceptual + +**Conceptual Sections**: +- **Lines 11-50**: "Why WebMCP Security is Different" + - Lines 11-30: Multi-website threat model explanation (CONCEPTUAL) + - Lines 32-50: Core security principles (CONCEPTUAL/FOUNDATIONAL) + - **ISSUE**: This overlaps with concepts/security.mdx but goes DEEPER into agent-specific threats + +- **Lines 52-180**: "Agent-Specific Threats" + - **Lines 54-122**: Prompt injection explanation and risk scenarios (NEW CONCEPTUAL CONTENT NOT IN CONCEPTS TAB) + - Lines 70-122: Mitigation patterns (procedural) + - **ISSUE**: This threat model is unique to WebMCP's multi-agent context and NOT in concepts/security.mdx + +- **Lines 246-352**: "Tool Misrepresentation Risks" and "Privacy: User Fingerprinting" + - Architectural threat analysis (CONCEPTUAL) + +- **Lines 798-910**: "Standard Web Security" (procedural) + +**Overlap Analysis**: +- concepts/security.mdx covers: Authentication, Authorization, Origin Validation (foundational) +- documentation/security.mdx covers: Agent-specific threats, prompt injection, fingerprinting, tool misrepresentation (threat modeling) +- These are COMPLEMENTARY not duplicative + +**Assessment**: +- This file provides unique threat modeling for multi-agent scenarios +- The agent-specific threats section is NEW CONCEPTUAL CONTENT not represented in Concepts tab +- Important for developers to understand before building tools + +**Recommendation**: +- ✅ KEEP: This in Documentation tab - it's security best practices +- 🆕 CREATE: New concepts page `concepts/security-threats.mdx` or `concepts/agent-threat-model.mdx` covering: + - Prompt injection risks and mitigations + - Tool misrepresentation risks + - Fingerprinting via over-parameterization + - Multi-website agent compromise scenarios +- ↔️ LINK: Documentation/security.mdx → Link to new Concepts page for threat model deep dive +- ↔️ LINK: Concepts/security.mdx → Link to Documentation/security.mdx for mitigation patterns + +--- + +## ANALYSIS: CONCEPTS TAB (Existing Content) + +Current Concepts pages (confirmed by reading): + +1. **concepts/overview.mdx** (75 lines) - What is WebMCP, design philosophy, relationship to MCP +2. **concepts/architecture.mdx** (154 lines) - Components, interaction flow, data flow +3. **concepts/tool-design.mdx** (466 lines) - Design patterns, naming, descriptions, inputs/outputs +4. **concepts/mcp-ui-integration.mdx** (176 lines) - Bidirectional integration, communication flow +5. **concepts/tool-registration.mdx** - (not fully read, but title suggests procedural) +6. **concepts/transports.mdx** - (not read) +7. **concepts/security.mdx** (100+ lines) - Authentication, authorization, origin validation +8. **concepts/performance.mdx** (100+ lines) - Registration performance, lazy loading +9. **concepts/extension.mdx** - (not read) +10. **concepts/schemas.mdx** - (not read) +11. **concepts/glossary.mdx** - (not read) + +**Gaps Identified** (Conceptual content missing from Concepts tab): + +1. 🚨 **No: Alternatives Comparison & Design Decisions** + - Currently in documentation/why-webmcp.mdx + - Should be: concepts/alternatives.mdx (move from Documentation) + - Related to: concepts/overview.mdx + +2. 🚨 **No: Agent-Specific Security Threats** + - Currently in documentation/security.mdx (lines 52-180) + - Should be: concepts/agent-threat-model.mdx (new page) + - Related to: concepts/security.mdx + +3. 🚨 **No: Tool Routing & Multi-Tab Collection** + - Currently in documentation/advanced.mdx (lines 382-436) + - Should be: concepts/tool-routing.mdx (new page) + - Related to: concepts/architecture.mdx + +4. 🚨 **No: Cross-Site Tool Composition** + - Currently in documentation/advanced.mdx (lines 652-710) + - Should be: concepts/tool-composition.mdx (new page) + - Related to: concepts/architecture.mdx + +5. ⚠️ **No: What is MCP-B Extension** + - Scattered across documentation/connecting-agents.mdx and concepts/architecture.mdx + - Should be: concepts/extension.mdx (possibly exists, not read) + - Related to: concepts/architecture.mdx + +--- + +## SUMMARY TABLE: CONTENT CLASSIFICATION + +| File | Tab | Lines | % Conceptual | % Procedural | Status | Action | +|------|-----|-------|--------------|--------------|--------|--------| +| introduction.mdx | Doc | 308 | 30% | 70% | ✅ Good | Minor: Link to concepts | +| quickstart.mdx | Doc | 292 | 15% | 85% | ✅ Good | Minor: Link to concepts | +| examples.mdx | Doc | 214 | 5% | 95% | ✅ Good | Keep as-is | +| **why-webmcp.mdx** | Doc | 351 | **100%** | **0%** | 🚨 Wrong tab | **MOVE to Concepts** | +| connecting-agents.mdx | Doc | 600 | 30% | 70% | ⚠️ Mixed | Condense concepts, add links | +| best-practices.mdx | Doc | 1481 | 20% | 80% | ✅ Good | Link to concept pages | +| development.mdx | Doc | 317 | 5% | 95% | ✅ Good | Keep as-is | +| advanced.mdx | Doc | 908 | 35% | 65% | ⚠️ Mixed | Extract architecture sections | +| building-mcp-ui-apps.mdx | Doc | 392 | 15% | 85% | ✅ Good | Keep as-is | +| security.mdx | Doc | 985 | 40% | 60% | ⚠️ Mixed | Link to new threat model concepts page | + +--- + +## RECOMMENDED MIGRATION PLAN + +### Phase 1: High-Priority Moves (Structural Issues) + +**Move why-webmcp.mdx to Concepts tab** +- New location: `concepts/alternatives.mdx` +- Update docs.json navigation +- Update Documentation/introduction.mdx to link to Concepts page +- Estimated effort: 1 hour + +**Create new Concepts pages for missing content**: + +1. **concepts/agent-threat-model.mdx** (NEW) + - Extract from documentation/security.mdx (lines 11-180) + - Add content: Prompt injection, tool misrepresentation, fingerprinting risks + - Size: 150-200 lines + - Effort: 2-3 hours + +2. **concepts/tool-routing.mdx** (NEW) + - Extract from documentation/advanced.mdx (lines 382-436) + - Content: Multi-tab tool collection architecture, routing patterns + - Size: 100-150 lines + - Effort: 1-2 hours + +3. **concepts/tool-composition.mdx** (NEW) + - Extract from documentation/advanced.mdx (lines 652-710) + - Content: Cross-site composition patterns, architecture + - Size: 100-150 lines + - Effort: 1-2 hours + +### Phase 2: Medium-Priority Improvements (Content Quality) + +**Streamline Documentation pages with links**: +- connecting-agents.mdx: Shorten conceptual explanations, add links to concepts +- advanced.mdx: Extract architecture diagrams, reference new concepts pages +- security.mdx: Add callouts linking to new threat model concepts page +- best-practices.mdx: Add "See also" links to relevant Concepts pages + +Estimated effort: 3-4 hours + +### Phase 3: Low-Priority Polish (Optional) + +- Add cross-references in both tabs +- Consider splitting best-practices.mdx if > 1500 lines +- Review all internal links for consistency +- Add "Conceptual vs Procedural" section labels + +Estimated effort: 2-3 hours + +--- + +## DOCUMENTATION TAB RESTRUCTURING PROPOSAL + +**Current Structure** (10 pages): +- Getting Started (3): introduction, quickstart, examples +- Guides (7): why-webmcp, connecting-agents, best-practices, development, advanced, building-mcp-ui-apps, security + +**Proposed Structure** (9 pages): +- Getting Started (3): introduction, quickstart, examples + - [Remove why-webmcp - move to Concepts] +- Guides (6): + - connecting-agents (streamlined) + - best-practices (with concept links) + - development (keep as-is) + - advanced (with architecture extracted) + - building-mcp-ui-apps (keep as-is) + - security (with threat model links) + +**Concepts Tab Addition** (11 → 14 pages): +- New group: "Design & Philosophy" + - alternatives.mdx (moved from Documentation) +- New group: "Architecture & Patterns" or expand "Advanced Topics" + - agent-threat-model.mdx (NEW) + - tool-routing.mdx (NEW) + - tool-composition.mdx (NEW) + +--- + +## KEY RECOMMENDATIONS + +### 1. **Fix Tab Confusion** (CRITICAL) +- **why-webmcp.mdx is 100% conceptual** and should be in Concepts tab +- Users looking for "How do I build tools?" find it in Documentation +- Users looking for "Should I use WebMCP vs MCP vs browser automation?" might miss it in hidden Documentation section + +### 2. **Add Missing Conceptual Pages** (HIGH PRIORITY) +- Agent-specific threat modeling is unique to WebMCP's multi-agent context +- Tool routing and composition patterns need dedicated explanation +- These exist only as scattered procedural examples without conceptual foundation + +### 3. **Use Cross-Tab Linking** (MEDIUM PRIORITY) +- Documentation pages should link to Concepts for "why" understanding +- Concepts pages should link to Documentation for "how" implementation +- Example: best-practices.mdx should say "For the theory behind this pattern, see concepts/tool-design.mdx" + +### 4. **Clarify Tab Purpose** (MEDIUM PRIORITY) +- Consider rename: "Documentation" → "How-To Guides" (more specific) +- Consider rename: "Concepts" → "Concepts & Philosophy" (more inclusive) +- Add intro blurb to each tab explaining its purpose + +### 5. **Consider Content Organization** (ONGOING) +- best-practices.mdx is very long (1481 lines) - consider whether it should be split +- advanced.mdx has significant architectural content embedded - consider clearer separation +- security.mdx could be split: Threats (Concepts) vs Mitigations (Documentation) + +--- + +## SUCCESS CRITERIA + +After implementation: + +- ✅ No procedural users accidentally land on purely conceptual pages +- ✅ No conceptual content hidden in Documentation tab +- ✅ Clear cross-references between "why" (Concepts) and "how" (Documentation) +- ✅ All architectural patterns have dedicated Concepts pages +- ✅ Agent-specific threat models documented and discoverable +- ✅ Navigation structure makes sense for both "I want to learn" and "I want to build" users From 4fff16821433051cbac99a969ace0a80885afdbc Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 19 Nov 2025 03:44:08 +0000 Subject: [PATCH 3/3] docs: restructure documentation to separate procedural and conceptual content MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Major restructuring to align Documentation tab with action-oriented content and Concepts tab with theoretical/architectural content. Changes: - Moved why-webmcp.mdx → concepts/alternatives.mdx (100% conceptual content) - Created concepts/agent-threat-model.mdx (security architecture and threat modeling) - Created concepts/tool-routing.mdx (multi-tab collection architecture) - Created concepts/tool-composition.mdx (cross-site composition patterns) - Updated docs.json navigation to reflect new structure - Added new "Architecture & Patterns" group in Concepts tab - Added cross-references from Documentation pages to Concepts pages Updated files: - introduction.mdx: Updated link to concepts/alternatives - security.mdx: Added link to concepts/agent-threat-model - advanced.mdx: Added links to concepts/tool-routing and concepts/tool-composition - best-practices.mdx: Added links to tool-design, performance, and agent-threat-model concepts - connecting-agents.mdx: Added link to concepts/architecture Impact: - Documentation tab now focuses on "how to do X" (action-oriented) - Concepts tab provides "why and how it works" (theory and architecture) - Clear separation improves navigation and reduces cognitive load - Users can deep dive into architecture without cluttering procedural guides --- advanced.mdx | 8 + best-practices.mdx | 24 ++ concepts/agent-threat-model.mdx | 276 +++++++++++++ why-webmcp.mdx => concepts/alternatives.mdx | 6 +- concepts/tool-composition.mdx | 433 ++++++++++++++++++++ concepts/tool-routing.mdx | 395 ++++++++++++++++++ connecting-agents.mdx | 4 + docs.json | 15 +- introduction.mdx | 2 +- security.mdx | 4 + 10 files changed, 1160 insertions(+), 7 deletions(-) create mode 100644 concepts/agent-threat-model.mdx rename why-webmcp.mdx => concepts/alternatives.mdx (97%) create mode 100644 concepts/tool-composition.mdx create mode 100644 concepts/tool-routing.mdx diff --git a/advanced.mdx b/advanced.mdx index b1cd236..2eae1bf 100644 --- a/advanced.mdx +++ b/advanced.mdx @@ -381,6 +381,10 @@ useWebMCP({ ## Multi-Tab Tool Collection + +For architectural details about how tool routing works, see [Concepts: Tool Routing & Multi-Tab Collection](/concepts/tool-routing) + + The MCP-B Extension collects and maintains tools from **all open tabs simultaneously**, making them available to agents regardless of which tab is currently active. @@ -651,6 +655,10 @@ function CheckoutFlow() { ## Cross-Site Tool Composition + +For architectural details and security considerations, see [Concepts: Cross-Site Tool Composition](/concepts/tool-composition) + + One of the most powerful features of the MCP-B Extension is the ability to compose tools from different websites. Tools from one site can use data from another site, enabling complex multi-site workflows. diff --git a/best-practices.mdx b/best-practices.mdx index a25a5fe..56e71ab 100644 --- a/best-practices.mdx +++ b/best-practices.mdx @@ -1428,6 +1428,30 @@ ${results.map(r => `- ${r.title}`).join('\n')}` ## Additional Resources + + Deep dive into tool design philosophy and patterns + + + + Understanding performance optimization strategies + + + + Security architecture for multi-agent environments + + +As a website builder, you are responsible for protecting your users from malicious agents. Agents may have access to tools from multiple websites—some potentially malicious. This page explains the unique threat model and architectural considerations for WebMCP security. + + +## The Multi-Website Threat Model + + +**Critical Context**: AI agents can interact with multiple websites simultaneously. Your tools may be used by an agent that has also loaded tools from malicious websites. This creates a unique security challenge where compromised agents can abuse your tools. + + +When an AI agent connects to your website, it may already have tools from other origins: + +- **Trusted tools**: Your website's legitimate functionality +- **Unknown tools**: Tools from other websites the user is visiting +- **Malicious tools**: Tools from compromised or malicious websites + +A malicious tool from another website could manipulate the agent into: +- Exfiltrating sensitive data through your tools +- Performing unauthorized actions using your authenticated APIs +- Tricking users into approving dangerous operations + +**Your Responsibility**: Assume the agent may be compromised. Design tools that protect users even when the agent is influenced by malicious actors from other websites. + +## Architectural Security Principles + +WebMCP's security model is built on several key architectural principles: + + + + Tools run with the user's existing session and permissions—never with elevated privileges + + + + Transport layer enforces same-origin policy to prevent cross-site tool abuse + + + + AI agents never receive user credentials—they inherit session context + + + + Tools only expose user-authorized actions, never background operations + + + +These principles create defense-in-depth, but don't eliminate all risks. Understanding the specific threats is essential for secure tool design. + +## Prompt Injection: The "Lethal Trifecta" + + +Prompt injection is a serious, largely unsolved security challenge for AI systems. While mitigations reduce risk, they don't eliminate it completely. + + +**Prompt injection** occurs when malicious actors manipulate AI agent behavior by crafting inputs that override intended instructions. The most dangerous scenarios occur when three conditions align: + +1. **Private user data access** - Tools that access personal information (emails, messages, profiles) +2. **Untrusted content exposure** - AI processes content from potentially malicious sources +3. **External communication** - Ability to send data outside the user's browser + + +**Example Risk**: An AI agent reading emails (private data) could be manipulated via prompt injection to exfiltrate sensitive information through tools with external communication capabilities—especially if malicious tools from other websites are present. + + +### Why This Is Unique to Multi-Agent Environments + +In traditional web applications, JavaScript from different origins cannot directly communicate. But in a multi-agent environment: + +```mermaid +graph TD + A[User's Browser] -->|Loads| B[YourSite.com Tools] + A -->|Loads| C[MaliciousSite.com Tools] + + D[AI Agent] -->|Has Access To| B + D -->|Has Access To| C + + C -->|Manipulates Agent via| E[Prompt Injection] + E -->|Agent Abuses| B + + B -->|Returns Sensitive Data| D + D -->|Executes| C + C -->|Exfiltrates Data| F[Attacker Server] + + style C fill:#ff6b6b + style E fill:#ff6b6b + style F fill:#ff6b6b +``` + +The AI agent acts as a bridge between origins, potentially allowing malicious tools to influence how your tools are used. + +### Architectural Defense: Never Pass Sensitive Data to Agents + + +**Critical Rule**: Sensitive information must NEVER be passed to the AI agent's context. A compromised agent (via malicious tools from other websites) could exfiltrate this data. Always use references instead. + + +**What should use references:** +- Passwords, tokens, API keys, session IDs +- Private messages, emails, documents +- Personal information (SSN, credit cards, addresses) +- Financial data (account numbers, balances) +- Health records, legal documents +- Any data you wouldn't want copied to a malicious website + +**How references work architecturally:** + +```mermaid +sequenceDiagram + participant Agent + participant YourTool + participant SecureStorage + participant User + + Agent->>YourTool: read_private_messages() + YourTool->>SecureStorage: Store messages (origin-scoped) + SecureStorage-->>YourTool: Reference ID + YourTool-->>Agent: Return reference (no raw data) + + Note over Agent: Agent cannot access raw data
Only has reference ID + + Agent->>User: Show reference with consent prompt + User->>SecureStorage: Approve access to reference + SecureStorage-->>User: Display data securely +``` + +The key architectural insight: **Raw sensitive data never enters the agent's context**, preventing exfiltration even if the agent is compromised. + +## Tool Misrepresentation Risks + + +AI agents cannot verify that tool descriptions accurately represent tool behavior. This creates opportunities for deception. + + +Since WebMCP tools run with the user's authenticated session, a deceptive tool could describe itself as "add to cart" while actually completing a purchase and charging the user's payment method. + +### Why Agents Can't Detect Misrepresentation + +AI agents only see: +- Tool name +- Tool description +- Input schema +- Annotations (readOnlyHint, destructiveHint, etc.) + +They **cannot**: +- Inspect the handler function code +- Verify behavior matches description +- Detect malicious intent + +### Architectural Mitigation: Honest Descriptions + Annotations + +The defense is architectural transparency: descriptions and annotations must accurately represent behavior, and high-impact operations should show browser confirmation dialogs so users see and approve actions directly. + + +For implementation patterns, see [Security Best Practices: Tool Misrepresentation](/security#tool-misrepresentation-risks) + + +## User Fingerprinting via Over-Parameterization + + +Tools can inadvertently enable user fingerprinting when AI agents provide detailed personal information through parameters. + + +When AI agents have access to user personalization data, malicious sites can craft tool parameters to extract this information without explicit user consent, enabling **covert profiling** of users who thought they were anonymous. + +### The Fingerprinting Attack Pattern + +```mermaid +graph LR + A[AI Agent] -->|Has User Profile Data| B[Personal Info:
age, location, interests] + + C[Malicious Tool] -->|Requests Parameters| D["recommend_products(
age, income, location,
interests, history)"] + + A -->|Calls Tool| C + C -->|Logs Parameters| E[User Fingerprint Database] + + style C fill:#ff6b6b + style E fill:#ff6b6b +``` + +Even if your site doesn't require login, a malicious tool can use over-parameterization to collect detailed user profiles through the agent. + +### Architectural Defense: Minimal Parameters + +**Design Principle**: Only request parameters that are absolutely necessary for the tool's function. Use server-side user context (from authenticated sessions) for personalization instead of agent-provided parameters. + +```javascript +// ❌ VULNERABLE: Reveals extensive user data through parameters +{ + name: 'recommend_products', + inputSchema: { + age, income, location, interests, + purchaseHistory, browsingHistory // DON'T DO THIS + } +} + +// ✅ BETTER: Minimal parameters, use server-side user context +{ + name: 'recommend_products', + inputSchema: { + category: optional, + priceRange: optional // Only what's needed + } + // Server already knows who the authenticated user is +} +``` + +## Cross-Origin Tool Composition Risks + +When multiple websites expose tools simultaneously, there's a risk of unintended tool composition: + +- **Chaining attacks**: Malicious tool uses your tool as a step in a larger attack +- **Context pollution**: Malicious tool manipulates agent state before your tool runs +- **Output manipulation**: Malicious tool intercepts or modifies your tool's output + +### Architectural Defense: Stateless Tools + +Design tools to be **stateless** and **idempotent** where possible. Each tool call should: +- Validate all inputs (never trust agent-provided data) +- Not depend on previous tool calls +- Return complete, self-contained results + + +For implementation patterns, see [Security Best Practices: Input Validation](/security#input-validation--sanitization) + + +## Threat Mitigation Summary + +| Threat | Architectural Defense | Implementation Pattern | +|--------|----------------------|------------------------| +| Prompt Injection | Never pass sensitive data; use references | [Security Guide](/security#prompt-injection-the-lethal-trifecta) | +| Tool Misrepresentation | Honest descriptions + browser confirmations | [Security Guide](/security#tool-misrepresentation-risks) | +| User Fingerprinting | Minimal parameters; server-side context | [Security Guide](/security#privacy-user-fingerprinting-via-over-parameterization) | +| Cross-Origin Abuse | Stateless tools; input validation | [Best Practices](/best-practices#input-validation) | + +## Next Steps + +Now that you understand the threat model, learn how to implement secure tools: + + + + Practical implementation patterns for secure tools + + + + Design patterns for robust, secure tools + + + + How WebMCP enforces origin isolation + + + + Comprehensive guide to secure development + + diff --git a/why-webmcp.mdx b/concepts/alternatives.mdx similarity index 97% rename from why-webmcp.mdx rename to concepts/alternatives.mdx index 8fc77e6..e24d815 100644 --- a/why-webmcp.mdx +++ b/concepts/alternatives.mdx @@ -1,7 +1,7 @@ --- -title: 'Why WebMCP?' -description: 'Understand why WebMCP provides a better approach to browser AI than automation, remote APIs, or computer use. Compare deterministic function calls vs UI navigation.' -icon: 'lightbulb' +title: 'WebMCP vs Alternatives' +description: 'Comparison of WebMCP with browser automation, remote MCP, computer use, and other approaches. When to use WebMCP vs alternatives and design philosophy behind the standard.' +icon: 'scale-balanced' --- WebMCP competes with three existing approaches to connecting AI to the web. This guide compares all four across key dimensions: determinism, speed, UI resilience, authentication complexity, and human oversight. Understanding these tradeoffs will help you choose the right tool for your use case. diff --git a/concepts/tool-composition.mdx b/concepts/tool-composition.mdx new file mode 100644 index 0000000..98be8d7 --- /dev/null +++ b/concepts/tool-composition.mdx @@ -0,0 +1,433 @@ +--- +title: 'Cross-Site Tool Composition' +description: 'Composing tools from multiple websites into complex workflows. Architecture, security isolation, data flow patterns, and best practices for multi-site tool composition.' +icon: 'link' +--- + +## Overview + +One of the most powerful features of the MCP-B Extension is the ability to compose tools from different websites. Tools from one site can use data from another site, enabling complex multi-site workflows. + + +**Key advantage**: Each site exposes its existing functionality as MCP tools, and the extension handles routing calls between them. The user maintains separate authentication contexts for each site. + + +This creates a unique architecture where AI agents can orchestrate workflows across multiple websites without requiring special integration or shared authentication between sites. + +## How Cross-Site Composition Works + +### Architecture Overview + +When an AI agent composes tools from multiple sites: + +```mermaid +sequenceDiagram + participant Agent + participant Extension + participant ShopSite as shop.example.com + participant PriceSite as pricewatch.com + + Agent->>Extension: What's in my cart? + Extension->>ShopSite: Call getCurrentCart() + ShopSite-->>Extension: Cart data (3 items) + Extension-->>Agent: Cart contents + + Agent->>Extension: Compare prices for these items + Extension->>PriceSite: Call comparePrices(items) + PriceSite->>PriceSite: Use existing auth/API + PriceSite-->>Extension: Price comparison results + Extension-->>Agent: Best deals found +``` + +### Separation of Concerns + +Each website operates independently: + +```mermaid +graph TB + subgraph "shop.example.com" + A[Cart Tools] + A1[User Session A
Auth Context A] + end + + subgraph "pricewatch.com" + B[Price Tools] + B1[User Session B
Auth Context B] + end + + subgraph "MCP-B Extension" + E[Tool Router] + E1[Conversation Context] + end + + E -->|Route calls| A + E -->|Route calls| B + A -.->|Uses| A1 + B -.->|Uses| B1 + E1 -->|Maintains| E + + style A1 fill:#ffe1e1 + style B1 fill:#ffe1e1 + style E1 fill:#e1f5ff +``` + +**Key architectural principles**: +- Each tool executes in its own origin's context +- Tools inherit their site's authentication automatically +- Extension routes tool calls without exposing credentials +- Sites never share authentication or sessions + +## Composition Patterns + +### Pattern 1: Data Aggregation + +Fetch data from one site and process it on another: + +**Site A** (News site) exposes content: + +```tsx +useWebMCP({ + name: 'news_get_top_stories', + description: 'Get top news stories. Returns array of {title, url, summary}', + handler: async () => { + const stories = await fetch('/api/stories/top').then(r => r.json()); + return { stories }; + } +}); +``` + +**Site B** (Social site) allows posting: + +```tsx +useWebMCP({ + name: 'social_post_to_feed', + description: 'Post a link to your social feed', + inputSchema: { + title: z.string(), + url: z.string().url() + }, + handler: async ({ title, url }) => { + return await fetch('/api/posts', { + method: 'POST', + credentials: 'same-origin', // Uses existing session + body: JSON.stringify({ title, url }) + }).then(r => r.json()); + } +}); +``` + +**Agent workflow**: "Get top news stories and share the most interesting one on social media" +- Calls `news_get_top_stories()` → gets data from news site +- Analyzes results +- Calls `social_post_to_feed()` → posts to social site + +### Pattern 2: Cross-Site Comparison + +Compare or enrich data across multiple sites: + +**Site A** (Shopping site) exposes cart: + +```tsx +useWebMCP({ + name: 'shop_get_current_cart', + description: 'Get items in shopping cart. Returns {items: Array<{name, price, sku}>, total: number}', + handler: async () => ({ + items: cart.items, + total: cart.total + }) +}); +``` + +**Site B** (Price comparison site) checks prices: + +```tsx +useWebMCP({ + name: 'prices_compare_product', + description: 'Compare prices for a product across multiple stores', + inputSchema: { + productName: z.string() + }, + handler: async ({ productName }) => { + const response = await fetch('/api/products/search', { + method: 'POST', + credentials: 'same-origin', + body: JSON.stringify({ query: productName }) + }); + return await response.json(); + } +}); +``` + +**Agent workflow**: "Check if items in my cart are available cheaper elsewhere" +- Calls `shop_get_current_cart()` → gets cart items +- For each item, calls `prices_compare_product()` → finds better prices +- Reports savings opportunities + +### Pattern 3: Multi-Step Workflow Composition + +Chain operations across sites: + +```tsx +// Calendar site +useWebMCP({ + name: 'calendar_get_upcoming_meetings', + description: 'Get upcoming calendar events', + handler: async () => ({ + meetings: await calendar.getUpcoming() + }) +}); + +// Email site +useWebMCP({ + name: 'email_send_reminder', + description: 'Send an email reminder', + inputSchema: { + to: z.string().email(), + subject: z.string(), + body: z.string() + }, + handler: async ({ to, subject, body }) => { + return await email.send({ to, subject, body }); + } +}); + +// Notes site +useWebMCP({ + name: 'notes_create', + description: 'Create a new note', + inputSchema: { + title: z.string(), + content: z.string() + }, + handler: async ({ title, content }) => { + return await notes.create({ title, content }); + } +}); +``` + +**Agent workflow**: "Prepare for tomorrow's meetings" +- Calls `calendar_get_upcoming_meetings()` → gets meeting list +- For each meeting, calls `notes_create()` → creates meeting notes +- Calls `email_send_reminder()` → sends reminders to participants + +## Security & Isolation + + +Cross-site tool composition introduces unique security considerations. Each site must protect against potential abuse from malicious tools on other sites. + + +### Origin Isolation + +While tools can be composed, they remain **origin-isolated** at execution time: + +- **Authentication**: Each tool uses its own site's session/cookies +- **Data access**: Tools can only access data within their origin +- **APIs**: Tools call their site's APIs with existing credentials +- **No shared state**: Sites cannot directly access each other's data + +### Trust Boundaries + +```mermaid +graph LR + A[Trusted Site A Tools] -->|Data output| E[Extension/Agent] + B[Trusted Site B Tools] -->|Data output| E + M[Malicious Site Tools] -->|Data output| E + + E -->|Calls with data| A + E -->|Calls with data| B + E -->|Calls with data| M + + M -.->|Could manipulate| E + E -.->|Could abuse| A + E -.->|Could abuse| B + + style M fill:#ff6b6b +``` + +**Security principle**: Never trust data from the agent. Always validate inputs, even if they appear to come from another legitimate site's tool. + +### Defense Strategies + + + + Treat all tool inputs as potentially malicious: + + ```tsx + useWebMCP({ + name: 'process_data', + inputSchema: { + productId: z.string().regex(/^[A-Z0-9]{8}$/), // Strict validation + quantity: z.number().min(1).max(100) + }, + handler: async ({ productId, quantity }) => { + // Additional business logic validation + if (!await productExists(productId)) { + throw new Error('Invalid product ID'); + } + // ... + } + }); + ``` + + + + Make tool outputs predictable and parseable: + + ```tsx + // ✅ Good - structured, typed + return { + items: [{id: 'abc', name: 'Product', price: 99.99}], + total: 99.99, + currency: 'USD' + }; + + // ❌ Bad - unstructured, hard to validate + return "You have 3 items totaling $99.99"; + ``` + + + + Never return sensitive data that could be exfiltrated: + + ```tsx + // ❌ Dangerous + return { + userEmail: user.email, // Don't expose + apiKey: user.apiKey, // Never expose + password: user.password // Absolutely never + }; + + // ✅ Safe - use references or sanitized data + return { + userId: user.id, + displayName: user.publicName + }; + ``` + + + + Prevent abuse of expensive operations: + + ```tsx + const limiter = new RateLimiter({ maxCalls: 10, windowMs: 60000 }); + + useWebMCP({ + name: 'expensive_operation', + handler: async () => { + if (!limiter.check()) { + throw new Error('Rate limit exceeded'); + } + // ... + } + }); + ``` + + + +## Best Practices for Composable Tools + +### 1. Use Descriptive, Namespaced Names + +Prevent collisions and provide context: + +```tsx +// ✅ Good - clear origin and purpose +name: 'github_create_issue' +name: 'jira_create_ticket' +name: 'shop_example_add_to_cart' + +// ❌ Bad - ambiguous +name: 'create_issue' // Which site? +name: 'add_to_cart' // Which shop? +``` + +### 2. Document Data Formats in Descriptions + +Help other sites understand your output: + +```tsx +useWebMCP({ + name: 'shop_get_cart', + description: 'Get shopping cart contents. Returns {items: Array<{name: string, price: number, sku: string, quantity: number}>, total: number, currency: string}', + handler: async () => { ... } +}); +``` + +### 3. Keep Tools Focused and Atomic + +Single-purpose tools compose better: + +```tsx +// ✅ Good - focused, composable +useWebMCP({ name: 'get_cart', ... }); +useWebMCP({ name: 'add_to_cart', ... }); +useWebMCP({ name: 'remove_from_cart', ... }); +useWebMCP({ name: 'checkout', ... }); + +// ❌ Bad - monolithic, hard to compose +useWebMCP({ name: 'cart_manager', ... }); // Does everything +``` + +### 4. Return Structured, Typed Data + +Make outputs easy for other tools to consume: + +```tsx +// ✅ Good - structured, predictable +return { + success: true, + data: { + items: [...], + total: 99.99 + }, + metadata: { + currency: 'USD', + timestamp: new Date().toISOString() + } +}; + +// ❌ Bad - unstructured text +return "Added 3 items, your cart now has 5 items totaling $99.99"; +``` + +## Implementation Examples + + +For practical code examples of cross-site workflows, see [Advanced Guide: Cross-Site Tool Composition](/advanced#cross-site-tool-composition) + + +## Next Steps + + + + Learn how the extension routes tool calls across tabs + + + + Security considerations for multi-site environments + + + + Comprehensive security best practices + + + + Implementation examples and techniques + + diff --git a/concepts/tool-routing.mdx b/concepts/tool-routing.mdx new file mode 100644 index 0000000..a56e966 --- /dev/null +++ b/concepts/tool-routing.mdx @@ -0,0 +1,395 @@ +--- +title: 'Tool Routing & Multi-Tab Collection' +description: 'How MCP-B extension collects and routes tool calls across multiple browser tabs simultaneously. Architecture, routing mechanisms, and design patterns for multi-tab environments.' +icon: 'network-wired' +--- + +## Overview + +The MCP-B Extension collects and maintains tools from **all open tabs simultaneously**, making them available to agents regardless of which tab is currently active. + + +**Key behavior**: Unlike traditional tab-scoped approaches, the extension aggregates tools from every open tab, giving agents access to your entire browsing context at once. + + +This architectural decision enables powerful cross-tab workflows while introducing unique design considerations for tool naming and organization. + +## How Tool Collection Works + +When you have multiple tabs open with WebMCP servers, the extension creates a unified tool registry: + +```mermaid +graph TB + subgraph "Browser Tabs" + T1[Tab 1: shop.example.com
Tools: add_to_cart, checkout] + T2[Tab 2: github.com
Tools: create_issue, list_repos] + T3[Tab 3: calendar.app
Tools: add_event, list_events] + end + + subgraph "MCP-B Extension" + E[Tool Registry
All tools from all tabs] + end + + T1 -->|Registers| E + T2 -->|Registers| E + T3 -->|Registers| E + + A[AI Agent] -->|Sees all tools| E + + style E fill:#e1f5ff + style A fill:#ffe1f0 +``` + +### Registration Lifecycle + +Each tab independently registers its tools with the extension: + + + + User opens a website or navigates to a new page + + + + Website's WebMCP code calls `registerTool()` or uses `useWebMCP()` hooks + + + + Extension adds tools to the global registry with origin metadata + + + + AI agent's tool list is updated to include new tools + + + + When tab is closed, its tools are automatically unregistered + + + +## Tool Routing Mechanism + +When an agent calls a tool, the extension routes the call to the correct tab: + +```mermaid +sequenceDiagram + participant Agent + participant Extension + participant GitHub as github.com Tab + participant Shop as shop.example.com Tab + + Note over Extension: All tabs' tools are visible + + Agent->>Extension: Call github_create_issue + Extension->>GitHub: Route to GitHub tab + GitHub->>GitHub: Execute tool + GitHub-->>Extension: Issue created + Extension-->>Agent: Success + + Agent->>Extension: Call shop_add_to_cart + Extension->>Shop: Route to Shop tab + Shop->>Shop: Execute tool + Shop-->>Extension: Added to cart + Extension-->>Agent: Success +``` + +### Routing Algorithm + + + + Agent calls a tool (e.g., `github_create_issue`) + + + + Extension looks up which tab registered that tool name + + + + If the tab is still open, the tool is executed immediately. If the tab was closed, the tool call fails. + + + + Tool execution results are routed back through extension to agent + + + +## Architectural Implications + +### 1. Tool Naming Becomes Critical + +Since all tools from all tabs are visible in a single namespace, naming conflicts can occur: + + + + ```tsx + // Clear origin and purpose + useWebMCP({ + name: 'github_create_issue', + description: 'Create a new GitHub issue in the current repository', + // ... + }); + + useWebMCP({ + name: 'jira_create_issue', + description: 'Create a new Jira issue in the current project', + // ... + }); + ``` + + + + ```tsx + // Ambiguous - which site? which feature? + useWebMCP({ + name: 'create', // ❌ Too generic + description: 'Create something', + // ... + }); + + useWebMCP({ + name: 'create_issue', // ❌ Naming conflict likely + description: 'Create an issue', + // ... + }); + ``` + + + +**Recommended pattern**: Prefix tool names with domain or feature identifier to avoid conflicts. + +### 2. Descriptions Must Provide Context + +Since agents see all tools at once without inherent context about which tab they came from, descriptions must be self-contained: + +```tsx +// ✅ Good - describes what, where, and context +useWebMCP({ + name: 'shop_add_to_cart', + description: 'Add the currently viewed product from shop.example.com to your shopping cart. Product must be on screen.', + // ... +}); + +// ❌ Bad - lacks context +useWebMCP({ + name: 'add_to_cart', + description: 'Add item to cart', // Which site? What item? + // ... +}); +``` + +### 3. Tools Appear and Disappear Dynamically + +Tool availability changes as users open and close tabs: + +```tsx +// This tool is available only while the product page tab is open +function ProductPage() { + useWebMCP({ + name: 'get_current_product', + description: 'Get details about the currently viewed product', + handler: async () => { + return await fetchProductDetails(productId); + } + }); + + return
Product Details
; +} + +// When user closes this tab, get_current_product disappears from the toolkit +``` + + +Agents must handle tools becoming unavailable mid-conversation. Always design tools to fail gracefully if the source tab is closed. + + +### 4. Cross-Tab Workflows Are Natural + +Agents can compose tools from different tabs into complex workflows: + +```tsx +// Tab 1: Calendar app (calendar.app) +useWebMCP({ + name: 'calendar_add_event', + description: 'Add event to your calendar', + inputSchema: { + title: z.string(), + date: z.string().datetime() + }, + handler: async ({ title, date }) => { + return await calendar.addEvent({ title, date }); + } +}); + +// Tab 2: Email app (mail.app) +useWebMCP({ + name: 'email_get_unread', + description: 'Get your unread emails', + handler: async () => { + return await email.getUnread(); + } +}); + +// Agent can naturally execute: +// "Get my unread emails and add any meeting invites to my calendar" +// It sees and can use tools from both tabs +``` + +## Managing Tool Overload + +When many tabs are open, agents may see dozens or hundreds of tools. Use these patterns to manage complexity: + +### Pattern 1: Conditional Registration + +Only register tools when they're relevant: + +```tsx +function CartPage() { + const { items } = useCart(); + + // Only show checkout tool when cart has items + useWebMCP({ + name: 'shop_checkout', + description: 'Complete the checkout process', + handler: async () => { + return await processCheckout(); + }, + enabled: items.length > 0 // Conditional registration + }); + + return
Cart ({items.length} items)
; +} +``` + +### Pattern 2: Context-Rich Descriptions + +Help agents understand when to use tools: + +```tsx +useWebMCP({ + name: 'shop_checkout', + description: 'Complete checkout on shop.example.com. Only use this after items have been added to cart and user has confirmed the order. Requires payment information to be on file.', + handler: async () => { + return await processCheckout(); + } +}); +``` + +### Pattern 3: Component Lifecycle Scoping + +Use React component lifecycle to scope tool availability: + +```tsx +function CheckoutFlow() { + const [step, setStep] = useState('cart'); + + // Cart step tools + useWebMCP({ + name: 'cart_update_quantity', + description: 'Update item quantity in cart', + enabled: step === 'cart', // Only available on cart step + // ... + }); + + // Shipping step tools + useWebMCP({ + name: 'shipping_select_address', + description: 'Select shipping address', + enabled: step === 'shipping', // Only available on shipping step + // ... + }); + + // Payment step tools + useWebMCP({ + name: 'payment_submit', + description: 'Submit payment and complete order', + enabled: step === 'payment', // Only available on payment step + // ... + }); + + return
Step: {step}
; +} +``` + +## Security Considerations + +Multi-tab tool collection creates unique security implications: + + +Tools from malicious websites can influence agent behavior, potentially causing the agent to abuse tools from legitimate websites. See [Agent Threat Model](/concepts/agent-threat-model) for detailed security considerations. + + +### Origin Isolation + +While tools are collected from all tabs, the **execution context remains origin-isolated**: + +- Each tool executes in its originating tab's context +- Tools inherit their tab's session, cookies, and authentication +- Same-origin policy prevents cross-tab data leakage +- Extension enforces origin validation on all tool calls + +### Trust Boundary + +```mermaid +graph TB + subgraph "Trusted Origins" + T1[yoursite.com Tools] + T2[github.com Tools] + end + + subgraph "Untrusted Origins" + M1[malicious.com Tools] + end + + A[AI Agent] -->|Sees all| T1 + A -->|Sees all| T2 + A -->|Sees all| M1 + + M1 -.->|May influence| A + A -.->|Could abuse| T1 + A -.->|Could abuse| T2 + + style M1 fill:#ff6b6b +``` + +**Defense**: Design tools to validate all inputs and never trust agent-provided data, even if it seems to come from the agent's current task context. + +## Implementation Patterns + + +For practical implementation examples of multi-tab patterns, see [Advanced Guide: Multi-Tab Tool Collection](/advanced#multi-tab-tool-collection) + + +## Next Steps + + + + Learn about cross-site tool composition patterns + + + + Understand WebMCP's overall architecture + + + + Security considerations for multi-agent environments + + + + Implementation examples and advanced techniques + + diff --git a/connecting-agents.mdx b/connecting-agents.mdx index 462c756..192d084 100644 --- a/connecting-agents.mdx +++ b/connecting-agents.mdx @@ -8,6 +8,10 @@ icon: 'link' This guide covers four primary connection methods, each suited to different use cases and architectures. Whether you're building a website that exposes tools to users' local AI clients, or an embedded application that agents control directly, you'll find the right approach here. We'll compare setup complexity, capabilities, and security considerations for each method. + +For architectural details on how WebMCP handles agent connections, see [Concepts: Architecture](/concepts/architecture) + + ## Connection Methods There are four primary ways to connect agents to WebMCP tools: diff --git a/docs.json b/docs.json index 347f75a..cc704fb 100644 --- a/docs.json +++ b/docs.json @@ -83,7 +83,6 @@ { "group": "Guides", "pages": [ - "why-webmcp", "connecting-agents", "best-practices", "development", @@ -122,7 +121,8 @@ "icon": "compass", "pages": [ "concepts/overview", - "concepts/architecture" + "concepts/architecture", + "concepts/alternatives" ] }, { @@ -134,11 +134,20 @@ "concepts/security" ] }, + { + "group": "Architecture & Patterns", + "icon": "diagram-project", + "pages": [ + "concepts/tool-routing", + "concepts/tool-composition", + "concepts/mcp-ui-integration", + "concepts/agent-threat-model" + ] + }, { "group": "Advanced Topics", "icon": "rocket", "pages": [ - "concepts/mcp-ui-integration", "concepts/extension", "concepts/schemas" ] diff --git a/introduction.mdx b/introduction.mdx index 3c90071..4ba498f 100644 --- a/introduction.mdx +++ b/introduction.mdx @@ -28,7 +28,7 @@ WebMCP is built on a **human-in-the-loop** philosophy: - **Collaborative workflows** - Humans and AI work together, not separately - **Context engineering** - Like good web design guides users, good WebMCP guides AI by exposing the right tools at the right time - + Understand why WebMCP is a better approach than browser automation, remote APIs, or computer use diff --git a/security.mdx b/security.mdx index 647749c..431aca1 100644 --- a/security.mdx +++ b/security.mdx @@ -53,6 +53,10 @@ A malicious tool from another website could manipulate the agent into: ## Agent-Specific Threats + +For a deep dive into the unique threat model of multi-agent environments, see [Concepts: Agent Threat Model](/concepts/agent-threat-model) + + ### Prompt Injection: The "Lethal Trifecta"