Second Brain MCP Server

# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## Project Overview This is an MCP (Model Context Protocol) server that captures structured markdown notes from Claude Code sessions. It automatically analyzes sessions with pattern detection and simple complexity analysis, and provides unified search/discovery features across all notes. ## Build & Development Commands ```bash # Install dependencies pnpm install # Build TypeScript → JavaScript (output: build/) pnpm run build # Watch mode (auto-rebuild on changes) pnpm run watch # Run server locally (builds first) pnpm run dev ``` **After making changes**: Always run `pnpm run build` before testing the MCP server with Claude Code, as MCP servers execute from `build/index.js`, not source files. ## Architecture ### Entry Point & Server Setup - **`src/index.ts`**: MCP server implementation using `@modelcontextprotocol/sdk` - Registers 3 tools (capture_session_note, search_notes, generate_weekly_report) - Handles tool execution via `CallToolRequestSchema` handler - Runs on stdio transport (communicates via stdin/stdout) ### Core Data Flow (capture_session_note) 1. **Receive**: SessionNote data (summary, commands, fileChanges, codeSnippets, tags, etc.) 2. **Analyze**: - Pattern detection (new-feature, bug-fix, refactoring, etc.) via `patternDetector.ts` - Simple complexity analysis (simple/moderate/complex) based on file count via `analysisUtils.ts` - Key file extraction and key changes generation via `analysisUtils.ts` 3. **Format**: Convert to markdown with emoji indicators via `noteFormatter.ts` 4. **Save**: Markdown file + metadata JSON via `storage.ts` ### Service Modules (src/services/) - **`storage.ts`**: File operations - saves notes to `~/notes/` (or `$SECOND_BRAIN_NOTES_DIR`), organized by project subdirectories. Creates `.meta.json` cache files for fast queries. - **`noteFormatter.ts`**: Converts SessionNote objects to markdown with emoji indicators, collapsible sections, and Key Changes bullets. - **`patternDetector.ts`**: Analyzes file changes, commands, and summary to classify session type (🆕 new-feature, 🐛 bug-fix, ♻️ refactoring, 📝 documentation, ⚙️ configuration, ✅ testing). - **`analysisUtils.ts`**: Simple inline helpers for complexity analysis (file count heuristic: <3=simple, 3-7=moderate, 8+=complex), key file extraction, and key changes generation. - **`searchEngine.ts`**: Unified search with text search and similarity-based discovery. Supports filters by date, pattern, complexity, tags. Includes weighted Jaccard similarity (tags 40%, pattern 30%, project 30%) for the `similarTo` parameter. - **`reportGenerator.ts`**: Aggregates sessions into weekly reports with statistics, project breakdown, pattern distribution, and complexity distribution. ### Type System (src/types/session.ts) All core types defined here: `SessionNote`, `SessionPattern`, `ComplexityLevel`, `SessionAnalysis`, `SearchFilters`, etc. ## Key Implementation Details ### Notes Directory Configuration Priority order: tool parameter > `SECOND_BRAIN_NOTES_DIR` env var > `~/notes` default ### Metadata Caching Each `.md` note has a corresponding `.meta.json` file containing extracted metadata (summary, timestamp, tags, analysis). This enables fast searches without parsing full markdown. ### File Naming Convention Format: `YYYY-MM-DD_HH-mm-ss_projectname-topic.md` Generated in `noteFormatter.ts:generateFilename()` ### TypeScript Module System - Uses ES modules (`"type": "module"` in package.json) - Import paths require `.js` extension (TypeScript convention for ES modules) - Compiled to Node16 module resolution (ES2022 target) ## Testing the Server 1. Build: `pnpm run build` 2. Configure in Claude Code settings at `~/.claude/settings.local.json`: ```json { "mcpServers": { "second-brain": { "command": "node", "args": ["/absolute/path/to/second_brain_mcp/build/index.js"], "env": { "SECOND_BRAIN_NOTES_DIR": "/home/user/notes" } } } } ``` 3. Restart Claude Code to load the MCP server 4. Use tools in conversation: "Capture this session with summary: 'Implemented authentication'" ## Common Modifications **Adding a new tool**: 1. Add tool definition in `ListToolsRequestSchema` handler in `src/index.ts` 2. Add tool execution in `CallToolRequestSchema` handler in `src/index.ts` 3. Create service module if needed (src/services/) **Changing analysis logic**: - Pattern detection: Edit `patternDetector.ts:detectPattern()` - Complexity thresholds: Edit `analysisUtils.ts:getComplexity()` (simple file count heuristic) - Key changes generation: Edit `analysisUtils.ts:generateKeyChanges()` **Modifying note format**: - Edit `noteFormatter.ts:formatNoteAsMarkdown()` - Update emoji indicators, section structure, Key Changes bullets **Enhancing search**: - Text search relevance: Edit `searchEngine.ts:calculateRelevance()` - Similarity scoring: Edit `searchEngine.ts:calculateSimilarity()` (weighted Jaccard) - Filter logic: Edit `searchEngine.ts:matchesFilters()`