Brain Trust MCP

🚀 Ask MCP - Hosted OpenAI MCP Server (v0.3.0)

🧠 Connect your IDE to OpenAI for intelligent question answering and structured plan reviews.

A hosted FastMCP server with 3 simple tools that connect your IDE directly to OpenAI. No local installation needed.

🌐 Visit ask-mcp.com - Try it instantly in your browser with setup guides for 8+ IDEs!

🚀 Quick Start

Prerequisites

• Python 3.12+
• OpenAI API key
• Docker (optional, but recommended)

Option 1: Docker (Recommended)

# Clone the repository
git clone <repository-url>
cd mcp-ask-questions

# Start the server (no API key needed)
docker-compose up -d

# Check logs
docker-compose logs -f

The server starts immediately without requiring an OpenAI API key. Configure the API key in your MCP client (see below).

Option 2: Local Python

# Install dependencies
pip install -r requirements.txt

# Run the server
python server.py

✨ Features

Master Review Framework

• 10-point structured evaluation for comprehensive plan analysis
• 5 progressive review levels from quick to expert
• FMEA-style failure analysis in deep_dive mode
• Enterprise-grade reviews with RACI, TCO, SLOs

Comprehensive Logging

• Full request/response tracing for debugging
• Environment-aware masking (debug vs production)
• 5+ log events per request with structured JSON output
• API key validation at every step

Professional Testing

• 92% code coverage with 18 pytest tests
• 10 integration tests with real OpenAI API calls
• Automatic skipping if API key not available
• Type-safe with full mypy compliance

Development Tools

• Pre-commit hooks enforce code quality automatically
• Auto-activate venv in VS Code/Cursor workspace
• Docker support for easy deployment
• HTTP header config support (optional)

📦 Installation

Configure in Cursor

Quick Install Button

Add to ~/.cursor/mcp.json

