# 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
