Lamplighter-MCP

Lamplighter-MCP is a backend service designed to act as an intelligent context engine for software development teams using AI coding assistants like Cursor, particularly within large and complex codebases. It addresses the challenges of providing relevant, up-to-date project context (code structure, feature specifications, task status) to AI models and developers, and automates the breakdown of large feature specifications into manageable tasks.

🌟 Features

• Codebase Analysis: Automatically analyze project structure and generate a summary
• Confluence Integration: Process Confluence specifications into actionable tasks
• Task Management: Track and update task status through MCP tools
• Intelligent Context: Provide structured context to AI coding assistants
• History Logging: Keep a record of all system events and actions
• MCP Integration: Seamlessly connect with Cursor through the Model Context Protocol

📋 Table of Contents

• Project Overview
• Installation
• Configuration
• Usage
• Architecture
• Directory Structure
• Testing
• Development Roadmap
• Contributing
• License

🔍 Project Overview

Lamplighter-MCP operates exclusively through the Model Context Protocol (MCP) for seamless integration with compatible tools. It serves as a centralized context provider for AI coding assistants, enhancing their understanding and code generation capabilities by maintaining:

• Structured codebase summaries
• Feature specifications and task breakdowns
• Task status tracking
• Project history logging

The project draws thematic inspiration from "The Little Prince," specifically the Lamplighter character, symbolizing guidance and dutiful tracking.

🚀 Installation

Prerequisites

• Node.js 18.x or higher
• npm 8.x or higher
• Access to Confluence API (for specification processing)
• Access to an LLM API (OpenAI, Google Gemini, etc.)

Setup

1. Clone the repository:

   git clone <repository-url>
   cd lamplighter-mcp

2. Install dependencies:

   npm install

3. Build the TypeScript code:

   npm run build

4. Create a .env file based on .env.example:

   cp .env.example .env
   # Edit .env with your configuration values

⚙️ Configuration

Configure the application by setting the following environment variables in your .env file:

# Server Configuration
PORT=3001
LAMPLIGHTER_CONTEXT_DIR=./lamplighter_context

# Confluence Configuration (for specification processing)
CONFLUENCE_URL=https://your-domain.atlassian.net
CONFLUENCE_API_TOKEN=your-api-token

# AI Service Configuration
AI_PROVIDER=openai  # openai or google
OPENAI_API_KEY=your-openai-key
GOOGLE_API_KEY=your-google-key
AI_MODEL=gpt-4  # or google's model name

📝 Usage

Using NPX (Recommended)

The easiest way to use Lamplighter-MCP is through npx:

# Initialize a new project with Lamplighter-MCP
npx lamplighter-mcp init

# Start the Lamplighter-MCP server
npx lamplighter-mcp start

# Get help with available commands
npx lamplighter-mcp help

You can also install it globally for easier access:

npm install -g lamplighter-mcp
lamplighter-mcp start

This approach is similar to how claude-task-master works, making it easy to integrate with your existing workflow.

Starting the Server Manually

Run the development server with hot reload:

npm run dev

Run the production server:

npm start

Cursor Integration

To integrate Lamplighter-MCP with Cursor, you can use one of these approaches:

Option 1: Use Local MCP Server

1. Start the Lamplighter-MCP server using npx lamplighter-mcp start
2. Configure your Cursor application to connect to the local server by enabling MCP in Cursor preferences
3. Access Lamplighter-MCP features directly through Cursor by prompting the AI to use the available tools

Option 2: Direct NPX Integration in Cursor

Add this to your .cursor/settings.json file:

{
  "mcpServers": {
    "lamplighter-mcp": {
      "command": "npx",
      "args": ["-y", "lamplighter-mcp", "start"],
      "env": {
        "CONFLUENCE_URL": "https://your-domain.atlassian.net",
        "CONFLUENCE_API_TOKEN": "your-api-token",
        "CONFLUENCE_USERNAME": "your-username",
        "AI_PROVIDER": "openai",
        "OPENAI_API_KEY": "your-openai-key"
      }
    }
  }
}

This configuration allows Cursor to automatically start the Lamplighter-MCP server when needed.

Available MCP Tools

• analyze_codebase: Analyzes project structure and generates a summary
• process_confluence_spec: Processes a Confluence specification into tasks
• update_task_status: Updates the status of a specific task
• suggest_next_task: Identifies the next task to work on
• get_codebase_summary: Retrieves the codebase summary
• get_history_log: Retrieves the history log
• get_feature_tasks: Retrieves tasks for a specific feature

🚢 Deployment & Testing

Deployment Options

Lamplighter-MCP can be deployed in several ways, depending on your needs:

1. Manual Deployment

   • Run on a development server via Node.js directly
   • Use a process manager like PM2: pm2 start dist/server.js --name lamplighter-mcp
   • Setup appropriate environment variables in .env

2. Containerized Deployment (Docker)

   # Build the Docker image
   docker build -t lamplighter-mcp:latest .
      
   # Run the container
   docker run -d -p 3001:3001 --env-file .env --name lamplighter-mcp lamplighter-mcp:latest

3. Cloud Deployment (AWS/Azure/GCP)

   • Deploy on a cloud VM with Node.js installed
   • Use a service like AWS Elastic Beanstalk or GCP App Engine
   • Configure environment variables in the cloud service console

For detailed deployment instructions, see documents/deployment_plan.md.

Health Check

The server provides a health endpoint at /health that can be used to verify server status:

curl http://localhost:3001/health

Expected response:

{
  "status": "ok",
  "uptime": 1234.56,
  "timestamp": "2025-04-13T06:20:01.618Z",
  "version": "1.0.0",
  "name": "Lamplighter-MCP"
}

Testing

