Second Brain MCP Server

# Second Brain MCP Server [](https://github.com/VoCoufi/second-brain-mcp/actions/workflows/ci.yml) [](https://github.com/VoCoufi/second-brain-mcp/actions/workflows/release.yml) [](https://github.com/VoCoufi/second-brain-mcp/releases) [](https://opensource.org/licenses/MIT) An MCP (Model Context Protocol) server that helps you create structured markdown notes from your Claude Code sessions. Capture commands executed, file changes, conversation summaries, and code snippets, then organize everything into a searchable second brain. ## Features ### Session Capture & Analysis - **Pattern Detection**: Automatically identifies session type (🆕 New Feature, 🐛 Bug Fix, ♻️ Refactoring, 📝 Documentation, ⚙️ Configuration, ✅ Testing) - **Complexity Analysis**: Simple file count-based classification (🟢 Simple: <3 files, 🟡 Moderate: 3-7 files, 🔴 Complex: 8+ files) - **Automatic Organization**: Notes organized by project into subdirectories - **Rich Metadata**: Captures commands, file changes, code snippets, and summaries with structured metadata - **Clean Markdown**: Readable format with emoji indicators and Key Changes bullets ### Search & Discovery - **Advanced Search**: Multi-criteria filters (project, tags, pattern, complexity, date range, text query) with relevance scoring - **Similarity Search**: Find related sessions using Jaccard similarity across tags, patterns, and projects - **Unified Search Tool**: Single `search_notes` tool handles both text search and similarity search ### Weekly Reports - **Comprehensive Summaries**: Statistics on sessions, files changed, and commands executed - **Pattern & Complexity Distribution**: Visual breakdown of work patterns and complexity levels - **Project Breakdown**: Sessions grouped by project - **Session List**: Chronological list of all sessions with summaries ### Technical - **No External Dependencies**: Everything runs locally without API keys or external services - **Metadata Caching**: Fast queries with JSON metadata files - **Flexible Configuration**: Customize where notes are stored - **TypeScript**: Full type safety with comprehensive test coverage ## Installation 1. Clone or download this repository 2. Install dependencies: ```bash pnpm install ``` 3. Build the TypeScript code: ```bash pnpm run build ``` ## Configuration Add the MCP server to your Claude Code configuration file (`~/.claude/settings.local.json`): ```json { "mcpServers": { "second-brain": { "command": "node", "args": ["/absolute/path/to/second_brain_mcp/build/index.js"] } } } ``` Replace `/absolute/path/to/second_brain_mcp` with the actual path to this project. ### Notes Directory Configuration By default, notes are saved to `~/notes` (your home directory). You can customize this in two ways: **Option 1: Environment Variable (Recommended)** Set the `SECOND_BRAIN_NOTES_DIR` environment variable: ```bash export SECOND_BRAIN_NOTES_DIR=~/Documents/my-notes ``` Or add it to your MCP server configuration: ```json { "mcpServers": { "second-brain": { "command": "node", "args": ["/absolute/path/to/second_brain_mcp/build/index.js"], "env": { "SECOND_BRAIN_NOTES_DIR": "/home/username/Documents/my-notes" } } } } ``` **Option 2: Per-Tool Parameter** Pass `notesDirectory` parameter when calling any tool (overrides environment variable): ``` Please capture this session with notesDirectory: "/path/to/custom/notes" ``` **Priority:** Tool parameter > Environment variable > Default (`~/notes`) ## Available Tools This MCP server provides 3 focused tools for managing your session notes: | Tool | Purpose | |------|---------| | `capture_session_note` | Capture and save detailed session notes with automatic pattern and complexity analysis | | `search_notes` | Search notes with advanced filters, text search, and similarity-based discovery | | `generate_weekly_report` | Generate comprehensive weekly summary reports | ## Usage Once configured, you can use these tools in your Claude Code conversations: ### Basic Example ``` Please capture this session with the summary: "Implemented user authentication with JWT tokens" ``` ### Full Example with All Fields ``` Please capture this session note: Summary: "Implemented user authentication system with JWT tokens and refresh token rotation" Project: "my-web-app" Topic: "authentication" Commands executed: - npm install jsonwebtoken bcrypt - npm run test File changes: - Created: src/auth/jwt.ts - JWT token generation and validation - Modified: src/server.ts - Added authentication middleware - Created: src/auth/routes.ts - Login and registration endpoints Code snippets: - The JWT validation middleware (from src/auth/middleware.ts) - The token generation function (from src/auth/jwt.ts) Tags: authentication, security, jwt, backend Working directory: /home/user/projects/my-web-app ``` ### Searching Notes ``` Search for notes about "authentication" Search for bug-fix sessions with complex complexity Find all notes tagged with "typescript" from the last month Find sessions similar to ~/notes/my-project/2025-01-15_14-30-22_my-project-authentication.md ``` ### Weekly Reports ``` Generate a weekly report of my coding sessions ``` ## Tool Reference ### capture_session_note Capture and save a markdown note from a Claude Code session with automatic analysis. **Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `summary` | string | Yes | High-level summary of what was accomplished | | `projectName` | string | No | Project name (used for organizing into subdirectories) | | `topic` | string | No | Specific topic or feature being worked on | | `commands` | array | No | List of commands executed with descriptions | | `fileChanges` | array | No | Files created, modified, or deleted | | `codeSnippets` | array | No | Important code snippets from the session | | `tags` | array | No | Tags for categorizing the note | | `workingDirectory` | string | No | Working directory (defaults to current directory) | | `notesDirectory` | string | No | Custom notes directory (defaults to ~/notes or $SECOND_BRAIN_NOTES_DIR) | **Command Object:** ```typescript { command: string; // The command that was executed description?: string; // What the command does output?: string; // Command output (optional) timestamp?: string; // When it was executed (ISO format) } ``` **File Change Object:** ```typescript { path: string; // File path type: 'created' | 'modified' | 'deleted'; description?: string; // What changed diff?: string; // Git-style diff (optional) } ``` **Code Snippet Object:** ```typescript { language: string; // Programming language for syntax highlighting code: string; // The code snippet description?: string; // What the code does filePath?: string; // Where the code is from } ``` --- ### search_notes Search session notes with advanced filters, text search, and similarity-based discovery. **Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `query` | string | No | Text to search for in notes | | `projectName` | string | No | Filter by project name | | `tags` | array | No | Filter by tags (notes must have at least one) | | `pattern` | string | No | Filter by session pattern (new-feature, bug-fix, refactoring, documentation, configuration, testing, mixed) | | `complexity` | string | No | Filter by complexity level (simple, moderate, complex) | | `startDate` | string | No | Filter by start date (ISO format) | | `endDate` | string | No | Filter by end date (ISO format) | | `similarTo` | string | No | Path to note for similarity search. Results ranked by similarity to this note. | | `notesDirectory` | string | No | Custom notes directory (defaults to ~/notes or $SECOND_BRAIN_NOTES_DIR) | **Text Search Examples:** ``` Search for notes about "authentication" Search for bug-fix sessions with complex complexity Find all notes tagged with "typescript" from the last month ``` **Similarity Search Examples:** ``` Find sessions related to ~/notes/my-project/2025-01-15_14-30-22_my-project-authentication.md Find similar sessions to my last authentication work ``` **Combined Search:** ``` Search for "database" sessions similar to ~/notes/my-project/2025-01-10_migration.md ``` Similarity is calculated using weighted Jaccard similarity: - Tags (40% weight) - Pattern matching (30% weight) - Project name (30% weight) Results are sorted by relevance score (combined text relevance and similarity if applicable) and include project, summary, date, tags, matched tags, and file path. --- ### generate_weekly_report Generate a comprehensive weekly summary of all sessions. **Parameters:** | Parameter | Type | Required | Description | |-----------|------|----------|-------------| | `notesDirectory` | string | No | Custom notes directory (defaults to ~/notes or $SECOND_BRAIN_NOTES_DIR) | **Example:** ``` Generate a weekly report of my coding sessions ``` The report includes: - Total sessions, files changed, commands executed - Project breakdown - Work patterns distribution (🆕 New Feature, 🐛 Bug Fix, etc.) - Complexity distribution (🟢 Simple, 🟡 Moderate, 🔴 Complex) - List of all sessions with date, time, and summaries --- ## Note Organization Notes are saved to a **centralized location** (`~/notes` by default) and organized by project: ``` ~/notes/ ├── my-web-app/ │ ├── 2025-01-15_14-30-22_my-web-app-authentication.md │ └── 2025-01-15_16-45-10_my-web-app-database-setup.md ├── cli-tool/ │ └── 2025-01-14_10-15-33_cli-tool-refactoring.md └── second-brain-mcp/ └── 2025-01-13_09-20-15_second-brain-mcp.md ``` **Organization structure:** - All notes are in one centralized directory (easier to search and backup) - Each project gets its own subdirectory - Filenames include date, time, project name, and topic - Notes without a project name go into a `session/` folder **Benefits of centralized storage:** - Easy to search across all projects - Simple to backup (one directory) - Works well with version control - Can be synced to cloud storage ## Output Format Generated notes include: 1. **Header**: Project name and topic 2. **Metadata**: Date, working directory, tags, **Pattern** (🆕/🐛/♻️/etc.), **Complexity** (🟢/🟡/🔴 with file count) 3. **Summary**: High-level description 4. **Key Changes**: 2-3 concise bullet points summarizing main changes 5. **Commands Executed**: All commands with outputs (collapsible) 6. **File Changes**: Organized by created/modified/deleted with descriptions 7. **Code Snippets**: With syntax highlighting and context ### Example Note ```markdown # my-web-app ## Authentication --- **Date**: 15/01/2025, 14:30:22 **Working Directory**: `/home/user/projects/my-web-app` **Tags**: #authentication, #security, #jwt **Pattern**: 🆕 New Feature **Complexity**: 🟡 Moderate (3 files) --- ## Summary Implemented user authentication system with JWT tokens and refresh token rotation ## Key Changes - Created JWT token generation and validation - Added authentication middleware - Implemented login and registration endpoints ## Commands Executed ### Install authentication dependencies ```bash npm install jsonwebtoken bcrypt ``` ### Run tests ```bash npm run test ``` ## File Changes ### Created Files - `src/auth/jwt.ts` - JWT token generation and validation - `src/auth/routes.ts` - Login and registration endpoints ### Modified Files - `src/server.ts` - Added authentication middleware ## Code Snippets ### JWT validation middleware *From: `src/auth/middleware.ts`* ```typescript export const authMiddleware = async (req, res, next) => { const token = req.headers.authorization?.split(' ')[1]; if (!token) return res.status(401).json({ error: 'No token provided' }); try { const decoded = jwt.verify(token, process.env.JWT_SECRET); req.user = decoded; next(); } catch (error) { res.status(401).json({ error: 'Invalid token' }); } }; ``` ``` ## Development ### Build ```bash pnpm run build ``` ### Watch Mode ```bash pnpm run watch ``` ### Run Locally ```bash pnpm run dev ``` ### Testing ```bash # Run tests pnpm run test # Run tests in watch mode pnpm run test:watch # Run tests with coverage pnpm run test:coverage ``` The project has comprehensive test coverage (95%+) covering all services and utilities. ## Tips 1. **End of Session**: Call the capture tool at the end of your coding session to document your work 2. **Consistent Project Names**: Use the same project name across sessions for better organization 3. **Meaningful Summaries**: Write clear summaries that you can search for later 4. **Use Tags**: Add relevant tags to make notes easier to find 5. **Include Context**: Add code snippets and file changes to provide context for future reference 6. **File Descriptions**: Add descriptions to file changes - they become Key Changes bullets in your notes ## Contributing Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details on: - Setting up the development environment - Code style and conventions - Commit message format (we use [Conventional Commits](https://www.conventionalcommits.org/)) - Pull request process - Running tests ### Quick Start for Contributors ```bash # Fork and clone the repository git clone https://github.com/VoCoufi/second_brain_mcp.git cd second_brain_mcp # Install dependencies pnpm install # Run tests pnpm run test # Build the project pnpm run build ``` ## Versioning This project uses [Semantic Versioning](https://semver.org/) and automated releases via [semantic-release](https://github.com/semantic-release/semantic-release). Version numbers and changelog entries are automatically generated based on commit messages. ## License MIT