olympus-mcp 1.0.0

package/README.md

@@ -0,0 +1,45 @@
+# Olympus MCP
+
+Warren Buffett-style value investing analysis for Claude AI.
+
+## Installation
+
+```bash
+npx olympus-mcp
+```
+
+This will:
+1. Install the package
+2. Auto-configure Claude Desktop
+3. No manual setup required!
+
+After installation, restart Claude Desktop.
+
+## Usage
+
+Ask Claude:
+- "Analyze Apple using value investing"
+- "Show me the value investing framework"
+- "Calculate earnings yield for..."
+
+## Features
+
+- Earnings Yield Analysis (>10% threshold)
+- ROIC Evaluation (5-year average)
+- Investment Classification (Lists 1-4)
+- Based on Buffett & Munger principles
+
+## The 4 Lists
+
+1. **LIST 1**: Good at Wonderful Price
+2. **LIST 2**: Wonderful at Fair Price ⭐
+3. **LIST 3**: FAT PITCH 🎯 (Rare opportunity!)
+4. **LIST 4**: Wonderful but Overvalued (Study & wait)
+
+## License
+
+MIT
+
+## Author
+
+Owen Taylor - Pallas AI

package/index.js

@@ -0,0 +1,591 @@
+#!/usr/bin/env node
+/**
+ * Olympus MCP Server
+ * Warren Buffett-style value investing analysis for Claude AI
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
+
+// Framework constants
+const EARNINGS_YIELD_THRESHOLD = 0.10;  // 10%
+const ROIC_THRESHOLD = 0.15;  // 15%
+const ROIC_WONDERFUL_THRESHOLD = 0.25;  // 25%
+
+// Initialize the MCP server
+const server = new Server(
+  {
+    name: "olympus-mcp",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// List available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return {
+    tools: [
+      {
+        name: "analyze_stock",
+        description:
+          "Performs comprehensive value investing analysis on a stock using the Buffett-style framework. " +
+          "Requires: company ticker/name, operating income (3-year data), enterprise value, " +
+          "ROIC data (5-year), and current stock price. Returns quantitative screening results, " +
+          "qualitative assessment, and classification (List 1-4).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            company_name: {
+              type: "string",
+              description: "Company name or ticker symbol",
+            },
+            operating_income_y1: {
+              type: "number",
+              description: "Operating income (GAAP) for year 1 (oldest of 3 years)",
+            },
+            operating_income_y2: {
+              type: "number",
+              description: "Operating income (GAAP) for year 2",
+            },
+            operating_income_y3: {
+              type: "number",
+              description: "Operating income (GAAP) for year 3 (most recent)",
+            },
+            enterprise_value: {
+              type: "number",
+              description: "Current enterprise value (market cap + debt - cash)",
+            },
+            roic_data: {
+              type: "array",
+              items: { type: "number" },
+              description: "Array of 5 years of ROIC percentages (as decimals, e.g., 0.25 for 25%)",
+            },
+            current_price: {
+              type: "number",
+              description: "Current stock price",
+            },
+            currency: {
+              type: "string",
+              description: "Currency symbol (e.g., '$', '₹', '€')",
+              default: "$",
+            },
+          },
+          required: [
+            "company_name",
+            "operating_income_y1",
+            "operating_income_y2",
+            "operating_income_y3",
+            "enterprise_value",
+            "roic_data",
+            "current_price",
+          ],
+        },
+      },
+      {
+        name: "calculate_earnings_yield",
+        description:
+          "Calculates the earnings yield for a stock. " +
+          "Earnings Yield = (3-year average operating income) / Enterprise Value. " +
+          "Returns whether it passes the >10% threshold.",
+        inputSchema: {
+          type: "object",
+          properties: {
+            operating_income_y1: { type: "number" },
+            operating_income_y2: { type: "number" },
+            operating_income_y3: { type: "number" },
+            enterprise_value: { type: "number" },
+          },
+          required: ["operating_income_y1", "operating_income_y2", "operating_income_y3", "enterprise_value"],
+        },
+      },
+      {
+        name: "calculate_roic",
+        description:
+          "Calculates the average ROIC over 5 years and determines if it meets " +
+          "the threshold (>15% for good business, >25% for wonderful business).",
+        inputSchema: {
+          type: "object",
+          properties: {
+            roic_data: {
+              type: "array",
+              items: { type: "number" },
+              description: "Array of 5 years of ROIC percentages (as decimals)",
+            },
+          },
+          required: ["roic_data"],
+        },
+      },
+      {
+        name: "classify_investment",
+        description:
+          "Classifies an investment into one of 4 lists based on the framework:\n" +
+          "LIST 1: Good business at wonderful price (ROIC 15-25%, earnings yield >10%)\n" +
+          "LIST 2: Wonderful business at fair price (ROIC >25%, fair valuation)\n" +
+          "LIST 3: FAT PITCH - Wonderful business at wonderful price (ROIC >25%, earnings yield >10%)\n" +
+          "LIST 4: Wonderful business overvalued (ROIC >25%, earnings yield <10%)",
+        inputSchema: {
+          type: "object",
+          properties: {
+            earnings_yield: {
+              type: "number",
+              description: "Earnings yield as a decimal (e.g., 0.12 for 12%)",
+            },
+            avg_roic: {
+              type: "number",
+              description: "Average ROIC as a decimal (e.g., 0.30 for 30%)",
+            },
+            business_quality: {
+              type: "string",
+              enum: ["good", "wonderful"],
+              description: "Business quality assessment",
+            },
+          },
+          required: ["earnings_yield", "avg_roic", "business_quality"],
+        },
+      },
+      {
+        name: "get_framework",
+        description:
+          "Returns the complete value investing framework documentation, " +
+          "including all classification criteria and investment philosophy.",
+        inputSchema: {
+          type: "object",
+          properties: {},
+        },
+      },
+    ],
+  };
+});
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "calculate_earnings_yield": {
+        const avgOI = (args.operating_income_y1 + args.operating_income_y2 + args.operating_income_y3) / 3;
+        const ev = args.enterprise_value;
+        const earningsYield = avgOI / ev;
+        const passes = earningsYield >= EARNINGS_YIELD_THRESHOLD;
+
+        const result = {
+          average_operating_income: Math.round(avgOI * 100) / 100,
+          enterprise_value: ev,
+          earnings_yield: Math.round(earningsYield * 10000) / 100,
+          earnings_yield_decimal: Math.round(earningsYield * 10000) / 10000,
+          threshold: EARNINGS_YIELD_THRESHOLD * 100,
+          passes: passes,
+          verdict: passes ? "✅ PASSES" : "❌ FAILS",
+        };
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "calculate_roic": {
+        const roicData = args.roic_data;
+
+        if (roicData.length !== 5) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: JSON.stringify({
+                  error: "ROIC data must contain exactly 5 years of data",
+                }),
+              },
+            ],
+          };
+        }
+
+        const avgROIC = roicData.reduce((a, b) => a + b, 0) / roicData.length;
+        const passesGood = avgROIC >= ROIC_THRESHOLD;
+        const passesWonderful = avgROIC >= ROIC_WONDERFUL_THRESHOLD;
+
+        const result = {
+          roic_data_percentages: roicData.map((r) => Math.round(r * 10000) / 100),
+          average_roic: Math.round(avgROIC * 10000) / 100,
+          average_roic_decimal: Math.round(avgROIC * 10000) / 10000,
+          threshold_good_business: ROIC_THRESHOLD * 100,
+          threshold_wonderful_business: ROIC_WONDERFUL_THRESHOLD * 100,
+          passes_good_threshold: passesGood,
+          passes_wonderful_threshold: passesWonderful,
+          classification: passesWonderful
+            ? "Wonderful Business (>25%)"
+            : passesGood
+            ? "Good Business (15-25%)"
+            : "Below Threshold (<15%)",
+        };
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "classify_investment": {
+        const ey = args.earnings_yield;
+        const roic = args.avg_roic;
+
+        let classification, description, action;
+
+        if (roic >= ROIC_WONDERFUL_THRESHOLD) {
+          if (ey >= EARNINGS_YIELD_THRESHOLD) {
+            classification = "LIST 3: FAT PITCH 🎯";
+            description = "Wonderful business at wonderful price - SWING HARD!";
+            action = "BUY AGGRESSIVELY - Size positions large";
+          } else if (ey >= 0.08) {
+            classification = "LIST 2: Wonderful at Fair Price";
+            description = "Wonderful business at reasonable valuation";
+            action = "BUY and HOLD FOREVER - Let quality compound";
+          } else {
+            classification = "LIST 4: Wonderful but Overvalued 📋";
+            description = "Study now, wait for better price";
+            action = "WATCHLIST - Monitor for price decline";
+          }
+        } else if (roic >= ROIC_THRESHOLD) {
+          if (ey >= EARNINGS_YIELD_THRESHOLD) {
+            classification = "LIST 1: Good Business at Wonderful Price";
+            description = "Solid fundamentals with margin of safety";
+            action = "BUY with discipline - 3-5 year hold";
+          } else {
+            classification = "PASS";
+            description = "Good business but insufficient margin of safety";
+            action = "Skip - wait for better opportunity";
+          }
+        } else {
+          classification = "PASS";
+          description = "Fails ROIC threshold";
+          action = "Skip entirely - poor business quality";
+        }
+
+        const result = {
+          classification,
+          description,
+          recommended_action: action,
+          earnings_yield: Math.round(ey * 10000) / 100,
+          avg_roic: Math.round(roic * 10000) / 100,
+          passes_quantitative_screens: roic >= ROIC_THRESHOLD && ey >= EARNINGS_YIELD_THRESHOLD,
+        };
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(result, null, 2),
+            },
+          ],
+        };
+      }
+
+      case "analyze_stock": {
+        const currency = args.currency || "$";
+        const company = args.company_name;
+
+        // Calculate earnings yield
+        const avgOI = (args.operating_income_y1 + args.operating_income_y2 + args.operating_income_y3) / 3;
+        const ev = args.enterprise_value;
+        const earningsYield = avgOI / ev;
+
+        // Calculate ROIC
+        const roicData = args.roic_data;
+        const avgROIC = roicData.reduce((a, b) => a + b, 0) / roicData.length;
+
+        // Determine business quality
+        const isWonderful = avgROIC >= ROIC_WONDERFUL_THRESHOLD;
+        const isGood = avgROIC >= ROIC_THRESHOLD;
+
+        // Classification
+        let classification, action;
+        if (isWonderful) {
+          if (earningsYield >= EARNINGS_YIELD_THRESHOLD) {
+            classification = "LIST 3: FAT PITCH 🎯";
+            action = "BUY AGGRESSIVELY";
+          } else if (earningsYield >= 0.08) {
+            classification = "LIST 2: Wonderful at Fair Price";
+            action = "BUY and HOLD FOREVER";
+          } else {
+            classification = "LIST 4: Wonderful but Overvalued";
+            action = "WATCHLIST";
+          }
+        } else if (isGood) {
+          if (earningsYield >= EARNINGS_YIELD_THRESHOLD) {
+            classification = "LIST 1: Good at Wonderful Price";
+            action = "BUY with Discipline";
+          } else {
+            classification = "PASS - Insufficient Margin of Safety";
+            action = "Skip";
+          }
+        } else {
+          classification = "PASS - Poor Business Quality";
+          action = "Skip Entirely";
+        }
+
+        // Build comprehensive report
+        let report = `
+═══════════════════════════════════════════════════════════════
+VALUE INVESTING ANALYSIS: ${company}
+═══════════════════════════════════════════════════════════════
+
+📊 QUANTITATIVE SCREENING
+───────────────────────────────────────────────────────────────
+
+1. EARNINGS YIELD TEST (Threshold: >10%)
+   Operating Income (3-year avg): ${currency}${avgOI.toLocaleString("en-US", { maximumFractionDigits: 0 })}
+   Enterprise Value: ${currency}${ev.toLocaleString("en-US", { maximumFractionDigits: 0 })}
+   Earnings Yield: ${(earningsYield * 100).toFixed(2)}%
+   Status: ${earningsYield >= EARNINGS_YIELD_THRESHOLD ? "✅ PASSES" : "❌ FAILS"}
+
+2. ROIC TEST (Threshold: >15% good, >25% wonderful)
+   Year 1: ${(roicData[0] * 100).toFixed(1)}%
+   Year 2: ${(roicData[1] * 100).toFixed(1)}%
+   Year 3: ${(roicData[2] * 100).toFixed(1)}%
+   Year 4: ${(roicData[3] * 100).toFixed(1)}%
+   Year 5: ${(roicData[4] * 100).toFixed(1)}%
+   5-Year Average: ${(avgROIC * 100).toFixed(1)}%
+   Status: ${
+          isWonderful
+            ? "✅ Wonderful Business (>25%)"
+            : isGood
+            ? "✅ Good Business (15-25%)"
+            : "❌ Below Threshold"
+        }
+
+───────────────────────────────────────────────────────────────
+📋 CLASSIFICATION
+───────────────────────────────────────────────────────────────
+
+${classification}
+
+Recommended Action: ${action}
+
+───────────────────────────────────────────────────────────────
+💡 FRAMEWORK GUIDANCE
+───────────────────────────────────────────────────────────────
+`;
+
+        if (classification.includes("FAT PITCH")) {
+          report += `
+🎯 FAT PITCH OPPORTUNITY
+This is a rare combination of wonderful business quality at a 
+wonderful price. "Back up the truck" - size this position aggressively.
+These opportunities appear briefly during market dislocations.
+
+Key: High ROIC + High Earnings Yield = Exceptional opportunity
+`;
+        } else if (classification.includes("LIST 2")) {
+          report += `
+📈 QUALITY COMPOUNDER
+Wonderful business at fair price. Quality compounds over time - 
+entry price matters less with sustained high ROIC. Hold 10+ years.
+This is where you spend most of your time per Charlie Munger.
+
+Key: Let quality compound, minimize trading
+`;
+        } else if (classification.includes("LIST 1")) {
+          report += `
+💰 CLASSICAL VALUE PLAY
+Good business with margin of safety. Price compensates for business
+limitations. Requires 3-5 year horizon per Benjamin Graham approach.
+
+Key: Solid fundamentals + discount = acceptable risk/reward
+`;
+        } else if (classification.includes("LIST 4")) {
+          report += `
+⏳ STUDY AND WAIT
+Wonderful business but trading above intrinsic value. Study deeply NOW:
+- Read 10-Ks and understand the moat
+- Set your buy price (target >10% earnings yield)
+- Monitor patiently with cash reserves ready
+
+When market offers your price, you'll be prepared to act immediately.
+
+Key: Patience is profitable - wait for fat pitch
+`;
+        } else {
+          report += `
+🚫 PASS ENTIRELY
+Either business quality insufficient (ROIC <15%) or valuation doesn't
+provide adequate margin of safety. Hold cash and wait for better
+opportunities. Remember: sometimes the best investment decision is
+saying "no."
+
+Key: Capital preservation > forced deployment
+`;
+        }
+
+        report += `
+
+───────────────────────────────────────────────────────────────
+Current Price: ${currency}${args.current_price.toFixed(2)}
+Analysis Date: ${new Date().toISOString().split("T")[0]}
+═══════════════════════════════════════════════════════════════
+`;
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: report,
+            },
+          ],
+        };
+      }
+
+      case "get_framework": {
+        const framework = `
+═══════════════════════════════════════════════════════════════
+VALUE INVESTING CLASSIFICATION FRAMEWORK
+Based on Warren Buffett & Charlie Munger's Principles
+═══════════════════════════════════════════════════════════════
+
+"The big money is not in the buying and selling, but in the waiting."
+— Charlie Munger
+
+───────────────────────────────────────────────────────────────
+📊 QUANTITATIVE SCREENS (REQUIRED)
+───────────────────────────────────────────────────────────────
+
+1. EARNINGS YIELD TEST: >10%
+   Calculation: 3-year average operating income / Enterprise Value
+   Purpose: Ensures adequate margin of safety
+
+2. ROIC TEST: >15% over 5 years
+   Good Business: 15-25% ROIC
+   Wonderful Business: >25% ROIC
+   Purpose: Identifies capital efficiency and competitive moats
+
+───────────────────────────────────────────────────────────────
+📋 THE FOUR LISTS
+───────────────────────────────────────────────────────────────
+
+LIST 1: Good Businesses at Wonderful Price
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• Quality: ROIC 15-25% (solid, not exceptional)
+• Price: Earnings yield >10% (significant discount)
+• Strategy: Classical Graham value - 3-5 year hold
+• Examples: Good companies with capital intensity or competitive pressures
+
+LIST 2: Wonderful Businesses at Fair Price ⭐
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• Quality: ROIC >25%, durable moats, pricing power
+• Price: Fair valuation (15-25x earnings), modest margin of safety
+• Strategy: Buy and hold "forever" - let quality compound
+• Note: Munger's sweet spot - where you spend most time
+
+LIST 3: FAT PITCH - Wonderful at Wonderful Price 🎯
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• Quality: ROIC >25%, strong moats, exceptional business
+• Price: Bargain prices despite quality (<15x earnings typically)
+• Strategy: "Back up the truck" - size positions aggressively
+• Frequency: Rare - appears during market panics every few years
+
+LIST 4: Wonderful Business Overvalued (Watchlist) 📋
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+• Quality: ROIC >25%, wonderful characteristics
+• Price: Above intrinsic value (often >30x earnings)
+• Strategy: Study deeply NOW, monitor patiently, maintain cash
+• Action: When market offers your price, act immediately
+
+───────────────────────────────────────────────────────────────
+🎯 QUICK CLASSIFICATION GUIDE
+───────────────────────────────────────────────────────────────
+
+1. Passes quantitative screens? → If NO, PASS entirely
+2. Is it wonderful (ROIC >25%)? → Determines List 2/3/4 vs List 1
+3. What's the price?
+   • Significant discount + wonderful → LIST 3 (Buy aggressively)
+   • Fair price + wonderful → LIST 2 (Buy and hold forever)
+   • Discount + good (not wonderful) → LIST 1 (Buy with discipline)
+   • Premium + wonderful → LIST 4 (Study and wait)
+
+───────────────────────────────────────────────────────────────
+⚠️ CRITICAL PRINCIPLES
+───────────────────────────────────────────────────────────────
+
+• High historical ROIC alone ≠ wonderful business
+• Must be SUSTAINABLE and IMPROVING
+• A shrinking business with great past returns is NOT wonderful
+• Margin of safety is PRIMARY criterion
+• Sometimes best decision is holding cash and saying "no"
+• "Wait for the fat pitch" - patience is often highest-return decision
+
+───────────────────────────────────────────────────────────────
+💡 PHILOSOPHY
+───────────────────────────────────────────────────────────────
+
+This framework emphasizes:
+1. Buying wonderful businesses at wonderful prices (rare but powerful)
+2. Holding quality forever when purchased at fair prices
+3. NEVER overpaying, even for quality
+4. Capital preservation through disciplined screening
+5. Patient opportunism over constant activity
+
+"It's far better to buy a wonderful company at a fair price than
+a fair company at a wonderful price." — Warren Buffett
+
+═══════════════════════════════════════════════════════════════
+`;
+
+        return {
+          content: [
+            {
+              type: "text",
+              text: framework,
+            },
+          ],
+        };
+      }
+
+      default:
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ error: `Unknown tool: ${name}` }),
+            },
+          ],
+        };
+    }
+  } catch (error) {
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ error: error.message }),
+        },
+      ],
+      isError: true,
+    };
+  }
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+
+main().catch((error) => {
+  console.error("Server error:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "olympus-mcp",
+  "version": "1.0.0",
+  "description": "Warren Buffett-style value investing analysis for Claude AI",
+  "type": "module",
+  "main": "index.js",
+  "bin": "index.js",
+  "scripts": {
+    "start": "node index.js"
+  },
+  "keywords": [
+    "mcp",
+    "value-investing",
+    "warren-buffett",
+    "stock-analysis",
+    "claude",
+    "olympus"
+  ],
+  "author": "Owen Taylor",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}