# Case Study Generator MCP Server

A Model Context Protocol (MCP) server that processes document content and GitHub repositories with Gemma3 to extract structured business insights for case study generation.

## Overview

This MCP server provides three main capabilities:

1. **Document Processing** - Extract business insights from documents (proposals, case studies, contracts)
2. **GitHub Repository Analysis** - Analyze repositories for business value and technical benefits  
3. **Company Research** - Real-time web research using Tavily + AI analysis for company insights

The server uses Gemma3 8B-Instruct via Ollama for local LLM processing, ensuring privacy and control over your data.

## Architecture

```
User → Claude Desktop → Google Drive (retrieve) → MCP Server (process) → Claude Desktop (reason & write) → Google Drive (save)
```

- **Claude Desktop**: Handles document retrieval, reasoning, writing, and saving
- **MCP Server**: Processes data with Gemma3 and returns structured insights
- **Ollama/Gemma3**: Local LLM for business analysis and insight extraction

## Prerequisites

### Required Software

1. **Python 3.11+** - Programming language runtime
2. **Ollama** - Local LLM inference server
3. **Gemma3 Model** - Language model for analysis

### Install Ollama

Visit [ollama.ai](https://ollama.ai) and install for your platform.

After installation, pull the Gemma3 model:
```bash
ollama pull gemma3n:e4b
```

Verify Ollama is running:
```bash
ollama list
```

## Installation

### Option 1: Using venv (Recommended)

```bash
# Clone the repository
git clone <repository-url>
cd case-study-mcp

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

# Install dependencies
pip install -r requirements.txt
```

### Option 2: Using Poetry

```bash
# Clone the repository
git clone <repository-url>
cd case-study-mcp

# Install with Poetry
poetry install
poetry shell
```

## Configuration

### Environment Variables (Optional)

Create a `.env` file in the project root:

```bash
# GitHub API token for higher rate limits (optional)
GITHUB_TOKEN=your_github_token_here

# Tavily API key for web search company research (optional)
TAVILY_API_KEY=your_tavily_api_key_here

# Ollama configuration
OLLAMA_HOST=http://localhost:11434
OLLAMA_MODEL=gemma3n:e4b

# Logging level
LOG_LEVEL=INFO
```

### GitHub Token Setup

For better GitHub API rate limits, create a personal access token:

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate a new token with `public_repo` scope
3. Add to `.env` file or set as environment variable

### Tavily API Setup (For Company Research)

For real company research capabilities, get a Tavily API key:

1. Sign up at [tavily.com](https://tavily.com)
2. Get your API key from the dashboard
3. Add `TAVILY_API_KEY=your_key_here` to `.env` file

**Note**: Without Tavily, company research will use LLM pattern matching only.

## Usage

### Starting the MCP Server

```bash
# Run the server
python mcp_server.py
```

The server communicates via stdio and will wait for MCP protocol messages.

### Integration with Claude Desktop

Add to your Claude Desktop MCP configuration:

```json
{
  "mcpServers": {
    "case-study-mcp": {
      "command": "python",
      "args": ["/path/to/case-study-mcp/mcp_server.py"],
      "cwd": "/path/to/case-study-mcp"
    }
  }
}
```

### Example Usage in Claude Desktop

```
User: "Create a case study for TechCorp using github.com/example/ecommerce-platform and my retail proposal document"

Claude: "I'll analyze the repository and document to create your case study..."

[Claude uses MCP tools:]
1. process_document_text(text="retail proposal content", doc_type="proposal")
2. analyze_github_repo(repo_url="github.com/example/ecommerce-platform") 
3. research_company_basic(company_name="TechCorp")

[Claude synthesizes results into compelling case study]
```

## MCP Tools

### 1. process_document_text

Extract business insights from document content.

**Parameters:**
- `text` (required): Document content text
- `doc_type` (optional): Type of document - "proposal", "case_study", "contract", or "general"

**Returns:**
```json
{
  "success": true,
  "document_type": "proposal",
  "insights": {
    "challenges": ["Legacy platform scalability issues"],
    "solutions": ["Microservices architecture"],
    "metrics": ["90% improvement in load times"],
    "context": "Mid-market e-commerce company",
    "key_stakeholders": ["CTO", "Engineering Team"],
    "timeline": "6-month implementation"
  }
}
```

### 2. analyze_github_repo

Analyze GitHub repository for business value.

**Parameters:**
- `repo_url` (required): GitHub repository URL

**Returns:**
```json
{
  "success": true,
  "repository": {
    "url": "github.com/example/repo",
    "name": "example/ecommerce-platform",
    "tech_stack": ["Python", "React", "Docker"],
    "stars": 1250,
    "language": "Python"
  },
  "business_analysis": {
    "problem_solved": "Scalable e-commerce platform",
    "key_features": ["Microservices", "Redis caching"],
    "business_value": "Enables 10x traffic scaling",
    "technical_benefits": ["Horizontal scaling", "Fault tolerance"],
    "target_users": "Mid to large-scale e-commerce businesses",
    "scalability": "Designed for high-traffic peaks",
    "integration_points": ["CRM systems", "Payment gateways"]
  }
}
```

### 3. research_company_basic

Real company research using web search + AI analysis.

**Parameters:**
- `company_name` (required): Name of the company
- `company_context` (optional): Additional context about the company

**Returns:**
```json
{
  "success": true,
  "company": {
    "name": "TechCorp",
    "profile": "Technology company specializing in...",
    "industry": "Technology",
    "business_model": "SaaS"
  },
  "insights": {
    "challenges": ["Digital transformation needs"],
    "opportunities": ["Cloud migration potential"],
    "technology_needs": ["Scalable infrastructure"]
  },
  "web_search_used": true,
  "search_sources": [
    {"title": "TechCorp - About Us", "url": "https://techcorp.com/about"},
    {"title": "TechCorp on LinkedIn", "url": "https://linkedin.com/company/techcorp"}
  ]
}
```

## Testing

### Manual Testing

Test each tool individually:

```bash
# Test document processing
echo '{"text": "Sample proposal text", "doc_type": "proposal"}' | python test_document.py

# Test GitHub analysis  
echo '{"repo_url": "github.com/microsoft/vscode"}' | python test_github.py

# Test company research
echo '{"company_name": "Microsoft"}' | python test_company.py
```

### Health Check

The server provides a health check resource:

```
URI: health://status
```

Returns status of all components including Gemma3, GitHub API, and processors.

## Troubleshooting

### Common Issues

**1. Ollama Connection Error**
```
Error: Failed to connect to Ollama
```
**Solution:** Ensure Ollama is running (`ollama serve`) and the model is pulled (`ollama pull gemma3n:e4b`).

**2. GitHub Rate Limit**
```
Error: GitHub API rate limit exceeded
```
**Solution:** Add a GitHub token to your `.env` file for higher limits.

**3. Model Not Found**
```
Error: Model ollama3n:4b not found
```
**Solution:** Pull the model with `ollama pull ollama3n:4b`.

**4. Import Errors**
```
ImportError: No module named 'mcp'
```
**Solution:** Install dependencies with `pip install -r requirements.txt`.

**5. Company Research Limited**
```
Warning: Tavily not configured. Company research will use LLM patterns only.
```
**Solution:** Get a Tavily API key from [tavily.com](https://tavily.com) and add to `.env` file.

### Performance Optimization

- **Memory Usage**: Ollama3n 4B requires ~4-6GB RAM for optimal performance
- **Processing Time**: Document processing typically takes 5-15 seconds
- **Concurrent Requests**: Server handles one request at a time by design

### Logging

Enable debug logging:
```bash
export LOG_LEVEL=DEBUG
python mcp_server.py
```

## Project Structure

```
case-study-mcp/
├── mcp_server.py              # Main MCP server entry point
├── gemma3_client.py           # Gemma3/Ollama client wrapper
├── document_processor.py      # Document analysis processor
├── github_analyzer.py         # GitHub repository analyzer  
├── company_researcher.py      # Company research processor
├── prompts.py                 # Gemma3 prompt templates
├── pyproject.toml            # Poetry configuration
├── requirements.txt          # Pip dependencies
├── README.md                 # This file
├── project_config.md         # Project specification
└── workflow_state.md         # Development workflow tracking
```

## Development

### Contributing

1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Submit a pull request

### Code Style

- Use Black for formatting: `black .`
- Use isort for imports: `isort .`
- Use mypy for type checking: `mypy .`

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
1. Check the troubleshooting section above
2. Review the project configuration in `project_config.md`
3. Open an issue with detailed error logs and steps to reproduce