Drupal侦察MCP
用于本地Drupal开发的模型上下文协议服务器。将本地文件索引与drush驱动的数据库查询相结合，让AI助手了解您网站的结构、内容和drupal.org生态系统。
专为本地开发环境而设计 （DDEV、Lando、Docker等）
为什么要使用Drupal Scout？
- 来回减少AI：一个MCP调用，而不是多个drush+grep命令
- 绕过令牌限制：将数千个节点/用户/术语导出到CSV文件
- 组合多个数据源：文件分析+数据库查询+drupal.org API单个响应
- 安全决策：显示更改前的依赖关系和使用情况
它的作用：
- 局部索引：在代码库中搜索模块、服务、路由、钩子
- 数据库查询：运行drush php:eval以获取实体、字段、视图、分类法、日志
- 安全分析：基于模式的XSS扫描、SQL注入、访问控制问题
- CSV导出：将大型数据集（节点、用户、分类）直接写入文件
- Drupal.org搜索：查找模块、问题和兼容性信息
- 只读：只查询数据，从不修改您的网站
它没有做什么：
- 修改文件或数据库（AI执行drush/composer命令进行更改）
- 实时更新（安装/删除模块后调用reindex_modules）
特性
深度Drupal分析（Drush驱动）
Drush集成支持实时数据库查询，以进行准确、最新的分析：
- 实体和内容类型结构：从活动数据库中完成字段配置、显示和捆绑
- 查看发现：按实体类型筛选，请参阅实时配置中的显示/筛选/关系
- 现场使用分析：跨捆绑包跟踪字段，在活动配置中查找重复项
- 分类管理：术语层次结构、使用分析、安全删除警告和实际内容检查
- 错误和警告日志：获取最近的监视器日志以诊断问题并修复代码问题
- 挂钩实施查找器：通过静态分析找到所有带有行号的钩子实现
- 模块依赖：反向deps、循环检测、卸载安全检查
- 安装状态：检查哪些模块实际安装，哪些模块仅存在于代码库中
本地模块分析
静态文件分析，实现快速离线洞察：
- 索引并搜索您的Drupal安装
- 跨自定义和控制模块查找功能
- 检测未使用的模块（通过drush检查代码使用情况和安装状态）
- 分析服务依赖关系和路由
- 解析.info.yml、.services.yml、.routing.yml文件
Drupal.org集成
访问整个Drupal生态系统：
- 在drupal.org上搜索50000多个模块
- 获取包含兼容性数据的详细模块信息
- 在问题队列中搜索特定问题的解决方案
- 自动Drupal版本过滤相关结果
智能推荐
做出明智的决定：
- 并排比较模块
- 根据您的需求获取建议
- 从问题讨论中查看迁移模式
- 确定维护人员活动和社区健康
安装
PyPI安装（推荐）
pip install drupal-scout-mcp快速安装脚本
curl -sSL https://raw.githubusercontent.com/davo20019/drupal-scout-mcp/main/install.sh | bash手动安装
- 克隆存储库
git clone https://github.com/davo20019/drupal-scout-mcp.git
cd drupal-scout-mcp- 创建虚拟环境（推荐）
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate- 安装依赖项
pip3 install -r requirements.txt💡 更新依赖关系： 当发布带有新功能（如Excel导出）的新版本时，请更新您的安装： ``bash source venv/bin/activate # Activate your venv first pip3 install -r requirements.txt --upgrade ``- 配置Drupal路径
mkdir -p ~/.config/drupal-scout
cp config.example.json ~/.config/drupal-scout/config.json编辑 ~/.config/drupal-scout/config.json:
{
"drupal_root": "/path/to/your/drupal",
"modules_path": "modules"
}- 添加到MCP客户端
对于MCP客户端（例如。， ~/Library/Application Support/Claude/claude_desktop_config.json):
使用虚拟环境（建议用于依赖隔离）：
{
"mcpServers": {
"drupal-scout": {
"command": "/path/to/drupal-scout-mcp/venv/bin/python3",
"args": ["/path/to/drupal-scout-mcp/server.py"]
}
}
}使用Python系统：
{
"mcpServers": {
"drupal-scout": {
"command": "python3",
"args": ["/path/to/drupal-scout-mcp/server.py"]
}
}
}💡 提示： 使用虚拟环境的Python解释器可确保所有依赖项都可用，并与系统包隔离。
对于光标，使用相同的格式添加到MCP设置中。
- 重新启动MCP客户端
可用工具
本地模块工具
搜索功能 -跨模块搜索功能
Example: "Do we have email functionality?"list_modules -列出所有已安装的模块及其详细信息
Example: "List all contrib modules"describe_module -获取特定模块的详细信息
Example: "Describe the webform module"find_unused_trib -查找自定义代码未使用的contrib模块
Example: "Find unused contrib modules"
Enhanced: Now checks both code usage AND installation status via drush
Shows: Installed vs not installed, actionable uninstall commands
Helps: Safely identify modules that can be removed without breaking functionality检查冗余 -在构建之前检查功能是否存在
Example: "Should I build a PDF export feature?"reindex_modules -模块更改时强制重新索引
Example: "Reindex modules"分析模块依赖关系 -分析模块依赖关系
Example: "Can I safely uninstall the token module?"
Shows: Reverse dependencies, circular deps, uninstall safety
Unique: Unlike drush, shows what DEPENDS ON a module查找_查看_实现 -查找Drupal钩子的所有实现
Example: "Which modules implement hook_form_alter?"
Shows: All implementations with file locations and line numbers
Use case: Debugging hook execution order, finding conflicts
No drush needed: Pure file-based search using cached indexget_entity_structure -获取全面的实体类型信息
Example: "What fields does the node entity have?"
Shows: Bundles, fields, view displays, form displays
Combines: Config files + drush (if available)
Replaces: Multiple drush and grep commands in a single callget_views_summary -通过筛选获取视图配置摘要
Example: "What views exist in the site?"
Example: "Do we have any user views?" (filters by entity_type="users")
Example: "Are there views showing articles?" (filters by entity_type="node")
Shows: View names, display types (page/block/feed), paths, filters, fields, relationships
Combines: Database active config via drush + config file parsing
Replaces: drush views:list + multiple greps
Use case: Understanding existing data displays before creating duplicates
Supports filtering by entity type (node, users, taxonomy_term, media, etc.)get_field_info -通过使用分析获取全面的现场信息
Example: "What fields exist on the article content type?"
Example: "Where is field_image used?"
Example: "Do we have a field for storing phone numbers?"
Example: "Show me all email fields" (partial matching)
Shows: Field types, labels, cardinality, where used (bundles), settings, requirements
Combines: Field storage + field instance configs from database/files
Replaces: Multiple field:list + config:get commands
Use case: Understanding data structure before adding fields, avoiding duplicates
Supports: Partial field name matching, entity type filtering, bundle usage tracking获取轴突信息 -获取分类词汇表、术语和使用分析
Example: "What taxonomy vocabularies exist?"
Example: "Show me all terms in the categories vocabulary"
Example: "Where is the 'Drupal' term used?" → Automatically shows usage (single match)
Example: "Can I safely delete the 'Old News' term?" → Auto-analyzes safety
Example: "Search for terms named 'tech'" → Shows matches with term IDs
Shows: Vocabularies, term counts, hierarchies, usage in content/views/fields, safety analysis
Combines: Taxonomy configs + content queries + field references
Replaces: Multiple taxonomy commands + node queries + field reference checks
Use case: Before deleting/renaming terms, understanding taxonomy structure, finding orphans
Unique: Auto-detects single term match and shows full usage analysis in ONE call
Smart: Shows parent/child relationships, which content uses each term, safe-to-delete warningsget_all_taxonomy用法 -词汇表中所有术语的批量分析
Example: "Analyze all terms in the tags vocabulary for cleanup"
Example: "Show me usage statistics for all category terms"
Shows: Complete usage analysis for every term in a vocabulary (optimized single query)
Performance: 96% token savings vs calling get_taxonomy_info() per term
Default limit: 100 terms (configurable with limit parameter)
Smart truncation: Warns when vocabulary has more terms than returned
Modes: summary_only=True (fast, counts only) or False (detailed with samples)
Use case: Bulk cleanup planning, vocabulary auditing, finding unused terms
Replaces: Hundreds of individual term queries with one efficient batch operationexport_taxomy_usage_to_csv -将分类分析直接导出到CSV文件
Example: "Export all tags to CSV with full details"
Example: "Export categories vocabulary to CSV for cleanup planning"
Bypasses: MCP token limits entirely by writing directly to filesystem
Speed: Much faster than AI-formatted output for large vocabularies
Output: Saves to Drupal root directory as taxonomy_export_{vocab}_{timestamp}.csv
Modes:
- summary_only=True: tid, name, count, needs_check (4 columns, fast)
- summary_only=False: 12 columns including content samples, code refs, safety analysis
Handles: Unlimited terms (no 100-term limit like get_all_taxonomy_usage)
Use case: Exporting 500+ terms, spreadsheet analysis, team reporting
Perfect for: Large vocabularies where token limits prevent full displayexport_taxonomy使用_toexcel -将分类导出到Excel，合并单元格布局显示每个术语的所有页面
Example: "Export tags to Excel with all page information"
Example: "Export categories to Excel with node details"
Bypasses: MCP token limits by writing directly to filesystem
Perfect for: Detailed taxonomy analysis with complete node information for each term
Output: Saves to Drupal root directory as taxonomy_export_{vocab}_{timestamp}.xlsx
Layout:
| Term Name | Term Desc | Node ID | Title | Status | URL | ... |
|--------------|-----------|---------|------------|-----------|--------|-----|
| Technology | Tech info | 123 | AI Article | published | /ai | ... |
| ↓ | ↓ | 124 | Web Dev | published | /web | ... |
| ↓ | ↓ | 125 | Cloud | published | /cloud | ... |
| Business | Biz info | 201 | Marketing | published | /mkt | ... |
- Single sheet (no tabs) - handles thousands of pages easily
- Term name/description in merged cells spanning all page rows
- Each page gets its own row with complete details
- Easy visual grouping by term
Features:
- Two detail modes:
* Quick (default): 7 essential columns - Term ID, Term Name, Node ID, Title, Type, Status, URL Alias
* Full (full_details=True): 21 columns - adds Term Description, Canonical URL, Author, Dates,
Language, Taxonomy Terms, Entity Refs, Metatags, Revisions, Promote/Sticky
- Professional formatting: Bold term names, merged cells, auto-sized columns,
freeze panes, filters
- Terms without pages show "(No pages)" with gray background
Parameters:
- full_details: False (default) = quick mode, True = all node details
- include_formatting: Apply Excel styling (default: True)
- check_code: Scan custom code for term references (default: False)
- limit: Limit number of terms (default: 0 = all)
Use case:
- Detailed content audit: See exactly which pages use each term
- Migration planning: Export complete page metadata for each taxonomy term
- SEO analysis: Review URLs, paths, and metatags grouped by term
- Easy visual scanning: Merged cells show clear term groupings
Requires: openpyxl library (pip install openpyxl)
Performance: 100 terms/500 pages ~15s, 500 terms/2000 pages ~60s
Capacity: Can handle tens of thousands of rows (Excel limit: 1M+ rows)export_nodes_to_csv -将内容/节点直接导出到CSV进行审核和迁移
Example: "Export all articles to CSV with full details"
Example: "Export all content for migration planning"
Example: "Export blog posts with field data for migration"
Example: "Export articles including body text and custom fields"
Bypasses: MCP token limits by writing directly to filesystem
Perfect for: Content audits, SEO analysis, migration planning, bulk reviews
Output: Saves to Drupal root directory as nodes_export_{type}_{timestamp}.csv
Filters: content_type (article, page, etc.), include_unpublished, limit
Modes:
- summary_only=True: nid, title, type, status, created, author (7 columns, fast)
- summary_only=False: 21+ columns including:
* Basic: nid, uuid, title, type, status, langcode, timestamps, author
* URLs/SEO: url_alias, canonical_url, redirects, metatags (title/desc/keywords)
* Relationships: taxonomy_terms, entity_references (nodes/media/users)
* Publishing: promote, sticky, front_page flags
* Revisions: revision_count, latest_revision_log
- include_field_data=True: Adds actual field content (use with summary_only=False)
**WHY USE THIS:**
- Migration planning: Map old field values to new structure
- Content quality audit: Find empty fields, missing alt text
- Data cleanup: Identify fields that need updating
- SEO review: Check body text length, image descriptions
- Translation prep: Export content for translation services
**WHAT YOU GET:**
* body: First 500 characters of body text (HTML stripped)
* body_format: Text format (full_html, basic_html, etc.)
* Images: Alt text + image count (field_image: "Logo image | 3 images total")
* Text/Link fields: Full values (perfect for link audits)
* Custom fields: Auto-detected and included (field_subtitle, field_author_bio, etc.)
* Performance: Adds 30-50% to export time but essential for migrations
Performance: 100 nodes ~10s, 1000 nodes ~60s, 5000 nodes ~5min
Use case: Migration planning, SEO audits, content inventory, finding broken refs
Smart detection: Auto-detects redirect and metatag modules for enhanced data
AI knows: Automatically sets include_field_data=True when user asks for "body text", "field data", "complete export", or "migration data"export_users_to_csv -将用户帐户直接导出到CSV进行审核和迁移
export_media_to_csv -将媒体实体直接导出到CSV进行资产审计和迁移
Example: "Export all images to CSV"
Example: "Export all media with usage analysis"
Example: "Export videos including orphaned media"
Bypasses: MCP token limits by writing directly to filesystem
Perfect for: Media audits, file storage analysis, migration planning, accessibility audits
Output: Saves to Drupal root directory as media_export_{type}_{timestamp}.csv
Filters: media_type (image, video, document, audio), include_unused, limit
Modes:
- summary_only=True: mid, name, bundle, file_size_mb, created, author (7 columns, fast)
- summary_only=False: 22+ columns including:
* Basic: mid, uuid, name, bundle (media type), status, langcode, timestamps, author
* Files: file_uri, file_url, file_mime, file_size, file_size_mb, file_extension
* Metadata: alt_text (images), width, height, thumbnail_uri
* Usage: usage_count, usage_locations (nodes/paragraphs/blocks), orphaned flag
- include_field_data=True: Adds custom media fields (use with summary_only=False)
**WHY USE THIS:**
- Migration planning: Map custom media fields to new system
- Field audit: Find incomplete metadata, missing captions
- Custom field analysis: See what media data exists
**WHAT YOU GET:**
* All custom media fields auto-detected and included
* Captions, credits, copyright fields
* Custom metadata fields
* Performance: Adds 20-30% to export time
Performance: 100 items ~10s, 1000 items ~60s, 5000 items ~5min
Use case: Migration planning, accessibility audits, file cleanup, storage optimization
Smart detection: Automatically sets include_field_data=True when user asks for "field data", "custom fields", or "complete export"
Accessibility: Find images missing alt text, identify media needing descriptions
Storage: Analyze file sizes, find large files, optimize storage usageexport_users_to_csv -将用户帐户直接导出到CSV进行审核和迁移
Example: "Export all users to CSV"
Example: "Export users with full profile data for migration"
Example: "Export all users including blocked accounts"
Bypasses: MCP token limits by writing directly to filesystem
Perfect for: User audits, compliance reporting (GDPR), migration planning, inactive account cleanup
Output: Saves to Drupal root directory as users_export_{timestamp}.csv
Filters: include_blocked (default: False), limit
Modes:
- summary_only=True: uid, name, email, status, roles, created, access (7 columns, fast)
- summary_only=False: 15+ columns including:
* Basic: uid, uuid, name, email, status, langcode
* Activity: created, changed, access (last login), login (last access)
* Authorization: roles (pipe-separated list, e.g., "administrator | editor")
* Profile: timezone, preferred_langcode, init (original email), picture
- include_field_data=True: Adds custom user profile fields (use with summary_only=False)
**WHY USE THIS:**
- Migration planning: Map profile fields to new system
- User data export: GDPR compliance, data portability
- Profile analysis: Find incomplete profiles, missing fields
- Custom field audit: See what profile data exists
**WHAT YOU GET:**
* All custom user fields auto-detected and included
* Profile pictures/avatars (file paths)
* Text fields, links, entity references
* Boolean fields (YES/NO format)
* Performance: Adds 20-30% to export time
Performance: 100 users ~5s, 1000 users ~30s, 5000 users ~2min
Use case: User migration, GDPR exports, security audits, cleanup planning
Smart detection: Automatically sets include_field_data=True when user asks for "profile data", "user fields", or "complete export"
Activity tracking: Shows last login, last access, account age for inactive user identificationget_watchdog_log -获取最近的Drupal错误和警告日志以进行调试
Example: "Show me recent errors"
Example: "What warnings are in the logs?"
Example: "Are there any PHP errors?"
Example: "Show me database-related errors"
Shows: Error messages, warnings, timestamps, log types, severity levels
Filters: By severity (error, warning, notice, etc.) and type (php, cron, system, etc.)
Helps: Diagnose issues, fix code problems, understand system behavior
AI benefits: Can analyze errors and suggest fixes or next steps
Default: Shows last 50 error/warning entries
Use case: Debugging production issues, understanding why something broke主题分析工具
get_theme_regions -以简单文本列表的形式获取主题区域布局
Example: "What regions does olivero have?"
Example: "Show me regions for my_custom_theme"
Example: "List theme regions"
Perfect for: Quick region overview, AI context, understanding layout
Output: Simple text list grouped by position
Shows:
- Full-width regions (header, footer, navigation)
- Main content area with positioning (Left, Center, Right)
- Block counts per region
- Empty regions marked
Uses icons: ▓ (full-width), ◄ (left), ■ (center), ► (right)
Use case: Fast region check, planning block placement, AI needs context
Format: Clean list AI can easily parse and referencedescribe_theme -获取全面的主题信息和元数据
Example: "Describe the olivero theme"
Example: "Tell me about my_custom_theme"
Example: "What regions does the claro theme have?"
Shows: Complete theme metadata and structure
Information:
- Name, description, version, compatibility
- Base theme and inheritance chain (theme → base → base's base)
- All regions defined (8 regions: header, content, footer, etc.)
- Libraries defined (CSS/JS files and dependencies)
- Theme dependencies
- Breakpoints (responsive design breakpoints)
- Installation status (installed, default theme, admin theme)
- Theme path location
Perfect for: Theme development, understanding theme structure, checking compatibility
Use case: Before modifying theme, understanding available regions, library discoveryget_theme_blocks -分析每个主题的块放置和配置
Example: "Show me blocks in the olivero theme"
Example: "What blocks are in my_custom_theme?"
Example: "List block placement for claro"
Shows: Detailed block assignment and visibility
Information per region:
- All blocks with display order (weights)
- Block labels and IDs
- Block plugin types
- Visibility conditions with smart summaries:
* Page restrictions: "Only on: /admin/*" or "Hidden on: /user/*"
* Role restrictions: "Only for roles: administrator, editor"
* Content type restrictions: "Only on content types: article, page"
* Language restrictions: "Only for languages: en, es"
* Custom conditions
- Empty regions (no blocks assigned)
- Block type statistics
Perfect for: Block placement planning, debugging visibility issues, theme documentation
Use case: Understanding current layout, planning new blocks, finding unused regions
Helps: Identify where to place new blocks, why blocks aren't showingget_active_themes -获取所有已安装和可用主题的状态
Example: "Show me active themes"
Example: "What themes are installed?"
Example: "List all themes"
Shows: Theme status overview
Information:
- Default (frontend) theme with path
- Admin theme with path
- All installed themes with markers [DEFAULT] [ADMIN]
- Theme versions and compatibility
- Available but not installed themes
- Theme paths
Perfect for: Quick theme status check, finding which themes are active
Use case: Theme management, checking installations, compatibility verification模板发现工具
find_theme_templates -使用图案过滤查找Twig模板文件
Example: "Find node templates in olivero"
Example: "What view templates exist?"
Example: "Find all templates with 'block' in the name"
Perfect for: Template discovery, seeing what's overridden, finding template locations
Searches: All .html.twig files in theme
Filters: Optional pattern (e.g., "node--", "views", "block")
Shows:
- Template filenames grouped by directory
- What each template likely overrides (core/contrib detection)
- Full file paths
Output: Organized list by directory with override hints
Use case: "What templates are in my theme?", "Do I have a node--article template?"
Token efficient: Fast structured output AI can parseget_theme_template_overrides -显示哪些核心/控制模板被覆盖
Example: "What templates override core in my theme?"
Example: "Show me template overrides for olivero"
Example: "Which contrib templates are customized?"
Perfect for: Understanding customizations, theme audit, migration planning
Analyzes: All theme templates vs core/contrib sources
Groups by: Core overrides, Contrib overrides, Other
Shows:
- Template filename
- Location in theme
- Original source path (core/modules/views, core/themes/stable9, etc.)
Use case: Theme audit, understanding what's customized, planning upgrades
Helps: Identify which templates need attention during Drupal upgradesget_template_建议 -获取实体的模板命名层次结构
Example: "Template suggestions for article nodes"
Example: "How do I name a block template?"
Example: "Template suggestions for taxonomy term"
Perfect for: Learning template naming, understanding specificity, creating overrides
Covers: node, block, taxonomy_term, user, field, page, and generic entities
Shows: Template naming options from most to least specific
Output:
1. node--article--123.html.twig (specific node)
2. node--article--teaser.html.twig (bundle + view mode)
3. node--article.html.twig (all articles)
4. node--123.html.twig (specific node ID)
5. node.html.twig (all nodes - base)
Use case: "How do I override just article nodes?", "Template naming for blocks?"
Educational: Explains Drupal's template hierarchyget_view_template_info -获取替代视图的模板命名
Example: "How do I override the taxonomy_term view?"
Example: "Template for frontpage view"
Example: "View template suggestions for content view"
Perfect for: View theming, understanding view template hierarchy
Instant answers: No need to navigate to view UI or enable Twig debugging
Shows:
- Exact template name to use (views-view--taxonomy_term.html.twig)
- Where to place it (your_theme/templates/)
- Base template location to copy from
- Related templates (field, unformatted, table, grid, etc.)
- Clear cache instructions
Supports: View-specific and display-specific templates
Use case: "I want to theme the taxonomy_term view", "Override frontpage view display"
Saves time: No fumbling with URLs or Twig debugging - instant answer段落分析工具
list_paragraph_types -列出所有段落类型及其用法和模板状态
Example: "List all paragraph types"
Example: "Show me paragraph types"
Perfect for: Quick paragraph overview, identifying duplicates, cleanup planning
Shows:
- Paragraph type machine name and label
- Field count per type
- Usage count (how many paragraphs exist)
- Template status (customized or using default)
- Preprocess hook status
Output: Table format with type, fields, usage, customization status
Use case: "What paragraph types exist?", "Which paragraphs aren't used?", "Which have custom templates?"
Token efficient: One call shows everything about all paragraph types描述_段落类型 -获取特定段落类型的全面信息
Example: "Describe the hero_banner paragraph"
Example: "Show me fields for call_to_action paragraph"
Example: "What is the text_block paragraph?"
Perfect for: Understanding paragraph structure, planning edits, finding duplicates
Shows:
- All fields with types and requirements
- Usage count and where it's used
- Template files and locations
- Preprocess hooks
- Similar paragraph types (helps find duplicates)
Use case: Before editing paragraph, understanding what fields it has, finding similar types
Helps: Identify duplicate functionality, plan field changes safelyfind_paragraph_templates -查找段落模板文件并预处理挂钩
Example: "Find templates for hero_banner paragraph"
Example: "Show all paragraph templates"
Example: "What templates exist for paragraphs?"
Perfect for: Theme development, finding customizations
Searches: Active theme for paragraph--*.html.twig and .theme file for hooks
Shows:
- Template files with naming (paragraph--bundle.html.twig)
- Preprocess hooks (hook_preprocess_paragraph__bundle)
- Template naming examples if none found
Use case: "How is this paragraph themed?", "What paragraphs have custom templates?"get_paragraph_用法 -获取段落类型的使用统计信息
Example: "Show usage for hero_banner paragraph"
Example: "How many call_to_action paragraphs exist?"
Example: "Get usage stats for all paragraphs"
Perfect for: Usage analysis, cleanup planning
Shows: Count of paragraph entities per type
Fast: Direct entity query for quick counts
Use case: "Is this paragraph type being used?", "How many times is it used?"check_paragraph_存在 -检查给定类型的段落是否存在
Example: "Do we have any paragraphs from hero_banner and call_to_action?"
Example: "Check if text_block paragraphs exist"
Perfect for: Quick existence check, answering "do we have any?"
Shows:
- Types with content (with counts)
- Empty types (no paragraphs)
Groups: HAS CONTENT vs EMPTY sections
Use case: Fast check before deeper analysis, "are these paragraph types in use?"get_paragraph_references -显示段落的使用位置（父实体）
Example: "Where is hero_banner used?"
Example: "Show me what uses call_to_action paragraphs"
Example: "Which content types use these paragraphs?"
Perfect for: Understanding paragraph placement, impact analysis
Shows:
- Parent entity types and bundles (e.g., node.article)
- Field name that contains the paragraph
- Usage count per parent type
- Example content items (up to 5 with titles and IDs)
Use case: "Where are these paragraphs?", "What content will be affected if I change this?"
Follow-up friendly: Natural response to "check_paragraph_existence"find_duplicate_paragraphs -查找可能重复的段落类型
Example: "Find duplicate paragraph types"
Example: "Are there similar paragraph types?"
Perfect for: Cleanup planning, identifying redundancy
Analyzes: Field structures to find similar types
Use case: "Can I merge these paragraph types?", "Do we have duplicate functionality?"
Helps: Reduce complexity by consolidating similar paragraphsexport_paragraphs_to.csv -将段落类型导出到CSV进行审核
Example: "Export all paragraphs to CSV"
Example: "Export paragraph audit to spreadsheet"
Perfect for: Team review, documentation, planning
Output: CSV file with all paragraph metadata
Use case: Large-scale audit, stakeholder review, migration planning实体和内容参考工具
get_entity_structure -获取全面的实体类型信息
Example: "What fields does the node entity have?"
Shows: Bundles, fields, view displays, form displays
Combines: Config files + drush (if available)
Replaces: Multiple drush and grep commands in a single callget_entity_references -显示其他实体引用实体的位置
Example: "Where are tags used?"
Example: "What references articles?"
Example: "Which blog posts use this category?"
Example: "Show me what uses field_hero_image"
Perfect for: Understanding entity relationships, impact analysis
Finds: Which content types, nodes, or other entities reference specific bundles
Parameters:
- entity_type: Target type (node, taxonomy_term, media, etc.)
- bundle: Optional bundle filter (article, blog_post, tags)
- field_name: Optional field filter (field_category, field_tags)
- limit: Max references to show (default 50)
Shows:
- Referencing entity type and bundle
- Field name containing the reference
- Reference count
- Example items (up to 5 with "Parent Title (ID) → Referenced Label")
Use case: "Where is this taxonomy term used?", "What content links to these articles?"
Follow-up friendly: Natural after checking entity structure
Format: Grouped by target bundle, shows parent → child relationshipsget_entity_info -获取特定实体的详细信息
Example: "Give me info about node 56"
Example: "What is taxonomy term 12?"
Example: "Show me details for user 1"
Example: "Describe media 45"
Perfect for: Debugging, understanding content, quick entity lookup
Shows:
- Basic info: ID, UUID, type/bundle, language, status
- Metadata: Created/changed dates, author/owner, path/URL
- All field values with smart display:
* Simple fields (text, number)
* Entity references (shows "Label (ID)" of referenced entities)
* Files/links (shows URIs)
* Multi-value fields (lists all values, up to 10)
* Long text auto-truncated to 200 chars
Supports: Any entity type (node, user, taxonomy_term, media, paragraph, etc.)
Use case: "What's in this node?", "Show me this user's profile", "What fields does this have?"
Format: Clean sections for Basic Info and Fields, easy to read安全分析工具
安全审计 -多种模式的全面安全扫描
Example: "Run security audit on my_custom_module"
Example: "Security audit on webform module, show HIGH issues only"
Example: "Audit the commerce module in summary mode"
Scans for:
- XSS vulnerabilities (unescaped output, unsafe render arrays)
- SQL injection (db_query concatenation, unsafe queries)
- Access control issues (missing permission checks)
- CSRF protection (custom POST handlers, state-changing operations)
- Command injection (exec, shell_exec, system with variables)
- Path traversal (file operations with user input, ../ patterns)
- Hardcoded secrets (API keys, passwords, credentials)
- Deprecated/unsafe API usage (eval, extract, Drupal 7 functions)
Modes:
- summary (default): Fast overview with counts, perfect for large modules
- high_only: Shows only HIGH severity findings with details
- findings: Detailed report with code snippets (respects max_findings limit)
Parameters:
- mode: "summary", "high_only", or "findings" (default: "summary")
- severity_filter: Filter by "high", "medium", or "low"
- max_findings: Limit results (default: 50, prevents token overflow)
Smart token management: Automatically handles large modules without hitting limits
Pattern-based: All findings are concrete code patterns, no AI guessingscan_匿名_探索 - 🎯 关键：识别可远程利用的漏洞
Example: "Scan my_api_module for anonymous exploits"
Example: "Check chatbot for vulnerabilities accessible to anonymous users"
Example: "What vulnerabilities in custom_api can be exploited remotely?"
This is the HIGHEST PRIORITY security scan - identifies vulnerabilities that can
be exploited remotely without authentication.
How it works:
1. Runs security scans (XSS, SQL injection, command injection, path traversal)
2. Parses routing.yml files to identify anonymous-accessible routes
3. Maps HIGH severity vulnerabilities to routes
4. Reports ONLY vulnerabilities in anonymous routes
Reports:
- Routes accessible to anonymous users
- Vulnerabilities that can be exploited remotely
- Prioritized by exploitability (anonymous = critical)
Why this matters:
- Anonymous exploits = Remote exploitation without credentials
- Highest priority for security fixes
- Critical for public-facing modules (APIs, chatbots, forms)
Parameters: max_findings (default: 50)
Use cases:
- Pre-deployment security validation
- API security assessment
- Public module vulnerability analysis
- Penetration testing preparation
Combines: Pattern-based vulnerability detection + Routing access analysis
Output: Prioritized list of remotely exploitable security issuesscan_xss -检测跨站点脚本漏洞
Example: "Scan my_module for XSS issues"
Example: "Check custom_auth module for XSS, limit to 20 findings"
Detects:
- Unescaped print/echo statements
- Unsafe render arrays
- Direct superglobal output ($_GET, $_POST, etc.)
- JavaScript innerHTML usage
- drupal_set_message with variables
Parameters: max_findings (default: 50)scan_sql_injection -检测SQL注入漏洞
Example: "Scan my_module for SQL injection"
Detects:
- db_query with string concatenation
- SQL queries with concatenation
- mysqli/PDO without prepared statements
- EntityQuery with unsanitized user input
Parameters: max_findings (default: 50)扫描访问控制 -查找缺失的访问控制检查
Example: "Check my_module for access control issues"
Detects:
- Routes without _permission requirements
- Forms without access checks
- Entity modifications without access verification
- User data access without permission checks
Parameters: max_findings (default: 50)scan_depreced_api -识别不推荐使用或不安全的API
Example: "Scan my_module for deprecated APIs"
Detects:
- Drupal 7 functions in D8+ code (drupal_set_message, variable_get, etc.)
- eval() usage
- unserialize() with user input
- Deprecated PHP functions (create_function, extract, assert)
Parameters: max_findings (default: 50)
Use case: Preparing modules for Drupal upgrades, security hardeningscan_csrf -检查CSRF（跨站点请求伪造）保护
Example: "Check my_module for CSRF protection"
Example: "Scan custom_api module for CSRF issues"
Detects:
- Custom POST handlers outside Form API (may need CSRF token)
- State-changing operations (save/delete/update)
- Potential GET routes with state changes (CSRF risk)
How it works:
- Scans PHP code for custom request handling
- Guides AI to verify routing files (*.routing.yml)
- Checks for Form API usage (auto CSRF protection)
Note: Advisory scan - AI should investigate routing files to confirm CSRF handling
Drupal Form API provides automatic CSRF protection
Parameters: max_findings (default: 50)
Use case: Custom route handlers, REST APIs, AJAX endpointsscan_command_injection -检测命令注入漏洞
Example: "Scan my_module for command injection"
Example: "Check system_integration for shell command issues"
Detects:
- exec(), shell_exec(), system(), passthru() with variables
- Backtick shell execution operator with variables
- Drush shell commands with user input
- PHP mail() with user input (header injection)
Parameters: max_findings (default: 50)
Use case: Modules that execute shell commands, system integration modulesscan_path_traversal -检测路径遍历漏洞
Example: "Scan my_module for path traversal issues"
Example: "Check file_manager for path traversal vulnerabilities"
Detects:
- File includes with user input (include, require)
- File read operations with unsanitized input
- Directory traversal patterns (../ sequences)
- Drupal file operations without validation
- File deletion with user input
Understands Drupal stream wrappers (public://, private://)
Parameters: max_findings (default: 50)
Use case: File management modules, import/export functionalityscan_hardcoded_secrets -查找硬编码的凭据和机密
Example: "Scan my_module for hardcoded secrets"
Example: "Check api_integration for hardcoded API keys"
Detects:
- API keys hardcoded in code
- Passwords in variables
- Database credentials
- Private/secret keys
- OAuth tokens
- AWS credentials
Excludes: Test files, examples, placeholders, comments
Parameters: max_findings (default: 50)
Use case: Pre-deployment security checks, code review, API integrations
Best practices:
- Use Drupal Key module for secret management
- Store secrets in settings.php (excluded from version control)
- Use environment variables验证漏洞 - 🎓 解释如何手动验证安全漏洞
Example: "How do I verify the XSS vulnerability found in MyController.php?"
Example: "Show me how to test the SQL injection in my_custom_module"
Example: "Explain how to verify this command injection vulnerability"
INFORMATIONAL TOOL - Does NOT automatically execute exploits.
Provides detailed educational content on how vulnerabilities work and how
developers can manually test them on their OWN sites.
Provides:
- Code context showing the vulnerable line
- Explanation of why the code is vulnerable
- Attack flow diagrams
- Step-by-step manual testing instructions
- Expected results for vulnerable vs. fixed code
- Specific remediation guidance
- Before/after verification workflow
Input (from scan results):
- Module name, file path, line number
- Vulnerability type (xss, sql_injection, etc.)
- Optional route path
Output:
- Detailed explanation of the vulnerability
- Safe, manual testing commands (NOT executed automatically)
- Browser console testing steps
- DDEV/Lando curl examples
- Remediation code with examples
- Legal and ethical warnings
Use cases:
- Understand how a vulnerability works (educational)
- Manually verify scan findings before filing bugs
- Learn manual penetration testing techniques
- Verify patch effectiveness after remediation
- Security training for development teams
Example workflow:
1. scan_xss("my_module") → Finds XSS at MyController.php:45
2. verify_vulnerability("my_module", "xss", "MyController.php", 45, "/api/endpoint")
3. Read the detailed explanation and testing instructions
4. Manually run the commands in your local DDEV environment
5. Apply the recommended fix
6. Re-run the manual tests to confirm the fix works
7. Run scan_xss("my_module") again to verify
⚠️ For AUTHORIZED testing of YOUR OWN sites only
⚠️ Includes legal warnings about unauthorized testing
⚠️ Educational purpose - teaches secure coding practices安全扫描限制和最佳实践
Scout的基于模式的安全分析非常适合：
- ✅ 快速安全筛查和首次漏洞检测
- ✅ 发现明显的问题（直接回声/打印、SQL连接）
- ✅ 使用Drupal感知过滤消除误报
- ✅ 识别不推荐使用/不安全的API
基于模式的分析可能会遗漏：
- 多行代码模式和复杂的数据流
- 通过函数或间接调用传递的变量
- 跨越多个函数的条件逻辑
- 自定义安全包装
对于全面的安全审计：
- 使用Scout进行初步筛查（快速，发现明显问题）
- 通过手动代码检查审查所有严重性高的发现
- 使用其他静态分析工具：
- PHPTan（静态分析） - Psalm（类型检查和安全） - Semgrep（自定义安全规则）
- 运行时验证的手动渗透测试
- 生产/合规要求的专业安全审计
Scout不应该是以下行为的唯一工具：
- 生产安全认证
- 合规性审计（PCI-DSS、SOC 2、HIPAA）
- 完整的漏洞覆盖
所有发现包括：文件位置、行号、代码片段、严重级别（高/中/低）以及Drupal文档链接的具体补救建议。
AST分析提高了准确性
Scout使用tree sitter php进行基于AST的安全分析（自动安装 pip install drupal-scout-mcp):
- 通过理解PHP语法结构减少误报
- 捕获多行代码模式（例如，跨行的SQL连接）
- 提供Drupal感知验证（将EntityQuery与SQL查询区分开来）
- 验证实际代码结构与简单模式匹配
- 如果树保姆不可用，则可以很好地回退到基于模式的分析
Drupal.org工具
search_drupal_org -在drupal.org上搜索模块
Example: "Search drupal.org for SAML authentication"get_drupal_org_module_details -获取全面的模块信息
Example: "Get details about samlauth from drupal.org"
Options: include_issues=True for deeper analysisget_popular_drupal_modules -按类别获取最受欢迎的模块
Example: "Show popular commerce modules"get_module_recommendation -获取针对特定需求的建议
Example: "Recommend a module for user authentication with OAuth"search_module_issues -查找问题队列中特定问题的解决方案
Example: "Search samlauth issues for Azure AD authentication error"
Features: Automatic Drupal version filtering用法示例
查找现有功能
User: "Do we have HTML email functionality?"
Result: Shows symfony_mailer module with email templating features发现新模块
User: "Search drupal.org for SAML authentication"
Result: Lists samlauth, simplesamlphp_auth, and other options with stats故障排除问题
User: "I'm getting an AttributeConsumingService error with samlauth"
Result: Finds matching issues with solutions and patches做出决定
User: "Should I use samlauth or simplesamlphp_auth for Drupal 11?"
Result: Compares modules, shows migration patterns, provides recommendation完整的工作流程：从发现到安装
User: "I need SAML authentication for Azure AD"
MCP: search_drupal_org("SAML authentication")
MCP: get_drupal_org_module_details("samlauth", include_issues=True)
MCP: search_module_issues("samlauth", "Azure AD")
Result: MCP provides comprehensive module data, issues, and recommendations
User: "Install samlauth"
AI: Uses Bash to run: ddev composer require drupal/samlauth && ddev drush en samlauth
AI: Calls reindex_modules() to update MCP's index
Result: Module installed with AI executing commands based on your environment清理工作流程（用Drush增强）
User: "Clean up unused modules"
MCP: find_unused_contrib()
Result: "UNUSED CONTRIB MODULES:
Found 5 modules not referenced by custom code
3 INSTALLED but unused (can be uninstalled):
- Devel (devel)
Development tools
Package: Development
- Kint (kint)
Debugging tool
Package: Development
- Admin Toolbar Tools (admin_toolbar_tools)
Extra admin toolbar features
Package: Administration
2 NOT INSTALLED (can be removed from codebase):
- Examples (examples)
Code examples
Package: Development
- Devel Generate (devel_generate)
Generate test content
Package: Development
RECOMMENDATIONS:
- Uninstall 3 unused modules: drush pmu devel kint admin_toolbar_tools
- Then remove from composer: composer remove drupal/MODULE_NAME
- Remove 2 uninstalled modules from composer
- This will reduce site complexity and improve performance"
User: "Uninstall the installed ones"
AI: Uses Bash to run: ddev drush pmu devel kint admin_toolbar_tools
AI: Then removes from composer: ddev composer remove drupal/devel drupal/kint drupal/admin_toolbar_tools
AI: Calls reindex_modules() to update MCP's index
Result: Safely removed 3 installed modules, avoiding any that are actually in use
MCP's drush check prevented breaking the site故障排除工作流
User: "Getting errors with webform"
MCP: search_module_issues("webform", "error description")
Result: MCP finds relevant issues from drupal.org with solutions
AI: Uses Bash to check logs, run updates, clear caches as needed
Result: AI executes fixes based on MCP's data依赖性分析工作流
User: "Can I safely uninstall the token module?"
MCP: analyze_module_dependencies("token")
Result: "CANNOT SAFELY UNINSTALL
- 27 modules depend on token
- Including: pathauto, metatag, my_custom_module
- Must remove dependents first"
User: "What are my most critical modules?"
MCP: analyze_module_dependencies() # System-wide analysis
Result: Shows modules with most dependents, circular dependencies,
custom module coupling, and safe-to-remove candidates分类管理工作流程
User: "I want to clean up old taxonomy terms"
MCP: get_taxonomy_info()
Result: "Taxonomy Vocabularies (4 found)
- Categories (categories)
Description: Content categories
Terms: 28
Used by fields: field_category, field_article_category
- Tags (tags)
Terms: 156
Used by fields: field_tags
- Departments (departments)
Terms: 12
Used by fields: field_department"
User: "Show me all terms in the tags vocabulary"
MCP: get_taxonomy_info(vocabulary="tags")
Result: "Vocabulary: Tags (tags)
Total terms: 156
Terms:
- Technology (tid: 42) (87 uses)
- AI/ML (tid: 43) (12 uses)
- Web Development (tid: 44) (23 uses)
- Business (tid: 50) (45 uses)
- Sports (tid: 60) (0 uses)
- Old Category (tid: 75) (0 uses)"
User: "Can I safely delete 'Old Category'?"
MCP: get_taxonomy_info(term_id=75)
Result: "Term: Old Category (tid: 75)
Vocabulary: Tags (tags)
Description: Deprecated - do not use
SAFE TO DELETE
This term is not used in content, views, or as a parent term."
User: "What about the 'Technology' term?"
MCP: get_taxonomy_info(term_id=42)
Result: "Term: Technology (tid: 42)
Vocabulary: Tags (tags)
Children: AI/ML, Web Development
Used in 87 content item(s):
- How AI is Changing Development (article) - nid: 123
- Tech Trends 2024 (blog) - nid: 156
- Future of Web (article) - nid: 189
... and 84 more
Vocabulary referenced by 2 field(s):
- Tags (field_tags) on article, blog
- Category (field_category) on article
WARNING: Has child terms
2 child term(s) will become orphaned if deleted.
Consider reassigning children or deleting them first.
CAUTION: Term is in use
Used in 87 content item(s) and 0 view(s).
Deleting will remove term references from content.
Consider merging with another term instead."
User: "I'll keep Technology and just delete 'Old Category'"
AI: Uses Bash to run: ddev drush taxonomy:term:delete 75
Result: Term safely deleted with MCP's confirmation it was unused
Avoided accidentally breaking 87 articles by checking first内容审核和SEO分析工作流（节点CSV导出）
User: "I need to do a content audit for our migration to the new site"
AI: "I'll export all your content to CSV with full details for analysis."
MCP: export_nodes_to_csv(summary_only=False, include_unpublished=True)
Result: "✅ Successfully exported 3,247 nodes to /path/to/drupal/nodes_export_all_20251025_153000.csv (2.1 MB)
Content types found: article (1,523), page (892), blog (654), event (178)
Columns included (21 total):
- Basic: nid, uuid, title, type, status, langcode, created, changed, author
- URLs/SEO: url_alias, canonical_url, redirects, metatag_title, metatag_description
- Relationships: taxonomy_terms, entity_references
- Publishing: promote, sticky, front_page
- Revisions: revision_count, latest_revision_log
Preview:
nid,uuid,title,type,status,langcode,created,changed,author,url_alias,canonical_url,redirects,taxonomy_terms,metatag_title...
1,abc-123,Home,page,published,en,2023-01-15 10:30:00,2024-10-20 14:22:00,admin,/home,https://example.com/home,,Category: News | Tags: Drupal,Welcome to Our Site...
2,def-456,About Us,page,published,en,2023-01-16 09:15:00,2024-09-12 11:05:00,editor,/about,https://example.com/about,/about-us | /company,,About Our Company..."
AI: "Perfect! I've exported all 3,247 nodes. The CSV includes:
- SEO data: All URL aliases, redirects, and metatags
- Taxonomy relationships for each node
- Entity references (media, related content)
- Revision history
- Publishing status and flags
You can now open this in Excel/Google Sheets to:
- Audit SEO metatags (sort by empty metatag_title)
- Find broken redirects
- Map content for migration
- Identify content without taxonomy terms
- Review publishing workflow
Would you like me to analyze specific patterns?"
User: "Show me articles without metatag descriptions"
AI: [Reads CSV file and filters]
"Found 234 articles missing metatag descriptions:
- Article nid:45 'How to Use Drupal' (published 2023-03-12)
- Article nid:67 'PHP Best Practices' (published 2023-04-08)
... [continues listing]
These should be updated before migration for better SEO."
User: "What about redirect analysis?"
AI: [Analyzes redirects column]
"Redirect analysis from CSV:
- 456 nodes have redirects (good for SEO continuity)
- 128 nodes have multiple redirects (shows URL history)
- Top 10 nodes by redirect count:
* nid:123 'Company History' - 8 redirects
* nid:456 'Product Launch' - 6 redirects
All redirect data is preserved in the CSV for migration planning."使用现场数据导出进行迁移规划
User: "I need to export all blog posts with their field content for our migration to the new CMS"
AI: "I'll export all blog posts including field data (body text, images, custom fields)."
MCP: export_nodes_to_csv(content_type="blog", summary_only=False, include_field_data=True, include_unpublished=True)
Result: "✅ Successfully exported 654 blog nodes to /path/to/drupal/nodes_export_blog_20251025_160000.csv (892 KB)
Columns included (32 total):
- Basic: nid, uuid, title, type, status, author...
- URLs/SEO: url_alias, canonical_url, metatags...
- Field Data:
* body (first 500 chars)
* body_format
* field_featured_image (alt text + count)
* field_author_bio
* field_publish_date
* field_related_links
* field_tags (auto-detected custom field)
* field_subtitle (auto-detected)
Preview:
nid,title,body,body_format,field_featured_image,field_author_bio,field_subtitle...
123,How to Migrate,"This comprehensive guide covers...(500 chars),full_html,"Migration guide banner | 3 images",John Doe is a...,The Ultimate Guide..."
AI: "Perfect! I've exported all 654 blog posts with complete field data. The CSV includes:
**Content Data:**
- Body text (first 500 chars) - ready for content analysis
- Body format - shows which posts use full_html vs basic_html
- Image alt text - identify missing accessibility data
- Custom fields - all detected and exported
**What you can do now:**
1. Content Quality Audit:
- Sort by empty 'body' to find placeholder content
- Find posts missing field_featured_image
- Check for missing alt text descriptions
2. Migration Mapping:
- Map field_subtitle → new_cms_field_intro
- Map field_author_bio → author.biography
- Identify which body_format to convert
3. Translation Preparation:
- Export body text for translation services
- See which fields need localization
4. SEO/Content Review:
- Check body text length (too short?)
- Find posts without field_subtitle
- Identify missing metadata"
User: "Show me posts with short body text that need more content"
AI: [Analyzes CSV body column]
"Found 47 blog posts with body text under 100 characters:
- nid:234 'Quick Update' - 45 chars ('Just a quick note about...')
- nid:567 'Announcement' - 78 chars ('We're excited to share that...')
These posts might be placeholders or need expansion before migration."
User: "What about missing image alt text?"
AI: [Checks field_featured_image column]
"Image analysis:
- 589 posts have featured images
- 123 posts missing alt text (empty field_featured_image)
- Posts to fix:
* nid:89 'Product Launch' - 2 images, no alt text
* nid:145 'Case Study' - 1 image, no alt text
You should add alt text to these before migration for accessibility."大词汇清理工作流程（CSV导出）
User: "I need to clean up our tags vocabulary - we have hundreds of old terms"
MCP: get_all_taxonomy_usage(vocabulary="tags", summary_only=True)
Result: "⚠️ TRUNCATED RESULTS: Showing 100 of 751 terms.
Options: (1) Increase limit, (2) Use CSV export, (3) Continue with 100"
User: "Export all 751 terms to CSV with full details"
MCP: export_taxonomy_usage_to_csv(vocabulary="tags", summary_only=False)
Result: "✅ Successfully exported 751 terms to /path/to/drupal/taxonomy_export_tags_20251025_143500.csv (125 KB)
Columns included:
- tid, name, description, parent, children
- content_count, content_usage_sample (first 5 nodes)
- fields_with_usage, code_usage, config_usage
- safe_to_delete, warnings
Preview:
tid,name,description,parent,children,content_count,content_usage_sample,...
1,Technology,,,,87,nid:123 (AI Article) | nid:156 (Tech Blog)...
2,Old News,Deprecated,,,0,,...,YES,
3,Music,,,,23,nid:45 (Concert Review) | nid:67 (Album Review)...
..."
AI: "I've exported all 751 terms to a CSV file in your Drupal root. The file includes:
- Full usage analysis for every term
- Sample content using each term
- Safety recommendations
- 234 terms marked as safe to delete (0 content usage)
You can open it in Excel/Google Sheets to filter and plan your cleanup."
User: "Great! Show me just the safe-to-delete terms"
AI: "Based on the CSV, here are the 234 terms safe to delete (0 content usage):
- Old News (tid: 2)
- Deprecated Category (tid: 15)
- Test Tag (tid: 47)
... [reads from CSV file]
Would you like me to generate a drush command to delete all of them?"
User: "Yes, delete all unused terms"
AI: Uses Bash to run: ddev drush taxonomy:term:delete 2,15,47,... [all safe term IDs]
Result: Cleaned up 234 unused terms in one operation
CSV export enabled analysis of 751 terms without hitting token limits
Much faster than AI formatting - took 30 seconds vs several minutes现场分析工作流程
User: "I need to add a phone number field to the staff content type"
MCP: get_field_info(field_name="phone")
Result: "Fields Summary (2 fields found) - Matching: phone
NODE:
- Phone Number (field_phone_number)
Type: telephone | Bundles: contact, vendor
- Mobile Phone (field_mobile_phone)
Type: telephone | Bundles: employee"
User: "Show me details about field_phone_number"
MCP: get_field_info(field_name="field_phone_number")
Result: "Field: Phone Number (field_phone_number)
Type: telephone
Entity Type: node
Storage: Single value
Settings: Max length: 255
Used in 2 bundle(s):
- Contact (required)
- Vendor"
User: "What fields does the article content type have?"
MCP: get_field_info(entity_type="node")
Result: "Fields Summary (15 fields found) - Entity type: node
NODE:
- Title (title)
Type: string | Bundles: article, page, blog
- Body (body)
Type: text_with_summary | Bundles: article, blog
- Image (field_image)
Type: image | Bundles: article, blog, school
- Category (field_category)
Type: entity_reference | Bundles: article, blog
..."
User: "Perfect! I can reuse field_phone_number on the staff content type"
Result: Discovered existing field with same purpose in a single query
Avoided creating duplicate field with different name
Showed exactly where fields are used for informed decisions调试工作流（带监视日志）
User: "The site is showing errors, can you check what's wrong?"
MCP: get_watchdog_logs()
Result: "DRUPAL WATCHDOG LOGS (most recent 15 entries)
ERROR (12 entries)
================================================================================
[2024-01-15 14:32:21] php
Message: Undefined array key 'field_category' in custom_module_preprocess_node()
Location: /modules/custom/custom_module/custom_module.module:line 45
--------------------------------------------------------------------------------
[2024-01-15 14:30:15] php
Message: Call to undefined method Drupal\node\Entity\Node::getCategory()
Location: /modules/custom/custom_module/src/Service/CategoryService.php:line 78
--------------------------------------------------------------------------------
WARNING (3 entries)
================================================================================
[2024-01-15 14:25:10] cron
Message: Cron run exceeded the time limit and was aborted
--------------------------------------------------------------------------------
NEXT STEPS:
1. Review the error messages above to identify issues
2. For PHP errors: Check the file and line number mentioned
3. For missing modules/dependencies: Use drush pm:list to verify
4. For database errors: Check database connectivity and permissions
5. Use get_watchdog_logs(type='php') to focus on PHP errors"
AI: "I can see two related PHP errors in your custom_module. The issue is:
1. Line 45 in custom_module.module is trying to access 'field_category' which doesn't exist
2. Line 78 in CategoryService.php is calling a method that doesn't exist on Node entities
Let me check the module code to fix these issues."
AI: Uses Read tool to examine /modules/custom/custom_module/custom_module.module
AI: Uses Read tool to examine /modules/custom/custom_module/src/Service/CategoryService.php
AI: Identifies the bugs and proposes fixes
AI: Uses Edit tool to fix both issues
AI: "I've fixed both errors. The problems were:
1. Missing field existence check before accessing field_category
2. Using non-existent getCategory() instead of get('field_category')
Run 'drush cache:rebuild' to clear the cache and test."
User: "Thanks! Any other issues I should know about?"
MCP: get_watchdog_logs(severity="warning")
Result: Shows the cron timeout warning
AI: "There's also a cron timeout issue. This usually means a cron task is taking too long.
You might want to review your cron hooks or increase the time limit."视图发现工作流
User: "Do we have any views that display user data?"
MCP: get_views_summary(entity_type="users")
Result: "Views Summary (2 views found) - Showing 'users' views only
User List (user_list)
Displays: master, page_1
Base: users_field_data
Staff Directory (staff_directory)
Displays: master, page_1, block_1
Base: users_field_data"
User: "What about school content?"
MCP: get_views_summary(entity_type="node") # Schools are a content type
Result: "Views Summary (5 views found) - Showing 'node' views only
Content (content)
Displays: master, page_1, block_1
Base: node
Schools Directory (schools_directory)
Displays: master, page_1
Base: node_field_data
Blog Posts (blog)
Displays: master, page_1
Base: node_field_data"
User: "Show me details about the schools_directory view"
MCP: get_views_summary("schools_directory")
Result: "View: Schools Directory (schools_directory)
Status: Enabled
Base Table: node_field_data
Displays (2):
- Master [master]
Filters: status, type
Fields: title, field_address, field_principal...
- Page [page]
Path: /schools
Filters: status, type, field_district"
User: "Perfect! The schools view already exists with the filters I need"
Result: Found existing view with needed filters in a single query
Entity type filtering prevented showing irrelevant views
Helped avoid creating duplicate functionality用户审核和迁移工作流（用户CSV导出）
User: "I need to audit our user accounts and prepare for migration to the new authentication system"
AI: "I'll export all your user accounts with full details for analysis."
MCP: export_users_to_csv(summary_only=False, include_blocked=True)
Result: "✅ Successfully exported 523 users to /path/to/drupal/users_export_20251025_143000.csv (85 KB)
Roles found: administrator (3), editor (12), content_creator (45), authenticated (463)
Columns included (15 total):
- Basic: uid, uuid, name, email, status, langcode
- Activity: created, changed, access (last login), login (last access)
- Authorization: roles
- Profile: timezone, preferred_langcode, init, picture
Preview:
uid,uuid,name,email,status,langcode,created,changed,access,login,roles,timezone,preferred_langcode,init,picture
1,abc-123,admin,admin@example.com,active,en,2020-01-15 10:30:00,2024-10-25 09:15:00,2024-10-25 14:30:00,2024-10-25 09:15:00,administrator,America/New_York,en,admin@example.com,public://pictures/picture-1.jpg
2,def-456,editor1,editor@example.com,active,en,2021-03-20 14:22:00,2024-10-20 11:05:00,2024-10-24 16:45:00,2024-10-20 11:05:00,editor,America/Los_Angeles,en,editor@example.com,"
AI: "Perfect! I've exported all 523 user accounts including blocked users. The CSV includes:
- User activity data: Last login, last access times
- Authorization: All role assignments
- Account status: Active vs blocked
- Original registration info: Creation date, initial email
- Profile settings: Timezone, language preferences
You can now open this in Excel/Google Sheets to:
- Identify inactive users (sort by 'access' column)
- Audit role assignments (filter by 'roles' column)
- Find accounts to cleanup (blocked status, never logged in)
- Plan migration mapping (email → new auth system)
- GDPR compliance (export user data on request)
Would you like me to analyze specific patterns?"
User: "Show me users who haven't logged in for over a year"
AI: [Reads CSV file and filters by access date]
"Found 87 users who haven't logged in since October 2023:
INACTIVE ADMINISTRATORS (2):
- uid:45 'old_admin' - Last login: 2022-08-15 (2+ years ago)
- uid:67 'backup_admin' - Last login: 2023-03-20 (1.5 years ago)
INACTIVE EDITORS (12):
- uid:89 'john.smith' - Last login: 2023-05-10
- uid:134 'jane.doe' - Last login: 2023-02-28
... [continues listing]
INACTIVE REGULAR USERS (73):
- Many accounts created but never logged in (access: Never)
RECOMMENDATIONS:
- Review administrator accounts - should backup_admin still have admin rights?
- Consider blocking or deleting accounts with 'Never' login status
- Send re-activation emails to editors before blocking"
User: "What about blocked accounts?"
AI: [Filters CSV by status column]
"Blocked accounts analysis:
- 23 blocked user accounts total
- 15 were spam accounts (registered but never verified)
- 5 were former employees (blocked after leaving)
- 3 were security-related blocks
Safe to delete: The 15 spam accounts (uids: 234, 267, 289...)"
User: "Export users with their profile fields for the migration"
AI: "I'll export with full profile data for migration planning."
MCP: export_users_to_csv(summary_only=False, include_field_data=True, include_blocked=True)
Result: "✅ Successfully exported 523 users with profile fields (142 KB)
Additional custom fields detected and included:
- field_department (entity reference to taxonomy)
- field_bio (text field)
- field_phone_number (telephone)
- field_office_location (text)
You can now map these fields to your new authentication system."
AI: "Perfect! The export now includes all custom profile fields. You can use this to:
1. Map field_department → new_system.department
2. Map field_bio → new_system.profile.about_me
3. Map field_phone_number → new_system.contact.phone
4. Identify which users have incomplete profiles (empty fields)"媒体审计和资产管理工作流程（媒体CSV导出）
User: "I need to audit our media library and find images missing alt text for accessibility compliance"
AI: "I'll export all your media with full details for analysis."
MCP: export_media_to_csv(summary_only=False)
Result: "✅ Successfully exported 1,523 media items to /path/to/drupal/media_export_all_20251026.csv (385 KB)
Media types found: image (1,200), video (200), document (123)
Total file size: 2,847.5 MB
Columns included (22 total):
- Basic: mid, uuid, name, bundle, status, langcode, created, changed, author
- Files: file_uri, file_url, file_mime, file_size, file_size_mb, file_extension
- Metadata: alt_text, width, height, thumbnail_uri
- Usage: usage_count, usage_locations, orphaned
Preview:
mid,uuid,name,bundle,status,file_url,file_size_mb,alt_text,usage_count,usage_locations,orphaned
1,abc-123,Hero Banner,image,published,https://example.com/.../hero.jpg,2.3,Homepage hero image,5,node:123 | node:456,NO
2,def-456,Product Photo,image,published,https://example.com/.../product.jpg,1.8,,3,node:789 | paragraph:12,NO
3,ghi-789,Old Video,video,published,https://example.com/.../video.mp4,45.2,,0,,YES"
AI: "Perfect! I've exported all 1,523 media items. The CSV includes:
- File information: Size, type, URL for each asset
- Accessibility data: Alt text for images
- Usage tracking: Where each media item is referenced
- Orphaned flag: Media not used anywhere
You can now open this in Excel/Google Sheets to:
- Audit accessibility (find missing alt text)
- Identify orphaned media (not referenced anywhere)
- Analyze storage usage (sort by file_size_mb)
- Plan migration (map file types to new system)
Would you like me to analyze specific patterns?"
User: "Show me all images missing alt text"
AI: [Reads CSV file and filters by empty alt_text]
"Found 234 images missing alt text:
HIGH PRIORITY (used in multiple places):
- mid:2 'Product Photo' - Used in 3 locations (node:789, paragraph:12, block:5)
- mid:45 'Team Photo' - Used in 2 locations (node:234, node:567)
- mid:89 'Logo Variant' - Used in 5 locations
MEDIUM PRIORITY (used once):
- mid:123 'Blog Image' - Used in 1 location (node:890)
... [continues listing]
RECOMMENDATIONS:
- Prioritize adding alt text to high-usage images first
- These images appear on multiple pages/content items
- Required for WCAG 2.1 AA compliance"
User: "What about orphaned media?"
AI: [Filters CSV by orphaned=YES]
"Storage cleanup analysis:
- 45 orphaned media items found (not referenced anywhere)
- Total wasted storage: 127.3 MB
SAFE TO DELETE:
Videos (3 items, 89.5 MB):
- mid:3 'Old Video' - 45.2 MB, uploaded 2 years ago
- mid:67 'Unused Demo' - 32.1 MB, uploaded 3 years ago
- mid:145 'Test Video' - 12.2 MB, uploaded 1 year ago
Images (38 items, 34.8 MB):
- Multiple old thumbnails and test images
- Duplicates from migration
Documents (4 items, 3.0 MB):
- Old PDFs no longer in use
You can safely delete these to free up 127.3 MB of storage."
User: "Export just the images so I can focus on accessibility fixes"
AI: "I'll export only images with detailed information."
MCP: export_media_to_csv(media_type="image", summary_only=False)
Result: "✅ Successfully exported 1,200 images to /path/to/drupal/media_export_image_20251026.csv (312 KB)
This filtered export makes it easier to:
- Focus on image accessibility (alt text audit)
- Review image dimensions (width/height)
- Identify large images needing optimization
- Plan image field migration"
AI: "Perfect! Now you have a focused CSV with only images. You can:
1. Sort by empty alt_text to prioritize fixes
2. Sort by file_size_mb to find images needing optimization
3. Filter by usage_count=0 to find unused images
4. Use the mid column to quickly update media via drush"运作原理
分工
MCP服务器（数据提供者）-Drupal Scout的功能：
- 为本地Drupal代码库建立索引
- 执行Drush命令以查询实时数据库配置
- 提供跨模块的快速搜索
- 从drupal.org获取数据（模块、问题、统计数据）
- 缓存drupal.org响应（1小时TTL）
- 分析依赖关系和冗余
- 根据您的需求推荐模块
AI助手（动作执行器）-你的AI做什么：
- 执行drush/composer/git命令进行修改
- 检测您的环境（DDEV、Lando、Docker等）
- 运行适合您的设置的命令
- 高效连锁经营
- 处理错误和边缘情况
- 更改后调用reindex_modules（）
技术细节
德鲁什融合
- 自动检测drush命令（DDEV、Lando、Docksal、全局等）
- 对实时数据执行只读drush命令
- 从数据库查询活动配置
- 检查模块安装状态
- 检索实体结构、视图、字段和分类数据
- 将静态文件分析与运行时数据相结合，以获得完整的图像
局部索引
- 解析.info.yml、.services.yml、.routing.yml和PHP文件
- 索引服务、路由、依赖关系和关键字
- 构建可搜索的功能数据库
- 安装/删除模块后调用reindex_modules（）
Drupal.org集成
- 使用drupal.org REST API获取模块数据
- 删除项目页面以实现准确的兼容性
- 获取问题队列以进行故障排除
- 自动Drupal版本过滤
为什么是这种架构？
- MCP专注于Drupal领域知识和只读分析
- MCP在内部执行drush查询以提高效率
- AI处理特定于环境的修改执行
- 更简单、更易于维护的代码
- 适用于任何开发环境（DDEV、Lando等）
- AI可以比硬编码命令更好地适应错误
安全考虑
Drupal Scout被设计为 用于可信本地环境的开发工具。请查看这些安全注意事项：
仅限受信任的Drupal安装
Drush PHP执行：
- Drupal Scout通过以下方式执行PHP代码
drush eval查询数据库 - 这与您的Drupal数据库用户具有相同的权限
- 可以读取Drupal安装可访问的任何数据
建议：
- ✅ 与您控制和信任的Drupal网站一起使用
- ✅ 非常适合本地开发环境（DDEV、Lando、Docker）
- ❌ 不适用于不受信任或受威胁的Drupal安装
配置安全
配置文件位置：
- 配置存储在
~/.config/drupal-scout/config.json - 可能包含敏感路径和设置
- 文件权限应仅限于您的用户帐户
建议：
- ✅ 将config.json保存在主目录中（默认位置）
- ❌ 不要将config.json提交到版本控制
- ✅ 添加
config.json到.gitignore如果创建特定于项目的配置 - ✅ 使用特定于环境的路径（不要在开发人员之间共享配置）
导出文件安全
CSV导出路径：
- 导出工具将CSV文件写入文件系统
- 验证路径以防止写入系统目录
- 允许的位置：
- Drupal根目录和子目录 - /tmp 和 /var/tmp - 用户的主目录
这防止了什么：
- ❌ 写信给
/etc/或其他系统目录 - ❌ 路径遍历攻击(
../../../etc/passwd) - ❌ 意外覆盖关键系统文件
建议：
- ✅ 使用默认路径（Drupal根目录）以便在IDE中轻松访问
- ✅ 使用
/tmp临时出口 - ⚠️ 注意导出的数据（可能包含用户电子邮件、内容）
开发工具上下文
重要提示：
- Drupal Scout是一个 开发工具，不是生产服务
- 假设本地环境可信
- 无身份验证/授权层（按设计）
- 不应暴露在不受信任的网络中
- 使用MCP协议（STDIO）-通常仅限本地使用
建议：
- ✅ 用于本地开发和暂存环境
- ✅ 与您自己的Drupal安装一起使用
- ❌ 不要暴露在公共网络中
- ❌ 不要与不受信任的Drupal安装一起使用
Drupal Scout不做什么
只读设计：
- 不修改数据库内容
- 不会更改代码库中的文件
- 不直接执行用户提供的PHP/SQL
- 不安装/卸载模块（AI通过单独的命令执行此操作）
安全子进程使用：
- 所有drush命令都使用safe-subprocess.run（）（无shell=True）
- 命令以列表而非字符串的形式传递
- 所有子流程调用超时
- 没有用户输入直接传递到shell
需求
- Python 3.10或更高版本
- Drupal 9、10或11安装
- MCP兼容客户端（克劳德桌面、光标等）
- 互联网连接（用于drupal.org功能）
配置
快速入门（建议用于MCP）
对于DDEV用户：
{
"drupal_root": "/path/to/your/drupal",
"drush_command": "ddev drush"
}对于Lando用户：
{
"drupal_root": "/path/to/your/drupal",
"drush_command": "lando drush"
}对于Docksal用户：
{
"drupal_root": "/path/to/your/drupal",
"drush_command": "fin drush"
}💡 提示： 通过MCP（光标、克劳德桌面）使用Scout时，显式设置 drush_command 是 强烈推荐 以避免自动检测问题。MCP在与终端不同的环境中运行，可能在PATH中找不到开发工具。基本配置（最小）
{
"drupal_root": "/var/www/drupal",
"modules_path": "modules"
}Scout将尝试自动检测drush，但在MCP环境中可能会失败。
高级选项
{
"drupal_root": "/var/www/drupal",
"modules_path": "modules",
"exclude_patterns": ["node_modules", "vendor"],
"drush_command": "ddev drush"
}Drush配置（重要！）
61个工具中有18个需要drush 访问Drupal数据库：
get_taxonomy_info()-分类学使用分析get_entity_structure()-实体/捆绑信息get_field_info()-现场配置get_views_summary()-查看详细信息get_watchdog_logs()-错误/警告日志export_taxonomy_usage_to_csv()-CSV导出export_nodes_to_csv()-CSV导出export_users_to_csv()-CSV导出export_media_to_csv()-CSV导出- 还有更多。..
自动检测（MCP中可能失败）：
Scout尝试按以下顺序自动检测drush：
- 用户配置(
drush_command在config.json中）← 将此用于MCP！ - DDEV：
ddev drush（如果.ddev/config.yaml存在和ddev在PATH中） - 国家：
lando drush（如果.lando.yml存在和lando在PATH中） - 码头：
fin drush（如果.docksal/存在和fin在PATH中） - 作曲家：
vendor/bin/drush（如果文件存在） - 全球的：
drush（如果在PATH中）
手动超控（建议用于MCP）：
{
"drush_command": "ddev drush"
}常见示例：
- DDEV：
"drush_command": "ddev drush" - 国家：
"drush_command": "lando drush" - 码头：
"drush_command": "fin drush" - 自定义Docker：
"drush_command": "docker-compose exec php drush" - SSH远程：
"drush_command": "ssh user@host drush" - 绝对路径：
"drush_command": "/path/to/vendor/bin/drush"
数据库连接故障排除
如果依赖数据库的工具不起作用，请运行：
check_scout_health()这将准确显示问题所在以及如何解决。
常见问题：
- ❌
[Errno 2] No such file or directory: 'ddev'
→ Add "drush_command": "ddev drush" 转到config.json
- ❌
Drush found but database not connected
→ 确保开发环境正在运行： ddev start
- ⚠️
Drush not found in any expected location
→ 添加显式 drush_command 转到config.json
看 故障排除.md 全面的解决方案。
演出
令牌效率
Drupal Scout的主要价值是通过用单个MCP调用替换多个命令来减少AI对话中的令牌消耗：
| 没有Drupal Scout | 有Drupal Scout |
|---|---|
| 多字段：列表+配置：获取命令 | get_field_info（）（单次调用） |
| 视图：列表+多个grep | get_views_summary（）（单次调用） |
| 多个分类+节点查询 | get_taxonomy_info（）（单个调用） |
| 多个配置：get调用 | get_entity_structure（）（单个调用） |
优点：
- 更快的AI响应（更少的来回）
- 降低代币使用和API成本
- 为复杂的对话提供更多空间
- 更好的上下文保留
- 预先分析、交叉引用的数据
速度
本地搜索
- 初始索引：2-5秒（典型站点）
- 搜索查询：\<100ms
- 重新索引：仅在需要时
Drupal.org API
- 模块搜索：~500ms
- 模块详细信息：~700ms（基本）或~1000ms（有问题）
- 问题搜索：约1秒
- 所有结果缓存1小时
故障排除
未找到模块
- 检查config.json中的drupal_root路径
- 运行“重新索引模块”
- 验证模块已启用
Drupal.org搜索为空
- 检查互联网连接
- 尝试更广泛的搜索词
- drupal.org上可能不存在模块
无问题结果
- 问题可能很旧（最近搜索100次）
- 尝试更广泛的关键字
- 检查模块名称拼写
发展
运行测试
python3 -m pytest tests/代码结构
src/
indexer.py - Module indexing logic
search.py - Local search functionality
drupal_org.py - Drupal.org API integration
parsers/ - File parsers (.yml, .php)
prioritizer.py - Result formatting
server.py - MCP server entry point贡献
欢迎投稿！拜托：
- 分叉存储库
- 创建要素分支
- 进行更改
- 如果适用，添加测试
- 提交拉取请求
许可证
MIT许可证-有关详细信息，请参阅许可证文件
支持
- 问题：https://github.com/davo20019/drupal-scout-mcp/issues
- 讨论：https://github.com/davo20019/drupal-scout-mcp/discussions
更新日志
有关详细更改，请参阅各个提交。
相关项目
- 模型上下文协议：https://modelcontextprotocol.io
- Drupal：https://www.drupal.org
- FastMCP：https://github.com/jlowin/fastmcp