For comprehensive end-to-end testing, we follow the test plan outlined in documents/e2e_testing_plan.md. Key testing approaches include:

1. Manual Testing: Using Cursor to interact with the MCP server
2. MCP Inspector: Direct testing of individual MCP tools
3. Automated API Tests: For validating endpoint responses

🧠 System Overview

Lamplighter-MCP serves as an intelligent context engine for software development teams. It operates as a bridge between AI coding assistants (like Cursor) and the complex context of software projects.

System Purpose

Lamplighter-MCP performs four key functions:

1. Understanding Codebase Structure: Analyzes your codebase to create a structured overview of its components, modules, and relationships.
2. Breaking Down Feature Specifications: Processes feature specifications from Confluence and breaks them into actionable tasks.
3. Tracking Task Status: Maintains the status of each task (ToDo, InProgress, Done) and suggests which task to work on next.
4. Maintaining Development History: Logs all interactions and changes to create a timeline of development activities.

Context Files

Lamplighter-MCP manages the following Markdown files that provide valuable context to both AI assistants and developers:

• codebase_summary.md: Contains a structured overview of the project, including key directories, modules, and architecture.
• feature_tasks/feature_[ID]_tasks.md: Contains the task breakdown for each feature specification, with task statuses.
• history_log.md: Contains a chronological log of all system events and actions.

Key Workflows

Codebase Analysis

1. AI Assistant Suggestion: "I notice we're working in a complex codebase. Would you like me to analyze it to better understand its structure?"
2. User Confirmation: "Yes, please analyze the codebase."
3. AI Execution: The AI uses the analyze_codebase tool, which generates a codebase_summary.md file.
4. AI Response: "I've analyzed the codebase. Here's a summary of its structure: [key insights from the analysis]"

Feature Specification Processing

1. User Request: "I have a new feature to implement from this Confluence page: [URL]"
2. AI Execution: The AI uses the process_confluence_spec tool with the URL parameter.
3. AI Response: "I've processed the specification and broken it down into tasks. Here they are: [list of tasks]"

Task Management

1. AI Suggestion: "Based on your feature '[feature_id]', the next task you should work on is: [task description]"
2. User Confirmation: "I've completed that task."
3. AI Execution: The AI uses the update_task_status tool to mark the task as Done.
4. AI Follow-up: "Task marked as complete. The next task to work on is: [next task description]"

AI Suggestion + User Confirmation Protocol

For any action that modifies data (especially task statuses), the AI should:

1. Suggest the action: "Would you like me to mark the task '[task]' as complete?"
2. Wait for confirmation: The user should explicitly confirm before the AI proceeds.
3. Execute the action: Only after confirmation should the AI use the appropriate tool.
4. Confirm completion: The AI should inform the user that the action has been completed.

This two-step process ensures that users maintain control over their project state while benefiting from AI assistance.

🏗️ Architecture

Lamplighter-MCP follows a modular architecture with clear separation of concerns:

• Core Modules (src/modules/): Contain the core business logic
• Services (src/services/): Integrate with external services (AI, Confluence)
• MCP Server (src/server.ts): Provides MCP tools and handles client connections
• Context Files (lamplighter_context/): Store structured Markdown files as the system's state

Key Components

• CodebaseAnalyzer: Analyzes the project structure and generates summaries
• HistoryLogger: Maintains an event log of system actions
• FeatureSpecProcessor: Processes specifications into actionable tasks
• TaskManager: Manages task status and retrieval
• AIService: Abstracts interactions with different LLM providers
• ConfluenceReader: Fetches content from Confluence

📂 Directory Structure

lamplighter-mcp/
├── .cursor/                  # Cursor configuration
│   ├── mcp.json              # MCP connection configuration
│   └── rules/                # AI guidance rules
│       └── *.mdc             # Markdown rule files
├── __tests__/                # Test files
│   ├── codebaseAnalyzer.test.ts
│   ├── historyLogger.test.ts
│   ├── server.test.ts
│   └── README.md             # Testing documentation
├── documents/                # Project documentation
│   ├── prd.md                # Product Requirements Document
│   ├── tasks.md              # Implementation Tasks
│   ├── erd.md                # Entity Relationship Document
│   └── mcp_*.md              # MCP documentation
├── lamplighter_context/      # Context storage directory
│   ├── codebase_summary.md   # Generated by CodebaseAnalyzer
│   ├── feature_tasks/        # Generated task files
│   └── history_log.md        # Generated by HistoryLogger
├── src/                      # Source code
│   ├── modules/              # Core logic modules
│   │   ├── codebaseAnalyzer.ts
│   │   ├── confluenceReader.ts
│   │   ├── featureSpecProcessor.ts
│   │   ├── historyLogger.ts
│   │   └── taskManager.ts
│   ├── services/             # External service integration
│   │   └── aiService.ts
│   └── server.ts             # MCP server implementation
├── .env.example              # Example environment variables
├── jest.config.ts            # Jest configuration
├── package.json              # Node.js dependencies
├── tsconfig.json             # TypeScript configuration
└── README.md                 # This file

🧪 Testing

Lamplighter-MCP uses Jest for testing. The test suite includes:

• Unit tests for core modules
• Mocked external dependencies
• Component tests for server elements

Running Tests

npm test -- --config=jest.config.ts

For more details, see the testing documentation.

🗺️ Development Roadmap

See tasks.md for the detailed implementation roadmap. The project is being developed in phases:

1. Phase 1: Project Setup & Core Infrastructure ✅
2. Phase 2: Core Logic Modules Implementation 🔄
3. Phase 3: MCP Tool Implementation & Integration 🔄
4. Phase 4: Cursor Integration & Finalization 🔄
5. Phase 5: Deployment & Testing 🔄

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Lamplighter-MCP: Illuminating the path for AI-assisted software development.