# 🚀 Enhanced Subject Researcher MCP
[](https://github.com/your-org/subject-researcher-mcp/actions)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://badge.fury.io/py/subject-researcher-mcp)
> **Advanced iterative target-driven research with multi-vertical search, sophisticated claim mining, and evidence-based synthesis**
## ✨ Features
### 🎯 **Iterative Target-Driven Research**
- **Quality Meters**: Coverage, recency, novelty, agreement, contradictions tracking
- **Stop Criteria**: Configurable quality gates with automatic continuation logic
- **Stagnation Detection**: Automatic scope widening when research plateaus
- **Adaptive Queries**: Smart query generation based on iteration state
### 🔍 **Multi-Vertical Search Engine**
- **Real Web Search**: DuckDuckGo integration for actual web results
- **5 Search Verticals**: Web, News, Docs, Community, Academic sources
- **Fallback System**: Graceful degradation with high-quality synthetic results
- **Source Deduplication**: Cross-iteration URL tracking
### ⚗️ **Sophisticated Claim Mining**
- **Atomic Claims**: Extracts falsifiable, standalone statements
- **Metadata Extraction**: Units, measurements, caveats automatically detected
- **Independence Detection**: Cross-source validation and duplicate identification
- **Confidence Scoring**: Evidence-based claim reliability assessment
### 📊 **Enhanced Credibility Scoring**
- **Multi-Factor Analysis**: Domain authority, recency, content quality, independence
- **Independence Matrix**: Detects source relationships and potential bias
- **Transparency**: Detailed credibility breakdown for every source
- **Real-Time Updates**: Dynamic scoring based on cross-validation
### 📋 **Answer-First Synthesis**
- **Direct Answers**: Immediate response to research questions
- **Inline Citations**: Professional citation system with automatic numbering
- **Evidence Weighting**: Confidence scores based on source quality
- **Professional Reports**: Executive summaries with actionable recommendations
## 🚀 Quick Start
### 🐳 Recommended: Docker Installation (Easiest)
The easiest way to use the Enhanced Subject Researcher MCP is with Docker - no Python dependencies or environment setup required!
**Why Docker?**
- ✅ **Zero setup** - No Python environment configuration needed
- ✅ **Consistent** - Works the same across all systems (Windows, macOS, Linux)
- ✅ **Isolated** - No conflicts with your existing Python packages
- ✅ **Latest version** - Always get the most recent release automatically
```bash
# Pull the latest Docker image
docker pull elad12390/subject-researcher-mcp:latest
# Test the server (optional)
docker run --rm -i elad12390/subject-researcher-mcp:latest
```
### Alternative: Python Installation
```bash
pip install subject-researcher-mcp
```
### Basic Usage
```python
import asyncio
from subject_researcher_mcp import ResearchEngine, ResearchInputs
async def research_example():
engine = ResearchEngine()
# Configure research parameters
inputs = ResearchInputs(
subject="Python async programming best practices",
objective="comprehensive_analysis",
max_sources=15,
constraints={
"max_iterations": 3,
"gate_thresholds": {
"min_coverage": 0.7,
"min_recency": 0.5,
"novelty_threshold": 0.1,
"max_contradictions": 0.3
}
}
)
# Execute iterative research
report = await engine.conduct_iterative_research(inputs)
print(f"Research completed: {len(report.sources)} sources, {len(report.claims)} claims")
print(f"Confidence: {report.confidence:.1%}")
print(f"Executive Summary: {report.executive_summary}")
await engine.close()
# Run the research
asyncio.run(research_example())
```
## 🔧 Installation for AI Editors
### Claude Desktop
**🐳 Recommended: Docker Method (Easiest)**
1. **Pull the Docker image:**
```bash
docker pull elad12390/subject-researcher-mcp:latest
```
2. **Configure Claude Desktop:**
- Open Claude Desktop
- Click the Claude menu → Settings
- Go to Developer tab → Edit Config
- Add this configuration:
```json
{
"mcpServers": {
"subject-researcher": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"elad12390/subject-researcher-mcp:latest"
],
"env": {
"GEMINI_API_KEY": "your-optional-gemini-api-key"
}
}
}
}
```
3. **Restart Claude Desktop** and look for the MCP server indicator (🔌) in the chat input.
**📦 Alternative: Python Method**
1. **Install the package:**
```bash
pip install subject-researcher-mcp
```
2. **Configure Claude Desktop:**
```json
{
"mcpServers": {
"subject-researcher": {
"command": "python",
"args": ["-m", "subject_researcher_mcp.server"],
"env": {
"GEMINI_API_KEY": "your-optional-gemini-api-key"
}
}
}
}
```
### Cursor IDE
**🐳 Recommended: Docker Method (Easiest)**
1. **Pull the Docker image:**
```bash
docker pull elad12390/subject-researcher-mcp:latest
```
2. **Configure Cursor:**
- Create `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global access)
- Add this configuration:
```json
{
"mcpServers": {
"subject-researcher": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"elad12390/subject-researcher-mcp:latest"
],
"enabled": true,
"env": {
"GEMINI_API_KEY": "your-optional-gemini-api-key"
}
}
}
}
```
3. **Usage in Cursor:**
- Open the Composer Agent
- MCP tools will be listed under "Available Tools"
- Ask for research using natural language
**📦 Alternative: Python Method**
1. **Install the package:**
```bash
pip install subject-researcher-mcp
```
2. **Configure Cursor:**
```json
{
"mcpServers": {
"subject-researcher": {
"command": "python",
"args": ["-m", "subject_researcher_mcp.server"],
"enabled": true,
"env": {
"GEMINI_API_KEY": "your-optional-gemini-api-key"
}
}
}
}
```
### Claude Code
**🚀 Command-Line Method (Easiest)**
```bash
# Using Docker (Recommended)
claude mcp add subject-researcher --env GEMINI_API_KEY=your-optional-key \
-- docker run --rm -i elad12390/subject-researcher-mcp:latest
# Or using Python
claude mcp add subject-researcher --env GEMINI_API_KEY=your-optional-key \
-- python -m subject_researcher_mcp.server
```
**🔧 Manual Configuration**
1. **Pull the Docker image:**
```bash
docker pull elad12390/subject-researcher-mcp:latest
```
2. **Add manually via JSON:**
```bash
claude mcp add-json subject-researcher '{
"type":"stdio",
"command":"docker",
"args":["run","--rm","-i","elad12390/subject-researcher-mcp:latest"],
"env":{"GEMINI_API_KEY":"your-optional-key"}
}'
```
### OpenCode
**🐳 Recommended: Docker Method (Easiest)**
1. **Pull the Docker image:**
```bash
docker pull elad12390/subject-researcher-mcp:latest
```
2. **Configure OpenCode:**
- In your project directory, edit `opencode.json`
- Add this to the configuration:
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"subject-researcher": {
"type": "local",
"command": [
"docker",
"run",
"--rm",
"-i",
"elad12390/subject-researcher-mcp:latest"
],
"enabled": true,
"environment": {
"GEMINI_API_KEY": "your-optional-gemini-api-key"
}
}
}
}
```
3. **Usage in OpenCode:**
- MCP tools are automatically available to the LLM
- Ask for research and OpenCode will use the tools as needed
**📦 Alternative: Python Method**
1. **Install the package:**
```bash
pip install subject-researcher-mcp
```
2. **Configure OpenCode:**
```json
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"subject-researcher": {
"type": "local",
"command": ["python", "-m", "subject_researcher_mcp.server"],
"enabled": true,
"environment": {
"GEMINI_API_KEY": "your-optional-gemini-api-key"
}
}
}
}
```
## 📖 MCP Server Usage
Once configured in your AI editor, you can use natural language to request research:
**Example requests:**
- "Research the latest developments in quantum computing applications"
- "Analyze current best practices for microservices architecture"
- "Investigate recent security vulnerabilities in popular Python packages"
The MCP server provides these tools:
- `conduct_iterative_research` - Full 11-phase research methodology
- `conduct_research` - Basic multi-source research
- `analyze_research_quality` - Quality assessment of research results
## 🔑 Environment Variables
The Subject Researcher MCP supports the following optional environment variables:
| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `GEMINI_API_KEY` | Google Gemini API key for enhanced analysis and synthesis | No | Not used |
**Note:** The research engine works fully without any API keys, using free search APIs. The Gemini API key is only used for optional enhanced analysis features.
### Direct MCP Server Usage
```bash
# Start the MCP server
python -m subject_researcher_mcp.server
# Or using Docker
docker run -p 8000:8000 your-org/subject-researcher-mcp:latest
```
## 🛠️ Development
### Prerequisites
- Python 3.10+
- Git
### Setup
```bash
# Clone the repository
git clone https://github.com/your-org/subject-researcher-mcp.git
cd subject-researcher-mcp
# Install in development mode
pip install -e .
# Install development dependencies
pip install pytest pytest-asyncio ruff build
```
### Running Tests
```bash
# Run all tests
pytest tests/ -v
# Run E2E tests
pytest tests/test_real_mcp_e2e.py -v
# Run quick validation
python -c "from src.subject_researcher_mcp.research_engine import ResearchEngine; print('✅ Validation passed')"
```
### Code Quality
```bash
# Lint code
ruff check src/ tests/
# Format code
ruff format src/ tests/
# Type checking (if using mypy)
mypy src/
```
## 📖 API Reference
### ResearchEngine
Main class for conducting iterative research.
```python
class ResearchEngine:
def __init__(self, gemini_api_key: Optional[str] = None)
async def conduct_iterative_research(self, inputs: ResearchInputs) -> ResearchReport
async def conduct_research(self, inputs: ResearchInputs) -> ResearchReport # Legacy method
```
### ResearchInputs
Configuration for research execution.
```python
@dataclass
class ResearchInputs:
subject: str
objective: str = "comprehensive_analysis" # or "best_options", "decision_support"
depth: str = "standard" # "fast", "standard", "deep"
max_sources: int = 50
recency_months: int = 18
constraints: Dict[str, Any] = field(default_factory=dict)
```
### Quality Gates Configuration
```python
gate_thresholds = {
"min_coverage": 0.7, # Minimum topic coverage (0-1)
"min_recency": 0.5, # Minimum source freshness (0-1)
"novelty_threshold": 0.1, # Minimum new info rate (0-1)
"max_contradictions": 0.3 # Maximum contradiction level (0-1)
}
```
## 🔧 Configuration
### Environment Variables
```bash
# Optional: Gemini API key for enhanced AI analysis
export GEMINI_API_KEY="your-gemini-api-key"
# Optional: Custom configuration
export RESEARCH_MAX_ITERATIONS=5
export RESEARCH_TIMEOUT=300
```
### MCP Client Configuration
```json
{
"mcpServers": {
"subject-researcher": {
"command": "python",
"args": ["-m", "subject_researcher_mcp.server"],
"env": {
"GEMINI_API_KEY": "your-key-here"
}
}
}
}
```
## 🏗️ Architecture
### Research Methodology
The Enhanced Subject Researcher implements an 11-phase iterative methodology:
1. **Plan** - Generate research questions and hypotheses
2. **Query Design** - Create adaptive search queries
3. **Harvest** - Multi-vertical search execution
4. **Triage** - Source quality filtering
5. **Claim Mining** - Atomic claim extraction
6. **Cluster & Triangulate** - Cross-source validation
7. **Evaluate Credibility** - Enhanced scoring with independence matrix
8. **Topic Logic** - Domain-specific analysis (for "best X" queries)
9. **Synthesize** - Answer-first report generation
10. **Self-Critique** - Gap identification and quality assessment
11. **Package & Verify** - Final report assembly and validation
### Quality Metrics
- **Coverage**: How comprehensively the topic has been researched
- **Recency**: Average age and freshness of sources
- **Novelty**: Rate of new information discovery per iteration
- **Agreement**: Level of consensus across sources
- **Contradictions**: Amount of conflicting information found
## 🔒 Security
### Data Privacy
- No personal data collection
- API keys handled securely
- Source URLs and content processed locally
### Security Scanning
- Automated dependency vulnerability scanning
- Code security analysis with Bandit
- Regular security updates
## 📊 Performance
### Benchmarks
- **Search Speed**: 2-5 real sources per iteration (15-45 seconds)
- **Claim Extraction**: 2-3 atomic claims per source
- **Memory Usage**: ~50-100MB for standard research
- **Accuracy**: 85%+ confidence scores in controlled tests
### Optimization Tips
- Use `depth="fast"` for quick research (2-3 iterations)
- Adjust `max_sources` based on thoroughness needs
- Configure `gate_thresholds` for different quality requirements
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
### Development Workflow
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass (`pytest`)
6. Submit a pull request
### Code Standards
- Follow PEP 8 style guidelines
- Add type hints for all functions
- Include docstrings for public APIs
- Maintain test coverage above 80%
## 📝 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- [MCP Protocol](https://github.com/modelcontextprotocol/python-sdk) for the foundation
- [DuckDuckGo](https://duckduckgo.com) for search capabilities
- [Wikipedia API](https://pypi.org/project/Wikipedia-API/) for reliable reference data
- Research methodology inspired by academic research best practices
## 📈 Roadmap
### v2.1.0 (Planned)
- [ ] Real-time research monitoring dashboard
- [ ] Advanced NLP for better claim extraction
- [ ] Integration with academic databases
- [ ] Research collaboration features
### v2.2.0 (Future)
- [ ] Machine learning for query optimization
- [ ] Multi-language research support
- [ ] Advanced visualization tools
- [ ] Research template system
## 📞 Support
- **Documentation**: [GitHub Wiki](https://github.com/your-org/subject-researcher-mcp/wiki)
- **Issues**: [GitHub Issues](https://github.com/your-org/subject-researcher-mcp/issues)
- **Discussions**: [GitHub Discussions](https://github.com/your-org/subject-researcher-mcp/discussions)
- **Email**: research-support@your-org.com
---
**Made with ❤️ by the Enhanced Subject Researcher Team**
> *"Transforming information chaos into evidence-based insights through intelligent automation"*
Raw data
{
"_id": null,
"home_page": null,
"name": "subject-researcher-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, claim-mining, credibility-scoring, evidence-based, iterative-research, mcp, multi-vertical-search, quality-metrics, research, web-search",
"author": null,
"author_email": "Enhanced Subject Researcher Team <research-support@your-org.com>",
"download_url": "https://files.pythonhosted.org/packages/83/a3/a07849f6fa5a2ca41f4d562eef91a22ebcf2d1e3bfbd303c450091220b22/subject_researcher_mcp-0.2.0.tar.gz",
"platform": null,
"description": "# \ud83d\ude80 Enhanced Subject Researcher MCP\n\n[](https://github.com/your-org/subject-researcher-mcp/actions)\n[](https://www.python.org/downloads/)\n[](https://opensource.org/licenses/MIT)\n[](https://badge.fury.io/py/subject-researcher-mcp)\n\n> **Advanced iterative target-driven research with multi-vertical search, sophisticated claim mining, and evidence-based synthesis**\n\n## \u2728 Features\n\n### \ud83c\udfaf **Iterative Target-Driven Research**\n- **Quality Meters**: Coverage, recency, novelty, agreement, contradictions tracking\n- **Stop Criteria**: Configurable quality gates with automatic continuation logic\n- **Stagnation Detection**: Automatic scope widening when research plateaus\n- **Adaptive Queries**: Smart query generation based on iteration state\n\n### \ud83d\udd0d **Multi-Vertical Search Engine**\n- **Real Web Search**: DuckDuckGo integration for actual web results\n- **5 Search Verticals**: Web, News, Docs, Community, Academic sources\n- **Fallback System**: Graceful degradation with high-quality synthetic results\n- **Source Deduplication**: Cross-iteration URL tracking\n\n### \u2697\ufe0f **Sophisticated Claim Mining**\n- **Atomic Claims**: Extracts falsifiable, standalone statements\n- **Metadata Extraction**: Units, measurements, caveats automatically detected\n- **Independence Detection**: Cross-source validation and duplicate identification\n- **Confidence Scoring**: Evidence-based claim reliability assessment\n\n### \ud83d\udcca **Enhanced Credibility Scoring**\n- **Multi-Factor Analysis**: Domain authority, recency, content quality, independence\n- **Independence Matrix**: Detects source relationships and potential bias\n- **Transparency**: Detailed credibility breakdown for every source\n- **Real-Time Updates**: Dynamic scoring based on cross-validation\n\n### \ud83d\udccb **Answer-First Synthesis**\n- **Direct Answers**: Immediate response to research questions\n- **Inline Citations**: Professional citation system with automatic numbering\n- **Evidence Weighting**: Confidence scores based on source quality\n- **Professional Reports**: Executive summaries with actionable recommendations\n\n## \ud83d\ude80 Quick Start\n\n### \ud83d\udc33 Recommended: Docker Installation (Easiest)\n\nThe easiest way to use the Enhanced Subject Researcher MCP is with Docker - no Python dependencies or environment setup required!\n\n**Why Docker?**\n- \u2705 **Zero setup** - No Python environment configuration needed\n- \u2705 **Consistent** - Works the same across all systems (Windows, macOS, Linux)\n- \u2705 **Isolated** - No conflicts with your existing Python packages\n- \u2705 **Latest version** - Always get the most recent release automatically\n\n```bash\n# Pull the latest Docker image\ndocker pull elad12390/subject-researcher-mcp:latest\n\n# Test the server (optional)\ndocker run --rm -i elad12390/subject-researcher-mcp:latest\n```\n\n### Alternative: Python Installation\n\n```bash\npip install subject-researcher-mcp\n```\n\n### Basic Usage\n\n```python\nimport asyncio\nfrom subject_researcher_mcp import ResearchEngine, ResearchInputs\n\nasync def research_example():\n engine = ResearchEngine()\n \n # Configure research parameters\n inputs = ResearchInputs(\n subject=\"Python async programming best practices\",\n objective=\"comprehensive_analysis\",\n max_sources=15,\n constraints={\n \"max_iterations\": 3,\n \"gate_thresholds\": {\n \"min_coverage\": 0.7,\n \"min_recency\": 0.5,\n \"novelty_threshold\": 0.1,\n \"max_contradictions\": 0.3\n }\n }\n )\n \n # Execute iterative research\n report = await engine.conduct_iterative_research(inputs)\n \n print(f\"Research completed: {len(report.sources)} sources, {len(report.claims)} claims\")\n print(f\"Confidence: {report.confidence:.1%}\")\n print(f\"Executive Summary: {report.executive_summary}\")\n \n await engine.close()\n\n# Run the research\nasyncio.run(research_example())\n```\n\n## \ud83d\udd27 Installation for AI Editors\n\n### Claude Desktop\n\n**\ud83d\udc33 Recommended: Docker Method (Easiest)**\n\n1. **Pull the Docker image:**\n ```bash\n docker pull elad12390/subject-researcher-mcp:latest\n ```\n\n2. **Configure Claude Desktop:**\n - Open Claude Desktop\n - Click the Claude menu \u2192 Settings\n - Go to Developer tab \u2192 Edit Config\n - Add this configuration:\n\n ```json\n {\n \"mcpServers\": {\n \"subject-researcher\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\",\n \"-i\",\n \"elad12390/subject-researcher-mcp:latest\"\n ],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-optional-gemini-api-key\"\n }\n }\n }\n }\n ```\n\n3. **Restart Claude Desktop** and look for the MCP server indicator (\ud83d\udd0c) in the chat input.\n\n**\ud83d\udce6 Alternative: Python Method**\n\n1. **Install the package:**\n ```bash\n pip install subject-researcher-mcp\n ```\n\n2. **Configure Claude Desktop:**\n ```json\n {\n \"mcpServers\": {\n \"subject-researcher\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"subject_researcher_mcp.server\"],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-optional-gemini-api-key\"\n }\n }\n }\n }\n ```\n\n### Cursor IDE\n\n**\ud83d\udc33 Recommended: Docker Method (Easiest)**\n\n1. **Pull the Docker image:**\n ```bash\n docker pull elad12390/subject-researcher-mcp:latest\n ```\n\n2. **Configure Cursor:**\n - Create `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global access)\n - Add this configuration:\n\n ```json\n {\n \"mcpServers\": {\n \"subject-researcher\": {\n \"command\": \"docker\",\n \"args\": [\n \"run\",\n \"--rm\", \n \"-i\",\n \"elad12390/subject-researcher-mcp:latest\"\n ],\n \"enabled\": true,\n \"env\": {\n \"GEMINI_API_KEY\": \"your-optional-gemini-api-key\"\n }\n }\n }\n }\n ```\n\n3. **Usage in Cursor:**\n - Open the Composer Agent\n - MCP tools will be listed under \"Available Tools\"\n - Ask for research using natural language\n\n**\ud83d\udce6 Alternative: Python Method**\n\n1. **Install the package:**\n ```bash\n pip install subject-researcher-mcp\n ```\n\n2. **Configure Cursor:**\n ```json\n {\n \"mcpServers\": {\n \"subject-researcher\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"subject_researcher_mcp.server\"],\n \"enabled\": true,\n \"env\": {\n \"GEMINI_API_KEY\": \"your-optional-gemini-api-key\"\n }\n }\n }\n }\n ```\n\n### Claude Code\n\n**\ud83d\ude80 Command-Line Method (Easiest)**\n\n```bash\n# Using Docker (Recommended)\nclaude mcp add subject-researcher --env GEMINI_API_KEY=your-optional-key \\\n -- docker run --rm -i elad12390/subject-researcher-mcp:latest\n\n# Or using Python\nclaude mcp add subject-researcher --env GEMINI_API_KEY=your-optional-key \\\n -- python -m subject_researcher_mcp.server\n```\n\n**\ud83d\udd27 Manual Configuration**\n\n1. **Pull the Docker image:**\n ```bash\n docker pull elad12390/subject-researcher-mcp:latest\n ```\n\n2. **Add manually via JSON:**\n ```bash\n claude mcp add-json subject-researcher '{\n \"type\":\"stdio\",\n \"command\":\"docker\",\n \"args\":[\"run\",\"--rm\",\"-i\",\"elad12390/subject-researcher-mcp:latest\"],\n \"env\":{\"GEMINI_API_KEY\":\"your-optional-key\"}\n }'\n ```\n\n### OpenCode\n\n**\ud83d\udc33 Recommended: Docker Method (Easiest)**\n\n1. **Pull the Docker image:**\n ```bash\n docker pull elad12390/subject-researcher-mcp:latest\n ```\n\n2. **Configure OpenCode:**\n - In your project directory, edit `opencode.json`\n - Add this to the configuration:\n\n ```json\n {\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"subject-researcher\": {\n \"type\": \"local\",\n \"command\": [\n \"docker\",\n \"run\",\n \"--rm\",\n \"-i\", \n \"elad12390/subject-researcher-mcp:latest\"\n ],\n \"enabled\": true,\n \"environment\": {\n \"GEMINI_API_KEY\": \"your-optional-gemini-api-key\"\n }\n }\n }\n }\n ```\n\n3. **Usage in OpenCode:**\n - MCP tools are automatically available to the LLM\n - Ask for research and OpenCode will use the tools as needed\n\n**\ud83d\udce6 Alternative: Python Method**\n\n1. **Install the package:**\n ```bash\n pip install subject-researcher-mcp\n ```\n\n2. **Configure OpenCode:**\n ```json\n {\n \"$schema\": \"https://opencode.ai/config.json\",\n \"mcp\": {\n \"subject-researcher\": {\n \"type\": \"local\",\n \"command\": [\"python\", \"-m\", \"subject_researcher_mcp.server\"],\n \"enabled\": true,\n \"environment\": {\n \"GEMINI_API_KEY\": \"your-optional-gemini-api-key\"\n }\n }\n }\n }\n ```\n\n## \ud83d\udcd6 MCP Server Usage\n\nOnce configured in your AI editor, you can use natural language to request research:\n\n**Example requests:**\n- \"Research the latest developments in quantum computing applications\"\n- \"Analyze current best practices for microservices architecture\"\n- \"Investigate recent security vulnerabilities in popular Python packages\"\n\nThe MCP server provides these tools:\n- `conduct_iterative_research` - Full 11-phase research methodology\n- `conduct_research` - Basic multi-source research\n- `analyze_research_quality` - Quality assessment of research results\n\n## \ud83d\udd11 Environment Variables\n\nThe Subject Researcher MCP supports the following optional environment variables:\n\n| Variable | Description | Required | Default |\n|----------|-------------|----------|---------|\n| `GEMINI_API_KEY` | Google Gemini API key for enhanced analysis and synthesis | No | Not used |\n\n**Note:** The research engine works fully without any API keys, using free search APIs. The Gemini API key is only used for optional enhanced analysis features.\n\n### Direct MCP Server Usage\n\n```bash\n# Start the MCP server\npython -m subject_researcher_mcp.server\n\n# Or using Docker\ndocker run -p 8000:8000 your-org/subject-researcher-mcp:latest\n```\n\n## \ud83d\udee0\ufe0f Development\n\n### Prerequisites\n\n- Python 3.10+\n- Git\n\n### Setup\n\n```bash\n# Clone the repository\ngit clone https://github.com/your-org/subject-researcher-mcp.git\ncd subject-researcher-mcp\n\n# Install in development mode\npip install -e .\n\n# Install development dependencies\npip install pytest pytest-asyncio ruff build\n```\n\n### Running Tests\n\n```bash\n# Run all tests\npytest tests/ -v\n\n# Run E2E tests\npytest tests/test_real_mcp_e2e.py -v\n\n# Run quick validation\npython -c \"from src.subject_researcher_mcp.research_engine import ResearchEngine; print('\u2705 Validation passed')\"\n```\n\n### Code Quality\n\n```bash\n# Lint code\nruff check src/ tests/\n\n# Format code\nruff format src/ tests/\n\n# Type checking (if using mypy)\nmypy src/\n```\n\n## \ud83d\udcd6 API Reference\n\n### ResearchEngine\n\nMain class for conducting iterative research.\n\n```python\nclass ResearchEngine:\n def __init__(self, gemini_api_key: Optional[str] = None)\n \n async def conduct_iterative_research(self, inputs: ResearchInputs) -> ResearchReport\n async def conduct_research(self, inputs: ResearchInputs) -> ResearchReport # Legacy method\n```\n\n### ResearchInputs\n\nConfiguration for research execution.\n\n```python\n@dataclass\nclass ResearchInputs:\n subject: str\n objective: str = \"comprehensive_analysis\" # or \"best_options\", \"decision_support\"\n depth: str = \"standard\" # \"fast\", \"standard\", \"deep\"\n max_sources: int = 50\n recency_months: int = 18\n constraints: Dict[str, Any] = field(default_factory=dict)\n```\n\n### Quality Gates Configuration\n\n```python\ngate_thresholds = {\n \"min_coverage\": 0.7, # Minimum topic coverage (0-1)\n \"min_recency\": 0.5, # Minimum source freshness (0-1)\n \"novelty_threshold\": 0.1, # Minimum new info rate (0-1)\n \"max_contradictions\": 0.3 # Maximum contradiction level (0-1)\n}\n```\n\n## \ud83d\udd27 Configuration\n\n### Environment Variables\n\n```bash\n# Optional: Gemini API key for enhanced AI analysis\nexport GEMINI_API_KEY=\"your-gemini-api-key\"\n\n# Optional: Custom configuration\nexport RESEARCH_MAX_ITERATIONS=5\nexport RESEARCH_TIMEOUT=300\n```\n\n### MCP Client Configuration\n\n```json\n{\n \"mcpServers\": {\n \"subject-researcher\": {\n \"command\": \"python\",\n \"args\": [\"-m\", \"subject_researcher_mcp.server\"],\n \"env\": {\n \"GEMINI_API_KEY\": \"your-key-here\"\n }\n }\n }\n}\n```\n\n## \ud83c\udfd7\ufe0f Architecture\n\n### Research Methodology\n\nThe Enhanced Subject Researcher implements an 11-phase iterative methodology:\n\n1. **Plan** - Generate research questions and hypotheses\n2. **Query Design** - Create adaptive search queries\n3. **Harvest** - Multi-vertical search execution\n4. **Triage** - Source quality filtering\n5. **Claim Mining** - Atomic claim extraction\n6. **Cluster & Triangulate** - Cross-source validation\n7. **Evaluate Credibility** - Enhanced scoring with independence matrix\n8. **Topic Logic** - Domain-specific analysis (for \"best X\" queries)\n9. **Synthesize** - Answer-first report generation\n10. **Self-Critique** - Gap identification and quality assessment\n11. **Package & Verify** - Final report assembly and validation\n\n### Quality Metrics\n\n- **Coverage**: How comprehensively the topic has been researched\n- **Recency**: Average age and freshness of sources\n- **Novelty**: Rate of new information discovery per iteration\n- **Agreement**: Level of consensus across sources\n- **Contradictions**: Amount of conflicting information found\n\n## \ud83d\udd12 Security\n\n### Data Privacy\n- No personal data collection\n- API keys handled securely\n- Source URLs and content processed locally\n\n### Security Scanning\n- Automated dependency vulnerability scanning\n- Code security analysis with Bandit\n- Regular security updates\n\n## \ud83d\udcca Performance\n\n### Benchmarks\n- **Search Speed**: 2-5 real sources per iteration (15-45 seconds)\n- **Claim Extraction**: 2-3 atomic claims per source\n- **Memory Usage**: ~50-100MB for standard research\n- **Accuracy**: 85%+ confidence scores in controlled tests\n\n### Optimization Tips\n- Use `depth=\"fast\"` for quick research (2-3 iterations)\n- Adjust `max_sources` based on thoroughness needs\n- Configure `gate_thresholds` for different quality requirements\n\n## \ud83e\udd1d Contributing\n\nWe welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.\n\n### Development Workflow\n\n1. Fork the repository\n2. Create a feature branch (`git checkout -b feature/amazing-feature`)\n3. Make your changes\n4. Add tests for new functionality\n5. Ensure all tests pass (`pytest`)\n6. Submit a pull request\n\n### Code Standards\n\n- Follow PEP 8 style guidelines\n- Add type hints for all functions\n- Include docstrings for public APIs\n- Maintain test coverage above 80%\n\n## \ud83d\udcdd License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## \ud83d\ude4f Acknowledgments\n\n- [MCP Protocol](https://github.com/modelcontextprotocol/python-sdk) for the foundation\n- [DuckDuckGo](https://duckduckgo.com) for search capabilities\n- [Wikipedia API](https://pypi.org/project/Wikipedia-API/) for reliable reference data\n- Research methodology inspired by academic research best practices\n\n## \ud83d\udcc8 Roadmap\n\n### v2.1.0 (Planned)\n- [ ] Real-time research monitoring dashboard\n- [ ] Advanced NLP for better claim extraction\n- [ ] Integration with academic databases\n- [ ] Research collaboration features\n\n### v2.2.0 (Future)\n- [ ] Machine learning for query optimization\n- [ ] Multi-language research support\n- [ ] Advanced visualization tools\n- [ ] Research template system\n\n## \ud83d\udcde Support\n\n- **Documentation**: [GitHub Wiki](https://github.com/your-org/subject-researcher-mcp/wiki)\n- **Issues**: [GitHub Issues](https://github.com/your-org/subject-researcher-mcp/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/your-org/subject-researcher-mcp/discussions)\n- **Email**: research-support@your-org.com\n\n---\n\n**Made with \u2764\ufe0f by the Enhanced Subject Researcher Team**\n\n> *\"Transforming information chaos into evidence-based insights through intelligent automation\"*",
"bugtrack_url": null,
"license": "MIT",
"summary": "Enhanced Subject Researcher MCP - Iterative target-driven research with multi-vertical search, quality metrics, and sophisticated claim mining",
"version": "0.2.0",
"project_urls": {
"Documentation": "https://github.com/your-org/subject-researcher-mcp/wiki",
"Homepage": "https://github.com/your-org/subject-researcher-mcp",
"Issues": "https://github.com/your-org/subject-researcher-mcp/issues",
"Repository": "https://github.com/your-org/subject-researcher-mcp.git"
},
"split_keywords": [
"ai",
" claim-mining",
" credibility-scoring",
" evidence-based",
" iterative-research",
" mcp",
" multi-vertical-search",
" quality-metrics",
" research",
" web-search"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "18f7bc31b37bc153007a861737d038bfd697c940a752c5689d687ddb49d6c4bc",
"md5": "ecd71e9686d530eeb3a0dd34bd9ef3bb",
"sha256": "19622d5fe21bba665f62d74fa202817420c6360e9cb4e07a8d101571f4954462"
},
"downloads": -1,
"filename": "subject_researcher_mcp-0.2.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ecd71e9686d530eeb3a0dd34bd9ef3bb",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 29440,
"upload_time": "2025-08-13T08:28:35",
"upload_time_iso_8601": "2025-08-13T08:28:35.816536Z",
"url": "https://files.pythonhosted.org/packages/18/f7/bc31b37bc153007a861737d038bfd697c940a752c5689d687ddb49d6c4bc/subject_researcher_mcp-0.2.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "83a3a07849f6fa5a2ca41f4d562eef91a22ebcf2d1e3bfbd303c450091220b22",
"md5": "1b17a303dda111d07accd1dda2602c7d",
"sha256": "cb20ebd2cf26721d9dd68860b9a6abc84e9b876f55fbbb92bd54f2dc7480d6df"
},
"downloads": -1,
"filename": "subject_researcher_mcp-0.2.0.tar.gz",
"has_sig": false,
"md5_digest": "1b17a303dda111d07accd1dda2602c7d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 1428422,
"upload_time": "2025-08-13T08:28:36",
"upload_time_iso_8601": "2025-08-13T08:28:36.737015Z",
"url": "https://files.pythonhosted.org/packages/83/a3/a07849f6fa5a2ca41f4d562eef91a22ebcf2d1e3bfbd303c450091220b22/subject_researcher_mcp-0.2.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-13 08:28:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "your-org",
"github_project": "subject-researcher-mcp",
"github_not_found": true,
"lcname": "subject-researcher-mcp"
}
JSON
