VoCoufi/second-brain-mcp

Second Brain MCP Server

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:

pnpm install

3. Build the TypeScript code:

pnpm run build

Configuration

Add the MCP server to your Claude Code configuration file (~/.claude/settings.local.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:

export SECOND_BRAIN_NOTES_DIR=~/Documents/my-notes

Or add it to your MCP server configuration:

{
  "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:

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:

Command Object:

{
  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:

{
  path: string;           // File path
  type: 'created' | 'modified' | 'deleted';
  description?: string;   // What changed
  diff?: string;          // Git-style diff (optional)
}

Code Snippet Object:

{
  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:

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:

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

# 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

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

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

pnpm run watch

Run Locally

pnpm run dev

Testing

# 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 for details on:

• Setting up the development environment
• Code style and conventions
• Commit message format (we use Conventional Commits)
• Pull request process
• Running tests

Quick Start for Contributors

# 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 and automated releases via semantic-release. Version numbers and changelog entries are automatically generated based on commit messages.

License

MIT