Skip to content

research

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History
 
 

research

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
.claude-plugin
.claude-plugin
 
 
commands
commands
 
 
.mcp.json
.mcp.json
 
 
README.md
README.md
 
 

README.md

Research Plugin

Comprehensive research workflow with MCP server integration and structured documentation output.

Overview

The research plugin provides the /research:conduct slash command for conducting thorough, multi-source research with automatic synthesis and structured markdown output.

Features

  • Multi-MCP Integration: Uses ref, context7, perplexity, and firecrawl for comprehensive coverage
  • Fallback Strategies: Automatic fallback from MCP → Firecrawl → WebFetch when sources fail
  • Parallel Execution: All MCP calls executed in parallel for 60-80% performance improvement
  • Structured Output: YAML frontmatter, executive summary, sections, references, metadata
  • INDEX.md Management: Automatic research catalog with categorization and statistics
  • Identity Disambiguation: Special handling for person research with conflict detection
  • Critical Analysis: Automatic search for criticism, alternatives, and negative perspectives
  • Source Verification: Cross-referencing across multiple sources with different perspectives

Installation

/plugin install research@melodic-software

Usage

/research:conduct <topic> [thinking-mode]

Arguments:

  • <topic> (required): Topic to research
  • [thinking-mode] (optional): Signals expected research depth. Options: "think", "think_hard", "think_harder", "ultrathink". Note: These are prompt instructions that signal expectations but don't control thinking token allocation (extended thinking is enabled by default at 31,999 tokens). Use MAX_THINKING_TOKENS env var to adjust budget.

Examples:

/research:conduct "Claude Code hooks system"
/research:conduct "Vertical Slice Architecture" think_harder
/research:conduct "John Smith software engineer" think

Output

Research files are saved to .claude/research/ with UTC timestamp:

  • Format: YYYY-MM-DD_HH-MM-SS-<topic-kebab-case>.md
  • Example: 2025-01-06_15-30-45-claude-code-hooks.md

INDEX.md is automatically created/updated with research catalog.

MCP Servers

This plugin bundles MCP servers that start automatically when the plugin is enabled.

Server Type Capabilities
context7 HTTP Library documentation lookup via Context7
perplexity stdio Web search, reasoning, deep research
ref HTTP Documentation search and retrieval
firecrawl stdio Web scraping, crawling, extraction

API Keys Required

Set these environment variables (or in settings.json):

Server Environment Variable
context7 CONTEXT7_API_KEY
perplexity PERPLEXITY_API_KEY
ref REF_API_KEY
firecrawl FIRECRAWL_API_KEY

Prerequisites

  • Node.js (for npx - perplexity and firecrawl servers)
  • API keys for each service you want to use

Environment Variables

Context7

Variable Default Description
CONTEXT7_API_KEY (required) API key from context7.com

Perplexity

Variable Default Description
PERPLEXITY_API_KEY (required) API key from perplexity.ai
PERPLEXITY_MODEL sonar-pro Default search model
PERPLEXITY_MODEL_REASON sonar-reasoning-pro Reasoning model
PERPLEXITY_MODEL_RESEARCH sonar-deep-research Deep research model
PERPLEXITY_TIMEOUT_MS 120000 Request timeout (ms)
PERPLEXITY_LOG_LEVEL ERROR Log level: DEBUG, INFO, WARN, ERROR

Ref

Variable Default Description
REF_API_KEY (required) API key from ref.tools
REF_SCOPE (none) Scope param: ?scope=user or ?scope=t-xxx

Firecrawl

Variable Default Description
FIRECRAWL_API_KEY (required) API key from firecrawl.dev
FIRECRAWL_API_URL (cloud) Self-hosted instance URL
FIRECRAWL_RETRY_MAX_ATTEMPTS 3 Max retry attempts
FIRECRAWL_CREDIT_WARNING_THRESHOLD 1000 Credit warning level

MCP Server Capabilities

The /research:conduct command uses these MCP servers:

  • ref - Documentation search and retrieval
  • context7 - Library documentation lookup
  • perplexity - Web search, reasoning, deep research
  • firecrawl - Web scraping (fallback)

Tool Permissions

Required tools (from frontmatter):

  • Bash(date -u +"%Y%m%dT%H%M%SZ")
  • Glob, Grep, MultiEdit, Read, Task, WebFetch, WebSearch, Write
  • mcp__firecrawl__firecrawl_scrape
  • mcp__firecrawl__firecrawl_search

Model

Uses: claude-sonnet-4-5-20250929

License

MIT License - Copyright (c) 2025 Melodic Software