# analysis-mcp

A FastMCP server for critical thinking and multi-perspective analysis of current affairs.

**Uses the LLM-Orchestrator Pattern**: Tools return structured prompts for the calling LLM to execute, enabling **iterative complexity building** through prompt chaining.

## 🧠 Core Concept: Prompt Chaining for Complexity

Instead of doing one analysis, **chain operations** to build increasingly sophisticated insights:

```
1. deconstruct_claim("AI will replace jobs")
   → Get structured breakdown
   
2. chain_analysis(previous_output, "extract_assumptions")
   → Find hidden assumptions in your analysis
   
3. chain_analysis(previous_output, "identify_contradictions")
   → Spot tensions in the argument
   
4. chain_analysis(previous_output, "steelman_argument")
   → Build strongest version of the claim
   
5. chain_analysis(previous_output, "suggest_next_step")
   → Get recommendation for deeper analysis
```

Each step builds on the last, creating layered, sophisticated thinking.

## Features

**Core Analytical Tools:**
- `deconstruct_claim` - Break down claims into components
- `compare_positions` - Multi-perspective ideological analysis
- `apply_lens` - Analyze through 9 frameworks (historical, economic, etc.)
- `get_trace` - Retrieve previous analysis plans

**🔗 Prompt Chaining Tools (NEW):**
- `apply_operation` - Apply 15+ analytical operations to any content
- `chain_analysis` - Chain operations on previous LLM outputs
- `list_available_operations` - Browse all available operations

**15+ Analytical Operations:**

*Deconstructive:*
- `extract_assumptions` - Find implicit/explicit assumptions
- `identify_contradictions` - Spot logical tensions
- `find_fallacies` - Detect rhetorical manipulation

*Constructive:*
- `steelman_argument` - Build strongest version
- `find_analogies` - Identify relevant precedents
- `extract_principles` - Derive universal patterns

*Synthetic:*
- `synthesize_perspectives` - Merge viewpoints
- `elevate_abstraction` - Raise to higher concepts
- `ground_in_specifics` - Add concrete examples

*Meta-analytical:*
- `identify_gaps` - Find missing elements
- `check_coherence` - Verify logical consistency
- `suggest_next_step` - Recommend next operation

*Transformative:*
- `convert_to_dialogue` - Reframe as Socratic dialogue
- `extract_counterfactuals` - Generate what-if scenarios
- `map_dependencies` - Chart logical dependencies

## Quick Start with Claude Desktop

1. **Install via uvx** (recommended):

Edit your Claude Desktop config file:
- **MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add this to the `mcpServers` section:

```json
{
  "mcpServers": {
    "analysis-mcp": {
      "command": "uvx",
      "args": [
        "git+https://github.com/YOUR_USERNAME/analysis_mcp",
        "analysis-mcp"
      ]
    }
  }
}
```

2. **Restart Claude Desktop**

3. **Verify installation**: Look for the 🔌 icon in Claude Desktop showing the analysis-mcp server is connected

## Alternative: Local Development Installation

If you want to modify the code or run it locally:

```bash
# Clone the repo
git clone https://github.com/YOUR_USERNAME/analysis_mcp.git
cd analysis_mcp

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in editable mode
pip install -e ".[dev]"

# Run tests
pytest -v

# Run server directly (for testing)
python -m analysis_mcp.server
```

For local development in Claude Desktop, update your config to point to the local path:

```json
{
  "mcpServers": {
    "analysis-mcp": {
      "command": "python",
      "args": [
        "-m",
        "analysis_mcp.server"
      ],
      "cwd": "/absolute/path/to/analysis_mcp",
      "env": {
        "PYTHONPATH": "/absolute/path/to/analysis_mcp/src"
      }
    }
  }
}
```

## 🔄 Example Workflows

### Workflow 1: Deep Claim Analysis
```
1. "Analyze: AI will replace all jobs in 10 years"
   → deconstruct_claim()
   → Get: assumptions, evidence, implications

2. "Now extract the assumptions from that analysis"
   → chain_analysis(prev, "extract_assumptions")
   → Get: implicit assumptions revealed

3. "Find contradictions in those assumptions"
   → chain_analysis(prev, "identify_contradictions")
   → Get: logical tensions

4. "Steelman the strongest version"
   → chain_analysis(prev, "steelman_argument")
   → Get: most defensible claim
```

### Workflow 2: Multi-Lens Synthesis
```
1. apply_lens("Fed raises rates", "economic")
   → Economic analysis

2. apply_lens("Fed raises rates", "political")  
   → Political analysis

3. apply_operation(both_outputs, "synthesize_perspectives")
   → Unified framework

4. chain_analysis(synthesis, "identify_gaps")
   → Find what's missing
```

### Workflow 3: Iterative Refinement
```
1. compare_positions("Climate policy")
   → Multi-perspective view

2. chain_analysis(output, "elevate_abstraction")
   → Broader systemic patterns

3. chain_analysis(output, "ground_in_specifics")
   → Concrete examples added

4. chain_analysis(output, "check_coherence")
   → Verify consistency

5. chain_analysis(output, "suggest_next_step")
   → AI recommends next operation
```

## 💡 Why This Approach?

**Traditional Analysis:** One-shot, limited depth
```
"Analyze X" → Single output → Done
```

**Chained Analysis:** Iterative, building complexity
```
"Analyze X" 
→ deconstruct 
→ extract assumptions 
→ find contradictions 
→ steelman argument 
→ identify gaps
→ synthesize
= Deep, multi-layered understanding
```

**Benefits:**
- ✅ **Build complexity incrementally** - Each operation adds a layer
- ✅ **Provider-agnostic** - Works with any LLM
- ✅ **No API keys needed** - Server never calls external LLMs
- ✅ **Fully traceable** - Every step logged with trace_id
- ✅ **Self-guided** - `suggest_next_step` operation recommends what to do next
- ✅ **Composable** - Mix with other MCP tools (Wikipedia, web search, etc.)

## Available Lenses

- **historical** - Compare to precedents and patterns
- **economic** - Analyze resource flows and incentives  
- **geopolitical** - Examine power balances and strategy
- **psychological** - Identify biases and manipulation
- **technological** - Explore tech's role and impact
- **sociocultural** - Analyze identity and narratives
- **philosophical** - Apply ethical frameworks
- **systems** - Map feedback loops and leverage points
- **media** - Deconstruct framing and agenda-setting

## Trace Storage

Analysis plans are logged to `~/.analysis_mcp/traces/` as JSON files. Each trace contains:
- `trace_id` - Unique identifier
- `tool` - Which tool was called
- `input` - Original parameters
- `outline` - Structured analysis plan
- `next_prompt` - The prompt for LLM execution
- `timestamp` - When it was created

Use `get_trace(trace_id)` to retrieve any previous analysis plan.

## Troubleshooting

**Server not connecting?**
- Verify `uvx` is installed: `pip install uvx`
- Check Claude Desktop logs (Help → View Logs)
- Ensure your config JSON is valid

**Tools not appearing?**
- Restart Claude Desktop after config changes
- Check the 🔌 icon shows "analysis-mcp" as connected

## Contributing

Pull requests welcome! Please run tests before submitting:

```bash
pytest -v
```