Claude Session Intelligence MCP Server

Universal access to development decisions, patterns, and accumulated wisdom

Transform your Claude Code sessions from forgetful conversations into intelligent, context-aware development sessions that build on accumulated knowledge.

🧠 What This Solves

Before: Context Amnesia

Session 1: "Let me explain our auth system..." → Solution A
Session 2: "Let me explain our auth system..." → Solution B (contradicts A)  
Session 3: "Let me explain our auth system..." → Repeat forever

After: Persistent Intelligence

Session 1: Discovers JWT pattern → Records decision with reasoning
Session 2: Loads JWT context → "I see you use JWT with 15min expiry because..."
Session 3: Inherits full auth knowledge → Focuses on new problems

📦 Installation

Standalone Installation

npm install -g claude-session-intelligence-mcp

With NX Plugin (Recommended)

npm install -D nx-claude-sessions
nx g nx-claude-sessions:init
# MCP server is automatically configured

🚀 Quick Setup

1. Install the MCP Server

npm install -g claude-session-intelligence-mcp

2. Configure Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "claude-session-intelligence": {
      "command": "npx",
      "args": ["claude-session-intelligence-mcp"],
      "env": {
        "WORKSPACE_ROOT": "/path/to/your/workspace"
      }
    }
  }
}

3. Start Using Intelligence

Open any Claude Code session and try:

Load context for my auth library

What JWT decisions were made in the past?

Show me authentication patterns I can reuse

🛠️ MCP Tools Available

Decision Management

record_decision

Capture architectural decisions with full reasoning:

// Claude automatically calls this tool when you say:
// "We decided to use JWT tokens because they're stateless and scale better than sessions"

{
  title: "JWT vs Session Authentication",
  decision: "Use JWT tokens with 15-minute expiry",
  reasoning: [
    "Stateless authentication needed for microservices",
    "Better scalability than server-side sessions", 
    "Client-side storage reduces server memory"
  ],
  alternatives_considered: [
    {
      option: "Session-based auth",
      pros: ["Simpler revocation", "Server-side security"],
      cons: ["Stateful scaling issues", "Memory overhead"]
    }
  ]
}

search_decisions

Find previous architectural decisions:

# Claude automatically searches when you ask:
# "How did we handle JWT token expiration before?"

→ Returns all JWT-related decisions with full reasoning
→ Shows what was tried, what worked, what didn't
→ Provides context for consistent decision-making

Pattern Management

get_patterns

Access proven code patterns:

# When you ask: "Show me authentication patterns"
→ Returns reusable patterns with usage examples
→ Filters by category, reusability, library
→ Includes dependencies and implementation notes

record_pattern

Capture reusable solutions:

// Claude calls this when you create something reusable:
{
  name: "JWT Guard with User Extraction",
  category: "authentication", 
  description: "Custom NestJS guard that validates JWT and injects user",
  file_path: "src/auth/jwt.guard.ts",
  reusability: "high",
  usage_notes: ["Use with @UseGuards decorator", "Requires JWT_SECRET env var"],
  dependencies: ["@nestjs/passport", "@nestjs/jwt"],
  example_usage: "@UseGuards(JwtAuthGuard)"
}

Context Management

get_library_context

Load complete library intelligence:

// Returns comprehensive context:
{
  context: "Library documentation and domain knowledge",
  decisions: ["All architectural decisions with reasoning"],
  patterns: ["Reusable code patterns and solutions"],
  sessions: ["Key learnings from previous sessions"],
  meta: {
    maturity_level: "stable",
    expertise_areas: ["jwt-authentication", "role-based-auth"],
    session_count: 15,
    decision_count: 8
  }
}

start_session_tracking

Begin intelligent session tracking:

# Start accumulating intelligence for this session
session_id = start_session_tracking({
  library: "auth",
  task: "Add 2FA support",
  task_type: "feature"
})

# Context automatically loaded:
# - Previous 2FA attempts and decisions  
# - Existing auth patterns to build on
# - Known challenges and solutions

📋 MCP Resources (Read-Only Data)

Library Resources

• library://auth/context - Full library documentation
• library://auth/decisions - All architectural decisions
• library://auth/patterns - Reusable code patterns

Workspace Resources

• workspace://decisions/recent - Recent decisions across all libraries
• workspace://patterns/popular - Most reused patterns

🎯 Usage Examples

Loading Context

I'm working on the auth library. Can you load its context?

→ Claude uses get_library_context tool
→ Returns: 8 decisions, 12 patterns, 15 sessions of accumulated knowledge
→ Response: "I can see your auth library uses JWT with refresh tokens. You've established patterns for role-based authorization and have solved token expiration challenges. What would you like to work on?"

Searching Previous Work

How have we handled password reset flows?

→ Claude uses search_decisions tool  
→ Finds: "Password Reset with Email Verification" decision from 3 months ago
→ Response: "You implemented password reset with email verification tokens that expire in 1 hour. The decision was made because SMS was too expensive and security codes in email provide good UX. The implementation is in src/auth/reset.service.ts."