{
  "mcpServers": {
    "brain-trust": {
      "url": "http://localhost:8000/mcp",
      "transport": "http",
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

How it works:

• The OPENAI_API_KEY from the MCP client configuration is set as an environment variable for the server
• The server reads the API key from the environment and uses it to authenticate with OpenAI
• Optional: You can override the model and max_tokens per tool call

Important: Make sure Docker is running and the server is started before using in Cursor!

💻 Usage Examples

Basic Usage

Example 1: Quick Question

Ask OpenAI directly:

Use phone_a_friend to ask: "What are Python best practices?"

Example 2: Context-Aware Question

Get answers specific to your situation:

Use phone_a_friend with the question "How should we structure our tests?"
and context "We use FastAPI with pytest, SQLAlchemy, and Docker"

Example 3: Plan Review

Get feedback on a planning document:

Use review_plan to review the file plans/compare-options-tool.md
with review_level "standard"

Example 4: Comprehensive Plan Analysis

Get deep analysis with specific focus:

Use review_plan on plans/compare-options-tool.md with review_level "expert",
context "Team of 2 engineers, need to build quickly",
and focus_areas ["timeline", "implementation", "risks"]

Advanced Usage

The 3 Simple Tools provided by the server offer more advanced usage scenarios.

1. 📞 phone_a_friend

Ask OpenAI any question, with optional context for better answers.

# Simple question
phone_a_friend("What is Docker?")

# Context-aware question
phone_a_friend(
    question="Should we use microservices?",
    context="Team of 5 engineers, launching MVP in 3 months"
)

2. 📋 review_plan

Get AI-powered feedback on planning documents using the Master Review Framework - a structured 10-point evaluation system. Master Review Framework Dimensions:

• Structure & Organization
• Completeness
• Clarity
• Assumptions & Dependencies
• Risks
• Feasibility
• Alternatives
• Validation
• Stakeholders
• Long-term Sustainability

Review Levels (Progressive Depth):

• quick - Basic checklist (1-2 suggestions)
• standard - Standard analysis (2-3 questions)
• comprehensive - Detailed coverage (3-5 questions)
• deep_dive - NEW! Technical FMEA-style analysis (4-6 questions)
• expert - Professional enterprise-level review (5-7 strategic questions)

# Deep technical review
review_plan(
    plan_content="# Q4 2025 Roadmap\n...",
    review_level="deep_dive",  # NEW technical level
    context="Startup with $500K budget, need to launch in 6 months",
    focus_areas=["scalability", "risks", "timeline"]
)

# Expert enterprise review
review_plan(
    plan_content="# Migration Plan\n...",
    review_level="expert",
    context="Fortune 500 company, 1M+ users"
)

Returns:

• Overall score (0.0-1.0)
• Strengths (list)
• Weaknesses (list)
• Suggestions (list)
• Detailed feedback (structured analysis)
• Review level used
• Timestamp

3. ❤️ health_check

Check server status and configuration.

health_check()
# Returns: {status, timestamp, plan_reviews_count}

📚 Documentation

Core Documentation

• README.md (this file) - Overview and quick start
• docs/LOGGING.md - Comprehensive logging system guide
• docs/HEADER_IMPLEMENTATION.md - Header-based configuration guide
• docs/MCP_CLIENT_HEADERS.md - Client configuration options
• tests/README.md - Testing documentation and examples

Release Notes

• release_notes/RELEASE_NOTES_v0.1.2.md - Latest release (current)
• release_notes/RELEASE_NOTES_v0.1.1.md - Previous release

Examples

• examples/server_with_headers.py - HTTP header configuration example

Planning Documents

• plans/ - Detailed planning documents and proposals
  • contextual-qa-mcp-server.md
  • technical-implementation.md
  • quick-start-guide.md
  • compare-options-tool.md

🔧 Technical Details

Architecture

┌─────────────────┐
│  Cursor / AI    │
│     Agent       │
└────────┬────────┘
         │ MCP Protocol (HTTP)
         │
┌────────▼────────┐
│   brain-trust   │
│   MCP Server    │
│  (FastMCP)      │
└────────┬────────┘
         │ OpenAI API
         │
┌────────▼────────┐
│    OpenAI       │
└─────────────────┘

Flow:

1. Agent calls MCP tool with API key from MCP client config
2. brain-trust server receives request with API key via HTTP
3. Server creates OpenAI client with provided API key
4. Server formats prompt and calls OpenAI API
5. OpenAI returns AI-generated response
6. Server returns structured response to agent

Docker Setup

The server runs in Docker with:

• FastMCP Server: Python 3.12, running on port 8000
• Nginx: Reverse proxy for HTTP requests
• Health Checks: Every 30 seconds
• Non-root User: Security best practice

# Start services
docker-compose up -d

# View logs
docker-compose logs -f

# Check status
curl http://localhost:8000/health

# Stop services
docker-compose down

Configuration

Environment Variables

The server supports environment-based configuration. Create a .env file:

# Server Configuration
ENVIRONMENT=development           # development or production
LOG_LEVEL=DEBUG                  # DEBUG, INFO, WARNING, ERROR, CRITICAL
PORT=8000                        # Default: 8000

# Optional: For development/testing only
OPENAI_API_KEY=sk-...           # Only needed for local testing

Logging Modes: Development (DEBUG):

• Full API keys visible in logs (for debugging)
• All request/response details logged
• Complete header information

Production (INFO):

• API keys masked (first 8 + last 4 chars only)
• Essential information only
• Reduced sensitive data logging

See docs/LOGGING.md for comprehensive logging documentation. Note: OpenAI API key is NOT required as an environment variable for production. The API key is passed directly from the MCP client with each tool call.

MCP Client Configuration (Required)

Configure your OpenAI API key in the MCP client settings (e.g., Cursor's ~/.cursor/mcp.json):

{
  "mcpServers": {
    "brain-trust": {
      "url": "http://localhost:8000/mcp",
      "transport": "http",
      "env": {
        "OPENAI_API_KEY": "your_actual_api_key_here"
      }
    }
  }
}

How it works:

1. You configure the API key in your MCP client
2. The MCP client automatically passes the key to tool calls
3. The server uses the key to authenticate with OpenAI per-request
4. No API key storage on the server side

Benefits:

• ✅ No API keys in Docker containers or environment files
• ✅ Secure key management via MCP client
• ✅ Different clients can use different API keys
• ✅ Per-request authentication

API Endpoints

When running locally:

• MCP Endpoint: http://localhost:8000/mcp
• Health Check: http://localhost:8000/health

Test the health endpoint:

curl http://localhost:8000/health
# Returns: {"status":"healthy","timestamp":"...","plan_reviews_count":0}

Testing

Quick Test

Test that the server is working:

# Check health
curl http://localhost:8000/health

# In Cursor, try:
# "Use phone_a_friend to ask: What is FastMCP?"

Test Suite

Run the comprehensive pytest test suite:

# Run all tests (18 tests, ~95 seconds)
pytest tests/

# Run with coverage report (92% coverage)
pytest --cov=server --cov-report=term-missing tests/

# Run only unit tests (fast, no API calls)
pytest tests/test_logging.py

# Run only integration tests (real OpenAI API calls)
pytest tests/test_tools.py

# Run specific test
pytest tests/test_tools.py::TestPhoneAFriend::test_phone_a_friend_basic -v

Test Coverage:

• ✅ 18 tests total
• ✅ 8 unit tests (logging, utilities)
• ✅ 10 integration tests (real OpenAI API calls)
• ✅ 92% code coverage
• ✅ All MCP tools tested
• ✅ All 5 review levels tested

Requirements:

• Tests require OPENAI_API_KEY in .env file for integration tests
• Unit tests run without API key
• Tests automatically skip if API key not available

See tests/README.md for complete testing documentation.

Project Structure

mcp-ask-questions/
├── server.py                    # Main MCP server with 3 tools
├── Dockerfile                   # Container definition
├── docker-compose.yml           # Multi-container orchestration
├── nginx.conf                   # Reverse proxy config
├── requirements.txt             # Python dependencies
├── pyproject.toml              # Project configuration (black, isort, mypy)
├── fastmcp.json                # FastMCP deployment config
├── .env.example                # Environment variables template
├── README.md                   # This file
├── docs/                       # Documentation
│   ├── LOGGING.md             # Comprehensive logging guide
│   ├── HEADER_IMPLEMENTATION.md  # Header-based config guide
│   └── MCP_CLIENT_HEADERS.md  # Client configuration guide
├── tests/                      # Pytest test suite (92% coverage)
│   ├── conftest.py            # Shared fixtures
│   ├── test_tools.py          # Tool tests (10 tests)
│   ├── test_logging.py        # Logging tests (8 tests)
│   └── README.md              # Testing documentation
├── release_notes/             # Release notes
│   ├── RELEASE_NOTES_v0.1.2.md
│   └── RELEASE_NOTES_v0.1.1.md
├── examples/                   # Example implementations
│   └── server_with_headers.py # Header-based config example
└── plans/                      # Planning documents
    ├── contextual-qa-mcp-server.md
    ├── technical-implementation.md
    ├── quick-start-guide.md
    └── compare-options-tool.md

📄 License

MIT License - see LICENSE file for details

🎯 Why brain-trust?

Simple

• Only 3 tools to learn
• Direct, straightforward usage
• No complex context management
• Clear, comprehensive documentation

Powerful

• Use your favorite GPT Model
• Context-aware answers
• 5 progressive review levels
• Master Review Framework with 10-point analysis

Practical

• Solves real problems (questions, plan reviews)
• Easy to integrate with Cursor
• Production-ready with Docker
• 92% test coverage ensures reliability

Extensible

• Easy to add new tools
• Clean, maintainable codebase
• Well-documented for contributions
• Professional testing infrastructure

🤝 Contributing

We welcome contributions! Here's how to contribute:

Adding a New Tool

1. Plan: Create a plan in plans/your-tool-name.md
2. Implement: Add tool to server.py with @mcp.tool() decorator
3. Test: Add tests in tests/test_tools.py
4. Document: Update README and add to docs/ if needed
5. Quality: Pre-commit hooks will run automatically
6. Submit: Create a pull request

See plans/compare-options-tool.md for an example plan.

Code Standards

• Python 3.12+ with type hints
• Black formatting (line length 88)
• isort for import sorting
• flake8 for linting
• mypy for type checking
• pytest for testing (aim for >80% coverage)
• Conventional commits for commit messages

Running Tests

# Run all tests
pytest tests/

# Run with coverage
pytest --cov=server tests/

# Pre-commit hooks run automatically
git commit -m "feat: add new tool"

Documentation Standards

• Add docstrings to all public functions
• Update README.md for user-facing changes
• Add examples for new features
• Keep docs/ up to date
• Follow existing documentation style

📊 Project Stats

• Tools: 3 (phone_a_friend, review_plan, health_check)
• Review Levels: 5 (quick, standard, comprehensive, deep_dive, expert)

🔗 Links

• Repository: https://github.com/bernierllc/brain-trust-mcp
• Issues: https://github.com/bernierllc/brain-trust-mcp/issues
• FastMCP Docs: https://gofastmcp.com
• MCP Specification: https://modelcontextprotocol.io/

Questions? Issues? Feedback? Open an issue or reach out! We're here to help. 🧠✨