Context Keeper MCP Server

Keep your project documentation in sync with codebase changes automatically. Context Keeper analyzes code changes, generates ADRs, and updates documentation files to ensure your context is always fresh.

Features

• 🔍 Code Analysis: Detect architecture, API, and database changes automatically
• 📝 ADR Generation: Create Architecture Decision Records from significant changes
• 🔄 Documentation Sync: Keep architecture and API docs in sync with code
• 🚀 Smart Sync: All-in-one analysis, ADR generation, and doc updates
• 🔧 Git Integration: Analyze changes by commit range, date, or specific files

Installation

Via npx (Recommended)

npx @xenergyschool/context-keeper-mcp --dir /path/to/project

Via npm

npm install -g @xenergyschool/context-keeper-mcp
context-keeper-mcp --dir /path/to/project

Usage

Command Line

# Use current directory
context-keeper-mcp

# Specify project directory
context-keeper-mcp --dir /path/to/project

MCP Configuration

Add to your MCP settings (e.g., Claude Desktop config):

{
  "mcpServers": {
    "context-keeper": {
      "command": "npx",
      "args": ["@xenergyschool/context-keeper-mcp", "--dir", "/path/to/project"]
    }
  }
}

MCP Tools

1. keeper.analyzeChanges

Analyze code changes to determine documentation impact.

Input:

{
  "files": ["src/api/revenue.py"],        // Optional: specific files
  "commitRange": "HEAD~5..HEAD",          // Optional: commit range
  "since": "2024-01-01"                   // Optional: changes since date
}

Output:

{
  "ok": true,
  "filesAnalyzed": 3,
  "changes": {
    "architecture": {
      "impacted": true,
      "modules": ["RevenueSplitEngineV2"],
      "severity": "major"
    },
    "apiContracts": {
      "impacted": true,
      "endpoints": [{
        "method": "POST",
        "path": "/revenue-split/process-v2",
        "file": "service/main.py"
      }]
    },
    "needsADR": true,
    "adrSuggestion": {
      "title": "Revenue Split Engine V2 Implementation",
      "reason": "Major architecture change introducing new components"
    }
  }
}

2. keeper.generateADR

Generate Architecture Decision Record.

Input:

{
  "title": "Revenue Split Engine V2",
  "context": "Need to remove fallback company share logic",
  "decision": "Use split_rules as single source of truth",
  "consequences": [
    "✅ More explicit configuration",
    "⚠️ Existing integrations may need updates"
  ],
  "status": "Proposed"
}

Output:

{
  "ok": true,
  "adrPath": "docs/context/adr/2025-10-02-revenue-split-engine-v2.md",
  "created": true
}

3. keeper.syncArchitecture

Update architecture documentation.

Input:

{
  "changes": {
    "newModules": ["RevenueSplitEngineV2"],
    "modifiedModules": ["BatchProcessor"],
    "removedModules": []
  },
  "mode": "smart-merge"  // append | replace | smart-merge
}

4. keeper.syncAPIContracts

Update API contracts documentation.

Input:

{
  "scanPattern": "**/*.py",
  "framework": "fastapi",
  "extractFrom": "code"
}

5. keeper.smartSync

All-in-one: analyze, generate ADR, and sync docs.

Input:

{
  "commitRange": "HEAD~3..HEAD",
  "autoCommit": false,
  "dryRun": false
}

Output:

{
  "ok": true,
  "summary": [
    "Created ADR: docs/context/adr/2025-10-02-api-update.md",
    "Updated 01-architecture.md",
    "Updated 03-api-contracts.md (3 new endpoints)"
  ]
}

6. keeper.listADRs

List all Architecture Decision Records.

Output:

{
  "ok": true,
  "count": 5,
  "adrs": [
    {
      "file": "2025-10-02-revenue-split-v2.md",
      "title": "Revenue Split Engine V2",
      "status": "Accepted",
      "date": "2025-10-02"
    }
  ]
}

Project Structure Requirements

Context Keeper expects the following structure:

your-project/
├── docs/
│   └── context/
│       ├── 01-architecture.md
│       ├── 03-api-contracts.md
│       └── adr/
│           └── YYYY-MM-DD-title.md
├── src/           # Your source code
└── .git/          # Git repository

ADR Criteria

Context Keeper suggests ADR creation when detecting:

1. Architecture changes: New modules, services, or boundary crossings
2. API changes: New endpoints or contract modifications
3. Database changes: Schema updates or migrations
4. Security changes: Authentication, authorization, or encryption
5. Multiple impacts: Changes affecting 2+ areas

Documentation Format

Architecture Document (01-architecture.md)

## Component Notes
- **ModuleName**: Description
- **NewModule**: [New component - documentation pending]
- ~~**DeprecatedModule**~~: Description *(deprecated)*

<!-- Last updated by context-keeper: 2025-10-02T10:00:00Z -->

API Contracts (03-api-contracts.md)

## Section Name
| Method | Path | Description |
| --- | --- | --- |
| POST | `/api/endpoint` | Description |

<!-- API Contracts last synced: 2025-10-02T10:00:00Z -->

ADR Format

# ADR-2025-10-02: Title

## Status
Proposed

## Context
Background and motivation...

## Decision
What was decided and why...

## Consequences
- ✅ Positive outcome
- ⚠️ Trade-off or concern

## Files Affected
- src/file.py

## Metadata
- Created: 2025-10-02T10:00:00Z
- Generator: context-keeper-mcp

Workflow Integration

With Factory.ai Droid

# In mcp_bootstrap.sh
droid <<EOF
/mcp add keeper "npx @xenergyschool/context-keeper-mcp --dir ."
EOF

CI/CD Pipeline

# .github/workflows/docs.yml
- name: Sync Documentation
  run: |
    npx @xenergyschool/context-keeper-mcp --dir . \
      keeper.smartSync '{"commitRange": "${{ github.event.before }}..${{ github.sha }}"}'

Git Hooks

# .git/hooks/post-commit
#!/bin/bash
npx @xenergyschool/context-keeper-mcp --dir . \
  keeper.smartSync '{"commitRange": "HEAD~1..HEAD"}'

Best Practices

1. Regular Syncs: Run keeper.smartSync after significant changes
2. Review ADRs: Transition from "Proposed" to "Accepted" after review
3. Dry Run First: Use dryRun: true to preview changes
4. Backup Important Docs: Context Keeper creates .backup files automatically

Framework Support

Currently supported:

• FastAPI (Python) - Full support
• Express (Node.js) - Coming soon
• Django (Python) - Coming soon

Development

# Clone repository
git clone https://github.com/xenergyschool/context-keeper-mcp.git
cd context-keeper-mcp

# Install dependencies
npm install

# Run locally
npm start -- --dir /path/to/project

License

MIT

Author

xenergyschool

Contributing

Contributions welcome! Please submit PRs with:

• New framework support
• Additional analyzers
• Documentation improvements