Building on Patterns

I need to add OAuth login support

→ Claude uses get_patterns + get_library_context
→ Finds: Existing JWT infrastructure and auth guard patterns
→ Response: "I can help you add OAuth. You already have JWT infrastructure and a custom auth guard pattern. I'll build the OAuth flow to integrate with your existing JWT system and reuse your proven patterns for token handling."

Recording New Insights

We're implementing OAuth, and I decided to use the authorization code flow with PKCE because it's more secure for SPAs than implicit flow

→ Claude automatically calls record_decision
→ Decision saved with full reasoning
→ Available for future sessions
→ Response: "Decision recorded! This will help future OAuth work build on your security-conscious approach."

🏗️ File System Structure

The MCP server works with library intelligence stored in .claude/ directories:

your-workspace/
├── libs/
│   └── auth/
│       ├── src/
│       └── .claude/
│           ├── decisions.json    # Architectural decisions with reasoning
│           ├── patterns.json     # Reusable code patterns  
│           ├── context.md        # Library domain knowledge
│           ├── session-history.json # Compressed session learnings
│           ├── dependencies.json # Cross-library relationships
│           └── meta.json        # Intelligence metadata
└── .claude-session-intelligence/
    └── config.json              # MCP server configuration

🔧 Configuration

Basic Configuration

{
  "mcpServers": {
    "claude-session-intelligence": {
      "command": "npx",
      "args": ["claude-session-intelligence-mcp"],
      "env": {
        "WORKSPACE_ROOT": "/path/to/workspace"
      }
    }
  }
}

Advanced Configuration

{
  "mcpServers": {
    "claude-session-intelligence": {
      "command": "npx", 
      "args": [
        "claude-session-intelligence-mcp",
        "--max-decisions=100",
        "--compression-threshold=50",
        "--auto-detect-patterns=true"
      ],
      "env": {
        "WORKSPACE_ROOT": "/path/to/workspace",
        "AUTO_DETECT_LIBRARIES": "true",
        "INTELLIGENCE_LEVEL": "high"
      }
    }
  }
}

NX Workspace Auto-Detection

{
  "mcpServers": {
    "claude-session-intelligence": {
      "command": "npx",
      "args": ["claude-session-intelligence-mcp", "--nx-workspace", "."],
      "env": {
        "AUTO_DETECT_LIBRARIES": "true"
      }
    }
  }
}

🚀 Integration with Development Workflow

With NX Plugin (Full Experience)

# NX plugin provides full orchestration + uses MCP internally
nx start-claude-session auth --task="Add OAuth support"
# → Intelligent session with accumulated context
# → Automatic decision and pattern recording
# → Cross-library dependency awareness

Standalone (Universal Access)

# Any Claude Code session can use the intelligence
claude-code --workspace /path/to/project
# → Load context for any library
# → Search decisions across projects  
# → Record new patterns and decisions

With Other Tools

// Other MCP-compatible tools can access the intelligence
const decisions = await mcpClient.callTool('search_decisions', {
  query: 'authentication patterns',
  library: 'auth'
});

📊 Intelligence Metrics

The system tracks intelligence accumulation:

// Library maturity levels
"experimental" // < 3 sessions, minimal decisions
"developing"   // 3-10 sessions, some patterns
"stable"       // 10-20 sessions, established patterns
"mature"       // 20+ sessions, comprehensive knowledge

// Expertise areas (auto-detected)
["jwt-authentication", "role-based-authorization", "oauth-integration"]

// Complexity metrics
{
  files_managed: 12,        // Files with recorded patterns
  test_coverage: 0.95,      // Test coverage percentage
  dependency_depth: 2,      // How deep dependencies go
  pattern_reuse: 0.80      // How often patterns are reused
}

🔍 Troubleshooting

MCP Server Not Found

# Verify installation
npx claude-session-intelligence-mcp --version

# Check configuration
cat ~/.config/Claude/claude_desktop_config.json

No Intelligence Available

# Check workspace structure
ls -la .claude/  # Should exist in library directories

# Initialize if needed  
npx claude-session-intelligence-mcp --init-workspace

Context Loading Issues

# Verify permissions
ls -la libs/*/\.claude/

# Check file formats
npx claude-session-intelligence-mcp --validate-data

🤝 Contributing

This MCP server is part of the nx-conductor project. Contributions welcome!

Development Setup

git clone <repository>
cd nx-conductor/libs/nx-claude-sessions/src/mcp-server
npm install
npm run dev

Testing

# Test MCP server
npm run test

# Test with real Claude Desktop  
npm run build
claude-desktop # Should show the server in available tools

📄 License

MIT - Same as nx-conductor parent project

🧠 Every conversation builds on accumulated wisdom

Transform your development workflow with persistent, searchable, and continuously learning AI assistance.