Langfuse MCP Server

# Documentation Index - Langfuse MCP Server Complete guide to all documentation available for this project. Use this as your navigation hub. --- ## Document Overview ### 1. **docs/ARCHITECTURE.md** (1,316 lines) **For**: Understanding the "big picture" and design decisions **Content**: - Overview and design philosophy (section 1) - File structure and directories (section 2) - MCP server structure (section 3) - Tool architecture (18 tools organized in 3 categories) (section 3) - Langfuse client wrapper design (section 4) - Configuration system (section 5) - Complete type system reference (section 6) - Tool implementation patterns (7 patterns) (section 7) - Data processing & aggregation strategies (section 8) - Error handling strategy (section 9) - Build process and development (section 10) - Testing framework (section 11) - Key dependencies and roles (section 12) - Configuration patterns and best practices (section 13) - How to add new tools/APIs (step-by-step) (section 14) - Architectural decisions and trade-offs (section 15) - Known limitations and improvements (section 16) - Quick reference guide (section 17) **Read this first to understand**: The overall system architecture, tool categories, data flows, and design patterns. --- ### 2. **docs/DEVELOPER_GUIDE.md** (500+ lines) **For**: Hands-on development tasks **Content**: - Quick start setup and commands - Common development tasks with examples: - Task 1: Add a new MCP tool (complete working example) - Task 2: Add a new Langfuse API endpoint - Task 3: Fix a broken tool (debugging steps) - Task 4: Add configuration option - Task 5: Update/fix tool tests - Code organization principles - Naming conventions - Error handling patterns - Type validation patterns - Debugging tips and tricks - Common issues and solutions - Release & deployment instructions - Testing checklist - Useful resources **Read this when**: You're actively developing and need step-by-step instructions with code examples. --- ### 3. **docs/TECHNICAL_DIAGRAMS.md** (500+ lines) **For**: Visual understanding of complex flows **Content**: - Request processing flow (diagram 1) - Tool categories and dependencies (diagram 2) - API endpoint map (diagram 3) - Data flow example: get_cost_analysis (diagram 4) - Authentication flow (diagram 5) - Error handling architecture (diagram 6) - Tool registration and dispatch mechanism (diagram 7) - Dependency injection pattern (diagram 8) - Type system validation flow (diagram 9) - Multi-project architecture (future) (diagram 10) **Read this when**: You want to understand how different components interact visually, or you're explaining the system to others. --- ### 4. **README.md** (264 lines) **For**: Users and installation **Content**: - Project description and features - Installation options (npx, local development) - Configuration (environment variables) - Complete list of 18 available tools - Usage with Claude Desktop (2 options) - Example queries - Development workflow - Publishing to NPM - Project structure overview - API integration overview - Troubleshooting (common issues and solutions) **Read this first if**: You're a user trying to install and use the MCP server, not a developer. --- ### 5. **docs/IMPLEMENTATION_NOTES.md** (95 lines) **For**: Development history and API details **Content**: - Architecture decisions (3 key principles) - Known limitations (API, field mapping, tag parsing) - Next steps and future improvements - Testing checklist - API implementation details: - Authentication (Basic Auth) - Metrics API format and response processing - Troubleshooting common issues - Performance considerations - Security notes **Read this when**: You need API implementation details or understand why certain decisions were made. --- ## Navigation by Role ### I'm a **Product Manager** or **Decision Maker** 1. Read: README.md (Features & capabilities) 2. Read: docs/ARCHITECTURE.md Section 1 (Overview) 3. Skim: docs/TECHNICAL_DIAGRAMS.md (Understand flow) **Estimated time**: 30 minutes --- ### I'm a **User** installing the server 1. Read: README.md (Installation & Configuration) 2. Follow: Installation instructions 3. Test: Run npm run test 4. Reference: Example queries in README.md **Estimated time**: 15 minutes + testing time --- ### I'm a **Junior Developer** joining the team 1. Read: docs/DEVELOPER_GUIDE.md (Quick Start) 2. Read: docs/ARCHITECTURE.md Section 3 (Tool structure) 3. Read: docs/DEVELOPER_GUIDE.md (Common tasks) 4. Reference: docs/ARCHITECTURE.md Section 14 (Adding new tools) 5. Try: Add a test tool using the example **Estimated time**: 2 hours --- ### I'm a **Senior Developer** or **Architect** 1. Read: docs/ARCHITECTURE.md (complete, 1-17 sections) 2. Skim: docs/TECHNICAL_DIAGRAMS.md (validate understanding) 3. Review: Source code (src/ directory) 4. Reference: docs/DEVELOPER_GUIDE.md for specific tasks **Estimated time**: 3-4 hours --- ### I'm **Debugging a specific issue** 1. Go to: docs/DEVELOPER_GUIDE.md Section "Debugging Tips" 2. Check: docs/DEVELOPER_GUIDE.md Section "Common Issues & Solutions" 3. Verify: docs/IMPLEMENTATION_NOTES.md Section "Troubleshooting" 4. Trace: docs/TECHNICAL_DIAGRAMS.md (find relevant flow) **Estimated time**: 30 minutes --- ### I'm **Adding a new feature** 1. Review: docs/ARCHITECTURE.md Section 14 (How to add tools/APIs) 2. Follow: docs/DEVELOPER_GUIDE.md Task 1 or 2 (with code examples) 3. Reference: Existing tool file (pattern matching) 4. Test: docs/DEVELOPER_GUIDE.md Testing checklist **Estimated time**: 1-2 hours per feature --- ## Quick Lookup Reference ### "How do I..." | Question | Answer Location | |----------|-----------------| | Install and run the server? | README.md → Installation | | Add a new MCP tool? | docs/DEVELOPER_GUIDE.md → Task 1 | | Add a new API endpoint? | docs/DEVELOPER_GUIDE.md → Task 2 | | Understand the architecture? | docs/ARCHITECTURE.md → Sections 1-3 | | Debug a failing tool? | docs/DEVELOPER_GUIDE.md → Debugging Tips | | Understand tool categories? | docs/ARCHITECTURE.md → Section 3.3 | | See API endpoints used? | docs/TECHNICAL_DIAGRAMS.md → Diagram 3 | | Understand authentication? | docs/TECHNICAL_DIAGRAMS.md → Diagram 5 | | Fix type validation errors? | docs/TECHNICAL_DIAGRAMS.md → Diagram 9 | | Configure environment variables? | README.md → Configuration | | Deploy to production? | docs/DEVELOPER_GUIDE.md → Release & Deployment | | Understand error handling? | docs/ARCHITECTURE.md → Section 9 | | Learn about dependencies? | docs/ARCHITECTURE.md → Section 12 | | Understand configuration options? | docs/ARCHITECTURE.md → Section 13 | --- ## Document Statistics | Document | Lines | Sections | Topics | |----------|-------|----------|--------| | docs/ARCHITECTURE.md | 1,316 | 17 | 40+ architectural topics | | docs/DEVELOPER_GUIDE.md | 550+ | 8 main | 5 hands-on tasks, 10 debugging tips | | docs/TECHNICAL_DIAGRAMS.md | 500+ | 10 | Visual flow diagrams | | README.md | 264 | 12 | User-facing features | | docs/IMPLEMENTATION_NOTES.md | 95 | 5 | Implementation details | | **TOTAL** | **2,725+** | **52+** | **100+ topics** | --- ## Key Topics Quick Index ### Architecture & Design - Architecture overview (docs/ARCHITECTURE.md 1.1) - Design philosophy (docs/ARCHITECTURE.md 1.2) - Single project design (docs/ARCHITECTURE.md 15.1) - Metrics API vs manual aggregation (docs/ARCHITECTURE.md 15.2) ### Tools & MCP - Tool architecture (docs/ARCHITECTURE.md 3.2) - Tool categories (docs/ARCHITECTURE.md 3.3) - Adding tools (docs/ARCHITECTURE.md 14.1, docs/DEVELOPER_GUIDE.md Task 1) - Tool registration (docs/TECHNICAL_DIAGRAMS.md 7) ### APIs & Integration - Langfuse client (docs/ARCHITECTURE.md 4) - API methods (docs/ARCHITECTURE.md 4.2) - API endpoint map (docs/TECHNICAL_DIAGRAMS.md 3) - Adding endpoints (docs/ARCHITECTURE.md 14.2, docs/DEVELOPER_GUIDE.md Task 2) ### Configuration - Configuration system (docs/ARCHITECTURE.md 5) - Environment variables (docs/ARCHITECTURE.md 5, README.md) - Adding config options (docs/DEVELOPER_GUIDE.md Task 4) - Multi-project setup (docs/ARCHITECTURE.md 13.1) ### Type System - Types overview (docs/ARCHITECTURE.md 6) - Type validation patterns (docs/ARCHITECTURE.md 7.5) - Zod validation (docs/TECHNICAL_DIAGRAMS.md 9) ### Error Handling - Error strategy (docs/ARCHITECTURE.md 9) - Error flow (docs/TECHNICAL_DIAGRAMS.md 6) - Debugging (docs/DEVELOPER_GUIDE.md) ### Testing - Testing framework (docs/ARCHITECTURE.md 11) - Test-endpoints.js (README.md, docs/ARCHITECTURE.md 11.1) - Testing checklist (docs/DEVELOPER_GUIDE.md) ### Development Workflow - Build process (docs/ARCHITECTURE.md 10) - Development commands (README.md, docs/DEVELOPER_GUIDE.md) - Quick start (docs/DEVELOPER_GUIDE.md) --- ## Suggested Reading Order ### For Complete Understanding (5-6 hours) 1. README.md (15 min) - Understand what it does 2. docs/ARCHITECTURE.md sections 1-3 (45 min) - Big picture 3. docs/ARCHITECTURE.md sections 4-7 (60 min) - Key components 4. docs/TECHNICAL_DIAGRAMS.md (45 min) - Visual understanding 5. docs/ARCHITECTURE.md sections 8-14 (90 min) - Implementation patterns 6. docs/DEVELOPER_GUIDE.md (60 min) - Practical workflows 7. Source code review (60 min) - See it in practice ### For Practical Development (2-3 hours) 1. docs/DEVELOPER_GUIDE.md Quick Start (15 min) 2. docs/ARCHITECTURE.md section 3 (30 min) - Tool structure 3. docs/ARCHITECTURE.md section 14 (45 min) - Adding tools 4. docs/DEVELOPER_GUIDE.md Common Tasks (60 min) - With examples ### For Issue Resolution (30 min) 1. docs/DEVELOPER_GUIDE.md Debugging Tips (15 min) 2. Relevant docs/TECHNICAL_DIAGRAMS.md (10 min) 3. docs/DEVELOPER_GUIDE.md Common Issues (5 min) --- ## Document Maintenance Notes ### Last Updated - docs/ARCHITECTURE.md: Comprehensive, current - docs/DEVELOPER_GUIDE.md: Comprehensive, current - docs/TECHNICAL_DIAGRAMS.md: Complete with 10 diagrams - README.md: User-facing, maintained separately - docs/IMPLEMENTATION_NOTES.md: Historical, development reference ### When to Update - Add new tool: Update docs/ARCHITECTURE.md (section 3.3) - Change architecture: Update docs/ARCHITECTURE.md, docs/TECHNICAL_DIAGRAMS.md - New API endpoint: Update docs/ARCHITECTURE.md (4.2), docs/TECHNICAL_DIAGRAMS.md (3) - New configuration: Update docs/ARCHITECTURE.md (5), README.md (Configuration) - Bug fix: Consider adding to docs/DEVELOPER_GUIDE.md "Common Issues" --- ## External References ### Langfuse Documentation - **Metrics API**: https://langfuse.com/docs/metrics/features/metrics-api - **Traces API**: https://langfuse.com/docs/api-and-data-platform - **Observations**: https://langfuse.com/docs/api-and-data-platform - **SDK**: https://langfuse.com/docs/sdk/python ### MCP Protocol - **MCP Specification**: https://modelcontextprotocol.io - **MCP SDK**: https://github.com/modelcontextprotocol/specification ### Technologies - **TypeScript**: https://www.typescriptlang.org - **Zod**: https://zod.dev - **Node.js**: https://nodejs.org --- ## Support & Questions ### For Usage Questions → Start with README.md and docs/IMPLEMENTATION_NOTES.md ### For Architecture Questions → Start with docs/ARCHITECTURE.md and docs/TECHNICAL_DIAGRAMS.md ### For Development Questions → Start with docs/DEVELOPER_GUIDE.md ### For Bug Reports → Include: Error message, steps to reproduce, relevant section from docs ### For Feature Requests → Review: docs/ARCHITECTURE.md sections 15-16 (limitations and improvements) --- This documentation index is your map. Use it to navigate quickly to the information you need. **Happy developing!**